gritHEAD → docs/worktree
Commands / Branches and tagsMarkdown

grit worktree

List, add, and remove linked worktrees for the same repository.

grit worktree list
grit worktree add <path> [<rev>]
grit worktree add -b <branch> <path> [<rev>]
grit worktree add -B <branch> <path> [<rev>]
grit worktree add --detach <path> [<rev>]
grit worktree add --lock [--reason <text>] <path> [<rev>]
grit worktree add --no-checkout <path> [<rev>]
grit worktree add --track <path> [<rev>]
grit worktree add -f <path> [<rev>]
grit worktree remove <path>
grit worktree remove -f <path>
grit worktree lock <path> [--reason <text>]
grit worktree unlock <path>
grit worktree move <worktree> <new-path> [-f] [--dry-run]
grit worktree repair [<path>…] [--dry-run]
grit worktree prune

Description

Git linked worktrees share one object database but have separate working trees and HEAD. grit worktree list shows the main worktree first, then linked worktrees (same order as git worktree list). The current worktree is prefixed with * in human output. Detached checkouts are labeled (detached HEAD) in human output (same idea as git worktree list). When the repository was opened from a bare clone, the main row is shown as (bare) without * or a branch name — bare HEAD is not a checkout and does not block grit worktree add for that branch. Linked rows whose working tree directory is gone are marked prunable, matching git worktree list --porcelain reason text in JSON.

Paths in human, --json, and --markdown output use normal absolute paths (no Windows \\?\ verbatim prefix) with forward slashes, so scripts can pass them to cd or grit worktree remove unchanged.

grit worktree add creates the admin directory under .git/worktrees/, writes the gitdir / commondir files, checks out the tree (unless --no-checkout), and registers the new worktree. After checkout it runs the post-checkout hook from the new worktree with a null old object id, the start commit, and flag 1, as Git does (skipped for --no-checkout and orphan branches). With only a path, grit creates a new branch named after the directory basename at HEAD. With a <rev> that names an existing branch, that branch is checked out (it must not already be checked out elsewhere). Use -b to create a new branch at <rev> (default HEAD). Use -B to create or reset a branch to <rev> (writes a reflog entry when resetting). Use --detach for a detached HEAD at the resolved commit. Use --lock (optional --reason) to write the locked file before checkout finishes. Use --no-checkout to register HEAD without populating the working tree. Use --track when the start point is a remote-tracking branch to set branch.*.remote / merge like git worktree add --track.

If <path> is already registered but its directory was deleted manually, grit refuses the add (same as Git). Use -f / --force to replace the stale registration, or grit worktree prune / grit worktree remove to clear it first.

While grit worktree add is checking out files, Ctrl+C (or SIGTERM / SIGHUP on Unix) stops with error: operation cancelled and exit code 130. Grit removes the half-created worktree registration, rolls back a newly created branch, and leaves no stale index.lock in the linked admin directory. A second interrupt terminates grit immediately without that cleanup.

grit worktree remove deletes the linked worktree's admin directory and, with -f, the working tree even when it has local changes.

grit worktree prune removes admin directories for linked worktrees whose working tree is missing (skips locked worktrees). Use --dry-run to list what would be pruned without deleting registrations.

grit worktree lock writes a locked file under the worktree admin directory (same on-disk format as git worktree lock). Locked worktrees are skipped by prune and refused by remove unless -f.

grit worktree unlock removes that lock file.

grit worktree move relocates a linked worktree and rewrites the worktree .git gitfile and admin gitdir file atomically (same on-disk layout as git worktree move). The main worktree cannot be moved. Locked worktrees require -f / --force (Git requires -f twice; grit uses one force flag). Populated submodules block the move, matching Git.

grit worktree repair fixes broken .git / gitdir links after a manual directory move. With no paths, grit repairs every registered linked worktree from the open repository.

Options

list

No flags.

add

Option Description
<path> Directory for the new working tree (must be missing or empty).
<rev> Commit or branch to check out (default HEAD).
-b, --branch Create and check out a new branch at <rev>.
-B Create or reset a branch to <rev> (refuses when that branch is checked out elsewhere).
--detach Detached HEAD at the resolved commit.
--lock Write the locked file before checkout completes.
--reason Reason stored in the lock file (requires --lock).
--no-checkout Register the worktree without checking out files.
--track Set upstream when <rev> is a remote-tracking branch.
-f, --force Replace a stale registration when the directory is missing.

remove

Option Description
<path> Path to the linked worktree.
-f, --force Remove even when locked or dirty.

lock

Option Description
<path> Path to the linked worktree.
--reason Optional reason stored in the lock file (shown by git worktree list).

unlock

Option Description
<path> Path to the linked worktree.

prune

Option Description
--dry-run Report prunable worktrees without removing registrations.

move

Option Description
<worktree> Path to the linked worktree to move.
<new-path> Destination (must not exist; if it is an existing directory, the worktree basename is appended).
-f, --force Move even when the worktree is locked.
--dry-run Preview the move without renaming or rewriting link files.

repair

Option Description
[<path>…] Linked worktree roots to repair (default: all linked worktrees).
--dry-run List repairs without writing files.

JSON output

Schema: v1 · worktree.add v1 · worktree.remove v1 · worktree.prune v2 · worktree.lock v1 · worktree.unlock v1 · worktree.move v1 · worktree.repair v1

Pass --json on any subcommand. The top-level action is list, add, remove, prune, lock, unlock, move, or repair.

Field Type Meaning
action string list, add, remove, prune, lock, unlock, move, or repair.
worktrees array For list, one object per worktree (fields below).
path string For add / remove / lock / unlock, absolute path to the working tree.
from string For move, previous worktree path.
to string For move, new worktree path.
repairs array For repair, objects with path and kind for each link rewritten.
head string For add, current commit oid checked out in the new worktree.
branch string or null For add, branch checked out when not detached.
locked boolean For add, whether the worktree was created locked.
checked_out boolean For add, whether files were checked out (false with --no-checkout).
dry_run boolean For prune, whether registrations were left intact.
reason string or null For lock, optional reason stored in the lock file.
pruned array For prune, objects with path and reason for each pruned (or would-be pruned) worktree.

Each object in worktrees (list action) includes path, head, branch, detached, bare, locked, lock_reason (always present, null when absent), prunable, optional prunable_reason, and is_current.

Repair kind values: git_file_admin_dir, gitdir_worktree_path, git_file_path_style, gitdir_path_style.

Markdown output

Pass --markdown for structured output.

Schema: worktree.list v1 · worktree.add v1 · worktree.remove v1 · worktree.prune v2 · worktree.lock v1 · worktree.unlock v1 · worktree.move v1 · worktree.repair v1

Add and remove use short headings with the path and branch (or detached HEAD) and commit oid.

Exit status

Code Meaning
0 Success (success).
1 Command failed (failure).
2 Invalid flags or arguments (usage).

See Exit codes for shared rules and structured --json kind values.