Git Worktree Workflow (git-wt)

Overview

This skill provides a streamlined Git workflow using the bare repository pattern with the git-wt tool. Instead of stashing and switching branches, worktrees allow multiple branches to coexist simultaneously in separate directories while sharing a single git history.

Key Benefits:

• No more git stash context switching
• Parallel development on multiple features
• Isolated environments for AI agents
• Clean, organized workspace with branches as directories

Quick Start

Installation

The skill includes the git-wt script. Install it to your PATH:

# Copy to a directory in your PATH
cp /Users/mac/.claude/skills/git-wt/scripts/git-wt ~/.local/bin/
chmod +x ~/.local/bin/git-wt

# Or use the install helper
bash /Users/mac/.claude/skills/git-wt/scripts/install.sh

Requirements:

• Git 2.7+
• fzf (optional, for interactive commands)

Clone a New Repository

git wt clone https://github.com/user/repo.git
cd repo/main

This creates the bare structure:

repo/
├── .bare/          # All git data
├── .git            # Pointer to .bare
└── main/           # Worktree for main branch

Migrate Existing Repository

cd existing-repo
git wt migrate

Daily Workflow

Create a Worktree

Interactive mode (with fzf):

git wt add

Direct mode:

# From remote branch
git wt add feature-auth origin/feature-auth

# Create new branch
git wt add -b my-feature my-feature

Switch Between Worktrees

# Interactive picker
cd $(git wt switch)

# Or add a shell function to .bashrc/.zshrc:
wt() {
    local dir
    dir=$(git wt switch)
    [[ -n "$dir" ]] && cd "$dir"
}

Remove Worktrees

# Remove worktree and local branch
git wt remove feature-branch

# Remove worktree, local AND remote branch (destructive)
git wt destroy old-experiment

# Dry run to preview what would be removed
git wt remove --dry-run

Update Repository

# Fetch all remotes and fast-forward default branch
git wt update

Commands Reference

See references/commands.md for detailed command documentation.

Best Practices

1. Keep main/ pristine - Never work directly in it. Use as clean reference for diffing.
2. Name worktrees after branches - Directory = branch = no confusion.
3. Limit active worktrees - 2-3 is ideal. Each is a full checkout.
4. Project-level config - Store .claude/, .cursor/, .env at project root (outside worktrees).

AI Agent Workflow

Worktrees are ideal for AI coding agents:

# You're working on feature-A
cd ~/project/feature-A

# Spin up worktree for agent
git wt add -b agent-refactor ../agent-refactor

# Agent works independently
# You keep working uninterrupted

# Review agent's work
git diff main...agent-refactor

The Bare Repo Pattern

See references/bare-repo-pattern.md for detailed explanation.

Structure:

my-project/
├── .bare/            # All git data (bare repository)
├── .git              # File pointing to .bare
├── main/             # Worktree: main branch
└── feature/          # Worktree: feature branch

Why it works:

• Single .bare/ directory for all git data
• Worktrees are subdirectories (organized)
• Delete the folder = everything gone (no orphans)
• Project-level configs outside version control

Troubleshooting

"git wt: command not found"

• Ensure git-wt is in your PATH
• Try: ~/.local/bin/git-wt --help

Worktree already exists

• Use git wt remove <name> first
• Or choose a different name

No upstream configured

• git wt add sets upstream automatically
• Manual fix: git branch --set-upstream-to=origin/<branch>

Resources

• Bare Repo Pattern - Detailed pattern explanation
• Commands Reference - Full command documentation
• Original Tool - GitHub repository