Git Worktree

Git Worktree Skill

Help users manage multiple working directories from one Git repository without accidentally sharing a branch, deleting uncommitted changes, or removing worktree metadata that Git needs. Git allows one non-detached branch to be checked out by only one worktree at a time; verify this constraint before creating or switching a worktree.

Source of truth

Use the current local Git help and the official documentation when command behavior or version support matters:

• git worktree -h
• https://git-scm.com/docs/git-worktree

Do not state that a Git option is available until it has been checked against the user's Git version when compatibility is relevant.

Workflow

1. Identify the intent and affected paths

Determine whether the user wants to create, inspect, move, lock, unlock, remove, repair, or prune a worktree. Identify the repository, target path, branch, and starting commit. Ask one focused clarification question when any of these would change the command or risk profile.

Before a state-changing command, inspect:

git rev-parse --show-toplevel
git worktree list --porcelain
git branch --show-current
git status --short

For an existing worktree, inspect it explicitly:

git -C <worktree-path> status --short
git -C <worktree-path> branch --show-current

Use git worktree list --porcelain when a script or reliable parsing is needed. It is stable across Git versions and configuration; combine it with -z only when code must safely parse unusual path names.

2. Choose the safest command

Prefer explicit branches and paths. Do not rely on Git inferring a branch name from a directory name when a user needs a predictable checkout.

Use a relative sibling path such as ../project-feature only when the user has confirmed the layout. Otherwise show the exact absolute or repository-relative path being used.

3. Respect safeguards

• Never suggest -B for a new worktree unless the user explicitly intends to reset an existing branch; it can discard branch history by resetting it to the chosen start point.
• Do not add --force merely to bypass an error. Explain which protection Git reported, inspect the affected branch or path, and offer a non-destructive alternative first.
• If a branch is already checked out, list worktrees and use a different branch, remove the old worktree only after checking it is clean, or make a detached checkout when that serves the user's purpose. Do not force the same branch into two normal worktrees.
• Before remove, check git -C <path> status --short. An empty result supports ordinary removal; non-empty output means changes need committing, moving, stashing, or explicit destructive confirmation.
• git worktree remove --force discards an unclean worktree. A locked worktree needs force twice. Only show either form after the user has explicitly accepted that loss or override.
• Start stale cleanup with git worktree prune --dry-run --verbose; run prune --verbose only after reviewing the preview. Use repair when the on-disk worktree still exists but its registration links are out of date.
• Treat paths containing spaces as one shell argument. Quote them in shell examples.

4. Verify the result

After every mutation, show a concise verification sequence:

git worktree list --verbose
git -C <worktree-path> status --short
git -C <worktree-path> branch --show-current

For a newly created worktree, also confirm the branch relationship when relevant:

git -C <worktree-path> status --branch --short

Common scenarios

Start a task without leaving the current branch

git fetch origin
git worktree add -b feature/<topic> ../<repository>-<topic> origin/main

Explain the chosen start point and replace origin/main with the repository's actual integration branch when it differs. If the repository does not need a fetch, omit it rather than adding network activity by default.

Work on an existing local branch

First confirm it is not already checked out:

git worktree list --verbose
git branch --show-current

Then use:

git worktree add ../<repository>-<branch> <branch>

Remove a completed worktree

git -C ../<repository>-<topic> status --short
git worktree remove ../<repository>-<topic>
git worktree list --verbose

If status is not clean, stop and explain the choices. Do not silently stash or discard work.

Repair after a manual filesystem move

If the primary repository and moved worktree still exist, run from the primary repository:

git worktree repair <new-worktree-path>
git worktree list --verbose

If a worktree directory was intentionally deleted manually, preview stale entries first:

git worktree prune --dry-run --verbose
git worktree prune --verbose

Response format

Use this order unless the user asks for only a command:

1. Situation — current worktree/branch state and the goal.
2. Safe command — the smallest command sequence with placeholders replaced where known.
3. Before running — branch, path, dirty-state, or destructive-operation caveats that apply.
4. Verify — command(s) that prove the intended worktree is registered and clean.

Keep normal operations concise. When blocked by Git safeguards, describe the actual conflict and present the safest alternatives rather than treating --force as the default solution.