insert¶

git city insert slots a brand-new branch between an existing branch and its parent. The new branch is created at the parent's tip, becomes the existing branch's parent, and is checked out so you can start working on it immediately.

This is the tool you reach for when you realize a piece of work belongs below a branch you have already started — shared groundwork, a refactor that the rest of the stack should build on, or a reviewable slice you forgot to carve out first.

git city insert <name> [--branch <b>] [--dry-run]

Argument / Option	Meaning
`<name>`	Name of the new branch to insert. Created at the parent's tip.
`--branch <b>`	The branch to insert above `<name>`. Defaults to the current branch.
`--dry-run`	Print the exact ordered git commands and execute nothing.

No commits move

insert only edits lineage. The new branch starts empty (it points at the parent's tip), and the branch above it keeps every commit it already had. Nothing is rebased until your next sync.

What it does¶

Given a branch B whose parent is P, running git city insert M --branch B produces P → M → B:

Create M at the tip of P.
Record M's parent as P.
Re-home B so its parent is now M.
Check out M.

Because no commits move, B is now technically based on the old tip of P rather than on M. That is expected — develop M, then run sync and git-city restacks B onto M for you.

Example¶

Suppose you have a feature ui stacked on api, which is stacked on the trunk:

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

You realize ui and api should share some scaffolding that lives on its own branch. Insert shared below api:

git city insert shared --branch api

The lineage is now main → shared → api → ui, and you are checked out on the freshly created shared:

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

shared starts at main's tip with no commits of its own (↑0 ↓0). Add your scaffolding commits to it, then sync to restack everything above:

git city sync --all

sync walks the tree parents-before-children and rebases api (and then ui) onto the new shared.

→ How sync restacks a tree

Insert vs. reparent¶

Both commands edit lineage and move no commits, but they answer different questions:

You want to…	Use
Put a new branch between a branch and its parent	`git city insert`
Point an existing branch at a different existing parent	`git city reparent`

If you already have the branch you want as the new base, reparent is the right tool. If the base does not exist yet, insert creates it and wires it up in one step.

Dry run¶

Every mutating command supports --dry-run, which prints the ordered git commands and runs nothing:

git city insert shared --branch api --dry-run

Clean working tree required

insert is one of the commands that move refs, so it refuses to run on a dirty working tree — commit or stash your changes first. (--dry-run is always safe.)

new — create a feature branch off the trunk or stacked onto another branch.
reparent — re-point an existing branch onto a different existing parent.
sync — restack the branches above the one you just inserted.

→ The mental model: parents, trunks, and stacks