Git Worktree Workflows

Git Worktree Workflows

Master Git worktrees using the gw CLI tool for optimized parallel development workflows.

MANDATORY: Always Use gw, Never Raw git worktree

Non-negotiable in any repo where gw is installed. Check with which gw; if missing, suggest brew install mthines/gw-tools/gw or npm install -g @gw-tools/gw.

Rules

Workflow Patterns

Quick Reference

Primary Commands

Setup Commands

Proxy Commands (pass-through to git worktree)

Key Principles

• gw checkout is canonical. gw add and gw co are aliases — prefer gw checkout in explanations.
• One branch per worktree. Same branch cannot be checked out in two worktrees. gw checkout <existing> detects this and navigates instead.
• Remote probe before treating a branch as new. gw checkout runs git ls-remote (3s timeout) so a teammate's freshly-pushed branch isn't silently forked locally. Use --no-fetch when offline.
• Auto-copy beats manual copying. Configure autoCopyFiles once in gw init; .env, secrets, etc. land in every new worktree.
• Post-checkout hooks beat manual installs. Wire pnpm install / equivalent so each worktree is ready immediately.
• Shell integration is required for cd. Without eval "$(gw install-shell)" in ~/.zshrc, gw cd and auto-nav after gw checkout silently no-op.

Typical Worktree Workflow

# 1. First-time repo setup (one-time per project)
gw init git@github.com:org/repo.git \
  --auto-copy-files .env,.env.local \
  --post-checkout "pnpm install" \
  --interactive

# 2. Start a feature
gw checkout feat/my-feature
# - creates worktree, copies .env, runs pnpm install, auto-navigates

# 3. Work, then update with main
gw update

# 4. Open a PR for review (in another terminal / worktree)
gw pr 456
# - fetches PR branch, creates worktree, copies .env, auto-navigates

# 5. Navigate between worktrees
gw cd feat/my-feature
gw checkout main        # navigates to main worktree (already checked out)

# 6. Extract staged WIP to a new branch
git add src/new-thing.ts
gw checkout feat/extracted --from-staged

# 7. Clean up when done
gw remove feat/my-feature   # removes worktree + local branch
gw clean                    # batch remove safe (committed + pushed) worktrees
gw prune                    # full cleanup: worktrees + orphan branches

Config Reference

Config lives at .gw/config.json (committable) and .gw/config.local.json (gitignored, personal overrides):

{
  "defaultBranch": "main",
  "autoCopyFiles": [".env", ".env.local", "secrets/"],
  "hooks": {
    "checkout": {
      "pre": ["echo 'Creating: {worktree}'"],
      "post": ["pnpm install"],
    },
  },
  "cleanThreshold": 7, // days before worktrees are "stale" for gw clean
  "autoClean": true, // silently prune stale worktrees on gw checkout / gw list
  "updateStrategy": "merge", // "merge" | "rebase"
  "protectedBranches": ["staging"], // extra branches exempt from gw clean / auto-clean
}

Hook variables: {worktree}, {worktreePath}, {gitRoot}, {branch}.

Related Skills

• gw-config-management - Configure auto-copy files and hooks
• autonomous-workflow - Autonomous development in isolated worktrees (lives in mthines/agent-skills)

Resources

• Getting Started Example
• Parallel Development Example
• Troubleshooting Guide
• gw CLI Documentation