wtp: a Git worktree CLI that generates paths, tracks branches and runs setup hooks

The problem wtp solves for people who keep several branches checked out

Plain git worktree is a low-level command. Adding a branch means typing a full path: the README contrasts `git worktree add ../project-worktrees/feature/auth feature/auth` with `wtp add feature/auth`. The second form derives the path from the branch name, placing it under a base directory the project configures. Removal has the same shape: `wtp remove --with-branch feature/done` deletes the worktree and its branch together, where plain git requires two commands and a memory for the second one. The audience is developers who run parallel branches in separate directories, often in monorepos or microservices where each checkout needs its own dependencies and environment files. wtp is not a replacement for git; it shells out to git worktree underneath, and it needs Git 2.17 or later for that support.

How wtp decides where a worktree goes and which branch it tracks

The default base directory is `../worktrees`, relative to the project root, and it can be changed with the `base_dir` key under `defaults` in `.wtp.yml`. A branch named `feature/auth` becomes `../worktrees/feature/auth`, so the directory structure mirrors the branch namespace. Branch resolution has a remote fallback: if the branch is not found locally, wtp tracks the remote branch automatically, which the README shows with `wtp add feature/remote-only` creating a worktree that tracks `origin/feature/remote-only`. When the same branch name exists in more than one remote, wtp refuses to guess and prints an error naming the remotes, then tells you to create a local branch for the remote you want and run the command again. That refusal is the right call: silently picking origin over upstream would produce a worktree tracking the wrong history. Hooks run after creation. The `.wtp.yml` file defines `post_create` entries of three types: `copy`, `symlink` and `command`. A copy hook reads from the main worktree and writes into the new one, and the README notes that the source may be gitignored, which is how a real `.env` file travels between checkouts. A symlink hook shares a directory such as `.bin` between the main and new worktree. Command hooks run inside the new worktree, with an optional `env` map and an optional `work_dir`.

Installing wtp and creating your first worktree

Homebrew is the shortest path on macOS and Linux. The README gives the tap-qualified formula name, so the command is exactly this:

brew install satococoa/tap/wtp

If you already have a Go toolchain, the module path includes the v2 major version, and the binary lives under `cmd/wtp`:

go install github.com/satococoa/wtp/v2/cmd/wtp@latest

Prebuilt archives are published on GitHub Releases for macOS on Apple Silicon and for Linux on x86_64 and ARM64. The README shows a curl-and-tar sequence for each, for example the macOS arm64 archive:

curl -L https://github.com/satococoa/wtp/releases/latest/download/wtp_Darwin_arm64.tar.gz | tar xz
sudo mv wtp /usr/local/bin/

Building from source follows the usual Go shape: clone the repository, then `go build -o wtp ./cmd/wtp` from the repository root, and move the binary somewhere on your PATH. Once installed, the first real use is creating a worktree from an existing branch. Running `wtp add feature/auth` creates the directory under the base directory and, per the README, tracks the remote branch if no local branch exists. To create a new branch at the same time, use the `-b` flag, and to run a command inside the fresh worktree after the hooks finish, add `--exec`:

wtp add -b feature/new-feature --exec "npm test"

The README notes that interactive commands work when a TTY is available. For scripts, `--quiet` prints only the created absolute path, which is the form you want when another program consumes the output. Navigation is `wtp cd feature/auth`, and `wtp cd @` or bare `wtp cd` returns to the main worktree. Shell completion is available for Bash 4+ with bash-completion v2, Zsh and Fish.

The .wtp.yml hooks, and where they can bite you

A project configures setup once, and every `wtp add` replays it. The README's example copies `.env` and `.claude` from the main worktree, symlinks `.bin`, then runs `npm ci` and `npm run db:setup` as commands. The semantics matter: `from` is always relative to the main worktree, `to` is relative to the new worktree, and when `to` is omitted it defaults to the same value as `from` for relative paths. Copy hooks deliberately read files that git ignores, which is their point, and also their risk: a hook that copies a secrets file into a directory you later share or archive moves that secret with it. A symlinked directory is shared state between two checkouts, so a build tool that writes into `.bin` from either worktree will collide. The README recommends explicit single-step commands over a task runner, which keeps failures attributable to one step. What the README does not document is what happens when a hook fails midway: there is no described rollback, so a failed `npm ci` may leave a worktree that exists but is not usable. Treat hooks as a convenience for reproducible setup, not as a transaction.

Platform limits and the cases where plain git worktree is the better tool

The requirements section lists Linux on x86_64 or ARM64 and macOS on Apple Silicon. Windows is not listed, and neither is macOS on Intel. If your team develops on Windows, wtp is simply not an option, and `git worktree` remains the portable command. There is also a workflow case against it: if you create a worktree once a month, the path-typing savings are small, and adding a configuration file plus a third-party binary to the setup is more moving parts than the problem deserves. Branch tracking is convenient but implicit, so a developer who expects to inspect which remote a worktree tracks before it is created will find the automatic fallback surprising. The multi-remote error is the one place wtp forces an explicit decision, and it is worth reading that message rather than working around it. Finally, wtp is a CLI with no documented GUI, so anyone who wants a visual branch switcher should look elsewhere.

How wtp differs from plain git worktree and from scripted wrappers

The honest alternative is git worktree itself, and the difference is not capability but ceremony. `git worktree add` takes an explicit path and does nothing else: no base directory convention, no remote branch fallback, no hooks, no `cd` helper. A team can reproduce much of wtp with a shell function that builds the path and a Makefile target that copies `.env`, and that wrapper has no dependency beyond git. What it will not have is the multi-remote error message, the `--with-branch` removal that deletes branch and worktree together, or the `--quiet` output contract for scripts. Another alternative in spirit is any tool that manages parallel checkouts through its own workspace model rather than through git's worktree plumbing; those tools typically own the directory layout entirely, whereas wtp keeps git as the source of truth and only layers naming, tracking and hooks on top. That layering is the design choice to weigh: you keep full git compatibility, and you accept that wtp's value is concentrated in the conventions it enforces.

Maintenance, versioning and the MIT licence

The repository is not archived, and the last push was on 2026-03-30. The most recent releases listed are v2.10.3, v2.10.2 and v2.10.1, all from March 2026, with v2.10.2 and v2.10.3 published on the same day, 2026-03-08. The module path carries the v2 major version, so `go install` must include `/v2/` in the path; upgrading across a future major version would change that path and require a new install command. The project ships a `.goreleaser.yml` and a `Taskfile.yml` at the repository root, which indicates release automation and a task runner for local builds, though the README does not document an upgrade procedure beyond reinstalling via Homebrew or Go. The licence is MIT, which permits commercial and private use and requires that the copyright notice and permission notice be preserved in copies; that is a description of the licence text, not legal advice, and if you redistribute the binary inside a product you should have your own counsel read the LICENSE file. Nothing in the README describes a plugin or extension API, so extending wtp means forking it or contributing upstream.

Editorial conclusion

Adopt wtp if you create worktrees often enough that typing paths and copying .env files by hand has become a chore, and if you work on Linux or macOS with Git 2.17 or later. Skip it if you are on Windows, if you want a GUI, or if you would rather keep every worktree step explicit. Before committing a team to it, run wtp add -b test-branch in a scratch clone and read the resulting .wtp.yml hooks carefully: copy and symlink hooks act on real files in your main worktree, and the README does not document a rollback for a hook that fails halfway through.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. satococoa/wtp on GitHub