GitHub - jarredkenny/worktree-manager: Dead simple CLI for working with worktrees in a bare git repo - with hooks!

7 min read Original article ↗

Worktree Manager (wtm)

🌳 A fast, modern CLI tool for managing Git worktrees in bare repositories

Built with Bun TypeScript License: MIT

Worktree Manager simplifies Git worktree operations, making it easy to work with multiple branches simultaneously in bare repositories. Perfect for CI/CD environments, shared development servers, or anyone who wants to streamline their Git workflow.

✨ Features

  • 🚀 Lightning fast - Built with Bun for maximum performance
  • 🔒 Bare repository focused - Designed specifically for bare Git repositories
  • 🔄 Smart branch management - Automatic fetching and branch creation
  • 🪝 Hook system - Extensible post-creation hooks for automation
  • 📋 Clear output - Beautiful, informative command output
  • ⚡ Zero dependencies - Uses Bun's built-in shell capabilities
  • 🛡️ Safe operations - Comprehensive validation and error handling

📦 Installation

Prerequisites

  • Bun runtime (v1.0+)
  • Git repository configured as bare (git config core.bare true)
  • Git remotes configured (typically origin)

Install from npm

# Install globally with your preferred package manager
bun install -g @jx0/wtm

# or
pnpm add -g @jx0/wtm

# or
npm install -g @jx0/wtm

# or
yarn global add @jx0/wtm

# Verify installation
wtm help

Development Setup

For contributors who want to work on the source code:

# Clone the repository
git clone https://github.com/your-username/worktree-manager.git
cd worktree-manager

# Install dependencies
bun install

# Link for local development
bun link

# For development with auto-reload
bun run dev

🚀 Quick Start

# Navigate to your bare repository
cd /path/to/your/bare-repo.git

# Create a new worktree from main branch
# This spawns a new shell in the worktree directory
wtm create feature-auth --from main

# Work on your feature in the new shell...
# (edit files, make commits, etc.)

# Exit the shell when done
exit

# Back in the bare repository, list all worktrees
wtm list

# Clean up the worktree
wtm delete feature-auth

📖 Command Reference

wtm create <name> --from <base_branch>

Creates a new worktree with a new branch based on the specified base branch, then spawns a new shell in that worktree.

# Create worktree from main branch
wtm create feature-auth --from main

# Create hotfix from master
wtm create hotfix-123 --from master

# Create feature branch from another branch
wtm create review-pr --from feature-x

What it does:

  1. Validates you're in a bare repository
  2. Fetches the latest changes from the base branch
  3. Creates a new branch named <name>
  4. Creates a worktree directory at ./<name>
  5. Executes post_create hook if present
  6. Spawns a new shell session in the worktree directory

Important: This command starts a new shell in the worktree. When you're done working, use exit to return to your original shell in the bare repository.

wtm checkout <name>

Creates a worktree from an existing remote branch if it doesn't already exist locally.

# Create worktree from existing remote branch
wtm checkout existing-remote-branch

