Reference
Git Worktree Field Guide
A printable command map for working on several branches at once without losing the state of an unfinished task.
Core model
| State | Shared? | Practical consequence |
|---|---|---|
| Objects, commits, most refs | Yes | A commit in any worktree is visible everywhere. |
| Files, index, HEAD | No | Each worktree has its own edits, staging area, and checkout. |
| One branch checked out twice | Blocked by default | Use a distinct task branch or find the existing worktree. |
| Clean worktree removal | Required by default | Inspect before force or deletion. |
Normal workflow
List
git worktree list -vCreatebranch plus pathInspectstatus, diff, logCommitpreserve the taskIntegrateverify targetRemoveclean pathCommand map
| Command | Use when |
|---|---|
git worktree list --verbose | Find every attached path, branch, lock, or prune state. |
git worktree add -b fix/login ../repo-login | Create a new task branch and sibling worktree. |
git worktree add ../repo-review review/123 | Open an existing branch that is not checked out elsewhere. |
git worktree add --detach ../repo-scratch | Make a branchless experiment or test checkout. |
git status --short | Find tracked and untracked work before cleanup. |
git diff / git diff --cached | Read unstaged and staged changes separately. |
git log --oneline main..HEAD | Inspect task commits not yet in the target. |
git merge branch | Integrate the whole completed task branch. |
git cherry-pick <commit> | Integrate one selected commit. |
git worktree remove ../repo-login | Remove a clean linked worktree and its metadata. |
git worktree move <old> <new> | Relocate a worktree while keeping it connected. |
git worktree repair <new-path> | Reconnect a worktree moved manually. |
git worktree prune --dry-run | Preview stale records after a path disappeared. |
git worktree lock --reason "..." <path> | Protect a temporarily unavailable worktree from pruning. |
Before integration
- Commit the task worktree's changes.
- Read the task commit range.
- Choose merge or cherry-pick explicitly.
- Ensure the target worktree is clean.
- Run checks in the target after integration.
Before removal
- Run
git status --short. - Confirm useful commits are integrated or preserved.
- Use
git worktree remove. - Delete the branch only after it is no longer needed.
- Run
git worktree list --verboseagain.
Red flags
| You see | Meaning | Response |
|---|---|---|
| Branch already checked out | Another worktree owns that checkout. | Find it or make a new task branch; do not force by default. |
| Removal refuses dirty worktree | Tracked or untracked work is present. | Inspect, preserve, or explicitly discard it. |
| Prunable entry | Git cannot find a recorded path. | Preview prune; use repair if the path moved. |
| Worktree moved manually | Filesystem and Git metadata disagree. | Run git worktree repair at the new path. |
| Need different local config | Shared config may affect every checkout. | Learn extensions.worktreeConfig before using git config --worktree. |
The rule of thumb: inspect first, preserve commits, verify the target, then remove the clean worktree through Git.