wtree

A CLI tool for managing git worktrees with powerful workflow automation, on both bare-hub and standard repositories.

Git worktrees let you work on multiple branches simultaneously in separate directories. wtree wraps git worktree with a lifecycle hook system that automates your workflow—install dependencies, copy environment files, run setup scripts—all triggered automatically when you create, switch, or remove worktrees.

It works in two layouts (see Layouts): the original bare-hub layout created by wt clone, and any standard cloned repository adopted with wt init.

Why wtree?

Workflow Automation via Hooks

Most worktree tools stop at git worktree add. wtree goes further with a two-phase hook system that automates your entire development workflow:

# .wtree/hooks.toml
[create]
post = [
"cp \"$WT_HUB_ROOT/main/.env\"\"$WT_WORKTREE_PATH/.env\"",
"npm install"
]

Every time you create a new worktree, your environment is automatically set up. Switch to an existing worktree? Dependencies are synced. No manual steps, no forgotten setup.

Installation

Cargo

cargo install wtree

Shell Setup

Add to your .bashrc or .zshrc:

# Basheval"$(wt shell-init bash)"# Zsheval"$(wt shell-init zsh)"

Breaking change in v0.7.0: the shell-integration command moved from wt init <shell> to wt shell-init <shell>. wt init (no shell argument) now adopts a standard repository (see Layouts). Update your .bashrc/.zshrc accordingly. The emitted shell function is otherwise unchanged.

Layouts

wtree detects your repository layout automatically and behaves identically across both.

Bare-hub layout. Created by wt clone <url>, which clones into <repo>/.bare and places each worktree as a sibling directory (<repo>/<name>). State and hooks live in <repo>/.wtree/. This is the original layout and is unchanged.

Standard layout. Any ordinary cloned repository. Adopt it with wt init from inside the repo. Worktrees are created under .claude/worktrees/<name>/ by default, state and hooks live in .git/wtree/, and the worktree directory is added to .gitignore automatically. wt create also lazily initializes a never-adopted standard repo on first use, so wt init is optional.

cd my-cloned-repo
wt init # adopt this repo (state dir, hooks template, gitignore entry)
wt create feature-x # creates .claude/worktrees/feature-x/

Override where standard-layout worktrees are created with a worktree_base entry in .git/wtree/config.toml (relative paths resolve against the repo root, absolute paths are used as-is):

# .git/wtree/config.tomlworktree_base = "../my-worktrees"

Usage

Command	Description
wt clone <url> [-switch]	Clone repo as bare with default branch worktree
wt init	Adopt the current standard repo for wtree
wt create <name> [--checkout branch] [--base worktree] [-s]	Create new worktree (alias: c)
wt switch <name>	Switch to worktree (alias: sw)
wt list	List all worktrees (alias: ls)
wt remove <name>...	Remove one or more worktrees (alias: rm)
wt prune [-f]	Remove all worktrees except the default (alias: p)

Examples

# Clone a repository
wt clone git@github.com:user/repo.git
wt clone git@github.com:user/repo.git -s # clone and switch to default branch# Create worktrees
wt create feature-auth # new worktree from bare repo HEAD
wt create hotfix --checkout main # check out existing branch 'main' in new worktree
wt create feature-ui -s # create and switch to the new worktree
wt create fix-123 --base feature-auth # branch off 'feature-auth' worktree's current commit# Switch between worktrees
wt switch main
wt sw feature-auth
# List and remove
wt ls
wt rm feature-auth # remove single worktree
wt rm feature-one feature-two # remove multiple worktrees# Prune all non-default worktrees
wt prune # interactive confirmation
wt prune -f # skip confirmation

Flags

• -s, --switch: After clone/create, switch to the new worktree
• --checkout <branch>: Check out an existing branch in the new worktree. Fails if that branch is already checked out in another worktree. Use this when the branch already exists in the repository but is not currently active.
• --base <worktree>: Create the new worktree as a new branch starting at the given worktree's current commit. Use this to branch off work-in-progress from another worktree, even if its branch is already checked out. Cannot be combined with --checkout.
• -f, --force: Skip the confirmation prompt when pruning worktrees

Hooks

The hook system is wtree's core feature. Define shell commands that run automatically during worktree lifecycle events.

Local Hooks

When you clone a repository with wt clone, a customisble template .wtree/hooks.toml is created:

Global Default Hooks

Define default hooks that apply to all new repositories:

mkdir -p ~/.wtree
cat >~/.wtree/default-hooks.toml << 'EOF'[create]pre = []post = ["cp \"$WT_HUB_ROOT/main/.env\" \"$WT_WORKTREE_PATH/.env\""][switch]pre = []post = [][remove]pre = []post = []EOF

When you run wt clone, the tool will:

1. Check if ~/.wtree/default-hooks.toml exists
2. If it exists, copy its content as the new repository's .wtree/hooks.toml
3. If it doesn't exist, use the built-in template with commented examples

Environment Variables

Hooks receive full context via environment variables:

Variable	Description	Available in
WT_COMMAND	Command name (create/switch/remove)	All hooks
WT_WORKTREE_NAME	Name of the target worktree	All hooks
WT_WORKTREE_PATH	Absolute path to target worktree	All hooks
WT_HUB_ROOT	Repo root: hub root (parent of .bare) in bare layout, main worktree in standard layout	All hooks
WT_BRANCH	Branch name (if specified)	create only

In the standard layout WT_HUB_ROOT is the main worktree path rather than the parent of .bare; the variable keeps its name for backward compatibility, but its meaning is the repo root in the active layout.

Execution Model

Phase	Working Directory	On Failure
Pre-hooks	Repo root (hub root / main worktree)	Command aborted
Post-hooks	Target worktree directory	Warning logged, command completes

This design lets you:

• Use pre-hooks as gates (validate branch names, check prerequisites)
• Use post-hooks for setup (install deps, copy files) without blocking on failures

Real-World Examples

Node.js project with shared environment:

[create]
post = [
"cp \"$WT_HUB_ROOT/main/.env\"\"$WT_WORKTREE_PATH/.env\"",
"npm install"
]
[switch]
post = ["npm install"]

Python project with virtual environments:

[create]
post = [
"python -m venv .venv",
"source .venv/bin/activate && pip install -r requirements.txt"
]
[switch]
post = ["source .venv/bin/activate"]

Validate branch naming convention:

[create]
pre = ["[[ \"$WT_WORKTREE_NAME\" =~ ^(feature|fix|hotfix)- ]]"]
post = []

Development

cargo build # debug build
cargo build --release # release build
cargo test# run tests

Install from source

git clone https://github.com/imqdee/wtree.git
cd wtree
cargo build --release
cp target/release/wt ~/.local/bin/ # or anywhere in your PATH

Development Git Hooks

This project uses lefthook for git hooks.

# Install lefthook (macOS)
brew install lefthook
# Install hooks
lefthook install

Hooks run automatically on commit (fmt, clippy) and push (test, build).

License

MIT