Behavior:

  • If worktree already exists: displays a success message (but does NOT change your shell's directory)
  • If worktree doesn't exist but remote branch exists: creates worktree from the remote branch
  • If neither exists: shows available worktrees and creation instructions

Important Note: Due to how shells work, this command cannot change your current shell's directory. To work in a worktree:

  • Use wtm create which spawns a new shell in the worktree, OR
  • Manually cd into the worktree directory after creation

This command is primarily useful for creating worktrees from existing remote branches without specifying a base branch.

wtm list

Displays all worktrees in a formatted table.

Output:

Worktrees:
────────────────────────────────────────────────────────────────────────────────
feature-auth                   [feature-auth]       a1b2c3d4e
main-work                      [main]              f5g6h7i8j
(bare)                         (bare)              k9l0m1n2o

wtm delete <name> [--force]

Removes a worktree and its associated files.

# Safe deletion (with confirmation if needed)
wtm delete feature-auth

# Force deletion (skips safety checks)
wtm delete old-feature --force

Safety features:

  • Cannot delete bare repository
  • Validates worktree exists before deletion
  • Force flag available for stuck worktrees

wtm help

Shows comprehensive help information including examples and features.

🪝 Hook System

Worktree Manager supports executable hooks that run automatically during worktree lifecycle events. Hooks are placed in the bare repository root and must be executable.

Available Hooks

post_create

Runs immediately after a worktree is created, with the working directory set to the new worktree.

Environment Variables:

  • $WORKTREE_DIR - Absolute path to the new worktree
  • $WORKTREE_NAME - Name of the worktree
  • $BASE_BRANCH - Branch the worktree was created from
  • $BARE_REPO_PATH - Path to the bare repository

Example post_create hook:

#!/bin/bash
# File: post_create (in bare repo root)

echo "🪝 Setting up new worktree: $WORKTREE_NAME"

# Install dependencies if package.json exists
if [ -f "package.json" ]; then
    echo "📦 Installing dependencies..."
    pnpm install --silent
fi

# Copy environment files from bare repo
if [ -f "$BARE_REPO_PATH/.env.example" ]; then
    echo "📄 Copying .env.example to .env"
    cp "$BARE_REPO_PATH/.env.example" ".env"
fi

# Copy configuration files
if [ -f "$BARE_REPO_PATH/.vscode/settings.json" ]; then
    mkdir -p .vscode
    cp "$BARE_REPO_PATH/.vscode/settings.json" ".vscode/"
fi

echo "✅ Worktree setup complete!"

Setup:

# Create the hook file in your bare repository
vim post_create

# Make it executable
chmod +x post_create

# Test by creating a new worktree
wtm create test-feature --from main

🏗️ Architecture

worktree-manager/
├── src/
│   ├── cli.ts           # Command parsing and routing
│   ├── worktree.ts      # Core worktree operations
│   └── hooks.ts         # Hook execution system
├── index.ts             # Main entry point
├── package.json         # Project configuration
└── README.md           # Documentation

Key Components:

  • WorktreeManager: Core class handling Git operations
  • HookManager: Executes lifecycle hooks with proper environment
  • CLI Parser: Robust argument parsing and command routing

🔧 Configuration

Worktree Manager works out of the box with standard bare repositories. No configuration files needed.

Repository Requirements:

# Must be a bare repository
git config core.bare true

# Should have remote configured
git remote -v
# origin  git@github.com:user/repo.git (fetch)
# origin  git@github.com:user/repo.git (push)

🎯 Use Cases

Development Server Workflows

Perfect for shared development servers where multiple developers work on different features:

# Developer 1
wtm create user-authentication --from main

# Developer 2
wtm create payment-integration --from main

# Code review
wtm create review-pr-123 --from feature-branch

CI/CD Environments

For automated build systems, you can use git worktree commands directly and use wtm for cleanup:

# Build script
git worktree add -b build-$BUILD_ID build-$BUILD_ID origin/$BRANCH_NAME
cd build-$BUILD_ID
# ... run build process ...
cd ..
wtm delete build-$BUILD_ID --force

Note: wtm create spawns an interactive shell, so it's not suitable for automated scripts. Use git's native worktree add command for CI/CD, and wtm delete for cleanup.

Feature Development

Streamline your feature development workflow:

# Start new feature (spawns new shell in worktree)
wtm create feature-dashboard --from main

# Work on feature in the new shell...
# (commits, testing, etc.)

# Exit when done
exit

# Back in bare repo, work on another feature if needed
wtm create hotfix-urgent --from main

# Work on hotfix...
exit

# Clean up when done
wtm delete feature-dashboard
wtm delete hotfix-urgent

🤝 Contributing

We welcome contributions! Please see our Contributing Guidelines for details.

Development

# Clone and setup
git clone https://github.com/your-username/worktree-manager.git
cd worktree-manager
bun install

# Run in development mode
bun run dev

# Build
bun run build

# Run tests (when available)
bun test

Project Structure

  • Keep core logic in src/worktree.ts
  • Add new commands in src/cli.ts
  • Hook system extensions go in src/hooks.ts
  • Follow existing TypeScript patterns

📝 License

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

🔗 Links

Made with ❤️ and Bun

Worktree Manager - Because managing Git worktrees shouldn't be a tree of problems 🌳