gh-worktree

A CLI tool that helps you manage Git worktrees. Built as a GitHub CLI (gh) extension, but works standalone.

Dependencies: git, gh

Table of Contents

• Quick Start
• Capabilities
• How It Works
  • Directory Structure
  • Hooks
  • Templates
• Commands
  • init
  • create
  • checkout
  • remove
  • install
  • version
• Installation
• AI Disclosure
• License

Quick Start

pip install gh-worktree

Or with uv:

uvx gh-worktree

Or download the PEX file from the releases page.

See recipes for hooks and templates.

Capabilities

How It Works

Directory Structure

After initializing a repository (e.g., gh-worktree):

gh-worktree/
  .bare/                 # Bare git repository
  .git                   # Points to .bare/
  .gh/
    worktree/
      hooks/             # Project-level hooks
      templates/         # Project-level templates
      config.json        # Project configuration
  my-new-worktree/       # Created worktrees
    README.md
    ...

Hooks

Hooks are executable scripts that run at specific lifecycle points. They can be configured at:

• Global level: ~/.gh/worktree/hooks/ (or parent directories outside the project)
• Project level: .gh/worktree/hooks/ (copied from repo on init if present)

Execution order: global hooks first, then project hooks.

Hooks must be executable and allowed (via checksum validation) to run.

#!/usr/bin/env bash

WORKTREE_NAME="$1"            # Full worktree name
BASE_REF="$2"                 # Format: remote/branch
WORKTREE_NAME_NORMALIZED="$3" # Worktree name with non-alphanumeric characters replaced by dashes

pushd "$WORKTREE_NAME"

uv venv
uv sync --group dev
prek install -f

popd

Templates

Files in .gh/worktree/templates/ are copied to new worktrees before post-hooks execute.

Tip: Add template files to .gitignore.

Templates support environment variable substitution using ${ENVVAR_NAME} syntax. Allowlist variable names in ~/.gh/worktree/config.json under allowed_envvars.

Provided variables:

${REPO_NAME}.${WORKTREE_NAME_NORMALIZED}

Commands

Run gh-worktree without any arguments for usage information.

Installation

Tested on Linux. Requires Python 3.10+ for PEX.

As a GitHub CLI extension (gh)

1. Download the latest release binary.
2. Make executable: chmod +x gh-worktree
3. Install: ./gh-worktree install --gh-ext
4. Test: gh worktree

Standalone

1. Download the latest release binary or PEX.
2. Make executable: chmod +x gh-worktree*
3. Install: ./gh-worktree install --path-bin or ./gh-worktree.pex install --path-bin
4. Test: gh-worktree version

Aliasing

./gh-worktree install --alias=wktr --path-bin
wktr version

From source

git clone https://github.com/bjester/gh-worktree.git
cd gh-worktree
uv venv
source .venv/bin/activate
uv sync --group dev
make dist/gh-worktree
./dist/gh-worktree install --path-bin

AI Disclosure

LLMs were used in the development of this project, mostly for brainstorming and bootstrapping code, particularly tests. The contribution proportion is roughly 80 / 20, human and AI code respectively. This may change over time as I try out agents!

License

MIT :: Copyright 2026 Blaine Jester