new¶

Create a feature branch and record where it belongs in your branch tree.

git city new is how you start a piece of work. It creates a branch, records its parent so git-city knows where it lives in the hierarchy, and checks it out — all in one step. By default the new branch is rooted on the trunk; with --onto you stack it on top of another branch instead.

git city new <name> [--onto <branch>] [--dry-run]

What it does¶

Step	Behavior
Create	Creates a new feature branch `<name>` at the tip of its parent.
Record parent	Stores the parent in Git config (`git-city.branch.<name>.parent`), so the branch joins the tree.
Check out	Switches you onto the new branch.

The parent is the trunk by default. Pass --onto <branch> to parent the new branch on <branch> instead — this is how you build a stack, placing one feature on top of another.

Note

new moves commits (it creates a ref), so it refuses to run on a dirty working tree. Commit or stash your changes first.

Options¶

Option	Description
`<name>`	Name of the feature branch to create. Required.
`--onto <branch>`	Stack the new branch onto `<branch>` instead of the trunk. `<branch>` becomes the recorded parent.
`--dry-run`	Print the exact ordered git commands that would run, and execute nothing.

Examples¶

Start a feature off the trunk¶

git city new add-login

This branches add-login off the trunk (here, main), records main as its parent, and checks it out. The dashboard then shows the new branch in the stack:

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

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

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

Stack a feature on top of another¶

git city new ui --onto api

This creates ui at the tip of api and records api as its parent, building a two-level stack:

main  (trunk)
└─ api  ↑3 ↓0
   └─ ● ui  ↑2 ↓0

Preview without changing anything¶

Use --dry-run to see exactly what new will do before committing to it:

git city new add-login --dry-run

The command prints the ordered git operations and runs nothing.

Tip

Every mutating git-city command accepts --dry-run. It is the safest way to learn what a command does on your repo — it shows the precise git plan and never touches a single ref.

Errors¶

git-city validates before it acts. Errors print as a clean git-city: <message> on stderr with exit code 1 — never a raw traceback.

Situation	What happens
A branch named `<name>` already exists	Refused; pick a different name.
`--onto <branch>` names a branch that does not exist	Refused as an unknown parent.
The working tree is dirty	Refused; commit or stash first.

After creating a branch¶

Move between branches with switch — a fast, validated navigation command (interactive picker when you give no name).
As the parent or the remote advances, restack your feature with sync, which rebases it onto its parent and force-pushes safely with --force-with-lease.

To understand trunks, features, parents, and stacks — the model new builds on — read the concepts page.

→ The mental model