worktrunk 0.42.0

---
source: tests/integration_tests/help.rs
info:
  program: wt
  args:
    - config
    - "--help"
  env:
    CLICOLOR_FORCE: "1"
    COLUMNS: "500"
    GIT_EDITOR: ""
    LANG: C
    LC_ALL: C
    NO_COLOR: ""
    PSModulePath: ""
    RUST_LOG: warn
    SHELL: ""
    TERM: alacritty
    WORKTRUNK_APPROVALS_PATH: /nonexistent/test/approvals.toml
    WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
    WORKTRUNK_SYSTEM_CONFIG_PATH: /etc/xdg/worktrunk/config.toml
    WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
    WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
    WORKTRUNK_TEST_EPOCH: "1735776000"
    WORKTRUNK_TEST_NUSHELL_ENV: "0"
    WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
    WORKTRUNK_TEST_POWERSHELL_ENV: "0"
    WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
success: true
exit_code: 0
----- stdout -----
wt config - Manage user & project configs

Includes shell integration, hooks, and saved state.

Usage: wt config [OPTIONS] <COMMAND>

Commands:
  shell      Shell integration setup
  create     Create configuration file
  show       Show configuration files & locations
  update     Update deprecated config settings
  approvals  Manage command approvals
  alias      Inspect and preview aliases
  plugins    Plugin management
  state      Manage internal data and cache

Options:
  -h, --help
          Print help (see a summary with '-h')

Global Options:
  -C <path>
          Working directory for this command

      --config <path>
          User config file path

  -v, --verbose...
          Verbose output (-v: info logs + hook/alias template variable & output; -vv: debug logs + diagnostic report + trace.log/output.log under .git/wt/logs/)

  -y, --yes
          Skip approval prompts

Examples

Install shell integration (required for directory switching):

  wt config shell install

Create user config file with documented examples:

  wt config create

Create project config file (.config/wt.toml) for hooks:

  wt config create --project

Show current configuration and file locations:

  wt config show

Configuration files

      File                 Location                                Contains                     Committed & shared 
 ────────────── ─────────────────────────────── ─────────────────────────────────────────────── ────────────────── 
 User config    ~/.config/worktrunk/config.toml Worktree path template, LLM commit configs, etc ✗                  
 Project config .config/wt.toml                 Project hooks, dev server URL                   ✓                  

Organizations can also deploy a system-wide config file for shared defaults — run wt config show for the platform-specific location.

User config — personal preferences:

  # ~/.config/worktrunk/config.toml
  worktree-path = ".worktrees/{{ branch | sanitize }}"
  
  [commit.generation]
  command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"

Project config — shared team settings:

  # .config/wt.toml
  [pre-start]
  deps = "npm ci"
  
  [pre-merge]
  test = "npm test"

USER CONFIGURATION

Create with wt config create. Values shown are defaults unless noted otherwise.

Location:

- macOS/Linux: ~/.config/worktrunk/config.toml (or $XDG_CONFIG_HOME if set)
- Windows: %APPDATA%\worktrunk\config.toml

Worktree path template

Controls where new worktrees are created.

Available template variables:

- {{ repo_path }} — absolute path to the repository root (e.g., /Users/me/code/myproject. Or for bare repos, the bare directory itself)
- {{ repo }} — repository directory name (e.g., myproject)
- {{ owner }} — primary remote owner path (may include subgroups like group/subgroup)
- {{ branch }} — raw branch name (e.g., feature/auth)
- {{ branch | sanitize }} — filesystem-safe: / and \ become - (e.g., feature-auth)
- {{ branch | sanitize_db }} — database-safe: lowercase, underscores, hash suffix (e.g., feature_auth_x7k)

Examples for repo at ~/code/myproject, branch feature/auth:

Default — sibling directory (~/code/myproject.feature-auth):

  worktree-path = "{{ repo_path }}/../{{ repo }}.{{ branch | sanitize }}"

Inside the repository (~/code/myproject/.worktrees/feature-auth):

  worktree-path = "{{ repo_path }}/.worktrees/{{ branch | sanitize }}"

Centralized worktrees directory (~/worktrees/myproject/feature-auth):

  worktree-path = "~/worktrees/{{ repo }}/{{ branch | sanitize }}"

By remote owner path (~/development/max-sixty/myproject/feature/auth):

  worktree-path = "~/development/{{ owner }}/{{ repo }}/{{ branch }}"

Bare repository (~/code/myproject/feature-auth):

  worktree-path = "{{ repo_path }}/../{{ branch | sanitize }}"

~ expands to the home directory. Relative paths resolve from repo_path.

LLM commit messages

Generate commit messages automatically during merge. Requires an external CLI tool.

Claude Code

  [commit.generation]
  command = "CLAUDECODE= MAX_THINKING_TOKENS=0 claude -p --no-session-persistence --model=haiku --tools='' --disable-slash-commands --setting-sources='' --system-prompt=''"

