### Project config TOML example Source: https://worktrunk.dev/config Example project configuration file at `.config/wt.toml` with pre-start and pre-merge hooks. ```toml # .config/wt.toml [pre-start] deps = "npm ci" [pre-merge] test = "npm test" ``` -------------------------------- ### TOML hooks configuration example Source: https://worktrunk.dev/extending Example TOML configuration defining three hooks: a pre-start hook to install dependencies, a post-start hook to run a dev server with a template variable, and a pre-merge hook to run tests. Hooks are defined in TOML config and support template variables. ```toml [pre-start] deps = "npm ci" [post-start] server = "npm run dev -- --port {{ branch | hash_port }}" [pre-merge] test = "npm test" ``` -------------------------------- ### User config TOML example Source: https://worktrunk.dev/config Example user configuration file at `~/.config/worktrunk/config.toml` with worktree path template and LLM commit settings. ```toml # ~/.config/worktrunk/config.toml worktree-path = ".worktrees/{{ branch | sanitize }}" [commit.generation] command = "MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --safe-mode --setting-sources='user' --system-prompt=''" ``` -------------------------------- ### wt hook post-start example output Source: https://worktrunk.dev/hook Shows the output of running the post-start hook manually, which runs the post-start project at a specific path. ```console $ wt hook post-start ◎ Running post-start: project @ ~/acme ``` -------------------------------- ### Create user config file Source: https://worktrunk.dev/config Creates a user config file with documented examples. ```console $ wt config create ``` -------------------------------- ### Reference task runners in hooks Source: https://worktrunk.dev/tips-patterns Use Taskfile, Justfile, or Makefile commands inside hook definitions. The example shows a `pre-start` hook running `task install` and a `pre-merge` hook running `just test lint`. ```toml [pre-start] "setup" = "task install" [pre-merge] "validate" = "just test lint" ``` -------------------------------- ### Install shell integration with wt config shell install Source: https://worktrunk.dev/config Installs the shell integration required for Worktrunk to change directories when switching worktrees. Without it, `wt switch` prints the target directory but cannot `cd` into it. For manual setup, see `wt config shell init --help`. ```console $ wt config shell install ``` -------------------------------- ### Pipeline hook: [[post-start]] blocks in order Source: https://worktrunk.dev/hook A pipeline hook form runs [[hook]] blocks in order. Each block is one step; multiple keys within a block run concurrently. A failing step aborts the rest of the pipeline. Here install runs first, then build and server run together. Templates are syntax-checked before the pipeline starts and rendered as each step runs, so a step can store per-branch vars that later steps read via {{ vars. }}. ```toml [[post-start]] install = "npm ci" [[post-start]] build = "npm run build" server = "npm run dev" ``` -------------------------------- ### Single-command hook: pre-start = "npm install" Source: https://worktrunk.dev/hook A string hook form runs a single command. Hooks can be defined in .config/wt.toml or ~/.config/worktrunk/config.toml; both use the same format. ```toml pre-start = "npm install" ``` -------------------------------- ### Install Worktrunk with Cargo and install shell integration Source: https://worktrunk.dev/ Installs Worktrunk using Cargo, then configures shell integration. ```bash cargo install worktrunk && wt config shell install ``` -------------------------------- ### Using worktree_path_of_branch in a template including JSON example Source: https://worktrunk.dev/hook Shows how to use the worktree_path_of_branch function in a TOML setup command to copy a config file from the main worktree. Also includes a Python script that reads JSON context to conditionally run a command. ```toml [pre-start] # Copy config from main worktree setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}" ``` ```python import json, sys, subprocess ctx = json.load(sys.stdin) if ctx.get('branch', '').startswith('feature/') and 'backend' in ctx['repo']: subprocess.run(['make', 'seed-db']) ``` -------------------------------- ### Post-start hook configuration for dev server Source: https://worktrunk.dev/step Example `.config/wt.toml` configuration that runs a dev server via `wt step tether` in a `post-start` hook, automatically torn down when the worktree is removed. ```toml # .config/wt.toml [post-start] server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}" ``` -------------------------------- ### wt hook pre-merge example output Source: https://worktrunk.dev/hook Shows the output of running `wt hook pre-merge` manually, displaying progress and test results for project hooks. ```console $ wt hook pre-merge ◎ Running pre-merge project:test cargo test Finished test [unoptimized + debuginfo] target(s) in 0.12s Running unittests src/lib.rs (target/debug/deps/worktrunk-abc123) running 18 tests test auth::tests::test_jwt_decode ... ok test auth::tests::test_jwt_encode ... ok test auth::tests::test_token_refresh ... ok test auth::tests::test_token_validation ... ok test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s ◎ Running pre-merge project:lint cargo clippy Checking worktrun v0.1.0 Finished dev [unoptimized + debuginfo] target(s) in 1.23s ``` -------------------------------- ### Create and start Claude: wt switch -c -x claude feat vs git worktree add, cd, claude Source: https://worktrunk.dev/worktrunk Create a new worktree and start Claude Code in one command with wt switch -c -x claude feat. The plain git equivalent requires three sequential shell commands: git worktree add -b feat ../repo.feat, cd ../repo.feat, then claude. ```plaintext wt switch -c -x claude feat ``` ```bash git worktree add -b feat ../repo.feat && \ cd ../repo.feat && \ claude ``` -------------------------------- ### Install shell integration Source: https://worktrunk.dev/config Installs shell integration required for directory switching. ```console $ wt config shell install ``` -------------------------------- ### Install Worktrunk with Pixi and install shell integration Source: https://worktrunk.dev/ Installs Worktrunk globally with Pixi, then configures shell integration. Community-maintained feedstock. ```bash pixi global install worktrunk && wt config shell install ``` -------------------------------- ### Configure post-start hook to copy gitignored files Source: https://worktrunk.dev/step Adds a `[post-start]` hook in `.config/wt.toml` that runs `wt step copy-ignored` after a worktree starts, copying gitignored files from the primary worktree to the new one. ```toml # .config/wt.toml [post-start] copy = "wt step copy-ignored" ``` -------------------------------- ### Show all stored state with wt config state get Source: https://worktrunk.dev/config Displays all stored state entries, including configuration and log files. ```console $ wt config state get ``` -------------------------------- ### Install Pi plugin Source: https://worktrunk.dev/claude-code Installs the activity hook for Pi. Writes to `~/.omp/agent/hooks/pre/worktrunk.ts`. Uninstall with `wt config plugins pi uninstall`. ```bash wt config plugins pi install ``` -------------------------------- ### Custom subcommand execution examples Source: https://worktrunk.dev/extending Demonstrates how custom subcommands follow the wt- pattern and how arguments and flags are forwarded to the child process. ```bash wt sync origin # runs: wt-sync origin wt -C /tmp/repo sync # -C is forwarded as the child's working directory ``` -------------------------------- ### wt step rebase examples Source: https://worktrunk.dev/step Shows three ways to invoke `wt step rebase`: with no target (default branch), with a branch name, and with a tag. ```console $ wt step rebase # Rebase onto default branch $ wt step rebase develop # Rebase onto develop $ wt step rebase v1.2.0 # Rebase onto a tag ``` -------------------------------- ### Schema 2 JSON envelope example Source: https://worktrunk.dev/list Example of the schema 2 envelope format emitted by `--format=json`. Shows the envelope object with `schema`, `repo`, `collected`, and `items` array, where each item carries independent facts and rendered strings under `display`. Note that `null` is used for requested-but-not-determined values, while absent fields mean not applicable or not requested. ```json { "schema": 2, "repo": { "default_branch": "main", "forge": {"url": "https://github.com/org/repo", "provider": "github", "host": "github.com", "owner": "org", "name": "repo", "remote": "origin"} }, "collected": {"ci": false, "summary": false}, "items": [ { "branch": "feature", "head": {"sha": "05a4a45d…", "short_sha": "05a4a45", "subject": "Add login page", "committed_at": "2025-01-01T08:00:00Z"}, "worktree": {"path": "/home/user/repo.feature", "main": false, "current": true, "previous": false, "detached": false, "branch_mismatch": false, "duplicate_branch": false, "changes": {"staged": false, "modified": true, "untracked": false, "renamed": false, "deleted": false, "conflicted": false, "diff": {"added": 10, "deleted": 2}}}, "default_branch": {"ahead": 3, "behind": 1, "diff": {"added": 50, "deleted": 20}, "orphan": false, "integration": null, "merge_conflicts": false}, "upstream": {"remote": "origin", "branch": "feature", "ahead": 0, "behind": 2}, "display": {"state": "diverged", "symbols": "!↕", "statusline": "feature …"} } ] } ``` -------------------------------- ### wt step copy-ignored Source: https://worktrunk.dev/step Copies gitignored files from a source worktree to a destination worktree, eliminating cold starts by copying build caches and dependencies. Supports dry-run, force overwrite, and requiring .worktreeinclude. ```APIDOC ## wt step copy-ignored ### Description Copies gitignored files to another worktree. Eliminates cold starts by copying build caches and dependencies. ### Usage wt step copy-ignored [OPTIONS] ### Options #### --from - Type: string - Optional - Source worktree branch. Defaults to primary worktree. #### --to - Type: string - Optional - Destination worktree branch. Defaults to current worktree. #### --dry-run - Type: flag - Optional - Show what would be copied. #### --force - Type: flag - Optional - Overwrite existing files in destination. #### --require-include - Type: flag - Optional - Require .worktreeinclude to copy anything. #### --format - Type: string - Optional - Output format. JSON prints structured result to stdout after the copy completes. Default: text. Possible values: text, json. #### -h, --help - Type: flag - Optional - Print help (see a summary with '-h'). ### Global Options #### -C - Type: string - Optional - Working directory for this command. #### --config - Type: string - Optional - User config file path. #### --config-set - Type: string - Optional - Override config with inline TOML, e.g. --config-set list.full=true (repeatable). #### -v, --verbose... - Type: flag - Optional - Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere. #### -y, --yes - Type: flag - Optional - Skip approval prompts. ``` -------------------------------- ### Run a shell command with pipes or redirects via sh -c Source: https://worktrunk.dev/step Wraps the command in `sh -c` to support pipes, redirects, variables, or globs. The shell process is the command that gets tethered. ```console $ wt step tether -- sh -c 'PORT=$P npm run dev | tee dev.log' ``` -------------------------------- ### wt step copy-ignored command reference Source: https://worktrunk.dev/step Full CLI help output for `wt step copy-ignored`, showing usage, options, and global flags. Use this command to copy gitignored files (e.g., build caches) to another worktree, eliminating cold starts. Options include `--from`, `--to`, `--dry-run`, `--force`, `--require-include`, and `--format` (text or json). ```text wt step copy-ignored - Copy gitignored files to another worktree Eliminates cold starts by copying build caches and dependencies. Usage: wt step copy-ignored [OPTIONS] Options: --from Source worktree branch Defaults to primary worktree. --to Destination worktree branch Defaults to current worktree. --dry-run Show what would be copied --force Overwrite existing files in destination --require-include Require .worktreeinclude to copy anything -h, --help Print help (see a summary with '-h') Automation: --format Output format JSON prints structured result to stdout after the copy completes. [default: text] [possible values: text, json] Global Options: -C Working directory for this command --config User config file path --config-set Override config with inline TOML, e.g. --config-set list.full=true (repeatable) -v, --verbose... Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach -y, --yes Skip approval prompts ``` -------------------------------- ### Get database URL from state vars in a shell command Source: https://worktrunk.dev/tips-patterns Shows how to retrieve the `db_url` var set by the pipeline and use it as the `DATABASE_URL` environment variable when starting an app. ```bash DATABASE_URL=$(wt config state vars get db_url) npm start ``` -------------------------------- ### Subdomain routing with Caddy worktree config Source: https://worktrunk.dev/tips-patterns Configures Caddy subdomain routing for worktrees. The post-start hook starts the dev server on a deterministic port and registers a Caddy route mapping {{ branch | sanitize }}.{{ repo }}.localhost to that port; pre-remove deletes the route; list shows the clean URL. Requires Caddy installed (brew install caddy). ```toml # .config/wt.toml [post-start] server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}" proxy = """ curl -sf --max-time 0.5 http://localhost:2019/config/ || caddy start curl -sf http://localhost:2019/config/apps/http/servers/wt || \ curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt -H 'Content-Type: application/json' \ -d '{"listen":[":8080"],"automatic_https":{"disable":true},"routes":[]}' curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true curl -sfX PUT http://localhost:2019/config/apps/http/servers/wt/routes/0 -H 'Content-Type: application/json' \ -d '{"@id":"wt:{{ repo }}:{{ branch | sanitize }}","match":[{"host":["{{ branch | sanitize }}.{{ repo }}.localhost"]}],"handle":[{"handler":"reverse_proxy","upstreams":[{"dial":"127.0.0.1:{{ branch | hash_port }}"}]}]}' """ [pre-remove] proxy = "curl -sf -X DELETE http://localhost:2019/id/wt:{{ repo }}:{{ branch | sanitize }} || true" [list] url = "http://{{ branch | sanitize }}.{{ repo }}.localhost:8080" ``` -------------------------------- ### wt step rebase command reference Source: https://worktrunk.dev/step Full help output for `wt step rebase`, including usage, arguments, options, and global options. ```text wt step rebase - Rebase onto target Usage: wt step rebase [OPTIONS] [TARGET] Arguments: [TARGET] Target branch, tag, or commit Defaults to default branch. Options: -h, --help Print help (see a summary with '-h') Automation: --format Output format JSON prints structured result to stdout after the rebase completes. [default: text] [possible values: text, json] Global Options: -C Working directory for this command --config User config file path --config-set Override config with inline TOML, e.g. --config-set list.full=true (repeatable) -v, --verbose... Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach -y, --yes Skip approval prompts ``` -------------------------------- ### Configure dev server per worktree with hash_port and wt step tether Source: https://worktrunk.dev/tips-patterns Sets up a post-start hook that runs `npm run dev` on a deterministic port derived from the branch name, and a list URL that shows that port. The `wt step tether` command runs the server in its own process group and tears it down when the worktree is removed. ```toml # .config/wt.toml [post-start] server = "wt step tether -- npm run dev -- --port {{ branch | hash_port }}" [list] url = "http://localhost:{{ branch | hash_port }}" ``` -------------------------------- ### Run full diagnostics with wt config show --full Source: https://worktrunk.dev/config Runs diagnostic checks for CI tool status, commit generation, and version availability. Warnings exit zero; failures are rendered before exiting. ```console $ wt config show --full ``` -------------------------------- ### Install Worktrunk with Conda and install shell integration Source: https://worktrunk.dev/ Installs Worktrunk from conda-forge using Conda, then configures shell integration. Community-maintained feedstock. ```bash conda install -c conda-forge worktrunk && wt config shell install ``` -------------------------------- ### Install Worktrunk on Arch Linux with pacman and install shell integration Source: https://worktrunk.dev/ Installs Worktrunk via pacman on Arch Linux, then configures shell integration. ```bash sudo pacman -S worktrunk && wt config shell install ``` -------------------------------- ### Install Worktrunk with Homebrew and install shell integration Source: https://worktrunk.dev/ Installs Worktrunk via Homebrew on macOS and Linux, then configures shell integration so commands can change directories. ```bash brew install worktrunk && wt config shell install ``` -------------------------------- ### Command reference for wt step for-each Source: https://worktrunk.dev/step Full command reference showing usage, arguments, options, and global options. Includes default output format and possible values. ```text wt step for-each - Run command in each worktree Executes sequentially with real-time output; continues past command failures. Usage: wt step for-each [OPTIONS] -- ... Arguments: ... Command template (see --help for all variables) Options: --format Output format [default: text] [possible values: text, json] -h, --help Print help (see a summary with '-h') Global Options: -C Working directory for this command --config User config file path --config-set Override config with inline TOML, e.g. --config-set list.full=true (repeatable) -v, --verbose... Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach -y, --yes Skip approval prompts ``` -------------------------------- ### Install Claude Code plugin Source: https://worktrunk.dev/claude-code Installs the Worktrunk plugin for Claude Code. The manual equivalent uses `claude plugin marketplace add` and `claude plugin install`. Uninstall with `wt config plugins claude uninstall`. ```bash wt config plugins claude install ``` ```bash claude plugin marketplace add max-sixty/worktrunk claude plugin install worktrunk@worktrunk ``` -------------------------------- ### wt config update examples Source: https://worktrunk.dev/config These commands preview and apply config migrations, skip confirmation with --yes, or write the migration artifact to a file or stdout. The --output flag omits deprecated approved-commands with a stderr warning; only an in-place update migrates them to approvals.toml. ```console $ wt config update ``` ```console $ wt config update --yes ``` ```console $ wt config update --output migrated.toml ``` ```console $ wt config update --output=- ``` -------------------------------- ### Install Worktrunk on Windows with Winget Source: https://worktrunk.dev/worktrunk Installs Worktrunk on Windows via Winget. Because `wt` defaults to Windows Terminal's command, Worktrunk is installed as `git-wt` to avoid conflict. Alternatively, disable Windows Terminal's alias to use `wt` directly. ```bash winget install max-sixty.worktrunk git-wt config shell install ``` -------------------------------- ### First-run approval prompt for project commands Source: https://worktrunk.dev/hook Shown when a project command runs for the first time. Approvals are saved to ~/.config/worktrunk/approvals.toml; if a command changes, a new approval is required. Declining skips every project command for that operation, including already approved ones, and continues without them; saved approvals are unaffected. Use --yes to bypass prompts and --no-hooks to skip hooks (accepted by wt switch, wt merge, wt remove, wt step commit, wt step squash, not by wt hook). ```text ▲ repo needs approval to execute 3 commands: ○ pre-start install: npm ci ○ pre-start build: cargo build --release ○ pre-start env: echo 'PORT={{ branch | hash_port }}' > .env.local ❯ Allow and remember? [y/N] ``` -------------------------------- ### Matching several repositories with wildcard keys Source: https://worktrunk.dev/config Shows how to match several repositories with one entry using the * wildcard. A key containing * matches any run of characters, including /, so one entry can cover a whole host or namespace. * is the only wildcard; every other character is literal. ```toml # Every repository on a self-hosted forge whose hostname carries no brand [projects."git.company.example/*"] forge.platform = "gitlab" # Everything under one namespace shares a layout [projects."git.company.example/platform/*"] worktree-path = ".worktrees/{{ branch | sanitize }}" ``` -------------------------------- ### Show wt list output with per-worktree dev server URLs Source: https://worktrunk.dev/tips-patterns Example output of `wt list` showing each worktree's URL column with deterministic ports. The URL dims if the server isn't running. ```console $ wt list Branch Status HEAD± main↕ main…± Remote⇅ URL Commit @ main ? ^⇅ +5 ⇡1 ⇣1 http://localhost:12107 41ee083 + feature-api + ↕⇡ +54 -5 ↑4 ↓1 +234 -24 ⇡3 http://localhost:10703 6814f02 + fix-auth ↕| ↑2 ↓1 +25 -11 | http://localhost:16460 b772e68 + fix-typos _| | http://localhost:14301 41ee083 ○ Showing 4 worktrees, 2 with changes, 2 ahead, hidden: Path, Age, Message ``` -------------------------------- ### wt hook command reference Source: https://worktrunk.dev/hook Command-line help output for `wt hook`, listing all hook subcommands (show, pre-switch, post-switch, pre-start, post-start, pre-commit, post-commit, pre-merge, post-merge, pre-remove, post-remove) and global options. Use `-h` for a summary, `-C` to set the working directory, `--config` for a user config file, `--config-set` for inline TOML overrides, `-v` for verbose output (with `WORKTRUNK_VERBOSE` environment variable), and `-y` to skip approval prompts. ```text wt hook - Run configured hooks Usage: wt hook [OPTIONS] Commands: show Show configured hooks pre-switch Run pre-switch hooks post-switch Run post-switch hooks pre-start Run pre-start hooks post-start Run post-start hooks pre-commit Run pre-commit hooks post-commit Run post-commit hooks pre-merge Run pre-merge hooks post-merge Run post-merge hooks pre-remove Run pre-remove hooks post-remove Run post-remove hooks Options: -h, --help Print help (see a summary with '-h') Global Options: -C Working directory for this command --config User config file path --config-set Override config with inline TOML, e.g. --config-set list.full=true (repeatable) -v, --verbose... Verbose output (-v: info logs + hook/alias template variables on stderr; -vv: also debug logs and raw subprocess output written to .git/wt/logs/). Set WORKTRUNK_VERBOSE=0|1|2 to apply the same level everywhere — including shell completion, which no flag can reach -y, --yes Skip approval prompts ```