git-wt

A fast, reliable CLI tool for managing git worktrees with enhanced features like automatic setup, configuration copying, and interactive navigation.

Website: git-wt.paulie.app

Features

• Create worktrees with automatic branch creation and configuration copying
• Remove worktrees safely with multi-select support and branch cleanup
• Navigate between worktrees interactively with smart sorting
• List all worktrees with details or machine-readable format
• Clean deleted branches automatically remove worktrees for branches deleted from remote
• Configuration file support with user-level and project-level config files
• Generate shell aliases for seamless directory navigation
• Support for complex branch names with slashes and special characters
• Built with Zig for performance and zero runtime dependencies

Quick Start

Installation

Download pre-built binary from Releases or build from source:

# Download (macOS/Linux)
curl -L https://github.com/shhac/git-wt/releases/latest/download/git-wt-macos-universal.tar.gz | tar xz
mv git-wt ~/.local/bin/

# Build from source (requires Zig 0.15.1+)
git clone https://github.com/shhac/git-wt.git && cd git-wt
zig build -Doptimize=ReleaseFast
cp zig-out/bin/git-wt ~/.local/bin/

Requirements: Git (Zig only needed for building from source) Platforms: macOS (Universal/x86_64/ARM64), Linux (x86_64/ARM64), Windows (via WSL2)

Shell Integration Setup

# Add to your shell configuration (.zshrc, .bashrc, etc.)
echo 'eval "$(git-wt alias gwt)"' >> ~/.zshrc
source ~/.zshrc

Now use gwt for commands that change directories.

Basic Usage

# Create a new worktree
gwt new feature-branch

# Navigate between worktrees (interactive)
gwt go

# Remove worktrees (supports multi-select)
gwt rm

# List all worktrees  
git-wt list

Commands

Command	Description	Example
new <branch>	Create new worktree with branch	gwt new feature/auth
rm [branch...]	Remove worktree(s), interactive if no args	gwt rm old-feature
go [branch]	Navigate to worktree, interactive if no args	gwt go main
list	List all worktrees with details	git-wt list --plain
clean	Remove worktrees for deleted branches	git-wt clean --dry-run
alias <name>	Generate shell function for directory navigation	git-wt alias gwt

Interactive Features

• Arrow key navigation (↑/↓) with automatic fallback to number selection
• Multi-select removal: Use Space to toggle [*]/[ ], Enter to confirm
• Smart sorting: Worktrees sorted by modification time (most recent first)
• Terminal resize handling and graceful interrupt handling

Documentation

• Installation Guide - Detailed build and install instructions
• Usage Guide - Complete command reference and examples
• Configuration - Config file setup and options
• Shell Integration - Setup and troubleshooting shell aliases
• Testing - Running tests and development workflows
• Advanced Features - Configuration copying, locking, performance
• Troubleshooting - Common issues and solutions
• Design Principles - Architecture and development guidelines

How It Works

Creates worktrees in parallel directory structure:

my-repo/              # Main repository  
my-repo-trees/        # Worktrees directory
├── feature-a/
├── feature-b/
└── feature/
    ├── auth/         # Supports branch names with slashes
    └── ui/

• Configuration syncing: Automatically copies .env*, .claude, CLAUDE.local.md, .ai-cache
• Safety by default: Confirmation prompts, uncommitted changes detection, concurrent operation locking
• Shell integration: Uses a configurable file descriptor (fd3 by default) to enable directory changes from CLI

Contributing

1. Fork the repository
2. Create your feature branch (git-wt new my-feature)
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

Please ensure all tests pass (zig build test) and follow existing code patterns.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Built with Zig for performance and reliability
• Inspired by the need for better git worktree management workflows