worktree-util

Worktree Util

A simple TUI (Terminal User Interface) for managing Git worktrees, built with Go and Bubble Tea.

Features

• 📋 List all git worktrees in your repository
• ➕ Add new worktrees with custom branches (auto-organized in .worktrees/ folder)
• 🗑️ Remove worktrees safely
• 🎨 Beautiful terminal interface with keyboard navigation
• ⚠️ Smart error handling with helpful messages
• 🚀 Simple workflow - just enter a branch name, path is auto-generated

Installation

Homebrew (macOS/Linux)

brew install abtris/tap/worktree-util

Download Binary

Download the latest release for your platform from the releases page.

Build from Source

git clone https://github.com/abtris/worktree-util.git
cd worktree-util
go build -o worktree-util

Usage

TUI Mode

Run the tool from within a git repository to start the interactive TUI:

./worktree-util

CLI Commands

Manage configuration from the command line:

# Show current configuration
worktree-util config

# Initialize config file with defaults
worktree-util config init

# Set configuration values
worktree-util config set worktree_dir my-worktrees

# Get configuration values
worktree-util config get worktree_dir

# Add files to copy to new worktrees
worktree-util config add-copy-file .env
worktree-util config add-copy-file .env.local

# Remove files from copy list
worktree-util config remove-copy-file .env

# Show help
worktree-util --help

# Show version
worktree-util --version

Keyboard Shortcuts

List View

• a - Add a new worktree
• d - Delete selected worktree
• r - Refresh the list
• ↑/↓ - Navigate through worktrees
• q - Quit

Add Worktree View

• Enter - Create the worktree
• Esc - Cancel and return to list

Delete Confirmation

• y - Confirm deletion
• n or Esc - Cancel deletion

Requirements

• Go 1.21 or higher
• Git installed and available in PATH
• Must be run from within a git repository

How It Works

The tool uses git worktree commands under the hood:

• git worktree list --porcelain - to list worktrees
• git worktree add - to create new worktrees
• git worktree remove - to delete worktrees

Auto-Generated Paths

When you create a new worktree, you only need to provide the branch name. The tool automatically:

1. Creates a .worktrees/ directory in your repository root (if it doesn't exist)
2. Sanitizes the branch name (e.g., feature/new-feature → feature-new-feature)
3. Creates the worktree at .worktrees/<sanitized-branch-name>

This keeps all your worktrees organized in one place!

Configuration

Worktree Util supports optional configuration via ~/.config/worktree-util/config.yml.

Creating a Configuration File

1. Create the config directory:

   mkdir -p ~/.config/worktree-util
   

2. Create ~/.config/worktree-util/config.yml:

   # Directory where worktrees will be created (relative to repo root)
   worktree_dir: .worktrees
   
   # Files to copy from repo root to new worktrees
   copy_files:
     - .env
     - .env.local
   

Configuration Options

• worktree_dir: Directory where worktrees will be created (relative to repository root)

  • Default: .worktrees
  • Examples:
    • .worktrees - Creates worktrees in .worktrees/ folder
    • worktrees - Creates worktrees in worktrees/ folder
    • ../my-worktrees - Creates worktrees outside the repository

• copy_files: List of files to copy from repository root to new worktrees

  • Default: [] (no files copied)
  • Useful for files in .gitignore that are needed for development (e.g., .env files)
  • Files that don't exist will be silently skipped
  • Supports nested paths (e.g., config/local.yml)
  • Examples:

    copy_files:
      - .env
      - .env.local
      - config/local.yml
    

See config.example.yml for a complete example.

Note: Configuration is completely optional. If no config file exists, the tool uses sensible defaults.

Example Workflow

1. Run ./worktree-util in your git repository
2. Press a to add a new worktree
3. Enter the branch name (e.g., feature/new-feature)
4. Watch the path auto-generate (e.g., .worktrees/feature-new-feature)
5. Press Enter to create
6. The new worktree will appear in the list

Your worktrees will be organized like this:

my-repo/
├── .git/
├── .worktrees/
│   ├── feature-new-feature/
│   ├── bugfix-123/
│   └── experiment-api/
├── src/
└── README.md

License

MIT

worktree-util