Status & roadmap¶
git-city is early / pre-release. The local branch-workflow — branches, stacks, sync, land, undo, and stack editing — is complete and heavily tested, hardened across five adversarial review rounds with every confirmed data-integrity bug fixed and regression-tested. What is not built yet is forge integration: there is no propose command for opening a pull/merge request, and git-city does not talk to GitHub, GitLab, or any host. It works fully against a plain Git remote, or with no remote at all.
Pre-release
The daily loop is solid, but git-city makes no compatibility or stability promise yet. Commands, config keys, and output may change before a tagged release. Use it on repositories you can recover, and lean on git city undo and --dry-run while you build trust.
What works today¶
The complete command surface is implemented and tested. This is the full daily loop plus stack editing, onboarding, and navigation.
| Command | What it does |
|---|---|
git city info |
Dashboard: repo, trunk, remote, current-branch block, the stack tree, and any paused operation (read-only; -t / -v adjust detail). |
git city tree |
The branch hierarchy as an indented tree (read-only). |
git city new |
Create a feature branch off the trunk, or --onto another branch to stack it. |
git city switch |
Switch branches; no name opens an interactive fuzzy picker (on a TTY). |
git city sync |
Rebase a feature onto its parent and force-push with --force-with-lease; --all syncs everything in topological order. |
git city land |
Fast-forward the parent to the feature, re-home children, push; keep the branch (--delete to remove it). |
git city prune |
Delete the branches you've landed once their work is in the parent. |
git city delete |
Delete a branch without merging; re-home its children. |
git city reparent |
Change a branch's parent (lineage metadata only; the next sync restacks it). |
git city insert |
Insert a new branch between a branch and its parent. |
git city squash |
Compress a feature's commits into one. |
git city undo / continue / abort |
Reverse the last command, or resume / roll back a paused sync (inspect it with info). |
git city init |
Record the trunk (and --remote) in the local git-city.toml. |
git city config |
Print the effective configuration and config file paths. |
git city completions |
Print a shell completion script for bash, zsh, or fish. |
Two cross-cutting behaviors apply throughout and are equally solid:
- Every mutating command accepts
--dry-run, which prints the exact ordered Git commands it would run and executes nothing. git city undoreverses the last command — including force-pushed and deleted remote branches — and refuses rather than destroy.
Built on one reversible engine
Dry-run, undo, and conflict resume/rollback all fall out of a single model: a pure planner produces a list of steps, and an interpreter runs them while capturing how to reverse each one. That is why undo can restore force-pushed and deleted refs, and why a conflicted sync can be resumed or abandoned cleanly.
What is deferred, and why¶
git-city is deliberately forge-agnostic: the entire local workflow is designed to be useful and correct without ever contacting a host. That is a feature, not a gap — it is also why the host-facing pieces are the things still to come.
Forge integration (propose)¶
There is no propose command and no host integration yet. git-city cannot open a pull request or merge request, read review state, or push a patch series to a forge. To land work today you sync, then land (fast-forward the parent and push), or open the PR yourself through your host's own tooling.
Forge support is the headline item on the roadmap: a propose command for PR/MR or patch series. Until it exists, treat git-city as a powerful local stack manager that happens to push to a plain remote.
park / unpark / private toggle commands¶
The parked (skipped by sync) and private (synced with its parent but never pushed) modifier flags are fully respected by sync today. What is missing is the convenience commands to toggle them. For now, set them directly with git config:
# park a branch so sync skips it
git config git-city.branch.spike.parked true
# mark a branch private so it is never pushed
git config git-city.branch.draft.private true
Other-authors' commits guardrail¶
A planned guardrail will refuse to rewrite branches that carry commits authored by someone other than you. It is not built yet — but you are not unprotected in the meantime: every push git-city makes uses --force-with-lease, so it will never silently clobber remote work it has not seen.
No guardrail for shared-history rewrites yet
Until the guardrail lands, be careful running sync or squash on branches that carry other people's commits — rebasing rewrites history. --force-with-lease protects against clobbering unseen remote updates, but it does not stop you from rewriting commits you can already see.
Roadmap at a glance¶
| Area | Status |
|---|---|
| Local daily loop (new, sync, land, prune, delete) | Done |
| Stack editing (reparent, insert, squash) | Done |
| Onboarding (init, config) & navigation (switch, tree, info) | Done |
| Shell completions (bash, zsh, fish) | Done |
| Reversible engine (dry-run, undo, conflict resume/rollback) | Done |
Forge integration — propose (PR/MR or patch series) |
Not yet |
park / unpark / private toggle commands |
Not yet (set via git config) |
| Other-authors'-commits rewrite guardrail | Not yet |
git-city borrows git-town's best ideas — high-level verbs, the parent hierarchy, and a reversible-operation engine — without being a fork. The biggest visible difference today is exactly the forge: central to git-town's workflow, optional (and not yet built) here.