Git Worktrees

This skill follows engineering-doctrine.

Core Model

• One branch == one directory == one line of work
• All worktrees share a single .git database
• Each worktree is bound to its branch while it exists

Preferred Tooling

Use git wt (https://github.com/k1LoW/git-wt) as the default interface. It wraps git worktree with safer defaults and faster workflows.

Standard Setup

Optional, if you want worktrees stored in .worktrees:

mkdir -p .worktrees
git config wt.basedir .worktrees

Quick Start

git wt                       # list worktrees
git wt <branch|worktree>     # switch/create (creates branch and worktree if needed)
git wt --nocd <branch|worktree>
git wt -d <branch|worktree>  # safe delete (worktree + branch)
git wt -D <branch|worktree>  # force delete

Configuration

Use git config for defaults; override with flags when needed.

• wt.basedir / --basedir: base directory for worktrees (default ../{gitroot}-wt)
• wt.copyignored / --copyignored: copy gitignored files on create
• wt.copyuntracked / --copyuntracked: copy untracked files on create
• wt.copymodified / --copymodified: copy modified tracked files on create
• wt.nocopy / --nocopy: exclude files from copying (gitignore syntax)
• wt.copy / --copy: always copy specific patterns even if ignored
• wt.hook / --hook: run commands after creating a new worktree
• wt.nocd / --nocd: prevent automatic directory switching

Shell Integration (PowerShell)

Invoke-Expression (git wt --init powershell | Out-String)

Cleanup

always check if there are uncommitted changes in a worktree before

• removing its branch
• deleting the local worktree folder

Use git wt -d <branch|worktree> for clean removals. If a worktree folder was deleted manually, run git worktree prune. Ask user what to do with those uncommitted changes.