thds.gent 1.3.20260501190810

Git worktree management utilities - tree shepherds for your working trees

wt (The Git Ent)

"We are tree-herds, we old Ents. Few enough of us are left. Sheep get like shepherds, and shepherds like sheep, it is said; but slowly, and neither have long in the world. It is quicker and closer with trees and Ents, and they walk down the ages together." — Treebeard, The Two Towers

Git worktree management utilities - tree shepherds for your working trees.

Why use gent? Git worktrees are powerful but awkward to use directly. gent makes worktrees simple by establishing a clear directory convention (worktrees, branches, and directories share the same name) and providing simple commands for common operations.

About Ents

In J.R.R. Tolkien's Middle-earth, Ents are ancient tree-like beings who serve as shepherds of the forest. Patient and deliberate, they tend to the trees under their care, moving between them with purpose, ensuring each grows strong in its place. They are protectors and caretakers, speaking the old languages, remembering what was and what must be preserved.

Like the Ents of old, gent watches over your worktrees—those parallel branches of your repository that grow and develop in their own spaces. Where once you might have stumbled through tangled paths, switching contexts with git checkout and losing your place, wt guides you between your working trees with the steady wisdom of Treebeard himself. Each worktree stands as its own realm, isolated yet connected to the greater forest of your repository. Gent knows them all by name, can walk you from one to another, and tends to their creation and removal with the careful deliberation of one who has seen many ages of growth. No longer must you uproot your current work to tend to another branch—simply walk between the trees, and let wt shepherd your path.

Getting Started

gent requires a bare repository structure where each branch is its own directory. wt clone sets this up automatically.

Quick start

# Install gent
pip install thds.gent
# or with uv:
uv tool install thds.gent

# Set up shell integration (tab completion, directory navigation)
wt setup-shell

# Open a new terminal (or source your shell RC), then clone any repo
wt clone [e-mail]:user/repo.git

Or as a one-liner without installing (requires uv):

uvx --from thds.gent wt clone [e-mail]:user/repo.git

Bootstrap (ds-monorepo first-timer)

Clone ds-monorepo with a bare worktree structure using uvx:

# 1. Clone with bare worktree structure
uvx --from thds.gent wt clone [e-mail]:TrilliantHealth/ds-monorepo.git ~/work/ds-monorepo

# 2. Install as editable from the real clone (so updates come with git pull)
cd ~/work/ds-monorepo/main/libs/gent && ./install.sh

Already have a regular clone?

Consider cloning fresh with wt clone and deleting the old clone. If you want to convert your existing repo in place, see BARE_SETUP.md.

Shell integration

Navigation commands (wt cd, wt co, wt root) need shell integration to change your working directory. Non-navigation commands (wt clone, wt list, wt rm, etc.) work without it.

wt setup-shell

This copies shell scripts to ~/.gent/, adds tab completion, and configures your shell RC file. Safe to re-run to update shell scripts after upgrading gent.

Working with worktrees

wt list                    # See all worktrees
wt co feature/new-thing    # Create a new branch/worktree (auto-runs init)
wt cd main                 # Switch to main
wt start                   # Open editor

After setup, your repository uses a bare structure where each branch is a separate directory:

my-project/
├── .bare/          # Git metadata
├── main/           # Main branch/worktree
├── feature/foo/    # Feature branch/worktree
└── release/v2/     # Release branch/worktree

Usage

Commands

wt clone <url> [dir]   # Clone a repository with worktree structure
wt list                # List all worktrees
wt co <branch> [base]  # Checkout existing or create new branch as worktree
wt cd <branch>         # Navigate to a worktree
wt init [branch]       # Initialize worktree environment (.gent/init script)
wt start [branch]      # Run start hook (e.g. open editor)
wt rm <branch>         # Remove worktree and optionally delete branch
wt root                # Navigate to repository root
wt path <branch>       # Output path to a worktree (for scripting)

How wt co works:

The wt co command is smart about whether to checkout existing or create new:

1. If branch exists locally → checkout as worktree
2. If branch exists on remote → checkout and track remote
3. Otherwise → create new branch from base (current worktree, main, or specified)

Common Workflows

Checkout existing branch:

wt co feature/existing          # Checkout existing branch (local or remote)

Start a new feature:

wt co feature/new-feature       # Create new from current worktree (or main)
wt co feature/new-feature main  # Create new from main explicitly
wt start                        # Open editor (optional)

wt co automatically runs .gent/init when creating a new worktree. Use wt start to launch your editor or other "ready to work" actions.

Switch between branches:

wt cd main              # Jump to main
wt cd feature/testing   # Jump to feature

Clean up:

wt rm feature/old-branch         # Remove worktree and branch
wt rm feature/draft --force      # Force remove with uncommitted changes

Shell Integration

Commands that change your shell's directory require special shell integration. The install script sets this up automatically for bash, zsh, and xonsh:

• wt cd <branch> - Navigate to a worktree
• wt co <branch> - Create/checkout a worktree and navigate to it
• wt root - Navigate to repository root

For scripting where you need paths without changing directory, use wt path <branch>.

Configuration

Hook Scripts

gent supports hook scripts in the .gent/ directory. Each hook is searched in precedence order:

1. <worktree>/.gent/<hook>.local — user, worktree-specific override
2. <bare-root>/.gent/<hook>.local — user, repo-specific override
3. <worktree>/.gent/<hook> — shared/team default

All hooks receive these environment variables:

• GENT_WORKTREE_PATH: Absolute path to the worktree
• GENT_BRANCH: Branch name

.gent/init — Worktree Initialization

Runs automatically when wt co creates a new worktree, and manually via wt init. Use this for dependency installation and other setup that every worktree needs.

.gent/start — Start Working

Runs manually via wt start. Use this for actions you want on demand but not on every checkout — e.g. opening an editor or IDE.

Example hook:

#!/usr/bin/env -S uv run --script
# /// script
# requires-python = ">=3.10"
# ///
import os
import subprocess
from pathlib import Path

worktree_path = Path(os.environ["GENT_WORKTREE_PATH"])
print(f"Initializing {os.environ['GENT_BRANCH']}")

subprocess.run(["npm", "install"], cwd=worktree_path, check=True)

Make hooks executable: chmod +x .gent/init

Troubleshooting

"Shell integration not active" warning

If you see this warning when running wt cd:

⚠️  Shell integration not active - directory was NOT changed.

Run wt setup-shell to configure it, then restart your shell or run source ~/.zshrc.

"Shell integration is outdated" warning

If you see this warning:

⚠️  wt shell integration is outdated (v1 → v2)

This means the Python package has been updated but the shell scripts in ~/.gent/ are from an older version. Re-run:

wt setup-shell

Developing

See docs/DEVELOPING.md for architecture details and contribution guidelines.

Uninstalling

# 1. Uninstall the tool
uv tool uninstall thds-gent

# 2. Remove shell integration
rm -rf ~/.gent

# 3. Remove from your shell RC file:
#    - ~/.zshrc or ~/.bashrc: delete the `[ -f ~/.gent/init.sh ] && source ...` line
#    - ~/.xonshrc: delete the `source ~/.gent/wt.xsh` block