worktrunk

Worktrunk

Help users work with Worktrunk, a CLI tool for managing git worktrees.

Available documentation

Reference files are synced from worktrunk.dev documentation:

• reference/config.md: User and project configuration (LLM, hooks, command defaults)
• reference/hook.md: Hook types, timing, and execution order
• reference/switch.md, merge.md, list.md, etc.: Command documentation
• reference/extending.md: Aliases, multi-step pipelines, custom subcommands, and template-expansion gotchas (two-pass {% raw %} deferral, for-each recipes)
• reference/llm-commits.md: LLM commit message generation
• reference/tips-patterns.md: Practical recipes — aliases, per-branch variables, dev server per worktree, parallel agent patterns
• reference/shell-integration.md: Shell integration debugging
• reference/troubleshooting.md: Troubleshooting for LLM and hooks (Claude-specific)

For command-specific options, run wt <command> --help. For configuration, follow the workflows below.

Which worktree a command acts on

wt finds the repository from the working directory, and the worktree from the command's own arguments. Two rules cover every case:

1. A command that names a branch already names its worktree. Worktrees are addressed by branch name, so wt switch <branch>, wt remove <branch>, wt step diff --branch <branch>, and wt config state marker set --branch <branch> act on that branch's worktree no matter which worktree you run them from. Every such argument also accepts the worktree's own path, for the cases a branch cannot name — a second checkout of the same branch, or a detached worktree (which marker still rejects, since it keys state by branch name).
2. -C <path> moves the working directory, not the worktree selection. Reach for it when the repository lookup is what's wrong: a different repository; a command that acts on the current worktree and takes no branch argument (wt merge, wt step rebase|squash|push — their [TARGET] is the merge target, not a worktree); or a caller whose working directory isn't inside a repository at all, such as an agent hook the host pins elsewhere.

Layering -C on top of a branch argument names the same worktree twice. From inside the alpha worktree of a repo that also has beta: