git-worktrees
Use when starting feature work that needs isolation from the current workspace, before executing an implementation plan, or when creating, listing, merging, or cleaning up git worktrees. Covers direct
SKILL.mdclaude/git-worktrees/SKILL.md
GitHubGit Worktrees
Worktrees create isolated workspaces that share one repository, so you can work on several branches at once without switching. This skill covers the full lifecycle: choose a location → create → set up and verify → merge back → tear down.
Core principle: systematic directory selection + safety verification = reliable isolation.
1. Choose the worktree directory
Follow this priority order. Do not assume a location.
ls -d .worktrees 2>/dev/null # preferred (hidden, project-local)
ls -d worktrees 2>/dev/null # alternative
- An existing directory wins. If both exist, use
.worktrees/. - Otherwise check the project's agent instructions:
grep -i "worktree.*director" CLAUDE.md 2>/dev/null— if a preference is stated, use it without asking. - Otherwise ask, offering both conventions:
.worktrees/— project-local and hidden- a sibling
../<repo>_worktrees/— keeps the repo directory clean
Resolve the sibling path with:
REPO_ROOT="$(git rev-parse --show-toplevel)"
REPO_NAME="$(basename "$REPO_ROOT")"
WT_BASE="$(dirname "$REPO_ROOT")/${REPO_NAME}_worktrees"
2. Verify safety before creating
For a project-local directory (.worktrees/ or worktrees/), confirm it is ignored first:
git check-ignore -q .worktrees 2>/dev/null || git check-ignore -q worktrees 2>/dev/null
If it is not ignored: add it to .gitignore and commit that change before proceeding.
Otherwise worktree contents get tracked and pollute git status.
A sibling directory outside the repo needs no such check.
3. Create the worktree
# New branch
git worktree add "<path>/<name>" -b "<branch>" main
# Existing branch
git worktree add "<path>/<name>" "<branch>"
A wt/<name> branch prefix keeps worktree branches easy to spot, though any convention works as
long as the project is consistent.
4. Set up and verify a clean baseline
Auto-detect the project type rather than hardcoding commands:
[ -f package.json ] && npm install
[ -f Cargo.toml ] && cargo build
[ -f pyproject.toml ] && uv sync
[ -f requirements.txt ] && pip install -r requirements.txt
[ -f go.mod ] && go mod download
Then run the project's test command. If tests fail, report the failures and ask whether to proceed — a dirty baseline makes new bugs indistinguishable from pre-existing ones. If they pass, report the path, the test count, and that the worktree is ready.
5. Merge back to main
git checkout main
git merge <branch> --no-edit
On conflicts: read both sides and keep all non-overlapping changes. Where two branches touched different sections of the same document, combine both sides rather than picking one.
After merging, either tear down (below) or reset the worktree to keep working in it:
git -C "<path>/<name>" reset --hard main
6. List and tear down
git worktree list
Use scripts/wt_cleanup.sh — the manual sequence is error-prone (stale directories, leftover
metadata, force-removal needed for untracked files):
bash scripts/wt_cleanup.sh <name> # keep the branch
bash scripts/wt_cleanup.sh <name> --delete-branch # after a merge
Manual equivalent:
git worktree remove --force "<path>/<name>"— force is needed if untracked files existrm -rf "<path>/<name>"if a stale directory remainsgit worktree prunegit branch -D <branch>— only if merged
Optional: paired terminal sessions
If your setup uses a terminal multiplexer, pairing each worktree with a session keeps parallel work
navigable. With tmx2 and a ge_<name> session prefix:
tmx2 new-session -d -s "ge_<name>" -c "<path>/<name>" # create, alongside step 3
tmx2 ls # list sessions
tmx2 kill-session -t "ge_<name>" # kill, before step 6
Cross-reference git worktree list against tmx2 ls to spot orphaned sessions (session alive,
worktree gone) and unpaired worktrees. Adapt to tmux/screen as needed — this section is a
convenience, not part of the core lifecycle.
Common pitfalls
| Problem | Cause | Fix |
|---|---|---|
already exists on worktree add |
Stale directory from a previous removal | rm -rf the directory, git worktree prune, retry |
branch already exists on -b |
Branch survived cleanup | git branch -D <branch>, retry |
contains modified or untracked files |
Normal — worktrees accumulate artifacts | Use --force on git worktree remove |
Worktree contents show in git status |
Directory was never gitignored | Add to .gitignore and commit; see step 2 |
| Can't tell new bugs from old | Skipped the baseline test run | Always verify a clean baseline in step 4 |
| Session dies after worktree removal | Removing the directory kills the session's cwd | Recreate the session, or kill it first |
Red flags
Never create a project-local worktree without verifying it is ignored, skip the baseline test run, proceed past failing tests without asking, or assume a directory location when it is ambiguous.
Integration
| Skill | Relationship |
|---|---|
executing-plans, subagent-driven-development |
The work that happens inside the worktree |
finishing-a-development-branch |
Completes the work before teardown |
writing-plans |
Produces the plan the worktree isolates work for |