Codex

  [commit.generation]
  command = "codex exec -m gpt-5.1-codex-mini -c model_reasoning_effort='low' -c system_prompt='' --sandbox=read-only --json - | jq -sr '[.[] | select(.item.type? == \"agent_message\")] | last.item.text'"

OpenCode

  [commit.generation]
  command = "opencode run -m anthropic/claude-haiku-4.5 --variant fast"

llm

  [commit.generation]
  command = "llm -m claude-haiku-4.5"

aichat

  [commit.generation]
  command = "aichat -m claude:claude-haiku-4.5"

See LLM commits docs for setup and Custom prompt templates for template customization.

Command config

List

Persistent flag values for wt list. Override on command line as needed.

  [list]
  summary = false    # Enable LLM branch summaries (requires [commit.generation])
  
  full = false       # Show CI, main…± diffstat, and LLM summaries (--full)
  branches = false   # Include branches without worktrees (--branches)
  remotes = false    # Include remote-only branches (--remotes)
  
  task-timeout-ms = 0   # Kill individual git commands after N ms; 0 disables
  timeout-ms = 0        # Wall-clock budget for the entire collect phase; 0 disables

Commit

Shared by wt step commit, wt step squash, and wt merge.

  [commit]
  stage = "all"      # What to stage before commit: "all", "tracked", or "none"

Merge

Most flags are on by default. Set to false to change default behavior.

  [merge]
  squash = true      # Squash commits into one (--no-squash to preserve history)
  commit = true      # Commit uncommitted changes first (--no-commit to skip)
  rebase = true      # Rebase onto target before merge (--no-rebase to skip)
  remove = true      # Remove worktree after merge (--no-remove to keep)
  verify = true      # Run project hooks (--no-hooks to skip)
  ff = true          # Fast-forward merge (--no-ff to create a merge commit instead)

Switch

  [switch]
  cd = true          # Change directory after switching (--no-cd to skip)
  
  [switch.picker]
  pager = "delta --paging=never"   # Example: override git's core.pager for diff preview

Step

  [step.copy-ignored]
  exclude = []   # Additional excludes (e.g., [".cache/", ".turbo/"])

Built-in excludes always apply: VCS metadata directories (.bzr/, .hg/, .jj/, .pijul/, .sl/, .svn/) and tool-state directories (.conductor/, .entire/, .pi/, .worktrees/). User config and project config exclusions are combined.

Aliases

Command templates that run as wt <name>. See the Extending Worktrunk guide for usage and flags.

  [aliases]
  greet = "echo Hello from {{ branch }}"
  url = "echo http://localhost:{{ branch | hash_port }}"

Aliases defined here apply to all projects. For project-specific aliases, use the project config [aliases] section instead.

User project-specific settings

For context:

- Project config settings are shared with teammates.
- User configs generally apply to all projects.
- User configs _also_ has a [projects] table which holds project-specific settings for the user, such as worktree layout and setting overrides. That's what this section covers.

Entries are keyed by project identifier (e.g., github.com/user/repo). Scalar values (like worktree-path) replace the global value; everything else (hooks, aliases, etc.) appends, global first.

  [projects."github.com/user/repo"]
  worktree-path = ".worktrees/{{ branch | sanitize }}"
  list.full = true
  merge.squash = false
  pre-start.env = "cp .env.example .env"
  step.copy-ignored.exclude = [".repo-local-cache/"]
  aliases.deploy = "make deploy BRANCH={{ branch }}"

Custom prompt templates

Templates use minijinja syntax.

Commit template

Available variables:

- {{ git_diff }}, {{ git_diff_stat }} — diff content
- {{ branch }}, {{ repo }} — context
- {{ recent_commits }} — recent commit messages

Default template:

  [commit.generation]
  template = """
  <task>Write a commit message for the staged changes below.</task>
  
  <format>
  - Subject line under 50 chars
  - For material changes, add a blank line then a body paragraph explaining the change
  - Output only the commit message, no quotes or code blocks
  </format>
  
  <style>
  - Imperative mood: "Add feature" not "Added feature"
  - Match recent commit style (conventional commits if used)
  - Describe the change, not the intent or benefit
  </style>
  
  <diffstat>
  {{ git_diff_stat }}
  </diffstat>
  
  <diff>
  {{ git_diff }}
  </diff>
  
  <context>
  Branch: {{ branch }}
  {% if recent_commits %}<recent_commits>
  {% for commit in recent_commits %}- {{ commit }}
  {% endfor %}</recent_commits>{% endif %}
  </context>
  
  """

Squash template

Available variables (in addition to commit template variables):

- {{ commits }} — list of commits being squashed
- {{ target_branch }} — merge target branch

