treefort

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
  • prune
  • install
  • version
• Installation
• AI Disclosure
• License

Quick Start

pip install treefort

Or with uv:

uvx treefort

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., treefort):

treefort/
  .bare/                 # Bare git repository
  .git                   # Points to .bare/
  .treefort/
    hooks/             # Project-level hooks
    templates/         # Project-level templates
    config.toml        # 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: ~/.treefort/hooks/ (or parent directories outside the project)
• Project level: .treefort/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. Treefort stores approved hook checksums in ~/.treefort/allowed_hooks.json.

#!/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 .treefort/templates/ are copied to new worktrees before post-hooks execute.

Tip: Add template files to .gitignore.

Templates support environment variable substitution with ${ENVVAR_NAME} syntax. Add allowed variable names to allowed_envvars in ~/.treefort/config.toml.

Provided variables:

${REPO_NAME}.${WORKTREE_NAME_NORMALIZED}

Commands

Run treefort 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 treefort
3. Install: ./treefort install --gh-ext
4. Test: gh treefort

Standalone

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

Aliasing

./treefort install --alias=wktr --path-bin
wktr version

From source

git clone https://github.com/bjester/treefort.git
cd treefort
uv sync --group dev
source .venv/bin/activate
make dist/treefort
./dist/treefort 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