| description | Creates isolated git worktrees for parallel development. Use when starting feature work needing isolation or working on multiple branches simultaneously. NOT for simple branch switching, bulk branch cleanup (use cleanup-git), or git hook/config setup (use configuring-git-hygiene). |
| name | using-git-worktrees |
Git Worktrees
Use one sibling worktree root per project: <project>.worktrees/<branch-slug>. Keep the main worktree clean on the integration branch by default. Trivial solo one-liners may stay in the main worktree when a worktree would add pointless ceremony.
Treat a worktree as a disposable branch folder. Remove it and its branch after the PR merges.
Scope
Use this skill when:
- starting a feature, fix, or experiment that should not disturb current work
- working on multiple branches at once
- trying competing approaches
- the current worktree has uncommitted changes and the user wants to start something else
Do not use this skill for:
- simple branch switching with no parallel work
- bulk branch or stale worktree cleanup — use
cleanup-git
- git hook, Gitleaks,
.gitignore, or config setup — use configuring-git-hygiene
Create Workflow
Check state before any git worktree add:
git status --short
git branch --show-current
git worktree list
If the current worktree is dirty, ask whether to commit, stash, or proceed anyway. Do not stash silently.
Use the helper when available:
scripts/setup-worktree.sh <branch> [--base <ref>]
The helper creates <project>.worktrees/<branch-slug> from the main worktree root, handles existing local/remote branches, refuses path conflicts, and refuses dirty state unless --allow-dirty is passed after user approval.
Manual fallback lives in workflow.md.
Naming
- Root: sibling
<project>.worktrees/ directory.
- Directory: branch slug only; replace
/ with -.
- Examples:
fix-cron, feature-auth, bugfix-issue-123.
Cleanup Workflow
For one named worktree after PR merge:
scripts/cleanup-worktree.sh [branch]
The helper refuses unless gh confirms the PR is MERGED. Pass --force only after the user confirms the merge without gh or confirms the branch should be abandoned.
For bulk cleanup, stale worktrees, gone upstreams, or merged local branches, use cleanup-git.
Do not run git pull as part of cleanup. Pull the integration branch only after confirming the main worktree is checked out and clean.
Failure Handling
- Worktree path exists: pick a different branch/slug; never overwrite.
- Branch already exists remotely: check it out without
-b or use the helper.
- Dirty current worktree: ask to commit, stash, or continue with explicit approval.
git worktree remove fails because the worktree is dirty: confirm before --force.git branch -d fails after squash/rebase PR merge: confirm the PR is MERGED, then use -D.- Invoked from inside the worktree being removed: change to the main worktree before removing it.
Output
WORKTREE READY
==============
Action: CREATE | CLEANUP
Branch: <branch>
Path: <project>.worktrees/<slug>
Status: DONE | BLOCKED
Next:
- cd <path> and open the editor there, or
- pull the integration branch yourself after confirmed cleanup
For cleanup, report DONE only when the PR is confirmed MERGED or --force was used deliberately. Otherwise report BLOCKED with the script's reason.
References
- workflow.md — manual fallback and edge cases
- scripts/ —
setup-worktree.sh and cleanup-worktree.sh
