Skip to content

Commands overview

Every git-city command is a high-level verb that operates on your branch tree. You invoke them with git city <command>, and because the executable is named git-city, Git exposes it as a native subcommand — so git city sync and git-city sync are exactly equivalent. This documentation always uses the git city form.

git city sync          # high-level verb
git city new add-login # create a feature off the trunk
git city info          # read-only dashboard
git city               # no args: the grouped command menu (help)

If you have not run it before, start with the quick start, then come back here as a reference.

The commands at a glance

The commands fall into five groups: the daily loop you reach for constantly, the stack-editing operations that reshape your tree, the recovery commands that get you out of trouble, the one-time setup commands, and the read-only commands that never change anything.

Daily workflow

Command What it does
new <name> Create a feature branch off the trunk (or --onto another branch) and check it out.
switch [name] Switch branches; with no name, open an interactive fuzzy picker. Pure navigation.
sync [branch] Fetch, restack onto the parent, and force-push (with lease). --all syncs every feature.
land [branch] Fast-forward the parent to the feature, re-home its children, push — and keep the branch (--delete removes it).
prune Delete the branches you've landed once their work is in the parent.

Stack editing

Command What it does
delete [branch] Delete a branch without merging; re-home its children onto its parent.
reparent <new-parent> Change a branch's recorded parent. Next sync rebases it onto the new parent.
insert <name> Insert a new branch between a branch and its parent.
squash [branch] Compress a feature's commits into a single commit.

Recovery

Command What it does
undo Reverse the last git-city command (single-level). Refuses rather than destroy.
continue Resume a sync paused on a conflict, after you resolved it and git added.
abort Undo a paused operation entirely, returning to where it started.

Setup

Command What it does
init Record the trunk branch (and --remote) in the local git-city.toml.
config Print the effective configuration and the config file paths.
completions Print a shell completion script (bash, zsh, fish); --install to set it up.

Read-only

Command What it does
git city info The dashboard: repo header, current-branch block, and the stack tree. -t / -v adjust the detail; surfaces any paused operation.
git city tree The full branch hierarchy as an indented tree.

Bare git city shows the menu

Run with no arguments, git city prints the grouped list of commands (the same as git city --help) and exits — a quick reminder of what is available. For the repository dashboard, use git city info.

git city info prints the dashboard — a quick orientation you can run at any time:

git-city · my-project
  trunk:  main
  remote: origin

on  ● add-login   (feature, parent: main)
    working tree: clean
    vs main:  ↑2 ↓0
    vs origin/add-login:  ↑0 ↓0

stack:
main  (trunk)
└─ ● add-login  ↑2 ↓0

It also takes two knobs for how much it prints. --terse / -t collapses everything to a single current-branch line; the default adds your stack (with a one-line hint for any unparented branches); --verbose / -v lists every unparented branch and annotates each node with its short sha. When a sync is paused on a conflict, info leads with the pause banner before the dashboard — so it doubles as "where did that sync stop?". (git city status is a hidden alias.)

Two rules that apply everywhere

Two behaviors are universal, so they are worth learning once rather than per command.

--dry-run previews any mutation

Every mutating command accepts --dry-run. It prints the exact, ordered Git commands it would run and then executes nothing — a safe way to see precisely what a verb expands to before you commit to it.

  git fetch origin --prune
  git branch -f main origin/main
  git checkout add-login
  git rebase --onto main <base> add-login
  git push --force-with-lease=add-login:<sha> origin add-login

Nothing executed (--dry-run).

Read the plan before you run it

--dry-run is the same plan the real run executes — there is no separate "preview" code path. If a command is about to do something surprising, this is how you find out first.

Destructive commands confirm first

The commands that delete a branch or rewrite published history — delete, prune, squash, and land --delete — print their plan and ask for confirmation before running. Pass --yes (or -y) to skip the prompt. Running them non-interactively (a script or CI) without --yes is refused rather than assumed, so a destructive command never proceeds unattended by accident. Plain land keeps the branch and is reversible, so it does not prompt.

Commit-moving commands refuse a dirty working tree

Commands that move commits — new, sync, land, delete, prune, insert, squash — plus undo refuse to run when your working tree is dirty. Commit or stash your changes first.

switch and reparent are the exceptions: they never touch your files (one is navigation, the other only edits lineage metadata), so they run on a dirty tree.

No raw tracebacks

When something goes wrong, git-city prints a clean git-city: <message> to stderr and exits with code 1 — never a stack trace.

Where to go next

→ The mental model