Git worktree

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

1. Create a worktree on a fresh branch before starting work.
2. Work entirely inside that directory — treat it like a normal repo.
3. Commit as usual; history is shared with the main repo.
4. Verify the result (tests, review, etc.).
5. Merge or PR the branch back via standard git workflow.
6. 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