using-git-worktrees

Using Git Worktrees

Adapted from the MIT-licensed superpowers plugin.

Gives work its own checkout and branch, isolated from whatever is checked out. No stashing or branch-juggling needed.

Workflow

1. Rule out a submodule first.

   git rev-parse --show-superproject-working-tree
   

   • A returned path means you're in a submodule.
   • Treat it as a normal checkout and skip to step 3.
   • Skip step 2's test — it cannot tell a submodule from a main checkout.

2. Detect existing isolation. Compare git-dir against git-common-dir:

   GIT_DIR=$(cd "$(git rev-parse --git-dir)" && pwd -P)
   GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" && pwd -P)
   

   • GIT_DIR != GIT_COMMON means you're already in a linked worktree — skip to step 4.
   • Inside a submodule the two match (verified at git 2.47.3).
   • Step 1 must run first — alone, this test reads a submodule as a normal checkout.

3. In a normal checkout, confirm before creating.

   • Ask whether an isolated worktree is wanted for this work.
   • If no, work in place and skip to step 4.
   • If yes, pick a directory:
     • Reuse .worktrees/ if it already exists at the project root.
     • Otherwise create .worktrees/ there (local-ignored, project-local).

   Ignore it without a commit, so an unattended run leaves no stray commit behind:

   git check-ignore -q .worktrees || echo ".worktrees/" >> "$(git rev-parse --git-common-dir)/info/exclude"
   

   Then create the worktree on a new branch:

   git worktree add .worktrees/<branch-name> -b <branch-name>
   cd .worktrees/<branch-name>
   

4. Work there.

   • Install dependencies and confirm a clean baseline (tests pass) before making changes.
   • That way, any later failure is attributable to the new work, not pre-existing breakage.

5. Remove it when finished.

   • Decide what happens to the branch first — see finish-branch for the merge/PR/keep/discard choice.
   • Then, from the main checkout: