wt

wt is a Python CLI for working in Git branches as separate directories.

It is built around a compact workflow:

wt c git@github.com:tgbender/project.git
cd project/main
wt a feat-login -b
wt l
wt r feat-login -b -f

The PyPI package name is tgbender-wt; the installed command is wt.

Status

0.1.0 is usable alpha software. The core flows are covered by integration tests and dogfooding, especially dirty worktree removal, stash recovery, templates, config, init/deinit recovery, and wt doctor.

Install

uv tool install tgbender-wt

From a local checkout:

uv tool install .

Commands

Command	Alias	Purpose
wt clone <url>	wt c	Clone a repo into a wt-managed worktree project.
wt new <name>	wt n	Create a new empty project.
wt add [branch]	wt a	Add a worktree, prompting for a branch if omitted.
wt add <branch> -b [start]	wt a	Create a branch and worktree.
wt remove [branch]	wt r	Remove a worktree, or select one interactively.
wt list	wt l	List managed worktrees.
wt fetch	wt f	Fetch/prune configured remotes.
wt init		Convert a normal checkout into a wt-managed project.
wt deinit		Convert a wt-managed project back to a normal checkout.
wt abort		Recover the latest incomplete topology operation.
wt doctor		Check layout, worktrees, refs, state, hooks, and CAS objects.
wt stash ...		Manage searchable wt stashes.
wt config ...		Inspect and edit configuration.

Worktrees

Create a new branch from the current worktree:

wt a feat-login -b

Prompt for a branch and parent:

wt a -b

Create from a specific start point:

wt a fix-prod -b origin/main

Check out an existing branch:

wt a release-2026-05

Branches map to paths using the configured path style:

branch_path_style = "nested" # feat/login -> feat/login
branch_path_style = "flat"   # feat/login -> feat_login
flat_separator = "_"

Remove Without Losing Work

wt remove is conservative by default.

wt r
wt r feat-login
wt r feat-login -f
wt r feat-login -b -f
wt r feat-login --discard

• No branch argument opens an interactive selector.
• -f / --force auto-saves dirty tracked, untracked, and ignored files into a wt stash before removing the worktree.
• -b / --branch also deletes the Git branch.
• --discard / --no-save is the explicit destructive option.

So wt r feat-login -b -f means: save dirty work if needed, remove the worktree, then delete the branch.

Stash

wt stash stores metadata in SQLite so stashes are named, searchable, and tied back to branches/worktrees.

wt stash
wt stash --name login-wip -m "before cleanup" -t login
wt stash save login-wip -u -m "before cleanup" -t login
wt stash list
wt stash search login
wt stash show login-wip
wt stash apply login-wip
wt stash drop login-wip

Bare wt stash is the auto flow: it saves tracked, untracked, and ignored changes using the current branch as the default name. Use --tracked-only if you only want tracked modifications.

Tracked changes are stored behind private Git refs under refs/wt-stash/<id> and backed up as binary patches under .wt/patches/. Large untracked or ignored files over 4 MiB are stored in wt CAS under .wt/objects/sha256/.

drop and pop hide stashes from default listings but keep the backend data recoverable by id:

wt stash list --all
wt stash apply <id> --dropped

Init, Deinit, Abort

Convert a normal checkout:

wt init --plan
wt init --apply -y

Convert back:

wt deinit --plan
wt deinit --apply -y

Recover an interrupted topology operation:

wt abort

Topology-changing commands use preflight checks, persisted plans, transaction records, and recovery manifests. wt doctor is the first thing to run when a project looks inconsistent.

Config

Configuration is TOML and layered from global to project-local:

wt config init
wt config show
wt config get branch_path_style
wt config set branch_path_style flat

Common config:

branch_path_style = "flat"
flat_separator = "-"
default_remotes = "prompt"

[remotes]
github = "git@github.com:tgbender/${project}.git"

Templates

Files in .wt/templates/ are copied into new worktrees without overwriting existing files. Symlinks are preserved.

.wt/templates/
  .env.example
  .vscode/settings.json

Development

mise run setup
mise run check

Direct checks:

uv run pytest
uv run --with ruff ruff check .
uv run mypy src
uv build

License

MIT.