holocron/plugins/git/.apm/skills/git-worktrees/SKILL.md

name, description, metadata

name	description	metadata
git-worktrees	Manage Git worktrees to enable multi-branch parallel development across isolated directories. Use when the user needs to work on multiple branches simultaneously without stashing, switch between feature/hotfix/experimental work, or coordinate code reviews alongside ongoing development. Handles creation, listing, locking, moving, removal, pruning, and repair of worktrees. Provides structured results (paths, branches, lock status) for agent composition in git orchestration workflows. Do not use when only inspecting a single branch or when the user needs standard checkout/stash workflows.	category source_keys git git-scm-worktree-docs

Concept

A worktree lets you check out multiple branches simultaneously from one repository, each in its own directory. All worktrees share the same objects, config, and most refs (refs/). Each worktree has its own HEAD, index, and per-worktree metadata (ORIG_HEAD, MERGE_HEAD, refs/bisect/, refs/worktree/, refs/rewritten/) stored at $GIT_DIR/worktrees/<name>/. The main worktree (from git init/git clone) is exactly one per repo and cannot be removed; linked worktrees are the additional ones created via git worktree add.

Gotchas

• A branch can only be checked out in one worktree at a time. Attempting git worktree add for an already-checked-out branch fails unless you pass --force. Use --force only when intentional.
• Submodules are unsupported and block operations. Repos with submodules have incomplete worktree support. Worktrees containing submodules cannot be moved and require --force to remove.
• Never manually rm -rf a worktree directory. This leaves stale metadata in $GIT_DIR/worktrees/. Always use git worktree remove. If already deleted, run git worktree prune to clean up.
• Manual moves break bidirectional pointers. If a worktree directory is moved outside of git worktree move, run git worktree repair to fix connections.
• Force-flag escalation with locks. Removing or moving a locked worktree requires -ff (two flags), not just -f.
• Worktree identification is by full path, unique basename, or unique partial path. Ambiguous names error. Use git worktree list to see available identifiers.
• --lock on add is atomic; create-then-lock has a race window. Use --lock directly on git worktree add when consistency matters.
• extensions.worktreeConfig = true is a one-way door. It enables per-worktree config (git config --worktree ...) but makes the repo refuse to open in older Git versions. Once set, core.bare/core.worktree must live in config.worktree, not config. Don't enable it unless per-worktree config is actually needed.

Common Operations

Create and switch to a new worktree — default approach:

git worktree add -b <new-branch> <path>
cd <path>

This creates a new branch and checks it out in a new directory. Other branches cannot be checked out elsewhere simultaneously.

Create-or-reset a branch: git worktree add -B <branch> <path> — like -b but resets the branch to HEAD if it already exists.

Create a worktree for an existing remote branch:

git worktree add <path> <remote>/<branch>

For ambiguous names across remotes, disambiguate via checkout.defaultRemote config or --guess-remote. Full flag table and detail: references/worktrees.md.

Throwaway experiment in detached HEAD:

git worktree add -d ../experiment   # or --detach
# experiment freely, no branch created
git worktree remove ../experiment

List all worktrees with state:

git worktree list -v        # human-readable with lock/prune reasons
git worktree list --porcelain -z  # machine-readable, NUL-terminated

Move a worktree to a new path:

git worktree move <current-path> <new-path>
# Cannot move: main worktree, worktrees with submodules
# To override safeguards: -f; to override locked state too: -ff

Remove a worktree:

git worktree remove <path>        # only if clean
git worktree remove -f <path>     # force-remove unclean
git worktree remove -ff <path>    # force-remove even if locked

Prune stale metadata:

git worktree prune --dry-run        # preview what would be removed
git worktree prune                  # clean up orphaned metadata

Also triggered by git gc, controlled by gc.worktreePruneExpire config.

Repair broken connections (after a manual move):

git worktree repair  # from main worktree or after it was moved
git worktree repair <path>  # reconnect a specific linked worktree

Sparse-checkout worktrees, locking for removable media, the full add flag table, and the config key reference: references/worktrees.md.

Worked Examples

Emergency fix without disrupting current work — no stashing needed, ongoing work in the main worktree is untouched:

git worktree add -b emergency-fix ../temp main
cd ../temp
# fix, commit
git commit -a -m "fix: critical production bug"
cd -
git worktree remove ../temp

Review a PR branch alongside your current work — no context switch, both branches stay checked out:

git worktree add ../review-pr-123 origin/feature-xyz
# open ../review-pr-123 in a second editor window or terminal

Return Format for Agents

When invoking worktree operations, return structured results:

worktrees:
  - path: <directory-path>
    branch: <branch-name>
    commit: <short-hash>
    locked: <true/false>
    lock_reason: <reason or empty>
  - ...

Derive these fields from git worktree list --porcelain -z — its worktree/branch/HEAD/locked lines map directly to path/branch/commit/locked+lock_reason.

For single operations, include the operation result (e.g., created: true, removed: true, moved: true).

For multi-step flows spanning branch strategy plus worktree setup, compose with the git-workflow skill — it handles the broader orchestration, this skill handles the worktree mechanics.