Worktrunk: parallel worktrees, lifecycle control and source analysis
Install Worktrunk across macOS, Linux and Windows: binary, shell and configuration
Separate package installation from shell integration and repository hooks, with a versioned rollout and a narrow rollback plan.
What you will learn
- Deployment here means a local developer tool
- Treat shell integration as a separate configuration change
- Separate personal defaults from shared project behavior
Before you start
- Basic Git branches and command-line navigation
- A disposable repository for optional reader exercises
Explain worktree boundaries, verify a first checkout and review configured commands before adopting automation.
Key takeaways
- Package installation, shell integration and project configuration are separate layers.
- Windows users should distinguish wt, git-wt and git wt.
- Record the actual installed version instead of assuming a package matches the reviewed commit.
Deployment here means a local developer tool
Worktrunk is not a web service that inherently needs a container, database or public endpoint. The pinned README documents Homebrew and Cargo installation routes, and a Winget route on Windows. These commands obtain software; they do not prove that your current package registry supplies exactly the inspected commit. Record the installed version and compare relevant release changes before using this series as a command reference.
Building the pinned source has its own prerequisite: Cargo.toml declares Rust 1.97 and the 2024 edition. This is a source-build requirement, not a requirement that every binary user install a compiler. We did not install a package, compile Rust or change a shell profile during this review.
Treat shell integration as a separate configuration change
The README follows installation with wt config shell install, or git-wt config shell install on Windows. That step modifies shell configuration and deserves a backup and a review of the specific change. A binary on PATH and a wrapper loaded in the current shell are not the same acceptance condition. Start a fresh shell and verify navigation in a disposable repository.
The Windows distinction matters twice: wt is already used by Windows Terminal, and git wt is not equivalent to directly invoking git-wt for parent-shell navigation. Diagnose command resolution before reinstalling. Keep the original profile and the exact integration entry so a rollback can remove only the entry introduced by this rollout.
Separate personal defaults from shared project behavior
The documented user config is ~/.config/worktrunk/config.toml on macOS/Linux, subject to XDG configuration, and %APPDATA%\worktrunk\config.toml on Windows. Project configuration lives in .config/wt.toml and can be committed. System defaults and overrides can also matter; inspect wt config show in the environment you are evaluating rather than assuming one file explains every behavior.
Roll out to one volunteer profile and one disposable project first. Record package version, resolved command, configuration locations, wrapper activation and the result of the quickstart. Keep approval storage separate from portable project configuration. Upgrade only after reviewing changes to hooks, merge defaults and approvals; a narrow rollback restores the previous package and integration entries without deleting unrelated user settings.
Decision guide
| Criterion | Option A | Option B |
|---|---|---|
| Best when | You need predictable behavior and easy auditing | You need adaptive optimization and have reliable telemetry |
| Main risk | May leave performance on the table | Can become difficult to explain or debug |
Implementation steps
- 1
Choose the documented platform route and review its effects.
- 2
Record the installed version and command resolution.
- 3
Back up and inspect the shell integration change.
- 4
Validate a disposable checkout before sharing project hooks.
Copy-ready example
Installation review record
Package version: unknown until checked
Resolved executable: record its path
Shell integration: installed / active / bypassed
User config: record actual location
Project config: review .config/wt.toml
Rollback: previous package and exact profile entryFrequently asked questions
Do I need Docker?
The inspected project is a local CLI; this series does not prescribe a server deployment.
Is the Rust version mandatory for prebuilt binaries?
The manifest requirement applies to compiling the pinned source; a platform package has its own requirements.
Sources
- Worktrunk / README.mdSource checked 2026-09-14
- Worktrunk / Cargo.tomlSource checked 2026-09-14
- Worktrunk / docs/src/content/docs/config.mdSource checked 2026-09-14
- Worktrunk / src/output/shell_integration.rsSource checked 2026-09-14