git-wt

README

git-wt

A CLI for managing git worktrees with the bare repository workflow.

git-wt wraps git and gh to streamline worktree operations—cloning as bare repos, creating worktrees from branches or GitHub issues, and running post-create hooks.

Why Worktrees?

Problem	Solution
Context switching requires stashing	Each worktree is isolated
Can't run tests on main while developing	Parallel worktrees
Branch switching breaks IDE state	Each worktree is a separate directory

Install

# Homebrew
brew install raisedadead/tap/git-wt

# Go
go install github.com/raisedadead/git-wt/cmd/git-wt@latest

Requirements

• Git 2.20+
• GitHub CLI (gh) - optional, for GitHub issue/PR workflows
• zoxide (optional) - for quick worktree navigation

Quick Start

# Clone as bare repo with worktree structure
git wt clone owner/repo

# Create a feature worktree
git wt add --feature auth
# or
git wt add -f auth

# Create a bugfix linked to GitHub issue
git wt add --bugfix --issue 42

# Review a PR (uses actual PR branch for gh pr browse compatibility)
git wt add --pr-review 123

# Plain branch
git wt add my-experiment

# List worktrees
git wt list

# Clean up
git wt delete feature/auth
git wt prune

Quick Navigation with zoxide

Enable zoxide integration for instant worktree switching:

git wt hooks enable zoxide    # One-time setup

git wt add feature/auth       # Creates worktree
z auth                        # Jump to it instantly
z main                        # Jump back

Commands

Command	Description
clone <repo>	Clone as bare repo with initial worktree
add [branch]	Create worktree with workflow support (alias: new)
list	List worktrees
delete [branch]	Remove worktree and branch (interactive if no branch)
prune	Remove stale worktrees
config init	Create config file with documented defaults
config show	Show effective configuration with sources
hooks	Manage hooks (enable/disable/list)
completion	Print shell completion setup instructions

Workflow Flags (for add)

Flag	Description
--feature, -f	Feature workflow (branch: feat/{slug})
--bugfix, -b	Bugfix workflow (branch: fix/{slug})
--pr-review	PR review workflow (uses PR's head branch)
--issue <n>	Pass issue number to hooks
--pr <n>	Pass PR number to hooks
--workflow	Use custom workflow from config

Global Flags

Flag	Description
--json	Output in JSON format (for scripting/automation)

Common Flags

Flag	Commands	Description
--yes, -y	delete, prune	Skip confirmation prompt
--force, -f	delete, clone	Force operation
--dry-run	delete, prune	Show what would happen
--timeout	all	Override git operation timeout
--remote	add, prune	Override default remote

Passthrough Flags

Pass git flags after --:

git wt clone owner/repo -- --depth=1 --single-branch

Directory Structure

project/
├── .bare/          # Bare git repository
├── .git            # Pointer to .bare
├── main/           # Stable worktree
├── feature-auth/   # Feature worktree
└── issue-42/       # Issue worktree

Configuration

git-wt supports hierarchical configuration:

runtime flag > .git-wt.toml (repo) > ~/.config/git-wt/config.toml (global) > defaults

Create a config file with documented options:

git wt config init --global  # ~/.config/git-wt/config.toml
git wt config init           # .git-wt.toml in project root

View effective configuration:

git wt config show

Example config:

default_remote = "upstream"
default_base_branch = "develop"
branch_template = "{{type}}-{{number}}-{{slug}}"
hook_timeout = 30

[hooks]
post_clone = ["zoxide add $GIT_WT_PATH"]
post_add = ["direnv allow"]

See Configuration for all options.

Development

go build -v ./...      # Build
go test -v ./...       # Run tests
go vet ./...           # Static analysis
golangci-lint run      # Lint

Documentation

• Architecture - Design goals and internals
• Configuration - Config options and hooks
• Hooks Examples - Common hook recipes
• Contributing - Development setup
• Releasing - Release process

Links

• Git Worktrees Documentation - Official git worktree reference
• Bare Repo + Worktree Workflow - The workflow git-wt implements
• GitHub CLI - Required for issue/PR integration

License

MIT - see LICENSE