git-worktree-management

name	git-worktree-management
description	Git worktree management best practices for git worktree, bare repo layouts, parallel branches, stale base sync, branch cleanup, wrong-path recovery, fork remotes, and PR review worktrees. Use when creating, moving, removing, repairing, listing, pruning, or troubleshooting Git worktrees.

Git Worktree Management

Goal: one branch, one folder. No branch switching in busy repos.

Default Layout

Prefer bare repo with sibling worktrees:

~/code/repo/
  .bare/
  main/
  feature-x/
  bugfix-y/

Why: parallel work, clean IDE indexes, no stash dance, fast hotfix/review folders.

Create Layout

mkdir -p ~/code/repo
git clone --bare [e-mail]:owner/repo.git ~/code/repo/.bare
git -C ~/code/repo/.bare config remote.origin.fetch '+refs/heads/*:refs/remotes/origin/*'
git -C ~/code/repo/.bare fetch origin
git -C ~/code/repo/.bare worktree add ~/code/repo/main origin/main

Use real default branch. Do not assume main:

gh repo view owner/repo --json defaultBranchRef --jq '.defaultBranchRef.name'

New Branch

Always sync base first:

git -C ~/code/repo/.bare fetch origin main:refs/remotes/origin/main
git -C ~/code/repo/.bare worktree add -b feature-x ~/code/repo/feature-x origin/main

Use absolute paths when an agent/script runs command. Relative paths with git -C .bare resolve relative to .bare, not shell cwd.

Wrong:

git -C .bare worktree add -b feature-x feature-x main

Right:

git -C ~/code/repo/.bare worktree add -b feature-x ~/code/repo/feature-x origin/main

Existing Branch Or PR Review

Existing branch:

git -C ~/code/repo/.bare fetch origin feature-x
git -C ~/code/repo/.bare worktree add ~/code/repo/feature-x origin/feature-x

Detached review worktree:

git -C ~/code/repo/.bare worktree add --detach ~/code/repo/review-pr origin/feature-x

Daily Safety

• Run git worktree list before adding/removing.
• Never use plain --force unless command explains why.
• Commit or discard work before removing worktree.
• Rebase on current base before merge/PR final check.
• Do not create worktrees under .bare/.

Before Merge

git fetch origin
git rebase origin/main
task ci

Replace task ci with repo check command. Real command must fail loud.

Cleanup

After PR merged:

git -C ~/code/repo/.bare worktree remove ~/code/repo/feature-x
git -C ~/code/repo/main branch -D feature-x
git -C ~/code/repo/main fetch --prune origin
git -C ~/code/repo/.bare worktree prune

If directory was deleted manually:

git -C ~/code/repo/.bare worktree prune

If worktree moved manually:

git -C ~/code/repo/.bare worktree repair ~/code/repo/new-path

Wrong-Path Recovery

If worktree got created inside .bare/:

git -C ~/code/repo/.bare worktree move ~/code/repo/.bare/feature-x ~/code/repo/feature-x

Use absolute source and dest.

Fork Remote Rule

When pushing to non-tracking remote, use explicit refspec:

git push fork HEAD:main

Do not trust:

git push fork main

It can be a silent no-op when local branch tracks origin/main.

Useful Commands

git worktree list --porcelain
git worktree remove <path>
git worktree prune
git worktree repair <path>
git -C <worktree> status -sb

Agent Rules

• Confirm cwd and target path before worktree ops.
• Prefer absolute paths.
• Fetch explicit base ref in bare layouts.
• Stop and ask before removing dirty worktree.
• Never edit installed skill/plugin cache paths by accident.