Git Worktree Skill
Git worktrees let you check out multiple branches of the same repository into
separate directories simultaneously. Each directory is a fully independent
working tree — its own HEAD, index, and files — but all share the same .git
history and objects, so they stay lightweight.
Use this skill to give each agent or parallel task its own isolated workspace.
When to reach for worktrees
- Two or more agents might edit the same files simultaneously
- A task should not disturb the current branch's working state
- You need a throwaway sandbox that can be discarded cleanly if things go wrong
- The user asks to work on multiple features or fixes in parallel
- You want to run tests on one branch while editing another
Core commands
Create a worktree
# New branch from current HEAD
git worktree add ../my-task -b my-task-branch
# From a specific commit or existing branch
git worktree add ../hotfix -b hotfix origin/main
# Detached HEAD (no branch)
git worktree add --detach ../scratch HEAD
# Empty worktree on an unborn branch (blank slate)
git worktree add --orphan ../experiment -b experiment
The new directory is ready to use immediately. cd into it and work normally.
List all worktrees
git worktree list
# /path/to/main abc1234 [main]
# /path/to/my-task def5678 [my-task-branch]
Remove a worktree when done
# Clean remove (fails if the worktree has uncommitted changes)
git worktree remove ../my-task
# Force remove (discard dirty worktree)
git worktree remove --force ../my-task
# If you deleted the directory manually, clean up the metadata
git worktree prune
Move a worktree
git worktree move ../my-task ../new-location
Lock / unlock (for portable drives or network shares)
git worktree lock ../my-task --reason "on external drive"
git worktree unlock ../my-task
Repair after a manual move
# Run inside the moved worktree
git worktree repair
# Or from main, pointing at each moved worktree
git worktree repair ../new-location-1 ../new-location-2
Recommended layout for agents
Place worktrees as siblings of the main repo directory so paths stay
predictable and .gitignore patterns do not need updating:
projects/
my-app/ ← main repo (agents work here by default)
my-app-task-a/ ← worktree for task A
my-app-task-b/ ← worktree for task B
Create them from the main repo root:
git worktree add ../my-app-task-a -b task-a
git worktree add ../my-app-task-b -b task-b
Agent workflow
- Create a worktree on a fresh branch before starting work.
- Work entirely inside that directory — treat it like a normal repo.
- Commit as usual; history is shared with the main repo.
- Verify the result (tests, review, etc.).
- Merge or PR the branch back via standard git workflow.
- Remove the worktree once done.
# Step 1 — set up
git worktree add ../my-app-fix-login -b fix-login
# Step 2 — work
cd ../my-app-fix-login
# ... make changes ...
# Step 3 — commit
git add -A && git commit -m "fix: resolve login redirect loop"
# Step 4 — back in main repo, merge
cd ../my-app
git merge fix-login
# Step 5 — clean up
git worktree remove ../my-app-fix-login
git branch -d fix-login
Safety rules
- One branch per worktree. Git prevents the same branch from being checked
out in two worktrees at once. Use separate branch names for each worktree.
- Do not share an index. Never point two worktrees at the same directory.
- Avoid submodules in moved worktrees.
git worktree move cannot move a
worktree that contains submodules; handle those manually.
- Discard freely. If a worktree session goes wrong,
git worktree remove --force discards it entirely with no impact on other branches.
- Prune stale metadata. After manually deleting a worktree directory, run
git worktree prune in the main repo to remove orphaned administrative
files.
Troubleshooting
| Symptom | Fix |
|---|
fatal: '<branch>' is already checked out | Use a different branch name, or check git worktree list |
Worktree directory deleted but git worktree list still shows it | Run git worktree prune |
| Moved worktree can no longer find the repo | Run git worktree repair inside the moved directory |
| Locked worktree blocks removal | git worktree unlock <path> then remove |
| Changes in worktree not visible in main | Changes are per-worktree until committed and merged |