new

gitto new <name> [<base>] [--branch <branch>]

Copies the canonical into <canonical>-<name> beside it, puts the copy on a new branch, and prints where it landed. The copy carries everything: history, submodules at every depth, dependencies, build output, and the files git was told to ignore.

$ gitto new auth-fix
cloning storefront -> storefront-auth-fix by clonefile
  repointed core.hooksPath at this clone's own hooks
  branch auth-fix on origin/main, 4 submodules, 60 MB of disk
/Users/you/work/storefront-auth-fix

The last line is the path, so cd "$(gitto new auth-fix | tail -1)" works in any shell. The shell function from shell-init does it for you.

Choosing a base

The base defaults to origin/HEAD, which is what you want for a branch off the main line. Pass HEAD to take the canonical exactly as it stands, including work it has not committed, and its submodules stay where they are.

Any other base moves the tree and the submodules to what that revision records.

Naming the branch

The branch takes the clone's name. When the branch has to be something a directory name cannot hold, name it:

gitto new auth-fix --branch feat/auth-token-refresh

What it refuses

A filesystem that cannot share blocks, which is measured before anything is copied. A canonical that is a worktree, because its history lives elsewhere. A name already taken. A base that collides with uncommitted work in the canonical, which HEAD avoids.

Any failure removes the half-built clone before it exits.

While something else holds the canonical

A clone reads the canonical as it copies, and sync writes to it. Both announce themselves in the same lock, so several clones can be taken at once and a clone taken during a sync waits for it instead of copying a tree that is moving.

$ gitto new auth-fix
waiting for gitto sync in storefront

A lock whose holder is no longer running is taken, and the run that takes it says so. GITTO_LOCK_TIMEOUT sets how long a run waits before it gives up, 1800 seconds by default.

What it inherits, and how old that is

A clone checks out origin/HEAD from a fetch of its own, so its tracked files are current even when the canonical is behind. Everything git does not track comes from the canonical instead, and is exactly as old as the canonical is:

$ gitto new auth-fix
  the canonical is 43 commits behind origin/main, so what it had built is that old
  dependencies and build output came from there; 'gitto sync' moves it and runs .gitto-refresh