alexei-led/using-git-worktrees

<!-- generated by scripts/build/generate-skills.py — edits to this file will be overwritten by `make build`. Edit the canonical SKILL.md (or add a SKILL.codex.md / SKILL.pi.md sidecar to diverge). --> <!-- Pi platform guidance --> <!-- Use Pi tool names exactly: read, bash, edit, write, ask_user_question, structured_output, todo, Agent, get_subagent_result, steer_subagent, web_search, web_answer, web_research. --> <!-- Use Agent, get_subagent_result, and steer_subagent for delegated work. --> <!-- Use ctx7 or npx ctx7@latest through bash when Context7 documentation lookup is required. -->

Git Worktrees

Core Principle

Main repo stays on main/master — never edit directly. Every branch gets its own worktree (a sibling folder). Delete the worktree after the branch merges.

Think of a worktree as a disposable branch folder, not a long-lived parallel environment.

Exception: Trivial one-liner commits on a solo project can go directly on main to avoid ceremony overhead.

Workflow

Check repo state before creating a worktree. Any worktree workflow description must name this dirty-state check before 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 create the new worktree anyway before proceeding. Confirm before running cleanup commands that remove worktrees or delete branches.

# 1. Create worktree for new work (from main repo)
git worktree add ../myproject-fix-cron -b fix-cron

# 2. Work there (open editor/Claude Code in that folder)
cd ../myproject-fix-cron

# 3. After PR is merged — confirm cleanup, then run from main repo
cd ../myproject
git worktree remove ../myproject-fix-cron
git branch -d fix-cron
git pull

Directory Layout

Worktrees are sibling directories (not nested inside the repo):

~/projects/
├── myproject/                    # main worktree — always on main, always clean
├── myproject-fix-cron/           # worktree for fix-cron branch
└── myproject-add-model/          # worktree for add-model branch

Why siblings: no .gitignore pollution, clean git status, independent build artifacts.

Naming Convention

<project>-<branch-slug> — slashes become dashes, self-documenting.

| Branch | Worktree Directory | | ------------------ | --------------------------- | | fix-cron | ../myproject-fix-cron | | feature/auth | ../myproject-feature-auth | | bugfix/issue-123 | ../myproject-bugfix-123 |

When to Suggest Worktrees

• User wants to start a new feature, fix, or experiment
• User is about to edit code on main/master
• User wants to try multiple approaches to the same problem
• User has uncommitted changes and wants to start something else

References

• WORKFLOW.md - Detailed steps, project setup, common mistakes
• scripts/ - Helper script for automated setup