Skip to content
wtm

wtm user guide

How wtm works beyond --help. Every flag of every command is in wtm <command> --help and the generated command reference; these pages explain how the pieces fit together.

Start here

Section titled “Start here”
  • Getting started: install, two worktrees running side by side, cleaning one up. Ten minutes.
  • Installation: every way to install, a specific version, updating.
  • Platform support: macOS, Linux, WSL2, and what each one supports.
  • Recipes: complete setups to copy: a pnpm/turbo monorepo, a docker compose app, a shared postgres, agents in parallel, stacked PRs, one command across worktrees.
  • Troubleshooting: a port in use, a crashed job, wtm go not changing directory, .env drift, and the other usual suspects.

Worktrees

Section titled “Worktrees”
  • Configuration: config.toml, how .env files are provisioned, on_create / on_clean hooks, the environment of wtm exec, the global config.
  • Where wtm keeps its state: the files under <git-common-dir>/wtm/ and beside the global config.

Dev stacks with wtm run

Section titled “Dev stacks with wtm run”

Opt-in: nothing in this section applies until wtm run init writes run.toml.

  • Isolation: isolated or verbatim, what a worktree shares with its source, and touches for data it does not own.
  • Jobs, profiles and runners: services and tasks, what run up starts, the run view, port checks.
  • How wtm run works: the job environment, ports, what run init proposes, compose project names.
  • Shared services: one postgres for the repository, a namespace per worktree.
  • Named URLs: one address per job and worktree, the run proxy, port 80 on macOS.
  • run.toml reference: every key, with its default.

Integrations

Section titled “Integrations”
  • Integrations: driving wtm from scripts, agents and other tools: --yes, --output json, exit codes, the agent skill.
  • The event stream: wtm events, every worktree change as it happens.

Upgrading

Section titled “Upgrading”