Skip to content

Quick start

This page walks you through the daily loop end to end: tell git-city what your trunk is, start a feature branch, do some work, keep it in sync with the trunk, and finally land it. Every command here operates on plain Git — no forge account, no PR API, nothing but the repo in front of you.

If you have not installed git-city yet, start with install. The rest of this page assumes git city runs.

Note

git city <cmd> and git-city <cmd> are the same thing. Git discovers any git-city executable on your PATH and exposes it as the city subcommand. The docs use git city.

1. Record the trunk

git-city needs to know which branch is your long-lived trunk (the branch features branch off of and land back into). Run this once per repository:

git city init

With no flags it auto-detects main or master. On a terminal, if it cannot decide, it shows an interactive dropdown of your branches. To be explicit:

git city init --trunk main

This writes a small, committable git-city.toml at the repo root recording the trunk. That is the only setup step.

→ init

2. Start a feature

Create a feature branch off the trunk. It is checked out for you, and git-city records that main is its parent.

git city new add-login

A feature is anything you work on; it always knows its parent. Follow parents upward and you reach the trunk. That parent link is what powers sync and land later — you never have to remember a base branch by hand.

→ new · the mental model

3. Hack and commit

Now work normally. git-city does not get in the way of plain Git:

git add -A
git commit -m "Add the login form"

At any point, run git city info to see where you stand:

git city info

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

The dashboard is read-only. It shows the repo, the trunk and remote, a block for the current branch (its parent, whether your working tree is clean or dirty, how far it is ahead/behind the trunk and its remote tracking branch), and the stack tree below. Here add-login is two commits ahead of main and not yet pushed.

→ config

4. Sync with the trunk

While you were working, main may have moved. sync brings your feature up to date by rebasing it onto the latest trunk:

git city sync

For a feature, sync fetches, brings the parent up to date, rebases your feature onto it (first absorbing any commits the remote has that you do not), then force-pushes with --force-with-lease. You end up with a clean, linear history on top of the current trunk.

Look before you leap

Unsure what a command will do? Add --dry-run to any mutating command and git-city prints the exact, ordered Git commands it would run — and executes nothing.

git city sync --dry-run

  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).

If a rebase hits a conflict, sync pauses instead of leaving you stranded. Resolve the files, git add them, and run git city continue — or git city abort to roll the whole thing back. See conflicts and recovery.

→ sync · rebase-first

5. Land the feature

When the feature is ready, land integrates it into the trunk:

git city land

This fast-forwards main to your feature's tip (history stays linear), re-homes any child branches onto main, and pushes main. It keeps the feature branch (tagged landed) so that if you spot a bug right after landing you can switch back, fix it, and land again — no branch to recreate. When you're done with the landed branches, sweep them away:

git city prune

(Or git city land --delete to integrate and delete in one step.)

Warning

land refuses if the feature is behind its parent. Run git city sync first, then land.

→ land

The loop at a glance

Step Command What it does
Set up (once) git city init Record the trunk in git-city.toml.
Start git city new <name> Branch off the trunk; record its parent; check it out.
Inspect git city info Read-only dashboard of your current branch and stack.
Update git city sync Rebase the feature onto the latest trunk; force-push.
Finish git city land Fast-forward the trunk to the feature; keep the branch (then git city prune).

Safety nets

git-city is built to be undone. Two habits keep you safe:

  • Preview with --dry-run. Every mutating command supports it. You see the precise Git commands before anything happens.
  • Reverse with undo. git city undo reverses the last git-city command — restoring moved refs, recreated branches, even force-pushed or deleted remote branches. It is single-level and it refuses rather than destroy: it will not run on a dirty working tree, and it will not delete a branch carrying commits that live nowhere else.
git city undo

Tip

Commit or stash before any command that moves commits (new, sync, land, and friends). They refuse to run on a dirty working tree, so your uncommitted work is never at risk.

→ reversible operations · recovery

Where to next