git-wt

git-wt manages Git worktrees using a consistent path layout.

Managed worktrees live under the main worktree at:

<main>/.git/wt/<branch-name>

The branch name is used as-is (including /), so the worktree name and branch name are identical.

Example:

• main worktree: my-repo
• branch: feature/login
• worktree path: my-repo/.git/wt/feature/login

Use git-wt migrate to move existing worktrees (including the old sibling repo.branch layout) into this path.

Installation

Install using Go,

go install github.com/nnutter/git-wt@latest

git-wt requires Git on PATH.

Shell integration

Generate a zsh function that wraps the CLI (default name wt):

git-wt generate zsh
# or: git-wt generate zsh --name wt --out $XDG_DATA_HOME/zsh/site-functions --force

Ensure the output directory is on fpath, then restart zsh or run compinit.

The generated function:

• routes most commands to git-wt (wt create, wt list, wt prune, …)
• after a successful wt create, cds into the new worktree unless --no-cd, -r | --herdr, or automatic Herdr workspace creation applies
• provides a shell-only switch that cds into a worktree
• after a successful wt remove, cds to the main worktree

wt switch main
wt switch feature/login
wt create feature/login          # then cd into it
wt create --no-cd feature/login  # create only
wt remove feature/login          # then cd main
wt list

If you use carapace, exclude its built-in wt completer (worktrunk) so zsh uses the generated completion instead:

export CARAPACE_EXCLUDES=wt

Set this before source <(carapace _carapace). You may need carapace --clear-cache after changing excludes.

Commands

git-wt create <name>

Create a managed worktree for a branch.

• If the branch already exists, the worktree is created from that branch.
• If the branch does not exist, it is created from the branch pointed at by origin/HEAD; set it explicitly with --upstream | -u.
• When run inside Herdr (HERDR_ENV=1), automatically create a Herdr workspace whose --cwd is the new worktree and whose --label is the worktree name (branch name).
• Use -r | --herdr to create a Herdr workspace explicitly, or -R | --no-herdr to suppress automatic creation.
• Herdr workspace creation through wt create implies --no-cd.
• Herdr workspace creation requires herdr on PATH and a running Herdr server.

Example:

git-wt create feature/login
git-wt create -u origin/v1.2 hotfix/1.2.1
git-wt create -r feature/login
git-wt create -R feature/login

git-wt list

List managed worktrees in a table.

Columns:

• Name: branch name
• Path: relative worktree path
• Status: first line of git status -sb
• Dirty: whether the worktree has uncommitted changes

git-wt migrate

Bring existing branch worktrees under git-wt management.

• Creates managed worktrees for local branches that do not already have one.
• Renames existing non-managed branch worktrees into the managed path format.

Use --prompt | -p to review the proposed migrations before applying them.

Example:

git-wt migrate
git-wt migrate --prompt

git-wt prune

Remove managed worktrees that are both clean, no uncommitted changes, and merged into their upstream branch.

Use --prompt | -p to choose which worktrees to prune interactively.

git-wt remove [name]

Remove a managed worktree and delete its branch.

When name is omitted, removes the managed worktree that contains the current directory. It refuses to remove the main worktree, and refuses dirty or unmerged worktrees by default. Use --force | -f to force (destructive) removal.

When invoked through the shell wrapper (wt remove), the shell also switches to the main worktree after a successful removal.

Example:

git-wt remove
git-wt remove feature/login
git-wt remove --force feature/login

git-wt generate zsh

Generate a zsh wrapper function and completion (see Shell integration).

Typical Flow

# once: install wrapper
git-wt generate zsh

# in a repo
wt create feature/login
wt switch feature/login
# ... work ...
wt switch main
wt prune
# or:
wt remove feature/login

For jumping between repositories under a path, you can still use something like git-cd.