Default template:

  [commit.generation]
  squash-template = """
  <task>Write a commit message for the combined effect of these commits.</task>
  
  <format>
  - Subject line under 50 chars
  - For material changes, add a blank line then a body paragraph explaining the change
  - Output only the commit message, no quotes or code blocks
  </format>
  
  <style>
  - Imperative mood: "Add feature" not "Added feature"
  - Match the style of commits being squashed (conventional commits if used)
  - Describe the change, not the intent or benefit
  </style>
  
  <commits branch="{{ branch }}" target="{{ target_branch }}">
  {% for commit in commits %}- {{ commit }}
  {% endfor %}</commits>
  
  <diffstat>
  {{ git_diff_stat }}
  </diffstat>
  
  <diff>
  {{ git_diff }}
  </diff>
  
  """

Hooks

See wt hook for hook types, execution order, template variables, and examples. User hooks apply to all projects; project hooks apply only to that repository.
PROJECT CONFIGURATION

Project configuration lets teams share repository-specific settings — hooks, dev server URLs, and other defaults. The file lives in .config/wt.toml and is typically checked into version control.

To create a starter file with commented-out examples, run wt config create --project.

Hooks

Project hooks apply to this repository only. See wt hook for hook types, execution order, and examples.

  pre-start = "npm ci"
  post-start = "npm run dev"
  pre-merge = "npm test"

Dev server URL

URL column in wt list (dimmed when port not listening):

  [list]
  url = "http://localhost:{{ branch | hash_port }}"

Forge platform override

Override platform detection for SSH aliases or self-hosted instances:

  [forge]
  platform = "github"  # or "gitlab"
  hostname = "github.example.com"  # Example: API host (GHE / self-hosted GitLab)

Copy-ignored excludes

Additional excludes for wt step copy-ignored:

  [step.copy-ignored]
  exclude = [".cache/", ".turbo/"]

Built-in excludes always apply: VCS metadata directories (.bzr/, .hg/, .jj/, .pijul/, .sl/, .svn/) and tool-state directories (.conductor/, .entire/, .pi/, .worktrees/). User config and project config exclusions are combined.

Aliases

Command templates that run as wt <name>. See the Extending Worktrunk guide for usage and flags.

  [aliases]
  deploy = "make deploy BRANCH={{ branch }}"
  url = "echo http://localhost:{{ branch | hash_port }}"

Aliases defined here are shared with teammates. For personal aliases, use the user config [aliases] section instead.

SHELL INTEGRATION

Worktrunk needs shell integration to change directories when switching worktrees. Install with:

  wt config shell install

For manual setup, see wt config shell init --help.

Without shell integration, wt switch prints the target directory but cannot cd into it.

First-run prompts

On first run without shell integration, Worktrunk offers to install it. Similarly, on first commit without LLM configuration, it offers to configure a detected tool (claude, codex). Declining sets skip-shell-integration-prompt or skip-commit-generation-prompt automatically.

OTHER

Environment variables

All user config options can be overridden with environment variables using the WORKTRUNK_ prefix.

Naming convention

Config keys use kebab-case (worktree-path), while env vars use SCREAMING_SNAKE_CASE (WORKTRUNK_WORKTREE_PATH). The conversion happens automatically.

For nested config sections, use double underscores to separate levels:

          Config                   Environment Variable          
 ───────────────────────── ───────────────────────────────────── 
 worktree-path             WORKTRUNK_WORKTREE_PATH               
 commit.generation.command WORKTRUNK_COMMIT__GENERATION__COMMAND 
 commit.stage              WORKTRUNK_COMMIT__STAGE               

Note the single underscore after WORKTRUNK and double underscores between nested keys.

Example: CI/testing override

Override the LLM command in CI to use a mock:

  WORKTRUNK_COMMIT__GENERATION__COMMAND="echo 'test: automated commit'" wt merge

Other environment variables

             Variable                                                      Purpose                                         
 ───────────────────────────────── ─────────────────────────────────────────────────────────────────────────────────────── 
 WORKTRUNK_BIN                     Override binary path for shell wrappers; useful for testing dev builds                  
 WORKTRUNK_CONFIG_PATH             Override user config file location                                                      
 WORKTRUNK_SYSTEM_CONFIG_PATH      Override system config file location                                                    
 WORKTRUNK_PROJECT_CONFIG_PATH     Override project config file location (defaults to .config/wt.toml)                     
 XDG_CONFIG_DIRS                   Colon-separated system config directories (default: /etc/xdg)                           
 WORKTRUNK_DIRECTIVE_CD_FILE       Internal: set by shell wrappers. wt writes a raw path; the wrapper cds to it            
 WORKTRUNK_DIRECTIVE_EXEC_FILE     Internal: set by shell wrappers. wt writes shell commands; the wrapper sources the file 
 WORKTRUNK_SHELL                   Internal: set by shell wrappers to indicate shell type (e.g., powershell)               
 WORKTRUNK_MAX_CONCURRENT_COMMANDS Max parallel git commands (default: 32). Lower if hitting file descriptor limits.       
 NO_COLOR                          Disable colored output (standard)                                                       
 CLICOLOR_FORCE                    Force colored output even when not a TTY                                                

----- stderr -----