Git Worktrees

Git Worktrees

Overview

Git worktrees create isolated workspaces that share a repository while keeping separate checkouts.

Core principle: Systematic directory selection + safety verification = reliable isolation.

Use commands that fit the current shell and platform. For concrete examples, see references/powershell.md for PowerShell and references/posix.md for POSIX shells.

Workflow

1. Announce intent

State that you are setting up an isolated workspace with git worktrees.

2. Inspect existing conventions

Follow this priority order:

• Prefer an existing .worktrees/ directory.
• Otherwise prefer an existing worktrees/ directory.
• Otherwise check repository guidance such as CLAUDE.md, AGENTS.md, or README.md for a preferred location.
• Ask the user only if the location is still ambiguous.

3. Verify safety for project-local directories

For .worktrees/ or worktrees/, verify the directory is ignored before creating anything.

• Use git check-ignore instead of guessing.
• If the directory is not ignored, add an appropriate ignore rule before creating the worktree.
• If adding the ignore rule would create a visible repository change, call that out before committing it.

4. Create the worktree

Choose a path under the selected location and create the worktree on a branch that matches the task.

• Use git worktree add <path> -b <branch> when creating a new branch.
• If the branch already exists, create the worktree without -b.
• Change into the new worktree before running setup commands.

5. Prepare the project

Auto-detect the project tooling from files in the worktree.

• Install dependencies only when the repo uses a package manager that requires it.
• Run lightweight setup commands that establish a clean baseline.
• Avoid hardcoding package managers or shells when the repo indicates something else.
• Common signals: package.json or a Node lockfile (npm/yarn/pnpm install), Cargo.toml (cargo build), pyproject.toml or requirements.txt (pip/poetry install), go.mod (go mod download).
• Use the repository's existing scripts when available instead of inventing your own.

6. Verify the baseline

If the project has tests or an obvious smoke-check, run the appropriate baseline check before implementation.

• If checks fail, stop and ask whether to proceed with a dirty baseline.
• If checks pass, report the workspace as ready.

7. Report outcome

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement <feature-name>

Quick Reference

Common Mistakes

Skipping ignore verification

• Problem: Worktree contents get tracked, pollute git status
• Fix: Always use git check-ignore before creating a project-local worktree

Assuming directory location

• Problem: Creates inconsistency, violates project conventions
• Fix: Follow priority: existing directory > repo guidance > ask

Proceeding with failing tests

• Problem: Can't distinguish new bugs from pre-existing issues
• Fix: Report failures, get explicit permission to proceed

Hardcoding setup commands

• Problem: Breaks on projects using different tools
• Fix: Auto-detect from project files and existing scripts

Assuming a POSIX shell

• Problem: Commands fail in PowerShell or other environments
• Fix: Use the active shell, and consult references/powershell.md or references/posix.md for shell-specific examples

Example Workflow

You: I'm using the use-git-worktrees skill to set up an isolated workspace.

[Check .worktrees/ - exists]
[Verify ignored - git check-ignore confirms .worktrees/ is ignored]
[Create worktree: git worktree add .worktrees/auth -b feature/auth]
[Run project setup]
[Run baseline checks - passing]

Worktree ready at <full-path>
Tests passing (<N> tests, 0 failures)
Ready to implement auth feature

Red Flags

Never:

• Create a worktree without verifying it is ignored when using a project-local directory
• Skip baseline verification when the repo has tests or a smoke-check
• Proceed with failing baseline checks without asking
• Assume directory location when it is ambiguous
• Assume shell-specific commands will work everywhere

Always:

• Follow directory priority: existing directory > repo guidance > ask
• Verify directory is ignored for project-local locations
• Auto-detect and run project setup
• Verify a clean baseline before implementation