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