Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

refactor: simplify help snapshot tests and remove dead README sync code (#783)

Maximilian Roos16f763214351
diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rs
index 315ed871d..753f2d9d2 100644
--- a/tests/integration_tests/help.rs
+++ b/tests/integration_tests/help.rs
@@ -19,9 +19,6 @@ use rstest::rstest;
fn snapshot_help(test_name: &str, args: &[&str]) {
let mut settings = Settings::clone_current();
settings.set_snapshot_path("../snapshots");
- // Remove trailing ANSI reset codes at end of lines for cross-platform consistency
- settings.add_filter(r"\x1b\[0m$", "");
- settings.add_filter(r"\x1b\[0m\n", "\n");
settings.bind(|| {
let mut cmd = wt_command();
cmd.args(args);
@@ -125,9 +122,6 @@ fn test_help_md_subcommand() {
fn test_help_list_narrow_terminal() {
let mut settings = Settings::clone_current();
settings.set_snapshot_path("../snapshots");
- // Remove trailing ANSI reset codes for cross-platform consistency
- settings.add_filter(r"\x1b\[0m$", "");
- settings.add_filter(r"\x1b\[0m\n", "\n");
settings.bind(|| {
let mut cmd = wt_command();
cmd.env("COLUMNS", "80");
@@ -156,9 +150,6 @@ fn test_nested_subcommand_suggestion(
) {
let mut settings = Settings::clone_current();
settings.set_snapshot_path("../snapshots");
- // Remove trailing ANSI reset codes for cross-platform consistency
- settings.add_filter(r"\x1b\[0m$", "");
- settings.add_filter(r"\x1b\[0m\n", "\n");
settings.bind(|| {
let mut cmd = wt_command();
cmd.arg(subcommand);
diff --git a/tests/integration_tests/readme_sync.rs b/tests/integration_tests/readme_sync.rs
index 3d43ff510..4b8a62703 100644
--- a/tests/integration_tests/readme_sync.rs
+++ b/tests/integration_tests/readme_sync.rs
@@ -37,11 +37,7 @@ static MARKER_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
.unwrap()
});
-/// Regex to strip ANSI escape codes (actual escape sequences)
-static ANSI_ESCAPE_REGEX: LazyLock<Regex> =
- LazyLock::new(|| Regex::new(r"\x1b\[[0-9;]*m").unwrap());
-
-/// Regex to strip literal bracket notation (as stored in snapshots)
+/// Regex for literal bracket notation (as stored in snapshots) - used by literal_to_escape
static ANSI_LITERAL_REGEX: LazyLock<Regex> = LazyLock::new(|| Regex::new(r"\[[0-9;]*m").unwrap());
/// Regex to find docs snapshot markers (HTML output)
@@ -121,8 +117,6 @@ static ZOLA_FIGURE_PATTERN: LazyLock<Regex> = LazyLock::new(|| {
/// Output format for section updates
enum OutputFormat {
- /// README: plain text in ```console``` code block
- Readme,
/// Docs: HTML with ANSI colors in {% terminal() %} shortcode
DocsHtml,
/// Unwrapped: raw markdown content (help commands, doc sections)
@@ -155,33 +149,20 @@ impl MarkerType {
/// Get the OutputFormat for this marker type
fn output_format(&self) -> OutputFormat {
match self {
- Self::Snapshot => OutputFormat::Readme,
+ Self::Snapshot => unreachable!("README has no snapshot markers"),
Self::Help | Self::Section => OutputFormat::Unwrapped,
}
}
- /// Strip wrapper from content based on marker type
- /// Snapshots are wrapped in ```console```, help/sections are unwrapped
+ /// Extract inner content (help/sections are unwrapped)
fn extract_inner(&self, content: &str) -> String {
match self {
- Self::Snapshot => strip_code_block(content),
+ Self::Snapshot => unreachable!("README has no snapshot markers"),
Self::Help | Self::Section => content.to_string(),
}
}
}
-/// Regex to strip code block wrapper from content
-static CODE_BLOCK_REGEX: LazyLock<Regex> =
- LazyLock::new(|| Regex::new(r"(?s)^```\w*\n(.*)\n```$").unwrap());
-
-/// Strip code block wrapper if present, returning inner content
-fn strip_code_block(content: &str) -> String {
- CODE_BLOCK_REGEX
- .captures(content.trim())
- .map(|cap| cap.get(1).unwrap().as_str().to_string())
- .unwrap_or_else(|| content.to_string())
-}
-
/// Parse a snapshot file, returning the user-facing output content
///
/// Handles:
@@ -249,12 +230,6 @@ fn replace_placeholders(content: &str) -> String {
/// Format replacement content based on output format
fn format_replacement(id: &str, content: &str, format: &OutputFormat) -> String {
match format {
- OutputFormat::Readme => {
- format!(
- "<!-- ⚠️ AUTO-GENERATED from {} — edit source to update -->\n\n```console\n{}\n```\n\n<!-- END AUTO-GENERATED -->",
- id, content
- )
- }
OutputFormat::DocsHtml => {
format!(
"<!-- ⚠️ AUTO-GENERATED-HTML from {} — edit source to update -->\n\n{{% terminal() %}}\n{}\n{{% end %}}\n\n<!-- END AUTO-GENERATED -->",
@@ -404,12 +379,6 @@ fn expand_command_placeholders(content: &str, snapshots_dir: &Path) -> Result<St
Ok(result)
}
-/// Strip ANSI escape codes from text
-fn strip_ansi(text: &str) -> String {
- let text = ANSI_ESCAPE_REGEX.replace_all(text, "");
- ANSI_LITERAL_REGEX.replace_all(&text, "").to_string()
-}
-
/// Convert literal bracket notation [32m to actual escape sequences \x1b[32m
fn literal_to_escape(text: &str) -> String {
ANSI_LITERAL_REGEX
@@ -420,23 +389,6 @@ fn literal_to_escape(text: &str) -> String {
.to_string()
}
-/// Parse content from an insta snapshot file, optionally including command line.
-/// Command line comes from the README (preserved during update), not the snapshot.
-fn parse_snapshot_with_command(
- path: &Path,
- readme_command: Option<&str>,
-) -> Result<String, String> {
- let raw = fs::read_to_string(path)
- .map_err(|e| format!("Failed to read {}: {}", path.display(), e))?;
-
- let content = strip_ansi(&parse_snapshot_raw(&raw));
-
- Ok(match readme_command {
- Some(cmd) => format!("{}\n{}", cmd, content),
- None => content,
- })
-}
-
/// Trim trailing whitespace from each line and overall.
/// Preserves leading spaces (e.g., two-space gutter before table headers in `wt list`).
fn trim_lines(content: &str) -> String {
@@ -566,6 +518,7 @@ fn get_help_output(id: &str, project_root: &Path) -> Result<String, String> {
// Use the already-built binary from cargo test (wt_command provides isolation)
let output = wt_command()
+ .env("NO_COLOR", "1") // Plain text for README
.args(&args[1..]) // Skip "wt" prefix
.current_dir(project_root)
.output()
@@ -581,9 +534,6 @@ fn get_help_output(id: &str, project_root: &Path) -> Result<String, String> {
stderr.to_string()
};
- // Strip ANSI codes
- let help_output = strip_ansi(&help_output);
-
// Trim trailing whitespace from each line and join
let help_output = help_output
.lines()
@@ -788,21 +738,14 @@ fn get_docs_section_for_readme(id: &str, project_root: &Path) -> Result<String,
/// Get content for a README marker based on its type
///
-/// Handles all marker types: snapshots (.snap), help (`cmd`), sections (#anchor)
+/// Handles help (`cmd`) and section (#anchor) markers.
fn get_readme_content(
id: &str,
- current_content: &str,
+ _current_content: &str,
project_root: &Path,
) -> Result<String, String> {
match MarkerType::from_id(id) {
- MarkerType::Snapshot => {
- // Extract existing command line from README if present
- let inner = strip_code_block(current_content);
- let existing_command = inner.lines().next().filter(|line| line.starts_with("$ "));
- let full_path = project_root.join(id);
- parse_snapshot_with_command(&full_path, existing_command)
- .map(|content| trim_lines(&replace_placeholders(&content)))
- }
+ MarkerType::Snapshot => unreachable!("README has no snapshot markers"),
MarkerType::Help => get_help_output(id, project_root),
MarkerType::Section => {
get_docs_section_for_readme(id, project_root).map(|c| trim_lines(&c))
@@ -813,12 +756,8 @@ fn get_readme_content(
/// Sync all README markers in a single pass
///
/// Processes all AUTO-GENERATED markers in one regex traversal:
-/// - Snapshots (.snap) - terminal output in ```console``` blocks
/// - Help commands (`cmd`) - rendered markdown from --help-md
/// - Doc sections (#anchor) - extracted content from docs
-///
-/// Replaces the previous 3-pass approach with a single pass, detecting
-/// marker type from ID characteristics (extension, backticks, # anchor).
fn sync_readme_markers(
readme_content: &str,
project_root: &Path,
diff --git a/tests/snapshots/integration__integration_tests__help__help_config.snap b/tests/snapshots/integration__integration_tests__help__help_config.snap
new file mode 100644
index 000000000..3eceaf18d
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config.snap
@@ -0,0 +1,382 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+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
+ 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: hooks, templates; -vv: debug report)
+
+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 ✓
+
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+Worktrunk User Configuration
+
+Create with wt config create.
+
+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. Paths are relative to the repository root.
+
+Variables:
+
+- {{ repo }} — repository directory name
+- {{ 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 — siblings in parent directory
+ # Creates: ~/code/myproject.feature-auth
+ worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+ 
+ # Inside the repository
+ # Creates: ~/code/myproject/.worktrees/feature-auth
+ worktree-path = ".worktrees/{{ branch | sanitize }}"
+ 
+ # Namespaced (useful when multiple repos share a parent directory)
+ # Creates: ~/code/worktrees/myproject/feature-auth
+ worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+ 
+ # Nested bare repo (git clone --bare <url> project/.git)
+ # Creates: ~/code/project/feature-auth (sibling to .git)
+ worktree-path = "../{{ branch | sanitize }}"
+
+LLM commit messages
+
+Generate commit messages automatically during merge. Requires an external CLI tool. See LLM commits docs for setup and template customization.
+
+Using llm (install: pip install llm llm-anthropic):
+
+ [commit-generation]
+ command = "llm"
+ args = ["-m", "claude-haiku-4.5"]
+
+Using aichat:
+
+ [commit-generation]
+ command = "aichat"
+ args = ["-m", "claude:claude-haiku-4.5"]
+
+See Custom prompt templates for inline template options.
+
+Commands
+
+List
+
+Persistent flag values for wt list. Override on command line as needed.
+
+ [list]
+ full = false # Show CI status and main…± diffstat columns (--full)
+ branches = false # Include branches without worktrees (--branches)
+ remotes = false # Include remote-only branches (--remotes)
+
+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
+
+All 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-verify to skip)
+
+Select
+
+Pager behavior for wt select diff previews.
+
+ [select]
+ # Pager command with flags for diff preview (overrides git's core.pager)
+ # Use this to specify pager flags needed for non-TTY contexts
+ # Example:
+ # pager = "delta --paging=never"
+
+Per-project settings (Experimental)
+
+Per-project settings are keyed by project identifier (e.g., github.com/user/repo).
+These contain approved hook commands plus optional overrides of global settings.
+Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
+
+ [projects."github.com/user/repo"]
+ # Approved hook commands (auto-populated when approving on first run)
+ approved-commands = ["npm ci", "npm test"]
+ 
+ # Optional overrides (omit to use global settings)
+ worktree-path = ".worktrees/{{ branch | sanitize }}"
+ list.full = true
+ merge.squash = false
+
+For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at <repo>/.config/wt.toml. Run wt config create --project to create one, or see wt hook docs.
+
+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 = """
+ Write a commit message for the staged changes below.
+ 
+ <format>
+ - Subject under 50 chars, blank line, then optional body
+ - 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 = """
+ Combine these commits into a single commit message.
+ 
+ <format>
+ - Subject under 50 chars, blank line, then optional body
+ - 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>
+ 
+ """
+
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+Worktrunk Project Configuration
+
+The project config defines lifecycle hooks and project-specific settings. This file is checked into version control and shared across the team.
+
+Create .config/wt.toml in the repository root:
+
+ [post-create]
+ install = "npm ci"
+ 
+ [pre-merge]
+ test = "npm test"
+ lint = "npm run lint"
+
+See wt hook for complete documentation on hook types, execution order, template variables, and JSON context.
+
+Dev server URL
+
+The [list] section adds a URL column to wt list:
+
+ [list]
+ url = "http://localhost:{{ branch | hash_port }}"
+
+URLs are dimmed when the port isn't listening.
+
+CI platform override
+
+The [ci] section overrides CI platform detection for GitHub Enterprise or self-hosted GitLab with custom domains:
+
+ [ci]
+ platform = "github" # or "gitlab"
+
+By default, the platform is detected from the remote URL. Use this when URL detection fails (e.g., git.mycompany.com instead of github.mycompany.com).
+
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+Shell integration
+
+Worktrunk needs shell integration to change directories when switching worktrees. Install with:
+
+ wt config shell install
+
+Or manually add to the shell config:
+
+ # For bash: add to ~/.bashrc
+ eval "$(wt config shell init bash)"
+ 
+ # For zsh: add to ~/.zshrc
+ eval "$(wt config shell init zsh)"
+ 
+ # For fish: add to ~/.config/fish/config.fish
+ wt config shell init fish | source
+
+Without shell integration, wt switch prints the target directory but cannot cd into it.
+
+Skip first-run prompt
+
+On first run without shell integration, Worktrunk offers to install it. Suppress this prompt in CI or automated environments:
+
+ skip-shell-integration-prompt = true
+
+Or via environment variable:
+
+ export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
+
+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-generation.args WORKTRUNK_COMMIT_GENERATION__ARGS
+
+Note the single underscore after WORKTRUNK and double underscores between nested keys.
+
+Array values
+
+Array config values like args = ["-m", "claude-haiku"] can be specified as a single string in environment variables:
+
+ export WORKTRUNK_COMMIT_GENERATION__ARGS="-m claude-haiku"
+
+Example: CI/testing override
+
+Override the LLM command in CI to use a mock:
+
+ WORKTRUNK_COMMIT_GENERATION__COMMAND=echo \
+ WORKTRUNK_COMMIT_GENERATION__ARGS="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_DIRECTIVE_FILE Internal: set by shell wrappers to enable directory changes
+ 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
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
index a56ab1174..972245d47 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -25,329 +25,329 @@ exit_code: 0
----- stderr -----
wt config create - Create configuration file
-Usage: wt config create [OPTIONS]
+Usage: wt config create [OPTIONS]
-Options:
- --project
+Options:
+ --project
Create project config (.config/wt.toml) instead of user config
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
-User config
+User config
Creates ~/.config/worktrunk/config.toml with the following content:
- # ## Worktrunk User Configuration
- #
- # Create with `wt config create`.
- #
- # 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. Paths are relative to the repository root.
- #
- # **Variables:**
- #
- # - `{{ repo }}` — repository directory name
- # - `{{ 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 — siblings in parent directory
- # # Creates: ~/code/myproject.feature-auth
- # worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
- #
- # # Inside the repository
- # # Creates: ~/code/myproject/.worktrees/feature-auth
- # worktree-path = ".worktrees/{{ branch | sanitize }}"
- #
- # # Namespaced (useful when multiple repos share a parent directory)
- # # Creates: ~/code/worktrees/myproject/feature-auth
- # worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
- #
- # # Nested bare repo (git clone --bare <url> project/.git)
- # # Creates: ~/code/project/feature-auth (sibling to .git)
- # worktree-path = "../{{ branch | sanitize }}"
- #
- # ## LLM commit messages
- #
- # Generate commit messages automatically during merge. Requires an external CLI tool. See LLM commits docs (https://worktrunk.dev/llm-commits/) for setup and template customization.
- #
- # Using llm (https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
- #
- # [commit-generation]
- # command = "llm"
- # args = ["-m", "claude-haiku-4.5"]
- #
- # Using aichat (https://github.com/sigoden/aichat):
- #
- # [commit-generation]
- # command = "aichat"
- # args = ["-m", "claude:claude-haiku-4.5"]
- #
- # See Custom prompt templates (#custom-prompt-templates) for inline template options.
- #
- # ## Commands
- #
- # ### List
- #
- # Persistent flag values for `wt list`. Override on command line as needed.
- #
- # [list]
- # full = false # Show CI status and main…± diffstat columns (--full)
- # branches = false # Include branches without worktrees (--branches)
- # remotes = false # Include remote-only branches (--remotes)
- #
- # ### 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
- #
- # All 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-verify to skip)
- #
- # ### Select
- #
- # Pager behavior for `wt select` diff previews.
- #
- # [select]
- # # Pager command with flags for diff preview (overrides git's core.pager)
- # # Use this to specify pager flags needed for non-TTY contexts
- # # Example:
- # # pager = "delta --paging=never"
- #
- # ### Per-project settings (Experimental)
- #
- # Per-project settings are keyed by project identifier (e.g., `github.com/user/repo`).
- # These contain approved hook commands plus optional overrides of global settings.
- # Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
- #
- # [projects."github.com/user/repo"]
- # # Approved hook commands (auto-populated when approving on first run)
- # approved-commands = ["npm ci", "npm test"]
- #
- # # Optional overrides (omit to use global settings)
- # worktree-path = ".worktrees/{{ branch | sanitize }}"
- # list.full = true
- # merge.squash = false
- #
- # For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see `wt hook` docs (https://worktrunk.dev/hook/).
- #
- # ### Custom prompt templates
- #
- # Templates use minijinja (https://docs.rs/minijinja/) syntax.
- #
- # #### Commit template
- #
- # Available variables:
- #
- # - `{{ git_diff }}`, `{{ git_diff_stat }}` — diff content
- # - `{{ branch }}`, `{{ repo }}` — context
- # - `{{ recent_commits }}` — recent commit messages
- #
- # Default template:
- #
- # <!-- DEFAULT_TEMPLATE_START -->
- # [commit-generation]
- # template = """
- # Write a commit message for the staged changes below.
- #
- # <format>
- # - Subject under 50 chars, blank line, then optional body
- # - 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>
- #
- # """
- # <!-- DEFAULT_TEMPLATE_END -->
- #
- # #### Squash template
- #
- # Available variables (in addition to commit template variables):
- #
- # - `{{ commits }}` — list of commits being squashed
- # - `{{ target_branch }}` — merge target branch
- #
- # Default template:
- #
- # <!-- DEFAULT_SQUASH_TEMPLATE_START -->
- # [commit-generation]
- # squash-template = """
- # Combine these commits into a single commit message.
- #
- # <format>
- # - Subject under 50 chars, blank line, then optional body
- # - 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>
- #
- # """
- # <!-- DEFAULT_SQUASH_TEMPLATE_END -->
+ # ## Worktrunk User Configuration
+ #
+ # Create with `wt config create`.
+ #
+ # 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. Paths are relative to the repository root.
+ #
+ # **Variables:**
+ #
+ # - `{{ repo }}` — repository directory name
+ # - `{{ 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 — siblings in parent directory
+ # # Creates: ~/code/myproject.feature-auth
+ # worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+ #
+ # # Inside the repository
+ # # Creates: ~/code/myproject/.worktrees/feature-auth
+ # worktree-path = ".worktrees/{{ branch | sanitize }}"
+ #
+ # # Namespaced (useful when multiple repos share a parent directory)
+ # # Creates: ~/code/worktrees/myproject/feature-auth
+ # worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+ #
+ # # Nested bare repo (git clone --bare <url> project/.git)
+ # # Creates: ~/code/project/feature-auth (sibling to .git)
+ # worktree-path = "../{{ branch | sanitize }}"
+ #
+ # ## LLM commit messages
+ #
+ # Generate commit messages automatically during merge. Requires an external CLI tool. See LLM commits docs (https://worktrunk.dev/llm-commits/) for setup and template customization.
+ #
+ # Using llm (https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
+ #
+ # [commit-generation]
+ # command = "llm"
+ # args = ["-m", "claude-haiku-4.5"]
+ #
+ # Using aichat (https://github.com/sigoden/aichat):
+ #
+ # [commit-generation]
+ # command = "aichat"
+ # args = ["-m", "claude:claude-haiku-4.5"]
+ #
+ # See Custom prompt templates (#custom-prompt-templates) for inline template options.
+ #
+ # ## Commands
+ #
+ # ### List
+ #
+ # Persistent flag values for `wt list`. Override on command line as needed.
+ #
+ # [list]
+ # full = false # Show CI status and main…± diffstat columns (--full)
+ # branches = false # Include branches without worktrees (--branches)
+ # remotes = false # Include remote-only branches (--remotes)
+ #
+ # ### 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
+ #
+ # All 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-verify to skip)
+ #
+ # ### Select
+ #
+ # Pager behavior for `wt select` diff previews.
+ #
+ # [select]
+ # # Pager command with flags for diff preview (overrides git's core.pager)
+ # # Use this to specify pager flags needed for non-TTY contexts
+ # # Example:
+ # # pager = "delta --paging=never"
+ #
+ # ### Per-project settings (Experimental)
+ #
+ # Per-project settings are keyed by project identifier (e.g., `github.com/user/repo`).
+ # These contain approved hook commands plus optional overrides of global settings.
+ # Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
+ #
+ # [projects."github.com/user/repo"]
+ # # Approved hook commands (auto-populated when approving on first run)
+ # approved-commands = ["npm ci", "npm test"]
+ #
+ # # Optional overrides (omit to use global settings)
+ # worktree-path = ".worktrees/{{ branch | sanitize }}"
+ # list.full = true
+ # merge.squash = false
+ #
+ # For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see `wt hook` docs (https://worktrunk.dev/hook/).
+ #
+ # ### Custom prompt templates
+ #
+ # Templates use minijinja (https://docs.rs/minijinja/) syntax.
+ #
+ # #### Commit template
+ #
+ # Available variables:
+ #
+ # - `{{ git_diff }}`, `{{ git_diff_stat }}` — diff content
+ # - `{{ branch }}`, `{{ repo }}` — context
+ # - `{{ recent_commits }}` — recent commit messages
+ #
+ # Default template:
+ #
+ # <!-- DEFAULT_TEMPLATE_START -->
+ # [commit-generation]
+ # template = """
+ # Write a commit message for the staged changes below.
+ #
+ # <format>
+ # - Subject under 50 chars, blank line, then optional body
+ # - 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>
+ #
+ # """
+ # <!-- DEFAULT_TEMPLATE_END -->
+ #
+ # #### Squash template
+ #
+ # Available variables (in addition to commit template variables):
+ #
+ # - `{{ commits }}` — list of commits being squashed
+ # - `{{ target_branch }}` — merge target branch
+ #
+ # Default template:
+ #
+ # <!-- DEFAULT_SQUASH_TEMPLATE_START -->
+ # [commit-generation]
+ # squash-template = """
+ # Combine these commits into a single commit message.
+ #
+ # <format>
+ # - Subject under 50 chars, blank line, then optional body
+ # - 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>
+ #
+ # """
+ # <!-- DEFAULT_SQUASH_TEMPLATE_END -->
-Project config
+Project config
With --project, creates .config/wt.toml in the current repository:
- # Worktrunk Project Configuration
- # Copy to: <repo>/.config/wt.toml
- #
- # Project-specific hooks that run automatically during worktree operations.
- # Check this file into git to share hooks across all developers.
- 
- # ============================================================================
- # Hook Formats
- # ============================================================================
- # All hooks support two formats:
- #
- # Single command:
- # post-create = "npm install"
- #
- # Named table (multiple commands):
- # [post-create]
- # deps = "npm install"
- # build = "npm run build"
- #
- # Named commands appear in output, making it easier to identify failures.
- 
- # ============================================================================
- # Template Variables — see https://worktrunk.dev/hook/#template-variables
- # ============================================================================
- # Common variables:
- # {{ repo }} - Repository directory name (e.g., "myproject")
- # {{ branch }} - Branch name (e.g., "feature/auth")
- # {{ worktree_path }} - Absolute path to worktree
- # {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)
- # {{ default_branch }} - Default branch name (e.g., "main")
- # {{ target }} - Target branch (merge hooks only)
- #
- # Filters:
- # {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")
- # {{ branch | sanitize_db }} - Database-safe identifier with hash suffix (e.g., "feature_auth_x7k")
- # {{ branch | hash_port }} - Deterministic port 10000-19999
- 
- # ============================================================================
- # Hooks
- # ============================================================================
- 
- # Post-Create: Runs after worktree creation, BLOCKS until complete
- # Use for: installing dependencies, setting up databases, copying configs
- #
- # [post-create]
- # deps = "npm ci"
- # env = "cp .env.example .env"
- 
- # Post-Start: Runs in BACKGROUND after worktree creation (parallel)
- # Use for: dev servers, file watchers, background builds
- # Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log
- #
- # [post-start]
- # server = "npm run dev -- --port {{ branch | hash_port }}"
- # watch = "npm run watch"
- 
- # Post-Switch: Runs in BACKGROUND after every switch (parallel)
- # Use for: terminal tab naming, tmux window titles, IDE notifications
- #
- # post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"
- 
- # Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)
- # Use for: formatters, linters, quick checks
- #
- # [pre-commit]
- # format = "npm run format:check"
- # lint = "npm run lint"
- 
- # Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)
- # Use for: tests, build verification
- #
- # [pre-merge]
- # test = "npm test"
- # build = "npm run build"
- 
- # Post-Merge: Runs after successful merge, BLOCKS
- # Use for: deployment, notifications
- #
- # post-merge = "echo 'Merged {{ branch }} to {{ target }}'"
- 
- # Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)
- # Use for: cleanup, stopping services
- #
- # pre-remove = "docker compose down"
- 
- # ============================================================================
- # Dev Server URL (shown in `wt list`)
- # ============================================================================
- # [list]
- # url = "http://localhost:{{ branch | hash_port }}"
- 
- # ============================================================================
- # CI Platform Override
- # ============================================================================
- # Override CI platform detection for GitHub Enterprise or self-hosted GitLab
- # with custom domains where URL detection fails.
- #
- # [ci]
- # platform = "github" # or "gitlab"
+ # Worktrunk Project Configuration
+ # Copy to: <repo>/.config/wt.toml
+ #
+ # Project-specific hooks that run automatically during worktree operations.
+ # Check this file into git to share hooks across all developers.
+ 
+ # ============================================================================
+ # Hook Formats
+ # ============================================================================
+ # All hooks support two formats:
+ #
+ # Single command:
+ # post-create = "npm install"
+ #
+ # Named table (multiple commands):
+ # [post-create]
+ # deps = "npm install"
+ # build = "npm run build"
+ #
+ # Named commands appear in output, making it easier to identify failures.
+ 
+ # ============================================================================
+ # Template Variables — see https://worktrunk.dev/hook/#template-variables
+ # ============================================================================
+ # Common variables:
+ # {{ repo }} - Repository directory name (e.g., "myproject")
+ # {{ branch }} - Branch name (e.g., "feature/auth")
+ # {{ worktree_path }} - Absolute path to worktree
+ # {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)
+ # {{ default_branch }} - Default branch name (e.g., "main")
+ # {{ target }} - Target branch (merge hooks only)
+ #
+ # Filters:
+ # {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")
+ # {{ branch | sanitize_db }} - Database-safe identifier with hash suffix (e.g., "feature_auth_x7k")
+ # {{ branch | hash_port }} - Deterministic port 10000-19999
+ 
+ # ============================================================================
+ # Hooks
+ # ============================================================================
+ 
+ # Post-Create: Runs after worktree creation, BLOCKS until complete
+ # Use for: installing dependencies, setting up databases, copying configs
+ #
+ # [post-create]
+ # deps = "npm ci"
+ # env = "cp .env.example .env"
+ 
+ # Post-Start: Runs in BACKGROUND after worktree creation (parallel)
+ # Use for: dev servers, file watchers, background builds
+ # Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log
+ #
+ # [post-start]
+ # server = "npm run dev -- --port {{ branch | hash_port }}"
+ # watch = "npm run watch"
+ 
+ # Post-Switch: Runs in BACKGROUND after every switch (parallel)
+ # Use for: terminal tab naming, tmux window titles, IDE notifications
+ #
+ # post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"
+ 
+ # Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)
+ # Use for: formatters, linters, quick checks
+ #
+ # [pre-commit]
+ # format = "npm run format:check"
+ # lint = "npm run lint"
+ 
+ # Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)
+ # Use for: tests, build verification
+ #
+ # [pre-merge]
+ # test = "npm test"
+ # build = "npm run build"
+ 
+ # Post-Merge: Runs after successful merge, BLOCKS
+ # Use for: deployment, notifications
+ #
+ # post-merge = "echo 'Merged {{ branch }} to {{ target }}'"
+ 
+ # Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)
+ # Use for: cleanup, stopping services
+ #
+ # pre-remove = "docker compose down"
+ 
+ # ============================================================================
+ # Dev Server URL (shown in `wt list`)
+ # ============================================================================
+ # [list]
+ # url = "http://localhost:{{ branch | hash_port }}"
+ 
+ # ============================================================================
+ # CI Platform Override
+ # ============================================================================
+ # Override CI platform detection for GitHub Enterprise or self-hosted GitLab
+ # with custom domains where URL detection fails.
+ #
+ # [ci]
+ # platform = "github" # or "gitlab"
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_create_long.snap
new file mode 100644
index 000000000..a56ab1174
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create_long.snap
@@ -0,0 +1,353 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - create
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config create - Create configuration file
+
+Usage: wt config create [OPTIONS]
+
+Options:
+ --project
+ Create project config (.config/wt.toml) instead of user config
+
+ -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: hooks, templates; -vv: debug report)
+
+User config
+
+Creates ~/.config/worktrunk/config.toml with the following content:
+
+ # ## Worktrunk User Configuration
+ #
+ # Create with `wt config create`.
+ #
+ # 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. Paths are relative to the repository root.
+ #
+ # **Variables:**
+ #
+ # - `{{ repo }}` — repository directory name
+ # - `{{ 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 — siblings in parent directory
+ # # Creates: ~/code/myproject.feature-auth
+ # worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+ #
+ # # Inside the repository
+ # # Creates: ~/code/myproject/.worktrees/feature-auth
+ # worktree-path = ".worktrees/{{ branch | sanitize }}"
+ #
+ # # Namespaced (useful when multiple repos share a parent directory)
+ # # Creates: ~/code/worktrees/myproject/feature-auth
+ # worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+ #
+ # # Nested bare repo (git clone --bare <url> project/.git)
+ # # Creates: ~/code/project/feature-auth (sibling to .git)
+ # worktree-path = "../{{ branch | sanitize }}"
+ #
+ # ## LLM commit messages
+ #
+ # Generate commit messages automatically during merge. Requires an external CLI tool. See LLM commits docs (https://worktrunk.dev/llm-commits/) for setup and template customization.
+ #
+ # Using llm (https://github.com/simonw/llm) (install: `pip install llm llm-anthropic`):
+ #
+ # [commit-generation]
+ # command = "llm"
+ # args = ["-m", "claude-haiku-4.5"]
+ #
+ # Using aichat (https://github.com/sigoden/aichat):
+ #
+ # [commit-generation]
+ # command = "aichat"
+ # args = ["-m", "claude:claude-haiku-4.5"]
+ #
+ # See Custom prompt templates (#custom-prompt-templates) for inline template options.
+ #
+ # ## Commands
+ #
+ # ### List
+ #
+ # Persistent flag values for `wt list`. Override on command line as needed.
+ #
+ # [list]
+ # full = false # Show CI status and main…± diffstat columns (--full)
+ # branches = false # Include branches without worktrees (--branches)
+ # remotes = false # Include remote-only branches (--remotes)
+ #
+ # ### 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
+ #
+ # All 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-verify to skip)
+ #
+ # ### Select
+ #
+ # Pager behavior for `wt select` diff previews.
+ #
+ # [select]
+ # # Pager command with flags for diff preview (overrides git's core.pager)
+ # # Use this to specify pager flags needed for non-TTY contexts
+ # # Example:
+ # # pager = "delta --paging=never"
+ #
+ # ### Per-project settings (Experimental)
+ #
+ # Per-project settings are keyed by project identifier (e.g., `github.com/user/repo`).
+ # These contain approved hook commands plus optional overrides of global settings.
+ # Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
+ #
+ # [projects."github.com/user/repo"]
+ # # Approved hook commands (auto-populated when approving on first run)
+ # approved-commands = ["npm ci", "npm test"]
+ #
+ # # Optional overrides (omit to use global settings)
+ # worktree-path = ".worktrees/{{ branch | sanitize }}"
+ # list.full = true
+ # merge.squash = false
+ #
+ # For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at `<repo>/.config/wt.toml`. Run `wt config create --project` to create one, or see `wt hook` docs (https://worktrunk.dev/hook/).
+ #
+ # ### Custom prompt templates
+ #
+ # Templates use minijinja (https://docs.rs/minijinja/) syntax.
+ #
+ # #### Commit template
+ #
+ # Available variables:
+ #
+ # - `{{ git_diff }}`, `{{ git_diff_stat }}` — diff content
+ # - `{{ branch }}`, `{{ repo }}` — context
+ # - `{{ recent_commits }}` — recent commit messages
+ #
+ # Default template:
+ #
+ # <!-- DEFAULT_TEMPLATE_START -->
+ # [commit-generation]
+ # template = """
+ # Write a commit message for the staged changes below.
+ #
+ # <format>
+ # - Subject under 50 chars, blank line, then optional body
+ # - 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>
+ #
+ # """
+ # <!-- DEFAULT_TEMPLATE_END -->
+ #
+ # #### Squash template
+ #
+ # Available variables (in addition to commit template variables):
+ #
+ # - `{{ commits }}` — list of commits being squashed
+ # - `{{ target_branch }}` — merge target branch
+ #
+ # Default template:
+ #
+ # <!-- DEFAULT_SQUASH_TEMPLATE_START -->
+ # [commit-generation]
+ # squash-template = """
+ # Combine these commits into a single commit message.
+ #
+ # <format>
+ # - Subject under 50 chars, blank line, then optional body
+ # - 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>
+ #
+ # """
+ # <!-- DEFAULT_SQUASH_TEMPLATE_END -->
+
+Project config
+
+With --project, creates .config/wt.toml in the current repository:
+
+ # Worktrunk Project Configuration
+ # Copy to: <repo>/.config/wt.toml
+ #
+ # Project-specific hooks that run automatically during worktree operations.
+ # Check this file into git to share hooks across all developers.
+ 
+ # ============================================================================
+ # Hook Formats
+ # ============================================================================
+ # All hooks support two formats:
+ #
+ # Single command:
+ # post-create = "npm install"
+ #
+ # Named table (multiple commands):
+ # [post-create]
+ # deps = "npm install"
+ # build = "npm run build"
+ #
+ # Named commands appear in output, making it easier to identify failures.
+ 
+ # ============================================================================
+ # Template Variables — see https://worktrunk.dev/hook/#template-variables
+ # ============================================================================
+ # Common variables:
+ # {{ repo }} - Repository directory name (e.g., "myproject")
+ # {{ branch }} - Branch name (e.g., "feature/auth")
+ # {{ worktree_path }} - Absolute path to worktree
+ # {{ primary_worktree_path }} - Main worktree (or default branch worktree for bare repos)
+ # {{ default_branch }} - Default branch name (e.g., "main")
+ # {{ target }} - Target branch (merge hooks only)
+ #
+ # Filters:
+ # {{ branch | sanitize }} - Replace / and \ with - (e.g., "feature-auth")
+ # {{ branch | sanitize_db }} - Database-safe identifier with hash suffix (e.g., "feature_auth_x7k")
+ # {{ branch | hash_port }} - Deterministic port 10000-19999
+ 
+ # ============================================================================
+ # Hooks
+ # ============================================================================
+ 
+ # Post-Create: Runs after worktree creation, BLOCKS until complete
+ # Use for: installing dependencies, setting up databases, copying configs
+ #
+ # [post-create]
+ # deps = "npm ci"
+ # env = "cp .env.example .env"
+ 
+ # Post-Start: Runs in BACKGROUND after worktree creation (parallel)
+ # Use for: dev servers, file watchers, background builds
+ # Output logged to .git/wt-logs/{branch}-project-post-start-{name}.log
+ #
+ # [post-start]
+ # server = "npm run dev -- --port {{ branch | hash_port }}"
+ # watch = "npm run watch"
+ 
+ # Post-Switch: Runs in BACKGROUND after every switch (parallel)
+ # Use for: terminal tab naming, tmux window titles, IDE notifications
+ #
+ # post-switch = "echo -ne '\\033]0;{{ branch }}\\007'"
+ 
+ # Pre-Commit: Runs before committing during merge, BLOCKS (fail-fast)
+ # Use for: formatters, linters, quick checks
+ #
+ # [pre-commit]
+ # format = "npm run format:check"
+ # lint = "npm run lint"
+ 
+ # Pre-Merge: Runs before merging to target, BLOCKS (fail-fast)
+ # Use for: tests, build verification
+ #
+ # [pre-merge]
+ # test = "npm test"
+ # build = "npm run build"
+ 
+ # Post-Merge: Runs after successful merge, BLOCKS
+ # Use for: deployment, notifications
+ #
+ # post-merge = "echo 'Merged {{ branch }} to {{ target }}'"
+ 
+ # Pre-Remove: Runs before worktree removal, BLOCKS (fail-fast)
+ # Use for: cleanup, stopping services
+ #
+ # pre-remove = "docker compose down"
+ 
+ # ============================================================================
+ # Dev Server URL (shown in `wt list`)
+ # ============================================================================
+ # [list]
+ # url = "http://localhost:{{ branch | hash_port }}"
+ 
+ # ============================================================================
+ # CI Platform Override
+ # ============================================================================
+ # Override CI platform detection for GitHub Enterprise or self-hosted GitLab
+ # with custom domains where URL detection fails.
+ #
+ # [ci]
+ # platform = "github" # or "gitlab"
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_long.snap b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
index 3eceaf18d..3be0a17e8 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -22,73 +22,73 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt config - Manage user & project configs
+wt config - Manage user & project configs
-Includes shell integration, hooks, and saved state.
+Includes shell integration, hooks, and saved state.
-Usage: wt config [OPTIONS] <COMMAND>
+Usage: wt config [OPTIONS] <COMMAND>
-Commands:
+Commands:
shell Shell integration setup
create Create configuration file
show Show configuration files & locations
state Manage internal data and cache
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
-Examples
+Examples
Install shell integration (required for directory switching):
- wt config shell install
+ wt config shell install
Create user config file with documented examples:
- wt config create
+ wt config create
Create project config file (.config/wt.toml) for hooks:
- wt config create --project
+ wt config create --project
Show current configuration and file locations:
- wt config show
+ wt config show
-Configuration files
+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 ✓
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-Worktrunk User Configuration
+Worktrunk User Configuration
Create with wt config create.
Location:
- macOS/Linux: ~/.config/worktrunk/config.toml (or $XDG_CONFIG_HOME if set)
-- Windows: %APPDATA%\worktrunk\config.toml
+- Windows: %APPDATA%\worktrunk\config.toml
-Worktree path template
+Worktree path template
Controls where new worktrees are created. Paths are relative to the repository root.
-Variables:
+Variables:
- {{ repo }} — repository directory name
- {{ branch }} — raw branch name (e.g., feature/auth)
@@ -97,101 +97,101 @@ Controls where new worktrees are created. Paths are relative to the repository r
Examples for repo at ~/code/myproject, branch feature/auth:
- # Default — siblings in parent directory
- # Creates: ~/code/myproject.feature-auth
- worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
- 
- # Inside the repository
- # Creates: ~/code/myproject/.worktrees/feature-auth
- worktree-path = ".worktrees/{{ branch | sanitize }}"
- 
- # Namespaced (useful when multiple repos share a parent directory)
- # Creates: ~/code/worktrees/myproject/feature-auth
- worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
- 
- # Nested bare repo (git clone --bare <url> project/.git)
- # Creates: ~/code/project/feature-auth (sibling to .git)
- worktree-path = "../{{ branch | sanitize }}"
-
-LLM commit messages
+ # Default — siblings in parent directory
+ # Creates: ~/code/myproject.feature-auth
+ worktree-path = "../{{ repo }}.{{ branch | sanitize }}"
+ 
+ # Inside the repository
+ # Creates: ~/code/myproject/.worktrees/feature-auth
+ worktree-path = ".worktrees/{{ branch | sanitize }}"
+ 
+ # Namespaced (useful when multiple repos share a parent directory)
+ # Creates: ~/code/worktrees/myproject/feature-auth
+ worktree-path = "../worktrees/{{ repo }}/{{ branch | sanitize }}"
+ 
+ # Nested bare repo (git clone --bare <url> project/.git)
+ # Creates: ~/code/project/feature-auth (sibling to .git)
+ worktree-path = "../{{ branch | sanitize }}"
+
+LLM commit messages
Generate commit messages automatically during merge. Requires an external CLI tool. See LLM commits docs for setup and template customization.
Using llm (install: pip install llm llm-anthropic):
- [commit-generation]
- command = "llm"
- args = ["-m", "claude-haiku-4.5"]
+ [commit-generation]
+ command = "llm"
+ args = ["-m", "claude-haiku-4.5"]
Using aichat:
- [commit-generation]
- command = "aichat"
- args = ["-m", "claude:claude-haiku-4.5"]
+ [commit-generation]
+ command = "aichat"
+ args = ["-m", "claude:claude-haiku-4.5"]
See Custom prompt templates for inline template options.
-Commands
+Commands
-List
+List
Persistent flag values for wt list. Override on command line as needed.
- [list]
- full = false # Show CI status and main…± diffstat columns (--full)
- branches = false # Include branches without worktrees (--branches)
- remotes = false # Include remote-only branches (--remotes)
+ [list]
+ full = false # Show CI status and main…± diffstat columns (--full)
+ branches = false # Include branches without worktrees (--branches)
+ remotes = false # Include remote-only branches (--remotes)
-Commit
+Commit
Shared by wt step commit, wt step squash, and wt merge.
- [commit]
- stage = "all" # What to stage before commit: "all", "tracked", or "none"
+ [commit]
+ stage = "all" # What to stage before commit: "all", "tracked", or "none"
-Merge
+Merge
All 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-verify to skip)
+ [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-verify to skip)
-Select
+Select
Pager behavior for wt select diff previews.
- [select]
- # Pager command with flags for diff preview (overrides git's core.pager)
- # Use this to specify pager flags needed for non-TTY contexts
- # Example:
- # pager = "delta --paging=never"
+ [select]
+ # Pager command with flags for diff preview (overrides git's core.pager)
+ # Use this to specify pager flags needed for non-TTY contexts
+ # Example:
+ # pager = "delta --paging=never"
-Per-project settings (Experimental)
+Per-project settings (Experimental)
Per-project settings are keyed by project identifier (e.g., github.com/user/repo).
These contain approved hook commands plus optional overrides of global settings.
Setting overrides (worktree-path, list, commit, merge) are new; approved-commands is stable.
- [projects."github.com/user/repo"]
- # Approved hook commands (auto-populated when approving on first run)
- approved-commands = ["npm ci", "npm test"]
- 
- # Optional overrides (omit to use global settings)
- worktree-path = ".worktrees/{{ branch | sanitize }}"
- list.full = true
- merge.squash = false
+ [projects."github.com/user/repo"]
+ # Approved hook commands (auto-populated when approving on first run)
+ approved-commands = ["npm ci", "npm test"]
+ 
+ # Optional overrides (omit to use global settings)
+ worktree-path = ".worktrees/{{ branch | sanitize }}"
+ list.full = true
+ merge.squash = false
For project-specific hooks (post-create, post-start, pre-merge, etc.), use a project config at <repo>/.config/wt.toml. Run wt config create --project to create one, or see wt hook docs.
-Custom prompt templates
+Custom prompt templates
Templates use minijinja syntax.
-Commit template
+Commit template
Available variables:
@@ -201,39 +201,39 @@ Available variables:
Default template:
- [commit-generation]
- template = """
- Write a commit message for the staged changes below.
- 
- <format>
- - Subject under 50 chars, blank line, then optional body
- - 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
+ [commit-generation]
+ template = """
+ Write a commit message for the staged changes below.
+ 
+ <format>
+ - Subject under 50 chars, blank line, then optional body
+ - 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):
@@ -242,106 +242,106 @@ Available variables (in addition to commit template variables):
Default template:
- [commit-generation]
- squash-template = """
- Combine these commits into a single commit message.
- 
- <format>
- - Subject under 50 chars, blank line, then optional body
- - 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>
- 
- """
-
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-
-Worktrunk Project Configuration
+ [commit-generation]
+ squash-template = """
+ Combine these commits into a single commit message.
+ 
+ <format>
+ - Subject under 50 chars, blank line, then optional body
+ - 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>
+ 
+ """
+
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+Worktrunk Project Configuration
The project config defines lifecycle hooks and project-specific settings. This file is checked into version control and shared across the team.
Create .config/wt.toml in the repository root:
- [post-create]
- install = "npm ci"
- 
- [pre-merge]
- test = "npm test"
- lint = "npm run lint"
+ [post-create]
+ install = "npm ci"
+ 
+ [pre-merge]
+ test = "npm test"
+ lint = "npm run lint"
See wt hook for complete documentation on hook types, execution order, template variables, and JSON context.
-Dev server URL
+Dev server URL
The [list] section adds a URL column to wt list:
- [list]
- url = "http://localhost:{{ branch | hash_port }}"
+ [list]
+ url = "http://localhost:{{ branch | hash_port }}"
URLs are dimmed when the port isn't listening.
-CI platform override
+CI platform override
The [ci] section overrides CI platform detection for GitHub Enterprise or self-hosted GitLab with custom domains:
- [ci]
- platform = "github" # or "gitlab"
+ [ci]
+ platform = "github" # or "gitlab"
By default, the platform is detected from the remote URL. Use this when URL detection fails (e.g., git.mycompany.com instead of github.mycompany.com).
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-Shell integration
+Shell integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
- wt config shell install
+ wt config shell install
Or manually add to the shell config:
- # For bash: add to ~/.bashrc
- eval "$(wt config shell init bash)"
- 
- # For zsh: add to ~/.zshrc
- eval "$(wt config shell init zsh)"
- 
- # For fish: add to ~/.config/fish/config.fish
- wt config shell init fish | source
+ # For bash: add to ~/.bashrc
+ eval "$(wt config shell init bash)"
+ 
+ # For zsh: add to ~/.zshrc
+ eval "$(wt config shell init zsh)"
+ 
+ # For fish: add to ~/.config/fish/config.fish
+ wt config shell init fish | source
Without shell integration, wt switch prints the target directory but cannot cd into it.
-Skip first-run prompt
+Skip first-run prompt
On first run without shell integration, Worktrunk offers to install it. Suppress this prompt in CI or automated environments:
- skip-shell-integration-prompt = true
+ skip-shell-integration-prompt = true
Or via environment variable:
- export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
+ export WORKTRUNK_SKIP_SHELL_INTEGRATION_PROMPT=true
-Environment variables
+Environment variables
All user config options can be overridden with environment variables using the WORKTRUNK_ prefix.
-Naming convention
+Naming convention
Config keys use kebab-case (worktree-path), while env vars use SCREAMING_SNAKE_CASE (WORKTRUNK_WORKTREE_PATH). The conversion happens automatically.
@@ -355,21 +355,21 @@ For nested config sections, use double underscores to separate levels:
Note the single underscore after WORKTRUNK and double underscores between nested keys.
-Array values
+Array values
Array config values like args = ["-m", "claude-haiku"] can be specified as a single string in environment variables:
- export WORKTRUNK_COMMIT_GENERATION__ARGS="-m claude-haiku"
+ export WORKTRUNK_COMMIT_GENERATION__ARGS="-m claude-haiku"
-Example: CI/testing override
+Example: CI/testing override
Override the LLM command in CI to use a mock:
- WORKTRUNK_COMMIT_GENERATION__COMMAND=echo \
- WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
-  wt merge
+ WORKTRUNK_COMMIT_GENERATION__COMMAND=echo \
+ WORKTRUNK_COMMIT_GENERATION__ARGS="test: automated commit" \
+  wt merge
-Other environment variables
+Other environment variables
Variable Purpose
───────────────────────────────── ─────────────────────────────────────────────────────────────────────────────────
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_shell.snap b/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
index e6d4f529b..ae9c354d1 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
@@ -25,18 +25,18 @@ exit_code: 0
----- stderr -----
wt config shell - Shell integration setup
-Usage: wt config shell [OPTIONS] <COMMAND>
+Usage: wt config shell [OPTIONS] <COMMAND>
-Commands:
+Commands:
init Generate shell integration code
install Write shell integration to config files
uninstall Remove shell integration from config files
show-theme Show output theme samples
-Options:
+Options:
-h, --help Print help
-Global Options:
+Global Options:
-C <path> Working directory for this command
--config <path> User config file path
-v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_shell_init.snap b/tests/snapshots/integration__integration_tests__help__help_config_shell_init.snap
new file mode 100644
index 000000000..6eb6f10bf
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_shell_init.snap
@@ -0,0 +1,69 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - shell
+ - init
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config shell init - Generate shell integration code
+
+Usage: wt config shell init [OPTIONS] <bash|fish|zsh|powershell>
+
+Arguments:
+ <bash|fish|zsh|powershell>
+ Shell to generate code for
+
+ [possible values: bash, fish, zsh, powershell]
+
+Options:
+ --cmd <CMD>
+ Command name for shell integration (defaults to binary name)
+
+ Use this to create shell integration for an alternate command name. For example, --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt conflicts with Windows Terminal.
+
+ -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: hooks, templates; -vv: debug report)
+
+Outputs shell code for eval or sourcing. Most users should run wt config shell install instead, which adds this automatically.
+
+Manual setup
+
+Add one line to the shell config:
+
+Bash (~/.bashrc):
+ eval "$(wt config shell init bash)"
+
+Fish (~/.config/fish/config.fish):
+ wt config shell init fish | source
+
+Zsh (~/.zshrc):
+ eval "$(wt config shell init zsh)"
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_shell_install.snap b/tests/snapshots/integration__integration_tests__help__help_config_shell_install.snap
new file mode 100644
index 000000000..6f58fdf1f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_shell_install.snap
@@ -0,0 +1,73 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - shell
+ - install
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config shell install - Write shell integration to config files
+
+Usage: wt config shell install [OPTIONS] [bash|fish|zsh|powershell]
+
+Arguments:
+ [bash|fish|zsh|powershell]
+ Shell to install (default: all)
+
+ [possible values: bash, fish, zsh, powershell]
+
+Options:
+ -y, --yes
+ Skip confirmation prompt
+
+ --dry-run
+ Show what would be changed
+
+ --cmd <CMD>
+ Command name for shell integration (defaults to binary name)
+
+ Use this to create shell integration for an alternate command name. For example, --cmd=git-wt creates a git-wt shell function instead of wt, useful on Windows where wt conflicts with Windows Terminal.
+
+ -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: hooks, templates; -vv: debug report)
+
+Detects existing shell config files and adds the integration line.
+
+Examples
+
+Install for all detected shells:
+ wt config shell install
+
+Install for specific shell only:
+ wt config shell install zsh
+
+Shows proposed changes and waits for confirmation before modifying any files.
+Use --yes to skip confirmation.
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_shell_show_theme.snap b/tests/snapshots/integration__integration_tests__help__help_config_shell_show_theme.snap
new file mode 100644
index 000000000..2e970383b
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_shell_show_theme.snap
@@ -0,0 +1,51 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - shell
+ - show-theme
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config shell show-theme - Show output theme samples
+
+Usage: wt config shell show-theme [OPTIONS]
+
+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: hooks, templates; -vv: debug report)
+
+Displays samples of all output message types to preview how worktrunk output will appear in the terminal.
+
+Message types
+
+- Progress, success, error, warning, hint, info
+- Gutter formatting for quoted content
+- Prompts for user input
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_shell_uninstall.snap b/tests/snapshots/integration__integration_tests__help__help_config_shell_uninstall.snap
new file mode 100644
index 000000000..12166c4d7
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_shell_uninstall.snap
@@ -0,0 +1,74 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - shell
+ - uninstall
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config shell uninstall - Remove shell integration from config files
+
+Usage: wt config shell uninstall [OPTIONS] [bash|fish|zsh|powershell]
+
+Arguments:
+ [bash|fish|zsh|powershell]
+ Shell to uninstall (default: all)
+
+ [possible values: bash, fish, zsh, powershell]
+
+Options:
+ -y, --yes
+ Skip confirmation prompt
+
+ --dry-run
+ Show what would be changed
+
+ -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: hooks, templates; -vv: debug report)
+
+Removes shell integration lines from config files.
+
+Examples
+
+Uninstall from all shells:
+ wt config shell uninstall
+
+Uninstall from specific shell only:
+ wt config shell uninstall zsh
+
+Skip confirmation prompt:
+ wt config shell uninstall --yes
+
+Version tolerance
+
+Detects various forms of the integration pattern regardless of:
+- Command prefix (wt, worktree, etc.)
+- Minor syntax variations between versions
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_short.snap b/tests/snapshots/integration__integration_tests__help__help_config_short.snap
index 00cab1d8d..1aff1624b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_short.snap
@@ -24,18 +24,18 @@ exit_code: 0
----- stderr -----
wt config - Manage user & project configs
-Usage: wt config [OPTIONS] <COMMAND>
+Usage: wt config [OPTIONS] <COMMAND>
-Commands:
+Commands:
shell Shell integration setup
create Create configuration file
show Show configuration files & locations
state Manage internal data and cache
-Options:
+Options:
-h, --help Print help (see more with '--help')
-Global Options:
+Global Options:
-C <path> Working directory for this command
--config <path> User config file path
-v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_show.snap b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
index 7877a13a8..241c2d41c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_show.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
@@ -25,23 +25,23 @@ exit_code: 0
----- stderr -----
wt config show - Show configuration files & locations
-Usage: wt config show [OPTIONS]
+Usage: wt config show [OPTIONS]
-Options:
- --full
+Options:
+ --full
Run diagnostic checks (CI tools, commit generation)
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Shows location and contents of user config (~/.config/worktrunk/config.toml)
@@ -49,11 +49,11 @@ and project config (.config/wt.toml).
If a config file doesn't exist, shows defaults that would be used.
-Full diagnostics
+Full diagnostics
Use --full to run diagnostic checks:
- wt config show --full
+ wt config show --full
This tests:
- CI tool status — Whether gh (GitHub) or glab (GitLab) is installed and authenticated
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state.snap b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
index 5cae455ad..281ec539b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
@@ -25,9 +25,9 @@ exit_code: 0
----- stderr -----
wt config state - Manage internal data and cache
-Usage: wt config state [OPTIONS] <COMMAND>
+Usage: wt config state [OPTIONS] <COMMAND>
-Commands:
+Commands:
default-branch Default branch setting
previous-branch Previous branch (for wt switch -)
ci-status CI status cache
@@ -37,47 +37,47 @@ Usage: wt config state [OPTIONS] <COMMAND>
get Get all stored state
clear Clear all stored state
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
State is stored in .git/ (config entries and log files), separate from configuration files.
Use wt config show to view file-based configuration.
-Keys
+Keys
- default-branch: The repository's default branch (main, master, etc.)
-- previous-branch: Previous branch for wt switch -
+- previous-branch: Previous branch for wt switch -
- ci-status: CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)
- marker: Custom status marker for a branch (shown in wt list)
- logs: Background operation logs
-Examples
+Examples
Get the default branch:
- wt config state default-branch
+ wt config state default-branch
Set the default branch manually:
- wt config state default-branch set main
+ wt config state default-branch set main
Set a marker for current branch:
- wt config state marker set "🚧 WIP"
+ wt config state marker set "🚧 WIP"
Clear all CI status cache:
- wt config state ci-status clear --all
+ wt config state ci-status clear --all
Show all stored state:
- wt config state get
+ wt config state get
Clear all stored state:
- wt config state clear
+ wt config state clear
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap
index 31231e88a..810e59951 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status.snap
@@ -26,36 +26,36 @@ exit_code: 0
----- stderr -----
wt config state ci-status - CI status cache
-Usage: wt config state ci-status [OPTIONS] [COMMAND]
+Usage: wt config state ci-status [OPTIONS] [COMMAND]
-Commands:
+Commands:
get Get CI status for a branch
clear Clear CI status cache
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Caches GitHub/GitLab CI status for display in wt list.
-How it works
+How it works
1. Platform detection — From [ci] platform in project config, or detected from remote URL (github.com → GitHub, gitlab.com → GitLab)
2. CLI requirement — Requires gh (GitHub) or glab (GitLab) CLI, authenticated
3. What's checked — PRs/MRs first, then branch pipelines for branches with upstream
4. Caching — Results cached 30-60 seconds per branch+commit
-Status values
+Status values
Status Meaning
───────── ───────────────────────────────────────
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status_clear.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status_clear.snap
new file mode 100644
index 000000000..a30e3e939
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status_clear.snap
@@ -0,0 +1,61 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - ci-status
+ - clear
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state ci-status clear - Clear CI status cache
+
+Usage: wt config state ci-status clear [OPTIONS]
+
+Options:
+ --branch <BRANCH>
+ Target branch (defaults to current)
+
+ --all
+ Clear all CI status cache
+
+ -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: hooks, templates; -vv: debug report)
+
+Examples
+
+Clear CI status for current branch:
+ wt config state ci-status clear
+
+Clear CI status for a specific branch:
+ wt config state ci-status clear --branch=feature
+
+Clear all CI status cache:
+ wt config state ci-status clear --all
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status_get.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status_get.snap
new file mode 100644
index 000000000..b01b3c3f2
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_ci_status_get.snap
@@ -0,0 +1,60 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - ci-status
+ - get
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state ci-status get - Get CI status for a branch
+
+Usage: wt config state ci-status get [OPTIONS]
+
+Options:
+ --branch <BRANCH>
+ Target branch (defaults to current)
+
+ -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: hooks, templates; -vv: debug report)
+
+Returns: passed, running, failed, conflicts, no-ci, or error.
+
+Examples
+
+Get CI status for current branch:
+ wt config state ci-status
+
+Get CI status for a specific branch:
+ wt config state ci-status get --branch=feature
+
+Clear cache and re-fetch:
+ wt config state ci-status clear && wt config state ci-status get
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_clear.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_clear.snap
index 3d59758c5..3a0f68cad 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_clear.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_clear.snap
@@ -26,20 +26,20 @@ exit_code: 0
----- stderr -----
wt config state clear - Clear all stored state
-Usage: wt config state clear [OPTIONS]
+Usage: wt config state clear [OPTIONS]
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Clears all stored state:
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
index 6be39e34d..c36ac36f7 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
@@ -26,34 +26,34 @@ exit_code: 0
----- stderr -----
wt config state default-branch - Default branch setting
-Usage: wt config state default-branch [OPTIONS] [COMMAND]
+Usage: wt config state default-branch [OPTIONS] [COMMAND]
-Commands:
+Commands:
get Get the default branch
set Set the default branch
clear Clear the default branch cache
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Useful in scripts to avoid hardcoding main or master:
- git rebase $(wt config state default-branch)
+ git rebase $(wt config state default-branch)
Without a subcommand, runs get. Use set to override, or clear then get to re-detect.
-Detection
+Detection
Worktrunk detects the default branch automatically:
@@ -66,6 +66,6 @@ Once detected, the result is cached in worktrunk.default-branch for fast
The local inference fallback uses these heuristics in order:
- If only one local branch exists, uses it
-- For bare repos or empty repos, checks symbolic-ref HEAD
-- Checks git config init.defaultBranch
-- Looks for common names: main, master, develop, trunk
+- For bare repos or empty repos, checks symbolic-ref HEAD
+- Checks git config init.defaultBranch
+- Looks for common names: main, master, develop, trunk
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch_clear.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch_clear.snap
new file mode 100644
index 000000000..27b0dcd3a
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch_clear.snap
@@ -0,0 +1,38 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - default-branch
+ - clear
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state default-branch clear - Clear the default branch cache
+
+Usage: wt config state default-branch clear [OPTIONS]
+
+Options:
+ -h, --help Print help
+
+Global Options:
+ -C <path> Working directory for this command
+ --config <path> User config file path
+ -v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch_get.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch_get.snap
new file mode 100644
index 000000000..fbf1ff0cc
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch_get.snap
@@ -0,0 +1,52 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - default-branch
+ - get
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state default-branch get - Get the default branch
+
+Usage: wt config state default-branch get [OPTIONS]
+
+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: hooks, templates; -vv: debug report)
+
+Examples
+
+Get the default branch:
+ wt config state default-branch
+
+Clear cache and re-detect:
+ wt config state default-branch clear && wt config state default-branch get
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch_set.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch_set.snap
new file mode 100644
index 000000000..b461ce0d0
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch_set.snap
@@ -0,0 +1,53 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - default-branch
+ - set
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state default-branch set - Set the default branch
+
+Usage: wt config state default-branch set [OPTIONS] <BRANCH>
+
+Arguments:
+ <BRANCH>
+ Branch name to set as default
+
+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: hooks, templates; -vv: debug report)
+
+Examples
+
+Set the default branch:
+ wt config state default-branch set main
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap
index 6840122fa..59c82bf6f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_get.snap
@@ -26,31 +26,31 @@ exit_code: 0
----- stderr -----
wt config state get - Get all stored state
-Usage: wt config state get [OPTIONS]
+Usage: wt config state get [OPTIONS]
-Options:
- --format <FORMAT>
+Options:
+ --format <FORMAT>
Output format (table, json)
[default: table]
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Shows all stored state including:
- Default branch: Cached result of querying remote for default branch
-- Previous branch: Previous branch for wt switch -
+- Previous branch: Previous branch for wt switch -
- Branch markers: User-defined branch notes
- CI status: Cached GitHub/GitLab CI status per branch (30s TTL)
- Hints: One-time hints that have been shown
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_hints.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_hints.snap
new file mode 100644
index 000000000..70c379fb9
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_hints.snap
@@ -0,0 +1,62 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - hints
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state hints - One-time hints shown in this repo
+
+Usage: wt config state hints [OPTIONS] [COMMAND]
+
+Commands:
+ get List hints that have been shown
+ clear Clear hints (re-show on next trigger)
+
+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: hooks, templates; -vv: debug report)
+
+Some hints show once per repo on first use, then are recorded in git config
+as worktrunk.hints.<name> = true.
+
+Current hints
+
+ Name Trigger Message
+ ───────────── ──────────────────────── ──────────────────────────────────────────────
+ worktree-path First wt switch --create Customize worktree locations: wt config create
+
+Examples
+
+ wt config state hints # list shown hints
+ wt config state hints clear # re-show all hints
+ wt config state hints clear NAME # re-show specific hint
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_hints_clear.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_hints_clear.snap
new file mode 100644
index 000000000..1da5ea7d7
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_hints_clear.snap
@@ -0,0 +1,58 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - hints
+ - clear
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state hints clear - Clear hints (re-show on next trigger)
+
+Usage: wt config state hints clear [OPTIONS] [NAME]
+
+Arguments:
+ [NAME]
+ Specific hint to clear (clears all if not specified)
+
+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: hooks, templates; -vv: debug report)
+
+Clears hint state so hints will show again on next trigger.
+
+Examples
+
+Clear all hints:
+ wt config state hints clear
+
+Clear a specific hint:
+ wt config state hints clear worktree-path
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_hints_get.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_hints_get.snap
new file mode 100644
index 000000000..322ccaa92
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_hints_get.snap
@@ -0,0 +1,51 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - hints
+ - get
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state hints get - List hints that have been shown
+
+Usage: wt config state hints get [OPTIONS]
+
+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: hooks, templates; -vv: debug report)
+
+Lists which one-time hints have been shown in this repository.
+
+Examples
+
+List shown hints:
+ wt config state hints
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap
index fc2cf7863..660c733f6 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_logs.snap
@@ -26,29 +26,29 @@ exit_code: 0
----- stderr -----
wt config state logs - Background operation logs
-Usage: wt config state logs [OPTIONS] [COMMAND]
+Usage: wt config state logs [OPTIONS] [COMMAND]
-Commands:
+Commands:
get List background operation log files
clear Clear background operation logs
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
View and manage logs from background operations.
-What's logged
+What's logged
Operation Log file
────────────────── ───────────────────────────────────────
@@ -57,23 +57,23 @@ View and manage logs from background operations.
Source is user or project depending on where the hook is defined.
-Location
+Location
All logs are stored in .git/wt-logs/ (in the main worktree's git directory).
-Behavior
+Behavior
- Overwrites — Same operation on same branch overwrites previous log
- Persists — Logs from deleted branches remain until manually cleared
- Shared — All worktrees write to the same log directory
-Examples
+Examples
List all log files:
- wt config state logs get
+ wt config state logs get
View a specific log:
- cat "$(git rev-parse --git-dir)/wt-logs/feature-project-post-start-build.log"
+ cat "$(git rev-parse --git-dir)/wt-logs/feature-project-post-start-build.log"
Clear all logs:
- wt config state logs clear
+ wt config state logs clear
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_logs_clear.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_logs_clear.snap
new file mode 100644
index 000000000..9b5b3b5d9
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_logs_clear.snap
@@ -0,0 +1,38 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - logs
+ - clear
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state logs clear - Clear background operation logs
+
+Usage: wt config state logs clear [OPTIONS]
+
+Options:
+ -h, --help Print help
+
+Global Options:
+ -C <path> Working directory for this command
+ --config <path> User config file path
+ -v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_logs_get.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_logs_get.snap
new file mode 100644
index 000000000..f8d8bbcef
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_logs_get.snap
@@ -0,0 +1,51 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - logs
+ - get
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state logs get - List background operation log files
+
+Usage: wt config state logs get [OPTIONS]
+
+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: hooks, templates; -vv: debug report)
+
+Lists log files from background operations like post-start commands and worktree removal.
+
+Examples
+
+List log files:
+ wt config state logs
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap
index c371cc7c8..7237403e0 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_marker.snap
@@ -26,48 +26,48 @@ exit_code: 0
----- stderr -----
wt config state marker - Branch markers
-Usage: wt config state marker [OPTIONS] [COMMAND]
+Usage: wt config state marker [OPTIONS] [COMMAND]
-Commands:
+Commands:
get Get marker for a branch
set Set marker for a branch
clear Clear marker for a branch
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Custom status text or emoji shown in the wt list Status column.
-Display
+Display
Markers appear at the start of the Status column:
- Branch Status Path
- main ^ ~/code/myproject
- feature 🚧↑ ~/code/myproject.feature
- bugfix 🤖!↑⇡ ~/code/myproject.bugfix
+ Branch Status Path
+ main ^ ~/code/myproject
+ feature 🚧↑ ~/code/myproject.feature
+ bugfix 🤖!↑⇡ ~/code/myproject.bugfix
-Use cases
+Use cases
- Work status — 🚧 WIP, ✅ ready for review, 🔥 urgent
- Agent tracking — The Claude Code plugin sets markers automatically
-- Notes — Any short text: "blocked", "needs tests"
+- Notes — Any short text: "blocked", "needs tests"
-Storage
+Storage
Stored in git config as worktrunk.state.<branch>.marker. Set directly with:
- git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
+ git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
Without a subcommand, runs get for the current branch. For --branch, use get --branch=NAME.
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_marker_clear.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_marker_clear.snap
new file mode 100644
index 000000000..be50c1bc2
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_marker_clear.snap
@@ -0,0 +1,61 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - marker
+ - clear
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state marker clear - Clear marker for a branch
+
+Usage: wt config state marker clear [OPTIONS]
+
+Options:
+ --branch <BRANCH>
+ Target branch (defaults to current)
+
+ --all
+ Clear all markers
+
+ -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: hooks, templates; -vv: debug report)
+
+Examples
+
+Clear marker for current branch:
+ wt config state marker clear
+
+Clear marker for a specific branch:
+ wt config state marker clear --branch=feature
+
+Clear all markers:
+ wt config state marker clear --all
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_marker_get.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_marker_get.snap
new file mode 100644
index 000000000..4a970a90c
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_marker_get.snap
@@ -0,0 +1,55 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - marker
+ - get
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state marker get - Get marker for a branch
+
+Usage: wt config state marker get [OPTIONS]
+
+Options:
+ --branch <BRANCH>
+ Target branch (defaults to current)
+
+ -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: hooks, templates; -vv: debug report)
+
+Examples
+
+Get marker for current branch:
+ wt config state marker
+
+Get marker for a specific branch:
+ wt config state marker get --branch=feature
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_marker_set.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_marker_set.snap
new file mode 100644
index 000000000..8651d7cc2
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_marker_set.snap
@@ -0,0 +1,59 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - marker
+ - set
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state marker set - Set marker for a branch
+
+Usage: wt config state marker set [OPTIONS] <VALUE>
+
+Arguments:
+ <VALUE>
+ Marker text (shown in wt list output)
+
+Options:
+ --branch <BRANCH>
+ Target branch (defaults to current)
+
+ -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: hooks, templates; -vv: debug report)
+
+Examples
+
+Set marker for current branch:
+ wt config state marker set "🚧 WIP"
+
+Set marker for a specific branch:
+ wt config state marker set "✅ ready" --branch=feature
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch.snap
index c99a618fa..9b3a85710 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch.snap
@@ -26,30 +26,30 @@ exit_code: 0
----- stderr -----
wt config state previous-branch - Previous branch (for wt switch -)
-Usage: wt config state previous-branch [OPTIONS] [COMMAND]
+Usage: wt config state previous-branch [OPTIONS] [COMMAND]
-Commands:
+Commands:
get Get the previous branch
set Set the previous branch
clear Clear the previous branch
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Enables wt switch - to return to the previous worktree, similar to cd - or git checkout -.
-How it works
+How it works
Updated automatically on every wt switch. Stored in git config as worktrunk.history.
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch_clear.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch_clear.snap
new file mode 100644
index 000000000..d7d76fb80
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch_clear.snap
@@ -0,0 +1,38 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - previous-branch
+ - clear
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state previous-branch clear - Clear the previous branch
+
+Usage: wt config state previous-branch clear [OPTIONS]
+
+Options:
+ -h, --help Print help
+
+Global Options:
+ -C <path> Working directory for this command
+ --config <path> User config file path
+ -v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch_get.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch_get.snap
new file mode 100644
index 000000000..e933ef89f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch_get.snap
@@ -0,0 +1,49 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - previous-branch
+ - get
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state previous-branch get - Get the previous branch
+
+Usage: wt config state previous-branch get [OPTIONS]
+
+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: hooks, templates; -vv: debug report)
+
+Examples
+
+Get the previous branch (used by wt switch -):
+ wt config state previous-branch
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch_set.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch_set.snap
new file mode 100644
index 000000000..109a01b74
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_previous_branch_set.snap
@@ -0,0 +1,53 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - state
+ - previous-branch
+ - set
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt config state previous-branch set - Set the previous branch
+
+Usage: wt config state previous-branch set [OPTIONS] <BRANCH>
+
+Arguments:
+ <BRANCH>
+ Branch name to set as previous
+
+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: hooks, templates; -vv: debug report)
+
+Examples
+
+Set the previous branch:
+ wt config state previous-branch set feature
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook.snap b/tests/snapshots/integration__integration_tests__help__help_hook.snap
new file mode 100644
index 000000000..9b62a8801
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook.snap
@@ -0,0 +1,416 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook - Run configured hooks
+
+Usage: wt hook [OPTIONS] <COMMAND>
+
+Commands:
+ show Show configured hooks
+ post-create Run post-create hooks
+ post-start Run post-start hooks
+ post-switch Run post-switch hooks
+ pre-commit Run pre-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
+ approvals Manage command approvals
+
+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: hooks, templates; -vv: debug report)
+
+Hooks are shell commands that run at key points in the worktree lifecycle — automatically during wt switch, wt merge, & wt remove, or on demand via wt hook <type>. Both user (~/.config/worktrunk/config.toml) and project (.config/wt.toml) hooks are supported.
+
+Hook types
+
+ Hook When Blocking Fail-fast
+ ─────────── ────────────────────────── ─────────────── ─────────
+ post-start After worktree created No (background) No
+ post-create After worktree created Yes No
+ post-switch After every switch No (background) No
+ pre-commit Before commit during merge Yes Yes
+ pre-merge Before merging to target Yes Yes
+ post-merge After successful merge Yes No
+ pre-remove Before worktree removed Yes Yes
+ post-remove After worktree removed No (background) No
+
+Blocking: Command waits for hook to complete before continuing.
+Fail-fast: First failure aborts the operation.
+
+Background hooks show a single-line summary by default. Use -v to see expanded command details.
+
+post-start
+
+Dev servers, long builds, file watchers, copying caches. Output logged to .git/wt-logs/{branch}-{source}-post-start-{name}.log.
+
+ [post-start]
+ copy = "wt step copy-ignored"
+ server = "npm run dev -- --port {{ branch | hash_port }}"
+
+post-create
+
+Tasks that must complete before post-start hooks or --execute run: dependency installation, environment file generation.
+
+ [post-create]
+ install = "npm ci"
+ env = "echo 'PORT={{ branch | hash_port }}' > .env.local"
+
+post-switch
+
+Triggers on all switch results: creating new worktrees, switching to existing ones, or staying on current. Output logged to .git/wt-logs/{branch}-{source}-post-switch-{name}.log.
+
+ [post-switch]
+ tmux = "[ -n \"$TMUX\" ] && tmux rename-window '{{ branch | sanitize }}'"
+
+pre-commit
+
+Formatters, linters, type checking — runs during wt merge before the squash commit.
+
+ [pre-commit]
+ format = "cargo fmt -- --check"
+ lint = "cargo clippy -- -D warnings"
+
+pre-merge
+
+Tests, security scans, build verification — runs after rebase, before merge to target.
+
+ [pre-merge]
+ test = "cargo test"
+ build = "cargo build --release"
+
+post-merge
+
+Deployment, notifications, installing updated binaries. Runs in the target branch worktree if it exists, otherwise the main worktree.
+
+ post-merge = "cargo install --path ."
+
+pre-remove
+
+Cleanup tasks before worktree is deleted, saving test artifacts, backing up state. Runs in the worktree being removed, with access to worktree files.
+
+ [pre-remove]
+ archive = "tar -czf ~/.wt-logs/{{ branch }}.tar.gz test-results/ logs/ 2>/dev/null || true"
+
+post-remove
+
+Cleanup tasks after worktree removal: stopping dev servers, removing containers, notifying external systems. All template variables reference the removed worktree, so cleanup scripts can identify resources to clean up. Output logged to .git/wt-logs/{branch}-{source}-post-remove-{name}.log.
+
+ [post-remove]
+ kill-server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"
+ remove-db = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
+
+During wt merge, hooks run in this order: pre-commit → pre-merge → pre-remove → post-remove → post-merge. See wt merge for the complete pipeline.
+
+Security
+
+Project commands require approval on first run:
+
+ ▲ repo needs approval to execute 3 commands:
+ 
+ ○ post-create install:
+  echo 'Installing dependencies...'
+ 
+ ❯ Allow and remember? [y/N]
+
+- Approvals are saved to user config (~/.config/worktrunk/config.toml)
+- If a command changes, new approval is required
+- Use --yes to bypass prompts (useful for CI/automation)
+- Use --no-verify to skip hooks
+
+Manage approvals with wt hook approvals add and wt hook approvals clear.
+
+Configuration
+
+Hooks can be defined in two places: project config (.config/wt.toml) for repository-specific automation, or user config (~/.config/worktrunk/config.toml) for personal automation across all repositories.
+
+Project hooks
+
+Project hooks are defined in .config/wt.toml. They can be a single command or multiple named commands:
+
+ # Single command (string)
+ post-create = "npm install"
+ 
+ # Multiple commands (table) — run sequentially in declaration order
+ [pre-merge]
+ test = "cargo test"
+ build = "cargo build --release"
+
+User hooks
+
+Define hooks in ~/.config/worktrunk/config.toml to run for all repositories. User hooks run before project hooks and don't require approval.
+
+ # ~/.config/worktrunk/config.toml
+ [post-create]
+ setup = "echo 'Setting up worktree...'"
+ 
+ [pre-merge]
+ notify = "notify-send 'Merging {{ branch }}'"
+
+User hooks support the same hook types and template variables as project hooks.
+
+Key differences from project hooks:
+
+ Aspect Project hooks User hooks
+ ─────────────── ───────────────── ───────────────────────────────
+ Location .config/wt.toml ~/.config/worktrunk/config.toml
+ Scope Single repository All repositories
+ Approval Required Not required
+ Execution order After user hooks Before project hooks
+
+Skip hooks with --no-verify. To run a specific hook when user and project both define the same name, use user:name or project:name syntax.
+
+Use cases:
+- Personal notifications or logging
+- Editor/IDE integration
+- Repository-agnostic setup tasks
+- Filtering by repository using JSON context
+
+Filtering by repository:
+
+User hooks receive JSON context on stdin, enabling repository-specific behavior:
+
+ # ~/.config/worktrunk/config.toml
+ [post-create]
+ gitlab-setup = """
+ python3 -c '
+ import json, sys, subprocess
+ ctx = json.load(sys.stdin)
+ if "gitlab" in ctx.get("remote", ""):
+  subprocess.run(["glab", "mr", "create", "--fill"])
+ '
+ """
+
+Template variables
+
+Hooks can use template variables that expand at runtime:
+
+ Variable Description
+ ─────────────────────────── ────────────────────────────────────────────────────────────
+ {{ repo }} Repository directory name
+ {{ repo_path }} Absolute path to repository root
+ {{ branch }} Branch name
+ {{ worktree_name }} Worktree directory name
+ {{ worktree_path }} Absolute worktree path
+ {{ primary_worktree_path }} Main worktree path (for bare repos: default branch worktree)
+ {{ default_branch }} Default branch name
+ {{ commit }} Full HEAD commit SHA
+ {{ short_commit }} Short HEAD commit SHA (7 chars)
+ {{ remote }} Primary remote name
+ {{ remote_url }} Remote URL
+ {{ upstream }} Upstream tracking branch (if set)
+ {{ target }} Target branch (merge hooks only)
+ {{ base }} Base branch (creation hooks only)
+ {{ base_worktree_path }} Base branch worktree (creation hooks only)
+
+Some variables may not be defined: upstream is only set when the branch tracks a remote; target, base, and base_worktree_path are hook-specific. Using an undefined variable directly errors — use conditionals for optional behavior:
+
+ [post-create]
+ # Rebase onto upstream if tracking a remote branch (e.g., wt switch --create feature origin/feature)
+ sync = "{% if upstream %}git fetch && git rebase {{ upstream }}{% endif %}"
+
+Worktrunk filters
+
+Templates support Jinja2 filters for transforming values:
+
+ Filter Example Description
+ ─────────── ────────────────────────── ───────────────────────────────────────────────────────────────────
+ sanitize {{ branch | sanitize }} Replace / and \ with -
+ sanitize_db {{ branch | sanitize_db }} Database-safe identifier with hash suffix ([a-z0-9_], max 63 chars)
+ hash_port {{ branch | hash_port }} Hash to port 10000-19999
+
+The sanitize filter makes branch names safe for filesystem paths. The sanitize_db filter produces database-safe identifiers (lowercase alphanumeric and underscores, no leading digits, with a 3-character hash suffix to avoid collisions and reserved words). The hash_port filter is useful for running dev servers on unique ports per worktree:
+
+ [post-start]
+ dev = "npm run dev -- --host {{ branch }}.lvh.me --port {{ branch | hash_port }}"
+
+Hash any string, including concatenations:
+
+ # Unique port per repo+branch combination
+ dev = "npm run dev --port {{ (repo ~ '-' ~ branch) | hash_port }}"
+
+Worktrunk functions
+
+Templates also support functions for dynamic lookups:
+
+ Function Example Description
+ ─────────────────────────────── ───────────────────────────────────── ───────────────────────────────────────
+ worktree_path_of_branch(branch) {{ worktree_path_of_branch("main") }} Look up the path of a branch's worktree
+
+The worktree_path_of_branch function returns the filesystem path of a worktree given a branch name, or an empty string if no worktree exists for that branch. This is useful for referencing files in other worktrees:
+
+ [post-create]
+ # Copy config from main worktree
+ setup = "cp {{ worktree_path_of_branch('main') }}/config.local {{ worktree_path }}"
+
+JSON context
+
+Hooks also receive context as JSON on stdin, enabling hooks in any language:
+
+ import json, sys
+ ctx = json.load(sys.stdin)
+ print(f"Setting up {ctx['repo']} on branch {ctx['branch']}")
+
+The JSON includes all template variables plus hook_type and hook_name.
+
+Running hooks manually
+
+wt hook <type> runs hooks on demand — useful for testing during development, running in CI pipelines, or re-running after a failure.
+
+ wt hook pre-merge # Run all pre-merge hooks
+ wt hook pre-merge test # Run hooks named "test" from both sources
+ wt hook pre-merge user: # Run all user hooks
+ wt hook pre-merge project: # Run all project hooks
+ wt hook pre-merge user:test # Run only user's "test" hook
+ wt hook pre-merge project:test # Run only project's "test" hook
+ wt hook pre-merge --yes # Skip approval prompts (for CI)
+ wt hook post-create --var branch=feature/test # Override template variable
+
+The user: and project: prefixes filter by source. Use user: or project: alone to run all hooks from that source, or user:name / project:name to run a specific hook.
+
+The --var KEY=VALUE flag overrides built-in template variables — useful for testing hooks with different contexts without switching to that context.
+
+Designing effective hooks
+
+post-start vs post-create
+
+Both run when creating a worktree. The difference:
+
+ Hook Execution Best for
+ ─────────── ───────────────────── ─────────────────────────────────────────────────────────────
+ post-start Background, parallel Long-running tasks that don't block worktree creation
+ post-create Blocks until complete Tasks the developer needs before working (dependency install)
+
+Many tasks work well in post-start — they'll likely be ready by the time they're needed, especially when the fallback is recompiling. If unsure, prefer post-start for faster worktree creation.
+
+Background processes spawned by post-start outlive the worktree — pair them with post-remove hooks to clean up. See Dev servers and Databases for examples.
+
+Copying untracked files
+
+Git worktrees share the repository but not untracked files. wt step copy-ignored copies gitignored files between worktrees:
+
+ [post-start]
+ copy = "wt step copy-ignored"
+
+Use post-create instead if subsequent hooks or --execute command need the copied files immediately.
+
+Dev servers
+
+Run a dev server per worktree on a deterministic port using hash_port:
+
+ [post-start]
+ server = "npm run dev -- --port {{ branch | hash_port }}"
+ 
+ [post-remove]
+ server = "lsof -ti :{{ branch | hash_port }} | xargs kill 2>/dev/null || true"
+
+The port is stable across machines and restarts — feature-api always gets the same port. Show it in wt list:
+
+ [list]
+ url = "http://localhost:{{ branch | hash_port }}"
+
+For subdomain-based routing (useful for cookies/CORS), use lvh.me which resolves to 127.0.0.1:
+
+ [post-start]
+ server = "npm run dev -- --host {{ branch | sanitize }}.lvh.me --port {{ branch | hash_port }}"
+
+Databases
+
+Each worktree can have its own database. Docker containers get unique names and ports:
+
+ [post-start]
+ db = """
+ docker run -d --rm \
+  --name {{ repo }}-{{ branch | sanitize }}-postgres \
+  -p {{ ('db-' ~ branch) | hash_port }}:5432 \
+  -e POSTGRES_DB={{ branch | sanitize_db }} \
+  -e POSTGRES_PASSWORD=dev \
+  postgres:16
+ """
+ 
+ [post-remove]
+ db-stop = "docker stop {{ repo }}-{{ branch | sanitize }}-postgres 2>/dev/null || true"
+
+The ('db-' ~ branch) concatenation hashes differently than plain branch, so database and dev server ports don't collide.
+Jinja2's operator precedence has pipe | with higher precedence than concatenation ~, meaning expressions need parentheses to filter concatenated values.
+
+Generate .env.local with the connection string:
+
+ [post-create]
+ env = """
+ cat > .env.local << EOF
+ DATABASE_URL=postgres://postgres:dev@localhost:{{ ('db-' ~ branch) | hash_port }}/{{ branch | sanitize_db }}
+ DEV_PORT={{ branch | hash_port }}
+ EOF
+ """
+
+Progressive validation
+
+Quick checks before commit, thorough validation before merge:
+
+ [pre-commit]
+ lint = "npm run lint"
+ typecheck = "npm run typecheck"
+ 
+ [pre-merge]
+ test = "npm test"
+ build = "npm run build"
+
+Target-specific behavior
+
+Different actions for production vs staging:
+
+ post-merge = """
+ if [ "{{ target }}" = "main" ]; then
+  npm run deploy:production
+ elif [ "{{ target }}" = "staging" ]; then
+  npm run deploy:staging
+ fi
+ """
+
+Python virtual environments
+
+Use uv sync to recreate virtual environments (or python -m venv .venv && .venv/bin/pip install -r requirements.txt for pip-based projects):
+
+ [post-create]
+ install = "uv sync"
+
+For copying dependencies and caches between worktrees, see wt step copy-ignored.
+
+See also
+
+- wt merge — Runs hooks automatically during merge
+- wt switch — Runs post-create/post-start hooks on --create
+- wt config — Manage hook approvals
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap b/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
index cf61316b0..c73e9ff7f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
@@ -25,39 +25,39 @@ exit_code: 0
----- stderr -----
wt hook approvals - Manage command approvals
-Usage: wt hook approvals [OPTIONS] <COMMAND>
+Usage: wt hook approvals [OPTIONS] <COMMAND>
-Commands:
+Commands:
add Store approvals in config
clear Clear approved commands from config
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Project hooks require approval on first run to prevent untrusted projects from running arbitrary commands.
-Examples
+Examples
Pre-approve all commands for current project:
- wt hook approvals add
+ wt hook approvals add
Clear approvals for current project:
- wt hook approvals clear
+ wt hook approvals clear
Clear global approvals:
- wt hook approvals clear --global
+ wt hook approvals clear --global
-How approvals work
+How approvals work
Approved commands are saved to user config. Re-approval is required when the command template changes or the project moves. Use --yes to bypass prompts in CI.
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_approvals_add.snap b/tests/snapshots/integration__integration_tests__help__help_hook_approvals_add.snap
index bd159e4e5..90edf238c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_hook_approvals_add.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_approvals_add.snap
@@ -26,23 +26,23 @@ exit_code: 0
----- stderr -----
wt hook approvals add - Store approvals in config
-Usage: wt hook approvals add [OPTIONS]
+Usage: wt hook approvals add [OPTIONS]
-Options:
- --all
+Options:
+ --all
Show all commands
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Prompts for approval of all project commands and saves them to user config.
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_approvals_clear.snap b/tests/snapshots/integration__integration_tests__help__help_hook_approvals_clear.snap
index c98507e92..e74391976 100644
--- a/tests/snapshots/integration__integration_tests__help__help_hook_approvals_clear.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_approvals_clear.snap
@@ -26,23 +26,23 @@ exit_code: 0
----- stderr -----
wt hook approvals clear - Clear approved commands from config
-Usage: wt hook approvals clear [OPTIONS]
+Usage: wt hook approvals clear [OPTIONS]
-Options:
- -g, --global
+Options:
+ -g, --global
Clear global approvals
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Removes saved approvals, requiring re-approval on next command run.
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_post_create.snap b/tests/snapshots/integration__integration_tests__help__help_hook_post_create.snap
new file mode 100644
index 000000000..b91e5fa0c
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_post_create.snap
@@ -0,0 +1,56 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - post-create
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook post-create - Run post-create hooks
+
+Blocking — waits for completion before continuing.
+
+Usage: wt hook post-create [OPTIONS] [NAME]
+
+Arguments:
+ [NAME]
+ Filter by command name
+
+ Supports user:name or project:name to filter by source. user: alone runs all user hooks; project: alone runs all project hooks.
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --var <KEY=VALUE>
+ Override built-in template variable (KEY=VALUE)
+
+ -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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_post_merge.snap b/tests/snapshots/integration__integration_tests__help__help_hook_post_merge.snap
new file mode 100644
index 000000000..966be76f4
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_post_merge.snap
@@ -0,0 +1,54 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - post-merge
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook post-merge - Run post-merge hooks
+
+Usage: wt hook post-merge [OPTIONS] [NAME]
+
+Arguments:
+ [NAME]
+ Filter by command name
+
+ Supports user:name or project:name to filter by source. user: alone runs all user hooks; project: alone runs all project hooks.
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --var <KEY=VALUE>
+ Override built-in template variable (KEY=VALUE)
+
+ -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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_post_remove.snap b/tests/snapshots/integration__integration_tests__help__help_hook_post_remove.snap
new file mode 100644
index 000000000..90c4a75ea
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_post_remove.snap
@@ -0,0 +1,59 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - post-remove
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook post-remove - Run post-remove hooks
+
+Background by default. Use --foreground to run in foreground for debugging.
+
+Usage: wt hook post-remove [OPTIONS] [NAME]
+
+Arguments:
+ [NAME]
+ Filter by command name
+
+ Supports user:name or project:name to filter by source. user: alone runs all user hooks; project: alone runs all project hooks.
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --foreground
+ Run in foreground (block until complete)
+
+ --var <KEY=VALUE>
+ Override built-in template variable (KEY=VALUE)
+
+ -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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_post_start.snap b/tests/snapshots/integration__integration_tests__help__help_hook_post_start.snap
new file mode 100644
index 000000000..92ce03c9a
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_post_start.snap
@@ -0,0 +1,59 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - post-start
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook post-start - Run post-start hooks
+
+Background by default. Use --foreground to run in foreground for debugging.
+
+Usage: wt hook post-start [OPTIONS] [NAME]
+
+Arguments:
+ [NAME]
+ Filter by command name
+
+ Supports user:name or project:name to filter by source. user: alone runs all user hooks; project: alone runs all project hooks.
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --foreground
+ Run in foreground (block until complete)
+
+ --var <KEY=VALUE>
+ Override built-in template variable (KEY=VALUE)
+
+ -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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_post_switch.snap b/tests/snapshots/integration__integration_tests__help__help_hook_post_switch.snap
new file mode 100644
index 000000000..9c6d631ce
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_post_switch.snap
@@ -0,0 +1,59 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - post-switch
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook post-switch - Run post-switch hooks
+
+Background by default. Use --foreground to run in foreground for debugging.
+
+Usage: wt hook post-switch [OPTIONS] [NAME]
+
+Arguments:
+ [NAME]
+ Filter by command name
+
+ Supports user:name or project:name to filter by source. user: alone runs all user hooks; project: alone runs all project hooks.
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --foreground
+ Run in foreground (block until complete)
+
+ --var <KEY=VALUE>
+ Override built-in template variable (KEY=VALUE)
+
+ -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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_pre_commit.snap b/tests/snapshots/integration__integration_tests__help__help_hook_pre_commit.snap
new file mode 100644
index 000000000..1400de1a4
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_pre_commit.snap
@@ -0,0 +1,54 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - pre-commit
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook pre-commit - Run pre-commit hooks
+
+Usage: wt hook pre-commit [OPTIONS] [NAME]
+
+Arguments:
+ [NAME]
+ Filter by command name
+
+ Supports user:name or project:name to filter by source. user: alone runs all user hooks; project: alone runs all project hooks.
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --var <KEY=VALUE>
+ Override built-in template variable (KEY=VALUE)
+
+ -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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_pre_merge.snap b/tests/snapshots/integration__integration_tests__help__help_hook_pre_merge.snap
new file mode 100644
index 000000000..f0cb9eb9b
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_pre_merge.snap
@@ -0,0 +1,54 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - pre-merge
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook pre-merge - Run pre-merge hooks
+
+Usage: wt hook pre-merge [OPTIONS] [NAME]
+
+Arguments:
+ [NAME]
+ Filter by command name
+
+ Supports user:name or project:name to filter by source. user: alone runs all user hooks; project: alone runs all project hooks.
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --var <KEY=VALUE>
+ Override built-in template variable (KEY=VALUE)
+
+ -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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_pre_remove.snap b/tests/snapshots/integration__integration_tests__help__help_hook_pre_remove.snap
new file mode 100644
index 000000000..1634b7762
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_pre_remove.snap
@@ -0,0 +1,54 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - pre-remove
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook pre-remove - Run pre-remove hooks
+
+Usage: wt hook pre-remove [OPTIONS] [NAME]
+
+Arguments:
+ [NAME]
+ Filter by command name
+
+ Supports user:name or project:name to filter by source. user: alone runs all user hooks; project: alone runs all project hooks.
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --var <KEY=VALUE>
+ Override built-in template variable (KEY=VALUE)
+
+ -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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_short.snap b/tests/snapshots/integration__integration_tests__help__help_hook_short.snap
new file mode 100644
index 000000000..7f0780584
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_short.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - "-h"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook - Run configured hooks
+
+Usage: wt hook [OPTIONS] <COMMAND>
+
+Commands:
+ show Show configured hooks
+ post-create Run post-create hooks
+ post-start Run post-start hooks
+ post-switch Run post-switch hooks
+ pre-commit Run pre-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
+ approvals Manage command approvals
+
+Options:
+ -h, --help Print help (see more with '--help')
+
+Global Options:
+ -C <path> Working directory for this command
+ --config <path> User config file path
+ -v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_show.snap b/tests/snapshots/integration__integration_tests__help__help_hook_show.snap
new file mode 100644
index 000000000..49705296b
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_show.snap
@@ -0,0 +1,53 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - hook
+ - show
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt hook show - Show configured hooks
+
+Lists user and project hooks. Project hooks show approval status (❓ = needs approval).
+
+Usage: wt hook show [OPTIONS] [HOOK_TYPE]
+
+Arguments:
+ [HOOK_TYPE]
+ Hook type to show (default: all)
+
+ [possible values: post-create, post-start, post-switch, pre-commit, pre-merge, post-merge, pre-remove, post-remove]
+
+Options:
+ --expanded
+ Show expanded commands with current variables
+
+ -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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_list.snap b/tests/snapshots/integration__integration_tests__help__help_list.snap
new file mode 100644
index 000000000..0b35b11b3
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_list.snap
@@ -0,0 +1,282 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - list
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt list - List worktrees and their status
+
+Usage: wt list [OPTIONS]
+ wt list <COMMAND>
+
+Commands:
+ statusline Single-line status for shell prompts
+
+Options:
+ --format <FORMAT>
+ Output format (table, json)
+
+ [default: table]
+
+ --branches
+ Include branches without worktrees
+
+ --remotes
+ Include remote branches
+
+ --full
+ Include CI status and diff analysis (slower)
+
+ --progressive
+ Show fast info immediately, update with slow info
+
+ Displays local data (branches, paths, status) first, then updates with remote data (CI, upstream) as it arrives. Auto-enabled for TTY.
+
+ -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: hooks, templates; -vv: debug report)
+
+Shows uncommitted changes, divergence from the default branch and remote, and optional CI status.
+
+
+The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. With --full, CI status fetches from the network — the table displays instantly and CI fills in as results arrive.
+
+Examples
+
+List all worktrees:
+
+ $ wt list
+
+Include CI status and line diffs:
+
+ $ wt list --full
+
+Include branches that don't have worktrees:
+
+ $ wt list --branches --full
+
+Output as JSON for scripting:
+
+ $ wt list --format=json
+
+Columns
+
+ Column Shows
+ ─────── ─────────────────────────────────────────────────────────────────
+ Branch Branch name
+ Status Compact symbols (see below)
+ HEAD± Uncommitted changes: +added -deleted lines
+ main↕ Commits ahead/behind default branch
+ main…± Line diffs since the merge-base with the default branch (--full)
+ Path Worktree directory
+ Remote⇅ Commits ahead/behind tracking branch
+ URL Dev server URL from project config (dimmed if port not listening)
+ CI Pipeline status (--full)
+ Commit Short hash (8 chars)
+ Age Time since last commit
+ Message Last commit message (truncated)
+
+Note: main↕ and main…± refer to the default branch (header label stays main for compactness). main…± uses a merge-base (three-dot) diff.
+
+CI status
+
+The CI column shows GitHub/GitLab pipeline status:
+
+ Indicator Meaning
+ ───────── ─────────────────────────────────
+ ● green All checks passed
+ ● blue Checks running
+ ● red Checks failed
+ ● yellow Merge conflicts with base
+ ● gray No checks configured
+ ⚠ yellow Fetch error (rate limit, network)
+ (blank) No upstream or no PR/MR
+
+CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank. Results are cached for 30-60 seconds; use wt config state to view or clear.
+
+Status symbols
+
+The Status column has multiple subcolumns. Within each, only the first matching symbol is shown (listed in priority order):
+
+ Subcolumn Symbol Meaning
+ ──────────────── ────── ──────────────────────────────────────────────────────────────────────────────────────────
+ Working tree (1) + Staged files
+ Working tree (2) ! Modified files (unstaged)
+ Working tree (3) ? Untracked files
+ Worktree ✘ Merge conflicts
+ ⤴ Rebase in progress
+ ⤵ Merge in progress
+ / Branch without worktree
+ ⚑ Branch-worktree mismatch (branch name doesn't match worktree path)
+ ⊟ Prunable (directory missing)
+ ⊞ Locked worktree
+ Default branch ^ Is the default branch
+ ∅ Orphan branch (no common ancestor with the default branch)
+ ✗ Would conflict if merged to the default branch (with --full, includes uncommitted changes)
+ _ Same commit as the default branch, clean
+ – Same commit as the default branch, uncommitted changes
+ ⊂ Content integrated into the default branch or target
+ ↕ Diverged from the default branch
+ ↑ Ahead of the default branch
+ ↓ Behind the default branch
+ Remote | In sync with remote
+ ⇅ Diverged from remote
+ ⇡ Ahead of remote
+ ⇣ Behind remote
+
+Rows are dimmed when safe to delete (_ same commit with clean working tree or ⊂ content integrated).
+
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+
+JSON output
+
+Query structured data with --format=json:
+
+ # Current worktree path (for scripts)
+ wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+ 
+ # Branches with uncommitted changes
+ wt list --format=json | jq '.[] | select(.working_tree.modified)'
+ 
+ # Worktrees with merge conflicts
+ wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
+ 
+ # Branches ahead of main (needs merging)
+ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+ 
+ # Integrated branches (safe to remove)
+ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
+ 
+ # Branches without worktrees
+ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
+ 
+ # Worktrees ahead of remote (needs pushing)
+ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
+ 
+ # Stale CI (local changes not reflected in CI)
+ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
+
+Fields:
+
+ Field Type Description
+ ────────────────── ─────────── ───────────────────────────────────────────────────────────────────
+ branch string/null Branch name (null for detached HEAD)
+ path string Worktree path (absent for branches without worktrees)
+ kind string "worktree" or "branch"
+ commit object Commit info (see below)
+ working_tree object Working tree state (see below)
+ main_state string Relation to the default branch (see below)
+ integration_reason string Why branch is integrated (see below)
+ operation_state string "conflicts", "rebase", or "merge" (absent when clean)
+ main object Relationship to the default branch (see below, absent when is_main)
+ remote object Tracking branch info (see below, absent when no tracking)
+ worktree object Worktree metadata (see below)
+ is_main boolean Is the main worktree
+ is_current boolean Is the current worktree
+ is_previous boolean Previous worktree from wt switch
+ ci object CI status (see below, absent when no CI)
+ url string Dev server URL from project config (absent when not configured)
+ url_active boolean Whether the URL's port is listening (absent when not configured)
+ statusline string Pre-formatted status with ANSI colors
+ symbols string Raw status symbols without colors (e.g., "!?↓")
+
+Commit object
+
+ Field Type Description
+ ───────── ────── ───────────────────────────
+ sha string Full commit SHA (40 chars)
+ short_sha string Short commit SHA (7 chars)
+ message string Commit message (first line)
+ timestamp number Unix timestamp
+
+working_tree object
+
+ Field Type Description
+ ───────── ─────── ───────────────────────────────────────
+ staged boolean Has staged files
+ modified boolean Has modified files (unstaged)
+ untracked boolean Has untracked files
+ renamed boolean Has renamed files
+ deleted boolean Has deleted files
+ diff object Lines changed vs HEAD: {added, deleted}
+
+main object
+
+ Field Type Description
+ ────── ────── ─────────────────────────────────────────────────────
+ ahead number Commits ahead of the default branch
+ behind number Commits behind the default branch
+ diff object Lines changed vs the default branch: {added, deleted}
+
+remote object
+
+ Field Type Description
+ ────── ────── ────────────────────────────
+ name string Remote name (e.g., "origin")
+ branch string Remote branch name
+ ahead number Commits ahead of remote
+ behind number Commits behind remote
+
+worktree object
+
+ Field Type Description
+ ──────── ─────── ────────────────────────────────────────────────────────────────────────────────────
+ state string "no_worktree", "branch_worktree_mismatch", "prunable", "locked" (absent when normal)
+ reason string Reason for locked/prunable state
+ detached boolean HEAD is detached
+
+ci object
+
+ Field Type Description
+ ────── ─────── ─────────────────────────────────────────────────
+ status string CI status (see below)
+ source string "pr" (PR/MR) or "branch" (branch workflow)
+ stale boolean Local HEAD differs from remote (unpushed changes)
+ url string URL to the PR/MR page
+
+main_state values
+
+These values describe the relation to the default branch.
+
+"is_main" "orphan" "would_conflict" "empty" "same_commit" "integrated" "diverged" "ahead" "behind"
+
+integration_reason values
+
+When main_state == "integrated": "ancestor" "trees_match" "no_added_changes" "merge_adds_nothing"
+
+ci.status values
+
+"passed" "running" "failed" "conflicts" "no-ci" "error"
+
+Missing a field that would be generally useful? Open an issue at https://github.com/max-sixty/worktrunk.
+
+See also
+
+- wt select — Interactive worktree picker with live preview
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 0b35b11b3..02a7a09fa 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -24,43 +24,43 @@ exit_code: 0
----- stderr -----
wt list - List worktrees and their status
-Usage: wt list [OPTIONS]
- wt list <COMMAND>
+Usage: wt list [OPTIONS]
+ wt list <COMMAND>
-Commands:
+Commands:
statusline Single-line status for shell prompts
-Options:
- --format <FORMAT>
+Options:
+ --format <FORMAT>
Output format (table, json)
[default: table]
- --branches
+ --branches
Include branches without worktrees
- --remotes
+ --remotes
Include remote branches
- --full
+ --full
Include CI status and diff analysis (slower)
- --progressive
- Show fast info immediately, update with slow info
+ --progressive
+ Show fast info immediately, update with slow info
- Displays local data (branches, paths, status) first, then updates with remote data (CI, upstream) as it arrives. Auto-enabled for TTY.
+ Displays local data (branches, paths, status) first, then updates with remote data (CI, upstream) as it arrives. Auto-enabled for TTY.
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Shows uncommitted changes, divergence from the default branch and remote, and optional CI status.
@@ -68,25 +68,25 @@ Shows uncommitted changes, divergence from the default branch and remote, and op
The table renders progressively: branch names, paths, and commit hashes appear immediately, then status, divergence, and other columns fill in as background git operations complete. With --full, CI status fetches from the network — the table displays instantly and CI fills in as results arrive.
-Examples
+Examples
List all worktrees:
- $ wt list
+ $ wt list
Include CI status and line diffs:
- $ wt list --full
+ $ wt list --full
Include branches that don't have worktrees:
- $ wt list --branches --full
+ $ wt list --branches --full
Output as JSON for scripting:
- $ wt list --format=json
+ $ wt list --format=json
-Columns
+Columns
Column Shows
─────── ─────────────────────────────────────────────────────────────────
@@ -105,7 +105,7 @@ Output as JSON for scripting:
Note: main↕ and main…± refer to the default branch (header label stays main for compactness). main…± uses a merge-base (three-dot) diff.
-CI status
+CI status
The CI column shows GitHub/GitLab pipeline status:
@@ -121,7 +121,7 @@ The CI column shows GitHub/GitLab pipeline status:
CI indicators are clickable links to the PR or pipeline page. Any CI dot appears dimmed when there are unpushed local changes (stale status). PRs/MRs are checked first, then branch workflows/pipelines for branches with an upstream. Local-only branches show blank. Results are cached for 30-60 seconds; use wt config state to view or clear.
-Status symbols
+Status symbols
The Status column has multiple subcolumns. Within each, only the first matching symbol is shown (listed in priority order):
@@ -153,37 +153,37 @@ The Status column has multiple subcolumns. Within each, only the first matching
Rows are dimmed when safe to delete (_ same commit with clean working tree or ⊂ content integrated).
-────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
+────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
-JSON output
+JSON output
Query structured data with --format=json:
- # Current worktree path (for scripts)
- wt list --format=json | jq -r '.[] | select(.is_current) | .path'
- 
- # Branches with uncommitted changes
- wt list --format=json | jq '.[] | select(.working_tree.modified)'
- 
- # Worktrees with merge conflicts
- wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
- 
- # Branches ahead of main (needs merging)
- wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
- 
- # Integrated branches (safe to remove)
- wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
- 
- # Branches without worktrees
- wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
- 
- # Worktrees ahead of remote (needs pushing)
- wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
- 
- # Stale CI (local changes not reflected in CI)
- wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
-
-Fields:
+ # Current worktree path (for scripts)
+ wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+ 
+ # Branches with uncommitted changes
+ wt list --format=json | jq '.[] | select(.working_tree.modified)'
+ 
+ # Worktrees with merge conflicts
+ wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
+ 
+ # Branches ahead of main (needs merging)
+ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+ 
+ # Integrated branches (safe to remove)
+ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
+ 
+ # Branches without worktrees
+ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
+ 
+ # Worktrees ahead of remote (needs pushing)
+ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
+ 
+ # Stale CI (local changes not reflected in CI)
+ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
+
+Fields:
Field Type Description
────────────────── ─────────── ───────────────────────────────────────────────────────────────────
@@ -207,7 +207,7 @@ Query structured data with --format=json:
statusline string Pre-formatted status with ANSI colors
symbols string Raw status symbols without colors (e.g., "!?↓")
-Commit object
+Commit object
Field Type Description
───────── ────── ───────────────────────────
@@ -216,7 +216,7 @@ Query structured data with --format=json:
message string Commit message (first line)
timestamp number Unix timestamp
-working_tree object
+working_tree object
Field Type Description
───────── ─────── ───────────────────────────────────────
@@ -227,7 +227,7 @@ Query structured data with --format=json:
deleted boolean Has deleted files
diff object Lines changed vs HEAD: {added, deleted}
-main object
+main object
Field Type Description
────── ────── ─────────────────────────────────────────────────────
@@ -235,7 +235,7 @@ Query structured data with --format=json:
behind number Commits behind the default branch
diff object Lines changed vs the default branch: {added, deleted}
-remote object
+remote object
Field Type Description
────── ────── ────────────────────────────
@@ -244,7 +244,7 @@ Query structured data with --format=json:
ahead number Commits ahead of remote
behind number Commits behind remote
-worktree object
+worktree object
Field Type Description
──────── ─────── ────────────────────────────────────────────────────────────────────────────────────
@@ -252,7 +252,7 @@ Query structured data with --format=json:
reason string Reason for locked/prunable state
detached boolean HEAD is detached
-ci object
+ci object
Field Type Description
────── ─────── ─────────────────────────────────────────────────
@@ -261,22 +261,22 @@ Query structured data with --format=json:
stale boolean Local HEAD differs from remote (unpushed changes)
url string URL to the PR/MR page
-main_state values
+main_state values
These values describe the relation to the default branch.
-"is_main" "orphan" "would_conflict" "empty" "same_commit" "integrated" "diverged" "ahead" "behind"
+"is_main" "orphan" "would_conflict" "empty" "same_commit" "integrated" "diverged" "ahead" "behind"
-integration_reason values
+integration_reason values
-When main_state == "integrated": "ancestor" "trees_match" "no_added_changes" "merge_adds_nothing"
+When main_state == "integrated": "ancestor" "trees_match" "no_added_changes" "merge_adds_nothing"
-ci.status values
+ci.status values
-"passed" "running" "failed" "conflicts" "no-ci" "error"
+"passed" "running" "failed" "conflicts" "no-ci" "error"
Missing a field that would be generally useful? Open an issue at https://github.com/max-sixty/worktrunk.
-See also
+See also
- wt select — Interactive worktree picker with live preview
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
index ee020a341..890936e69 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_narrow_80.snap
@@ -24,44 +24,44 @@ exit_code: 0
----- stderr -----
wt list - List worktrees and their status
-Usage: wt list [OPTIONS]
- wt list <COMMAND>
+Usage: wt list [OPTIONS]
+ wt list <COMMAND>
-Commands:
+Commands:
statusline Single-line status for shell prompts
-Options:
- --format <FORMAT>
+Options:
+ --format <FORMAT>
Output format (table, json)
[default: table]
- --branches
+ --branches
Include branches without worktrees
- --remotes
+ --remotes
Include remote branches
- --full
+ --full
Include CI status and diff analysis (slower)
- --progressive
- Show fast info immediately, update with slow info
+ --progressive
+ Show fast info immediately, update with slow info
Displays local data (branches, paths, status) first, then updates with
- remote data (CI, upstream) as it arrives. Auto-enabled for TTY.
+ remote data (CI, upstream) as it arrives. Auto-enabled for TTY.
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Shows uncommitted changes, divergence from the default branch and remote, and
@@ -73,25 +73,25 @@ immediately, then status, divergence, and other columns fill in as background
git operations complete. With --full, CI status fetches from the network — the
table displays instantly and CI fills in as results arrive.
-Examples
+Examples
List all worktrees:
- $ wt list
+ $ wt list
Include CI status and line diffs:
- $ wt list --full
+ $ wt list --full
Include branches that don't have worktrees:
- $ wt list --branches --full
+ $ wt list --branches --full
Output as JSON for scripting:
- $ wt list --format=json
+ $ wt list --format=json
-Columns
+Columns
Column Shows
─────── ─────────────────────────────────────────────────────────────────
@@ -111,7 +111,7 @@ Output as JSON for scripting:
Note: main↕ and main…± refer to the default branch (header label stays main for
compactness). main…± uses a merge-base (three-dot) diff.
-CI status
+CI status
The CI column shows GitHub/GitLab pipeline status:
@@ -131,7 +131,7 @@ checked first, then branch workflows/pipelines for branches with an upstream.
Local-only branches show blank. Results are cached for 30-60 seconds; use wt
config state to view or clear.
-Status symbols
+Status symbols
The Status column has multiple subcolumns. Within each, only the first matching
symbol is shown (listed in priority order):
@@ -169,37 +169,37 @@ symbol is shown (listed in priority order):
Rows are dimmed when safe to delete (_ same commit with clean working tree or ⊂
content integrated).
-────────────────────────────────────────────────────────────────────────────────
+────────────────────────────────────────────────────────────────────────────────
-JSON output
+JSON output
Query structured data with --format=json:
- # Current worktree path (for scripts)
- wt list --format=json | jq -r '.[] | select(.is_current) | .path'
- 
- # Branches with uncommitted changes
- wt list --format=json | jq '.[] | select(.working_tree.modified)'
- 
- # Worktrees with merge conflicts
- wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
- 
- # Branches ahead of main (needs merging)
- wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
- 
- # Integrated branches (safe to remove)
- wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
- 
- # Branches without worktrees
- wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
- 
- # Worktrees ahead of remote (needs pushing)
- wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
- 
- # Stale CI (local changes not reflected in CI)
- wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
-
-Fields:
+ # Current worktree path (for scripts)
+ wt list --format=json | jq -r '.[] | select(.is_current) | .path'
+ 
+ # Branches with uncommitted changes
+ wt list --format=json | jq '.[] | select(.working_tree.modified)'
+ 
+ # Worktrees with merge conflicts
+ wt list --format=json | jq '.[] | select(.operation_state == "conflicts")'
+ 
+ # Branches ahead of main (needs merging)
+ wt list --format=json | jq '.[] | select(.main.ahead > 0) | .branch'
+ 
+ # Integrated branches (safe to remove)
+ wt list --format=json | jq '.[] | select(.main_state == "integrated" or .main_state == "empty") | .branch'
+ 
+ # Branches without worktrees
+ wt list --format=json --branches | jq '.[] | select(.kind == "branch") | .branch'
+ 
+ # Worktrees ahead of remote (needs pushing)
+ wt list --format=json | jq '.[] | select(.remote.ahead > 0) | {branch, ahead: .remote.ahead}'
+ 
+ # Stale CI (local changes not reflected in CI)
+ wt list --format=json --full | jq '.[] | select(.ci.stale) | .branch'
+
+Fields:
Field Type Description
────────────────── ─────────── ─────────────────────────────────────────────
@@ -230,7 +230,7 @@ Query structured data with --format=json:
symbols string Raw status symbols without colors (e.g.,
"!?↓")
-Commit object
+Commit object
Field Type Description
───────── ────── ───────────────────────────
@@ -239,7 +239,7 @@ Query structured data with --format=json:
message string Commit message (first line)
timestamp number Unix timestamp
-working_tree object
+working_tree object
Field Type Description
───────── ─────── ───────────────────────────────────────
@@ -250,7 +250,7 @@ Query structured data with --format=json:
deleted boolean Has deleted files
diff object Lines changed vs HEAD: {added, deleted}
-main object
+main object
Field Type Description
────── ────── ─────────────────────────────────────────────────────
@@ -258,7 +258,7 @@ Query structured data with --format=json:
behind number Commits behind the default branch
diff object Lines changed vs the default branch: {added, deleted}
-remote object
+remote object
Field Type Description
────── ────── ────────────────────────────
@@ -267,7 +267,7 @@ Query structured data with --format=json:
ahead number Commits ahead of remote
behind number Commits behind remote
-worktree object
+worktree object
Field Type Description
──────── ─────── ───────────────────────────────────────────────────────────
@@ -276,7 +276,7 @@ Query structured data with --format=json:
reason string Reason for locked/prunable state
detached boolean HEAD is detached
-ci object
+ci object
Field Type Description
────── ─────── ─────────────────────────────────────────────────
@@ -285,25 +285,25 @@ Query structured data with --format=json:
stale boolean Local HEAD differs from remote (unpushed changes)
url string URL to the PR/MR page
-main_state values
+main_state values
These values describe the relation to the default branch.
"is_main" "orphan" "would_conflict" "empty" "same_commit" "integrated"
-"diverged" "ahead" "behind"
+"diverged" "ahead" "behind"
-integration_reason values
+integration_reason values
When main_state == "integrated": "ancestor" "trees_match" "no_added_changes"
-"merge_adds_nothing"
+"merge_adds_nothing"
-ci.status values
+ci.status values
-"passed" "running" "failed" "conflicts" "no-ci" "error"
+"passed" "running" "failed" "conflicts" "no-ci" "error"
Missing a field that would be generally useful? Open an issue at
https://github.com/max-sixty/worktrunk.
-See also
+See also
- wt select — Interactive worktree picker with live preview
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_short.snap b/tests/snapshots/integration__integration_tests__help__help_list_short.snap
index bb6ee0095..3a5538100 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_short.snap
@@ -24,13 +24,13 @@ exit_code: 0
----- stderr -----
wt list - List worktrees and their status
-Usage: wt list [OPTIONS]
- wt list <COMMAND>
+Usage: wt list [OPTIONS]
+ wt list <COMMAND>
-Commands:
+Commands:
statusline Single-line status for shell prompts
-Options:
+Options:
--format <FORMAT> Output format (table, json) [default: table]
--branches Include branches without worktrees
--remotes Include remote branches
@@ -38,7 +38,7 @@ Usage: wt list [OPTIONS]
--progressive Show fast info immediately, update with slow info
-h, --help Print help (see more with '--help')
-Global Options:
+Global Options:
-C <path> Working directory for this command
--config <path> User config file path
-v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_statusline.snap b/tests/snapshots/integration__integration_tests__help__help_list_statusline.snap
new file mode 100644
index 000000000..b2bff226c
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_list_statusline.snap
@@ -0,0 +1,51 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - list
+ - statusline
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt list statusline - Single-line status for shell prompts
+
+For shell prompts, starship, or editor integrations.
+
+Usage: wt list statusline [OPTIONS]
+
+Options:
+ --claude-code
+ Claude Code mode: read context from stdin, add directory and model
+
+ Reads JSON from stdin with .workspace.current_dir and .model.display_name. Output: dir branch status ±working commits upstream ci | model
+
+ -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: hooks, templates; -vv: debug report)
+
+Format: branch status ±working commits upstream ci
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snap
new file mode 100644
index 000000000..3e3d0d43f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_merge.snap
@@ -0,0 +1,132 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - merge
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt merge - Merge current branch into target
+
+Squash & rebase, fast-forward target, remove the worktree.
+
+Usage: wt merge [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
+Options:
+ --no-squash
+ Skip commit squashing
+
+ --no-commit
+ Skip commit and squash
+
+ --no-rebase
+ Skip rebase (fail if not already rebased)
+
+ --no-remove
+ Keep worktree after merge
+
+ --no-verify
+ Skip hooks
+
+ -y, --yes
+ Skip approval prompts
+
+ --stage <STAGE>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - all: Stage everything: untracked files + unstaged tracked changes
+ - tracked: Stage tracked changes only (like git add -u)
+ - none: Stage nothing, commit only what's already in the index
+
+ -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: hooks, templates; -vv: debug report)
+
+Unlike git merge, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
+
+
+Examples
+
+Merge to the default branch:
+
+ wt merge
+
+Merge to a different branch:
+
+ wt merge develop
+
+Keep the worktree after merging:
+
+ wt merge --no-remove
+
+Preserve commit history (no squash):
+
+ wt merge --no-squash
+
+Skip committing/squashing (rebase still runs unless --no-rebase):
+
+ wt merge --no-commit
+
+Pipeline
+
+wt merge runs these steps:
+
+1. Squash — Stages uncommitted changes, then combines all commits since target into one (like GitHub's "Squash and merge"). Use --stage to control what gets staged: all (default), tracked, or none. A backup ref is saved to refs/wt-backup/<branch>. With --no-squash, uncommitted changes become a separate commit and individual commits are preserved.
+2. Rebase — Rebases onto target if behind. Skipped if already up-to-date. Conflicts abort immediately.
+3. Pre-merge hooks — Hooks run after rebase, before merge. Failures abort. See wt hook.
+4. Merge — Fast-forward merge to the target branch. Non-fast-forward merges are rejected.
+5. Pre-remove hooks — Hooks run before removing worktree. Failures abort.
+6. Cleanup — Removes the worktree and branch. Use --no-remove to keep the worktree. When already on the target branch or in the main worktree, the worktree is preserved.
+7. Post-merge hooks — Hooks run after cleanup. Failures are logged but don't abort.
+
+Use --no-commit to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless --no-rebase is passed. Useful after preparing commits manually with wt step. Requires a clean working tree.
+
+Local CI
+
+For personal projects, pre-merge hooks open up the possibility of a workflow with much faster iteration — an order of magnitude more small changes instead of fewer large ones.
+
+Historically, ensuring tests ran before merging was difficult to enforce locally. Remote CI was valuable for the process as much as the checks: it guaranteed validation happened. wt merge brings that guarantee local.
+
+The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run wt merge, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
+
+ [pre-merge]
+ test = "cargo test"
+ lint = "cargo clippy"
+
+See also
+
+- wt step — Run individual operations (commit, squash, rebase, push)
+- wt remove — Remove worktrees without merging
+- wt switch — Navigate to other worktrees
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
index 3e3d0d43f..bafef5a1d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -22,38 +22,38 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt merge - Merge current branch into target
+wt merge - Merge current branch into target
-Squash & rebase, fast-forward target, remove the worktree.
+Squash & rebase, fast-forward target, remove the worktree.
-Usage: wt merge [OPTIONS] [TARGET]
+Usage: wt merge [OPTIONS] [TARGET]
-Arguments:
- [TARGET]
- Target branch
+Arguments:
+ [TARGET]
+ Target branch
- Defaults to default branch.
+ Defaults to default branch.
-Options:
- --no-squash
+Options:
+ --no-squash
Skip commit squashing
- --no-commit
+ --no-commit
Skip commit and squash
- --no-rebase
+ --no-rebase
Skip rebase (fail if not already rebased)
- --no-remove
+ --no-remove
Keep worktree after merge
- --no-verify
+ --no-verify
Skip hooks
- -y, --yes
+ -y, --yes
Skip approval prompts
- --stage <STAGE>
+ --stage <STAGE>
What to stage before committing [default: all]
Possible values:
@@ -61,45 +61,45 @@ Usage: wt merge [OPTIONS] [TARGET]
- tracked: Stage tracked changes only (like git add -u)
- none: Stage nothing, commit only what's already in the index
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Unlike git merge, this merges current into target (not target into current). Similar to clicking "Merge pull request" on GitHub, but locally. Target defaults to the default branch.
-Examples
+Examples
Merge to the default branch:
- wt merge
+ wt merge
Merge to a different branch:
- wt merge develop
+ wt merge develop
Keep the worktree after merging:
- wt merge --no-remove
+ wt merge --no-remove
Preserve commit history (no squash):
- wt merge --no-squash
+ wt merge --no-squash
Skip committing/squashing (rebase still runs unless --no-rebase):
- wt merge --no-commit
+ wt merge --no-commit
-Pipeline
+Pipeline
wt merge runs these steps:
@@ -113,7 +113,7 @@ Skip committing/squashing (rebase still runs unless --no-rebase):
Use --no-commit to skip committing uncommitted changes and squashing; rebase still runs by default and can rewrite commits unless --no-rebase is passed. Useful after preparing commits manually with wt step. Requires a clean working tree.
-Local CI
+Local CI
For personal projects, pre-merge hooks open up the possibility of a workflow with much faster iteration — an order of magnitude more small changes instead of fewer large ones.
@@ -121,11 +121,11 @@ Historically, ensuring tests ran before merging was difficult to enforce locally
The full workflow: start an agent (one of many) on a task, work elsewhere, return when it's ready. Review the diff, run wt merge, move on. Pre-merge hooks validate before merging — if they pass, the branch goes to the default branch and the worktree cleans up.
- [pre-merge]
- test = "cargo test"
- lint = "cargo clippy"
+ [pre-merge]
+ test = "cargo test"
+ lint = "cargo clippy"
-See also
+See also
- wt step — Run individual operations (commit, squash, rebase, push)
- wt remove — Remove worktrees without merging
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge_short.snap b/tests/snapshots/integration__integration_tests__help__help_merge_short.snap
index 102c0b880..4fdd0a726 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_short.snap
@@ -24,12 +24,12 @@ exit_code: 0
----- stderr -----
wt merge - Merge current branch into target
-Usage: wt merge [OPTIONS] [TARGET]
+Usage: wt merge [OPTIONS] [TARGET]
-Arguments:
+Arguments:
[TARGET] Target branch
-Options:
+Options:
--no-squash Skip commit squashing
--no-commit Skip commit and squash
--no-rebase Skip rebase (fail if not already rebased)
@@ -39,7 +39,7 @@ Usage: wt merge [OPTIONS] [TARGET]
--stage <STAGE> What to stage before committing [default: all] [possible values: all, tracked, none]
-h, --help Print help (see more with '--help')
-Global Options:
+Global Options:
-C <path> Working directory for this command
--config <path> User config file path
-v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_no_args.snap b/tests/snapshots/integration__integration_tests__help__help_no_args.snap
index 5768bcaf4..9808f868d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_no_args.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_no_args.snap
@@ -22,9 +22,9 @@ exit_code: 0
----- stderr -----
wt - Git worktree management for parallel AI agent workflows
-Usage: wt [OPTIONS] [COMMAND]
+Usage: wt [OPTIONS] [COMMAND]
-Commands:
+Commands:
switch Switch to a worktree
list List worktrees and their status
remove Remove worktree; delete branch if merged
@@ -34,11 +34,11 @@ Usage: wt [OPTIONS] [COMMAND]
hook Run configured hooks
config Manage user & project configs
-Options:
+Options:
-h, --help Print help (see more with '--help')
-V, --version Print version
-Global Options:
+Global Options:
-C <path> Working directory for this command
--config <path> User config file path
-v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove.snap b/tests/snapshots/integration__integration_tests__help__help_remove.snap
new file mode 100644
index 000000000..72ebccbdd
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_remove.snap
@@ -0,0 +1,126 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - remove
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt remove - Remove worktree; delete branch if merged
+
+For finished feature branches. Removes the current worktree by default.
+
+Usage: wt remove [OPTIONS] [BRANCHES]...
+
+Arguments:
+ [BRANCHES]...
+ Branch name [default: current]
+
+Options:
+ --no-delete-branch
+ Keep branch after removal
+
+ -D, --force-delete
+ Delete unmerged branches
+
+ --foreground
+ Run removal in foreground (block until complete)
+
+ --no-verify
+ Skip hooks
+
+ -y, --yes
+ Skip approval prompts
+
+ -f, --force
+ Force worktree removal
+
+ Remove worktrees even if they contain untracked files (like build artifacts). Without this flag, removal fails if untracked files exist.
+
+ -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: hooks, templates; -vv: debug report)
+
+Examples
+
+Remove current worktree:
+
+ wt remove
+
+Remove specific worktrees:
+
+ wt remove feature-branch
+ wt remove old-feature another-branch
+
+Keep the branch:
+
+ wt remove --no-delete-branch feature-branch
+
+Force-delete an unmerged branch:
+
+ wt remove -D experimental
+
+Branch cleanup
+
+By default, branches are deleted when merging them would add nothing. This works with squash-merge and rebase workflows where commit history differs but file changes match.
+
+Worktrunk checks five conditions (in order of cost):
+
+1. Same commit — Branch HEAD equals the default branch. Shows _ in wt list.
+2. Ancestor — Branch is in target's history (fast-forward or rebase case). Shows ⊂.
+3. No added changes — Three-dot diff (target...branch) is empty. Shows ⊂.
+4. Trees match — Branch tree SHA equals target tree SHA. Shows ⊂.
+5. Merge adds nothing — Simulated merge produces the same tree as target. Handles squash-merged branches where target has advanced. Shows ⊂.
+
+The 'same commit' check uses the local default branch; for other checks, 'target' means the default branch, or its upstream (e.g., origin/main) when strictly ahead.
+
+Branches showing _ or ⊂ are dimmed as safe to delete.
+
+Force flags
+
+Worktrunk has two force flags for different situations:
+
+ Flag Scope When to use
+ ─────────────────── ──────── ──────────────────────────────────────────────────────────
+ --force (-f) Worktree Worktree has untracked files (build artifacts, IDE config)
+ --force-delete (-D) Branch Branch has unmerged commits
+
+ wt remove feature --force # Remove worktree with untracked files
+ wt remove feature -D # Delete unmerged branch
+ wt remove feature --force -D # Both
+
+Without --force, removal fails if the worktree contains untracked files. Without -D, removal keeps branches with unmerged changes. Use --no-delete-branch to keep the branch regardless of merge status.
+
+Background removal
+
+Removal runs in the background by default (returns immediately). Logs are written to .git/wt-logs/{branch}-remove.log. Use --foreground to run in the foreground.
+
+See also
+
+- wt merge — Remove worktree after merging
+- wt list — View all worktrees
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index 72ebccbdd..9eb8e5aeb 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -22,70 +22,70 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt remove - Remove worktree; delete branch if merged
+wt remove - Remove worktree; delete branch if merged
-For finished feature branches. Removes the current worktree by default.
+For finished feature branches. Removes the current worktree by default.
-Usage: wt remove [OPTIONS] [BRANCHES]...
+Usage: wt remove [OPTIONS] [BRANCHES]...
-Arguments:
- [BRANCHES]...
+Arguments:
+ [BRANCHES]...
Branch name [default: current]
-Options:
- --no-delete-branch
+Options:
+ --no-delete-branch
Keep branch after removal
- -D, --force-delete
+ -D, --force-delete
Delete unmerged branches
- --foreground
+ --foreground
Run removal in foreground (block until complete)
- --no-verify
+ --no-verify
Skip hooks
- -y, --yes
+ -y, --yes
Skip approval prompts
- -f, --force
- Force worktree removal
+ -f, --force
+ Force worktree removal
- Remove worktrees even if they contain untracked files (like build artifacts). Without this flag, removal fails if untracked files exist.
+ Remove worktrees even if they contain untracked files (like build artifacts). Without this flag, removal fails if untracked files exist.
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
-Examples
+Examples
Remove current worktree:
- wt remove
+ wt remove
Remove specific worktrees:
- wt remove feature-branch
- wt remove old-feature another-branch
+ wt remove feature-branch
+ wt remove old-feature another-branch
Keep the branch:
- wt remove --no-delete-branch feature-branch
+ wt remove --no-delete-branch feature-branch
Force-delete an unmerged branch:
- wt remove -D experimental
+ wt remove -D experimental
-Branch cleanup
+Branch cleanup
By default, branches are deleted when merging them would add nothing. This works with squash-merge and rebase workflows where commit history differs but file changes match.
@@ -101,7 +101,7 @@ The 'same commit' check uses the local default branch; for other checks, 'target
Branches showing _ or ⊂ are dimmed as safe to delete.
-Force flags
+Force flags
Worktrunk has two force flags for different situations:
@@ -110,17 +110,17 @@ Worktrunk has two force flags for different situations:
--force (-f) Worktree Worktree has untracked files (build artifacts, IDE config)
--force-delete (-D) Branch Branch has unmerged commits
- wt remove feature --force # Remove worktree with untracked files
- wt remove feature -D # Delete unmerged branch
- wt remove feature --force -D # Both
+ wt remove feature --force # Remove worktree with untracked files
+ wt remove feature -D # Delete unmerged branch
+ wt remove feature --force -D # Both
Without --force, removal fails if the worktree contains untracked files. Without -D, removal keeps branches with unmerged changes. Use --no-delete-branch to keep the branch regardless of merge status.
-Background removal
+Background removal
Removal runs in the background by default (returns immediately). Logs are written to .git/wt-logs/{branch}-remove.log. Use --foreground to run in the foreground.
-See also
+See also
- wt merge — Remove worktree after merging
- wt list — View all worktrees
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_short.snap b/tests/snapshots/integration__integration_tests__help__help_remove_short.snap
index cd991aa9a..14cb072d1 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_short.snap
@@ -24,12 +24,12 @@ exit_code: 0
----- stderr -----
wt remove - Remove worktree; delete branch if merged
-Usage: wt remove [OPTIONS] [BRANCHES]...
+Usage: wt remove [OPTIONS] [BRANCHES]...
-Arguments:
+Arguments:
[BRANCHES]... Branch name [default: current]
-Options:
+Options:
--no-delete-branch Keep branch after removal
-D, --force-delete Delete unmerged branches
--foreground Run removal in foreground (block until complete)
@@ -38,7 +38,7 @@ Usage: wt remove [OPTIONS] [BRANCHES]...
-f, --force Force worktree removal
-h, --help Print help (see more with '--help')
-Global Options:
+Global Options:
-C <path> Working directory for this command
--config <path> User config file path
-v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_root.snap b/tests/snapshots/integration__integration_tests__help__help_root.snap
new file mode 100644
index 000000000..8808a9382
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_root.snap
@@ -0,0 +1,66 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt - Git worktree management for parallel AI agent workflows
+
+Usage: wt [OPTIONS] [COMMAND]
+
+Commands:
+ switch Switch to a worktree
+ list List worktrees and their status
+ remove Remove worktree; delete branch if merged
+ merge Merge current branch into target
+ select Interactive worktree selector
+ step Run individual operations
+ hook Run configured hooks
+ config Manage user & project configs
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+ -V, --version
+ Print version
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose...
+ Verbose output (-v: hooks, templates; -vv: debug report)
+
+Getting started
+
+ wt switch --create feature # Create worktree and branch
+ wt switch feature # Switch to worktree
+ wt list # Show all worktrees
+ wt remove # Remove worktree; delete branch if merged
+
+Run wt config shell install to set up directory switching.
+Run wt config create to customize worktree locations.
+
+Docs: https://worktrunk.dev
+GitHub: https://github.com/max-sixty/worktrunk
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_long.snap b/tests/snapshots/integration__integration_tests__help__help_root_long.snap
index 8808a9382..200ee3c6c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root_long.snap
@@ -23,9 +23,9 @@ exit_code: 0
----- stderr -----
wt - Git worktree management for parallel AI agent workflows
-Usage: wt [OPTIONS] [COMMAND]
+Usage: wt [OPTIONS] [COMMAND]
-Commands:
+Commands:
switch Switch to a worktree
list List worktrees and their status
remove Remove worktree; delete branch if merged
@@ -35,21 +35,21 @@ Usage: wt [OPTIONS] [COMMAND]
hook Run configured hooks
config Manage user & project configs
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
- -V, --version
+ -V, --version
Print version
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Getting started
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_short.snap b/tests/snapshots/integration__integration_tests__help__help_root_short.snap
index 28b52a6a7..536866381 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root_short.snap
@@ -23,9 +23,9 @@ exit_code: 0
----- stderr -----
wt - Git worktree management for parallel AI agent workflows
-Usage: wt [OPTIONS] [COMMAND]
+Usage: wt [OPTIONS] [COMMAND]
-Commands:
+Commands:
switch Switch to a worktree
list List worktrees and their status
remove Remove worktree; delete branch if merged
@@ -35,11 +35,11 @@ Usage: wt [OPTIONS] [COMMAND]
hook Run configured hooks
config Manage user & project configs
-Options:
+Options:
-h, --help Print help (see more with '--help')
-V, --version Print version
-Global Options:
+Global Options:
-C <path> Working directory for this command
--config <path> User config file path
-v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_select.snap b/tests/snapshots/integration__integration_tests__help__help_select.snap
new file mode 100644
index 000000000..d3e6ecc8d
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_select.snap
@@ -0,0 +1,97 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - select
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt select - Interactive worktree selector
+
+Browse and switch worktrees with live preview.
+
+Usage: wt select [OPTIONS]
+
+Options:
+ --branches
+ Include branches without worktrees
+
+ --remotes
+ Include remote branches
+
+ -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: hooks, templates; -vv: debug report)
+
+
+Examples
+
+Open the selector:
+
+ wt select
+
+Preview tabs
+
+Toggle between views with number keys:
+
+1. HEAD± — Diff of uncommitted changes
+2. log — Recent commits; commits already on the default branch have dimmed hashes
+3. main…± — Diff of changes since the merge-base with the default branch
+4. remote⇅ — Diff vs upstream tracking branch (ahead/behind)
+
+Keybindings
+
+ Key Action
+ ───────────── ───────────────────────────
+ ↑/↓ Navigate worktree list
+ Enter Switch to selected worktree
+ Esc Cancel
+ (type) Filter worktrees
+ 1/2/3/4 Switch preview tab
+ Alt-p Toggle preview panel
+ Ctrl-u/Ctrl-d Scroll preview up/down
+
+With --branches, branches without worktrees are included — selecting one creates a worktree. This matches wt list --branches.
+
+Configuration
+
+Pager
+
+The preview panel pipes diff output through git's pager (typically less or delta). Override pager behavior in user config:
+
+ [select]
+ pager = "delta --paging=never"
+
+This is useful when the default pager doesn't render correctly in the embedded preview panel.
+
+See also
+
+- wt list — Static table view with all worktree metadata
+- wt switch — Direct switching to a known target branch
+
+Available on Unix only (macOS, Linux). On Windows, use wt list or wt switch directly.
diff --git a/tests/snapshots/integration__integration_tests__help__help_select_short.snap b/tests/snapshots/integration__integration_tests__help__help_select_short.snap
new file mode 100644
index 000000000..61723d9a4
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_select_short.snap
@@ -0,0 +1,37 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - select
+ - "-h"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt select - Interactive worktree selector
+
+Usage: wt select [OPTIONS]
+
+Options:
+ --branches Include branches without worktrees
+ --remotes Include remote branches
+ -h, --help Print help (see more with '--help')
+
+Global Options:
+ -C <path> Working directory for this command
+ --config <path> User config file path
+ -v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_step.snap b/tests/snapshots/integration__integration_tests__help__help_step.snap
new file mode 100644
index 000000000..09ea9d6c2
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_step.snap
@@ -0,0 +1,78 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - step
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt step - Run individual operations
+
+The building blocks of wt merge — commit, squash, rebase, push — plus standalone utilities.
+
+Usage: wt step [OPTIONS] <COMMAND>
+
+Commands:
+ commit Commit changes with LLM commit message
+ squash Squash commits since branching
+ push Fast-forward target to current branch
+ rebase Rebase onto target
+ copy-ignored Copy gitignored files to another worktree
+ for-each [experimental] Run command in each worktree
+
+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: hooks, templates; -vv: debug report)
+
+Examples
+
+Commit with LLM-generated message:
+
+ wt step commit
+
+Manual merge workflow with review between steps:
+
+ wt step commit
+ wt step squash
+ wt step rebase
+ wt step push
+
+Operations
+
+- commit — Stage and commit with LLM-generated message
+- squash — Squash all branch commits into one with LLM-generated message
+- rebase — Rebase onto target branch
+- push — Fast-forward target to current branch
+- copy-ignored — Copy gitignored files between worktrees
+- for-each — [experimental] Run a command in every worktree
+
+See also
+
+- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automatically
+- wt hook — Run configured hooks
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_commit.snap b/tests/snapshots/integration__integration_tests__help__help_step_commit.snap
new file mode 100644
index 000000000..0bb81a8fd
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_step_commit.snap
@@ -0,0 +1,94 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - step
+ - commit
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt step commit - Commit changes with LLM commit message
+
+Stages working tree changes and commits with an LLM-generated message.
+
+Usage: wt step commit [OPTIONS]
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --no-verify
+ Skip hooks
+
+ --stage <STAGE>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - all: Stage everything: untracked files + unstaged tracked changes
+ - tracked: Stage tracked changes only (like git add -u)
+ - none: Stage nothing, commit only what's already in the index
+
+ --show-prompt
+ Show prompt without running LLM
+
+ Outputs the rendered prompt to stdout for debugging or manual piping.
+
+ -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: hooks, templates; -vv: debug report)
+
+Stages all changes (including untracked files) and commits with an LLM-generated message.
+
+Options
+
+`--stage`
+
+Controls what to stage before committing:
+
+ Value Behavior
+ ─────── ───────────────────────────────────────────────────────
+ all Stage all changes including untracked files (default)
+ tracked Stage only modified tracked files
+ none Don't stage anything, commit only what's already staged
+
+ wt step commit --stage=tracked
+
+Configure the default in user config:
+
+ [commit]
+ stage = "tracked"
+
+`--show-prompt`
+
+Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
+
+ # Inspect the rendered prompt
+ wt step commit --show-prompt | less
+ 
+ # Pipe to a different LLM
+ wt step commit --show-prompt | llm -m gpt-5-nano
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap
new file mode 100644
index 000000000..fb1e132a8
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_step_copy_ignored.snap
@@ -0,0 +1,132 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - step
+ - copy-ignored
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt step copy-ignored - Copy gitignored files to another worktree
+
+Copies gitignored files to another worktree. By default copies all gitignored files; use .worktreeinclude to limit what gets copied. Useful in hooks to copy build caches and dependencies to new worktrees. Skips symlinks and existing files.
+
+Usage: wt step copy-ignored [OPTIONS]
+
+Options:
+ --from <FROM>
+ Source worktree branch
+
+ Defaults to main worktree.
+
+ --to <TO>
+ Destination worktree branch
+
+ Defaults to current worktree.
+
+ --dry-run
+ Show what would be copied
+
+ -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: hooks, templates; -vv: debug report)
+
+Git worktrees share the repository but not untracked files. This command copies gitignored files to another worktree, eliminating cold starts.
+
+Setup
+
+Add to the project config:
+
+ # .config/wt.toml
+ [post-start]
+ copy = "wt step copy-ignored"
+
+What gets copied
+
+All gitignored files are copied by default. Tracked files are never touched.
+
+To limit what gets copied, create .worktreeinclude with gitignore-style patterns. Files must be both gitignored and in .worktreeinclude:
+
+ # .worktreeinclude
+ .env
+ node_modules/
+ target/
+
+Common patterns
+
+ Type Patterns
+ ───────────────── ──────────────────────────────────────────────
+ Dependencies node_modules/, .venv/, target/, vendor/, Pods/
+ Build caches .cache/, .next/, .parcel-cache/, .turbo/
+ Generated assets Images, ML models, binaries too large for git
+ Environment files .env (if not generated per-worktree)
+
+Features
+
+- Uses copy-on-write (reflink) when available for space-efficient copies
+- Handles nested .gitignore files, global excludes, and .git/info/exclude
+- Skips existing files (safe to re-run)
+- Skips .git entries and other worktrees
+
+Performance
+
+Reflink copies share disk blocks until modified — no data is actually copied. For a 14GB target/ directory:
+
+ Command Time
+ ───────────────────────────── ────
+ cp -R (full copy) 2m
+ cp -Rc / wt step copy-ignored 20s
+
+Uses per-file reflink (like cp -Rc) — copy time scales with file count.
+
+Use the post-start hook so the copy runs in the background. Use post-create instead if subsequent hooks or --execute command need the copied files immediately.
+
+Language-specific notes
+
+Rust
+
+The target/ directory is huge (often 1-10GB). Copying with reflink cuts first build from ~68s to ~3s by reusing compiled dependencies.
+
+Node.js
+
+node_modules/ is large but mostly static. If the project has no native dependencies, symlinks are even faster:
+
+ [post-create]
+ deps = "ln -sf {{ primary_worktree_path }}/node_modules ."
+
+Python
+
+Virtual environments contain absolute paths and can't be copied. Use uv sync instead — it's fast enough that copying isn't worth it.
+
+Behavior vs Claude Code on desktop
+
+The .worktreeinclude pattern is shared with Claude Code on desktop, which copies matching files when creating worktrees. Differences:
+
+- worktrunk copies all gitignored files by default; Claude Code requires .worktreeinclude
+- worktrunk uses copy-on-write for large directories like target/ — potentially 30x faster on macOS, 6x on Linux
+- worktrunk runs as a configurable hook in the worktree lifecycle
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_for_each.snap b/tests/snapshots/integration__integration_tests__help__help_step_for_each.snap
new file mode 100644
index 000000000..8d4cbabff
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_step_for_each.snap
@@ -0,0 +1,74 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - step
+ - for-each
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt step for-each - [experimental] Run command in each worktree
+
+Usage: wt step for-each [OPTIONS] -- <ARGS>...
+
+Arguments:
+ <ARGS>...
+ Command template (see --help for all variables)
+
+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: hooks, templates; -vv: debug report)
+
+Executes a command sequentially in every worktree with real-time output. Continues on failure and shows a summary at the end.
+
+Context JSON is piped to stdin for scripts that need structured data.
+
+Template variables
+
+All variables are shell-escaped. See wt hook template variables for the complete list and filters.
+
+Examples
+
+Check status across all worktrees:
+
+ wt step for-each -- git status --short
+
+Run npm install in all worktrees:
+
+ wt step for-each -- npm install
+
+Use branch name in command:
+
+ wt step for-each -- "echo Branch: {{ branch }}"
+
+Pull updates in worktrees with upstreams (skips others):
+
+ git fetch --prune && wt step for-each -- '[ "$(git rev-parse @{u} 2>/dev/null)" ] || exit 0; git pull --autostash'
+
+Note: This command is experimental and may change in future versions.
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index 09ea9d6c2..03ce1e08b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -22,13 +22,13 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt step - Run individual operations
+wt step - Run individual operations
-The building blocks of wt merge — commit, squash, rebase, push — plus standalone utilities.
+The building blocks of wt merge — commit, squash, rebase, push — plus standalone utilities.
-Usage: wt step [OPTIONS] <COMMAND>
+Usage: wt step [OPTIONS] <COMMAND>
-Commands:
+Commands:
commit Commit changes with LLM commit message
squash Squash commits since branching
push Fast-forward target to current branch
@@ -36,34 +36,34 @@ Usage: wt step [OPTIONS] <COMMAND>
copy-ignored Copy gitignored files to another worktree
for-each [experimental] Run command in each worktree
-Options:
- -h, --help
+Options:
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
-Examples
+Examples
Commit with LLM-generated message:
- wt step commit
+ wt step commit
Manual merge workflow with review between steps:
- wt step commit
- wt step squash
- wt step rebase
- wt step push
+ wt step commit
+ wt step squash
+ wt step rebase
+ wt step push
-Operations
+Operations
- commit — Stage and commit with LLM-generated message
- squash — Squash all branch commits into one with LLM-generated message
@@ -72,7 +72,7 @@ Manual merge workflow with review between steps:
- copy-ignored — Copy gitignored files between worktrees
- for-each — [experimental] Run a command in every worktree
-See also
+See also
- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automatically
- wt hook — Run configured hooks
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_push.snap b/tests/snapshots/integration__integration_tests__help__help_step_push.snap
new file mode 100644
index 000000000..49fa8020f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_step_push.snap
@@ -0,0 +1,50 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - step
+ - push
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt step push - Fast-forward target to current branch
+
+Updates the local target branch (e.g., main) to include current commits. Similar to git push . HEAD:<target>, but uses receive.denyCurrentBranch=updateInstead internally.
+
+Usage: wt step push [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
+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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_rebase.snap b/tests/snapshots/integration__integration_tests__help__help_step_rebase.snap
new file mode 100644
index 000000000..372f1beb7
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_step_rebase.snap
@@ -0,0 +1,48 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - step
+ - rebase
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt step rebase - Rebase onto target
+
+Usage: wt step rebase [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
+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: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_short.snap b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
index 0f988511c..f0dcd217d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
@@ -24,9 +24,9 @@ exit_code: 0
----- stderr -----
wt step - Run individual operations
-Usage: wt step [OPTIONS] <COMMAND>
+Usage: wt step [OPTIONS] <COMMAND>
-Commands:
+Commands:
commit Commit changes with LLM commit message
squash Squash commits since branching
push Fast-forward target to current branch
@@ -34,10 +34,10 @@ Usage: wt step [OPTIONS] <COMMAND>
copy-ignored Copy gitignored files to another worktree
for-each [experimental] Run command in each worktree
-Options:
+Options:
-h, --help Print help (see more with '--help')
-Global Options:
+Global Options:
-C <path> Working directory for this command
--config <path> User config file path
-v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_squash.snap b/tests/snapshots/integration__integration_tests__help__help_step_squash.snap
new file mode 100644
index 000000000..35b985949
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_step_squash.snap
@@ -0,0 +1,96 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - step
+ - squash
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt step squash - Squash commits since branching
+
+Stages working tree changes, squashes all commits since diverging from target into one, generates message with LLM.
+
+Usage: wt step squash [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
+Options:
+ -y, --yes
+ Skip approval prompts
+
+ --no-verify
+ Skip hooks
+
+ --stage <STAGE>
+ What to stage before committing [default: all]
+
+ Possible values:
+ - all: Stage everything: untracked files + unstaged tracked changes
+ - tracked: Stage tracked changes only (like git add -u)
+ - none: Stage nothing, commit only what's already in the index
+
+ --show-prompt
+ Show prompt without running LLM
+
+ Outputs the rendered prompt to stdout for debugging or manual piping.
+
+ -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: hooks, templates; -vv: debug report)
+
+Stages all changes (including untracked files), then squashes all commits since diverging from the target branch into a single commit with an LLM-generated message.
+
+Options
+
+`--stage`
+
+Controls what to stage before squashing:
+
+ Value Behavior
+ ─────── ─────────────────────────────────────────────────────
+ all Stage all changes including untracked files (default)
+ tracked Stage only modified tracked files
+ none Don't stage anything, squash only committed changes
+
+ wt step squash --stage=none
+
+Configure the default in user config:
+
+ [commit]
+ stage = "tracked"
+
+`--show-prompt`
+
+Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
+
+ wt step squash --show-prompt | less
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snap
new file mode 100644
index 000000000..2c74eb642
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_switch.snap
@@ -0,0 +1,172 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - switch
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_EDITOR: ""
+ RUST_LOG: warn
+ SHELL: ""
+ TERM: alacritty
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WT_TEST_DELAYED_STREAM_MS: "-1"
+ WT_TEST_EPOCH: "1735776000"
+---
+success: true
+exit_code: 0
+----- stdout -----
+
+----- stderr -----
+wt switch - Switch to a worktree
+
+Creates one if needed.
+
+Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]
+
+Arguments:
+ <BRANCH>
+ Branch name or shortcut
+
+ Shortcuts: '^' (default branch), '-' (previous), '@' (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)
+
+ [EXECUTE_ARGS]...
+ Additional arguments for --execute command (after --)
+
+ Arguments after -- are appended to the execute command. Each argument is expanded for templates, then POSIX shell-escaped.
+
+Options:
+ -c, --create
+ Create a new branch
+
+ -b, --base <BASE>
+ Base branch
+
+ Defaults to default branch.
+
+ -x, --execute <EXECUTE>
+ Command to run after switch
+
+ Replaces the wt process with the command after switching, giving it full terminal control. Useful for launching editors, AI agents, or other interactive tools.
+
+ Supports ]8;;@/hook.md#template-variables\hook template variables]8;;\ ({{ branch }}, {{ worktree_path }}, etc.) and filters. {{ base }} and {{ base_worktree_path }} require --create.
+
+ Especially useful with shell aliases:
+
+ alias wsc='wt switch --create -x claude'
+ wsc feature-branch -- 'Fix GH #322'
+
+ Then wsc feature-branch creates the worktree and launches Claude Code. Arguments after -- are passed to the command, so wsc feature -- 'Fix GH #322' runs claude 'Fix GH #322', starting Claude with a prompt.
+
+ Template example: -x 'code {{ worktree_path }}' opens VS Code at the worktree, -x 'tmux new -s {{ branch | sanitize }}' starts a tmux session named after the branch.
+
+ -y, --yes
+ Skip approval prompts
+
+ --clobber
+ Remove stale paths at target
+
+ --no-verify
+ Skip hooks
+
+ -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: hooks, templates; -vv: debug report)
+
+Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike git switch, this navigates between worktrees rather than changing branches in place.
+
+Examples
+
+ wt switch feature-auth # Switch to worktree
+ wt switch - # Previous worktree (like cd -)
+ wt switch --create new-feature # Create new branch and worktree
+ wt switch --create hotfix --base production
+ wt switch pr:123 # Switch to PR #123's branch
+
+Creating a branch
+
+The --create flag creates a new branch from the --base branch (defaults to default branch). Without --create, the branch must already exist.
+
+Upstream tracking: Branches created with --create have no upstream tracking configured. This prevents accidental pushes to the wrong branch — for example, --base origin/main would otherwise make git push target main. Use git push -u origin <branch> to set up tracking when you're ready.
+
+Without --create, switching to a remote branch (e.g., wt switch feature when only origin/feature exists) creates a local branch tracking the remote — this is the standard git behavior and is preserved.
+
+Creating worktrees
+
+If the branch already has a worktree, wt switch changes directories to it. Otherwise, it creates one, running hooks.
+
+When creating a worktree, worktrunk:
+
+1. Creates worktree at configured path
+2. Switches to new directory
+3. Runs post-create hooks (blocking)
+4. Spawns post-start hooks (background)
+
+ wt switch feature # Existing branch → creates worktree
+ wt switch --create feature # New branch and worktree
+ wt switch --create fix --base release # New branch from release
+ wt switch --create temp --no-verify # Skip hooks
+
+Shortcuts
+
+ Shortcut Meaning
+ ──────── ─────────────────────────────
+ ^ Default branch (main/master)
+ @ Current branch/worktree
+ - Previous worktree (like cd -)
+ pr:{N} GitHub PR #N's branch
+ mr:{N} GitLab MR !N's branch
+
+ wt switch - # Back to previous
+ wt switch ^ # Default branch worktree
+ wt switch --create fix --base=@ # Branch from current HEAD
+ wt switch pr:123 # PR #123's branch
+ wt switch mr:101 # MR !101's branch
+
+GitHub pull requests (experimental)
+
+The pr:<number> syntax resolves the branch for a GitHub pull request. For same-repo PRs, it switches to the branch directly. For fork PRs, it fetches refs/pull/N/head and configures pushRemote to the fork URL.
+
+ wt switch pr:101 # Checkout PR #101
+
+Requires gh CLI to be installed and authenticated. The --create flag cannot be used with pr: syntax since the branch already exists.
+
+Fork PRs: The local branch uses the PR's branch name directly (e.g., feature-fix), so git push works normally. If a local branch with that name already exists tracking something else, rename it first.
+
+GitLab merge requests (experimental)
+
+The mr:<number> syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches refs/merge-requests/N/head and configures pushRemote to the fork URL.
+
+ wt switch mr:101 # Checkout MR !101
+
+Requires glab CLI to be installed and authenticated. The --create flag cannot be used with mr: syntax since the branch already exists.
+
+Fork MRs: The local branch uses the MR's branch name directly, so git push works normally. If a local branch with that name already exists tracking something else, rename it first.
+
+When wt switch fails
+
+- Branch doesn't exist — Use --create, or check wt list --branches
+- Path occupied — Another worktree is at the target path; switch to it or remove it
+- Stale directory — Use --clobber to remove a non-worktree directory at the target path
+
+To change which branch a worktree is on, use git switch inside that worktree.
+
+See also
+
+- wt select — Interactive worktree selection
+- wt list — View all worktrees
+- wt remove — Delete worktrees when done
+- wt merge — Integrate changes back to the default branch
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 2c74eb642..1782ab760 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -22,81 +22,81 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt switch - Switch to a worktree
+wt switch - Switch to a worktree
-Creates one if needed.
+Creates one if needed.
-Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]
+Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]
-Arguments:
- <BRANCH>
- Branch name or shortcut
+Arguments:
+ <BRANCH>
+ Branch name or shortcut
- Shortcuts: '^' (default branch), '-' (previous), '@' (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)
+ Shortcuts: '^' (default branch), '-' (previous), '@' (current), 'pr:{N}' (GitHub PR), 'mr:{N}' (GitLab MR)
- [EXECUTE_ARGS]...
- Additional arguments for --execute command (after --)
+ [EXECUTE_ARGS]...
+ Additional arguments for --execute command (after --)
- Arguments after -- are appended to the execute command. Each argument is expanded for templates, then POSIX shell-escaped.
+ Arguments after -- are appended to the execute command. Each argument is expanded for templates, then POSIX shell-escaped.
-Options:
- -c, --create
+Options:
+ -c, --create
Create a new branch
- -b, --base <BASE>
- Base branch
+ -b, --base <BASE>
+ Base branch
- Defaults to default branch.
+ Defaults to default branch.
- -x, --execute <EXECUTE>
- Command to run after switch
+ -x, --execute <EXECUTE>
+ Command to run after switch
- Replaces the wt process with the command after switching, giving it full terminal control. Useful for launching editors, AI agents, or other interactive tools.
+ Replaces the wt process with the command after switching, giving it full terminal control. Useful for launching editors, AI agents, or other interactive tools.
- Supports ]8;;@/hook.md#template-variables\hook template variables]8;;\ ({{ branch }}, {{ worktree_path }}, etc.) and filters. {{ base }} and {{ base_worktree_path }} require --create.
+ Supports ]8;;@/hook.md#template-variables\hook template variables]8;;\ ({{ branch }}, {{ worktree_path }}, etc.) and filters. {{ base }} and {{ base_worktree_path }} require --create.
- Especially useful with shell aliases:
+ Especially useful with shell aliases:
- alias wsc='wt switch --create -x claude'
- wsc feature-branch -- 'Fix GH #322'
+ alias wsc='wt switch --create -x claude'
+ wsc feature-branch -- 'Fix GH #322'
+ 
+ Then wsc feature-branch creates the worktree and launches Claude Code. Arguments after -- are passed to the command, so wsc feature -- 'Fix GH #322' runs claude 'Fix GH #322', starting Claude with a prompt.
- Then wsc feature-branch creates the worktree and launches Claude Code. Arguments after -- are passed to the command, so wsc feature -- 'Fix GH #322' runs claude 'Fix GH #322', starting Claude with a prompt.
-
- Template example: -x 'code {{ worktree_path }}' opens VS Code at the worktree, -x 'tmux new -s {{ branch | sanitize }}' starts a tmux session named after the branch.
+ Template example: -x 'code {{ worktree_path }}' opens VS Code at the worktree, -x 'tmux new -s {{ branch | sanitize }}' starts a tmux session named after the branch.
- -y, --yes
+ -y, --yes
Skip approval prompts
- --clobber
+ --clobber
Remove stale paths at target
- --no-verify
+ --no-verify
Skip hooks
- -h, --help
+ -h, --help
Print help (see a summary with '-h')
-Global Options:
- -C <path>
+Global Options:
+ -C <path>
Working directory for this command
- --config <path>
+ --config <path>
User config file path
- -v, --verbose...
+ -v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
Worktrees are addressed by branch name; paths are computed from a configurable template. Unlike git switch, this navigates between worktrees rather than changing branches in place.
-Examples
+Examples
- wt switch feature-auth # Switch to worktree
- wt switch - # Previous worktree (like cd -)
- wt switch --create new-feature # Create new branch and worktree
- wt switch --create hotfix --base production
- wt switch pr:123 # Switch to PR #123's branch
+ wt switch feature-auth # Switch to worktree
+ wt switch - # Previous worktree (like cd -)
+ wt switch --create new-feature # Create new branch and worktree
+ wt switch --create hotfix --base production
+ wt switch pr:123 # Switch to PR #123's branch
-Creating a branch
+Creating a branch
The --create flag creates a new branch from the --base branch (defaults to default branch). Without --create, the branch must already exist.
@@ -104,7 +104,7 @@ The --create flag creates a new branch from the --base branch (d
Without --create, switching to a remote branch (e.g., wt switch feature when only origin/feature exists) creates a local branch tracking the remote — this is the standard git behavior and is preserved.
-Creating worktrees
+Creating worktrees
If the branch already has a worktree, wt switch changes directories to it. Otherwise, it creates one, running hooks.
@@ -115,12 +115,12 @@ When creating a worktree, worktrunk:
3. Runs post-create hooks (blocking)
4. Spawns post-start hooks (background)
- wt switch feature # Existing branch → creates worktree
- wt switch --create feature # New branch and worktree
- wt switch --create fix --base release # New branch from release
- wt switch --create temp --no-verify # Skip hooks
+ wt switch feature # Existing branch → creates worktree
+ wt switch --create feature # New branch and worktree
+ wt switch --create fix --base release # New branch from release
+ wt switch --create temp --no-verify # Skip hooks
-Shortcuts
+Shortcuts
Shortcut Meaning
──────── ─────────────────────────────
@@ -130,41 +130,41 @@ When creating a worktree, worktrunk:
pr:{N} GitHub PR #N's branch
mr:{N} GitLab MR !N's branch
- wt switch - # Back to previous
- wt switch ^ # Default branch worktree
- wt switch --create fix --base=@ # Branch from current HEAD
- wt switch pr:123 # PR #123's branch
- wt switch mr:101 # MR !101's branch
+ wt switch - # Back to previous
+ wt switch ^ # Default branch worktree
+ wt switch --create fix --base=@ # Branch from current HEAD
+ wt switch pr:123 # PR #123's branch
+ wt switch mr:101 # MR !101's branch
-GitHub pull requests (experimental)
+GitHub pull requests (experimental)
The pr:<number> syntax resolves the branch for a GitHub pull request. For same-repo PRs, it switches to the branch directly. For fork PRs, it fetches refs/pull/N/head and configures pushRemote to the fork URL.
- wt switch pr:101 # Checkout PR #101
+ wt switch pr:101 # Checkout PR #101
Requires gh CLI to be installed and authenticated. The --create flag cannot be used with pr: syntax since the branch already exists.
Fork PRs: The local branch uses the PR's branch name directly (e.g., feature-fix), so git push works normally. If a local branch with that name already exists tracking something else, rename it first.
-GitLab merge requests (experimental)
+GitLab merge requests (experimental)
The mr:<number> syntax resolves the branch for a GitLab merge request. For same-project MRs, it switches to the branch directly. For fork MRs, it fetches refs/merge-requests/N/head and configures pushRemote to the fork URL.
- wt switch mr:101 # Checkout MR !101
+ wt switch mr:101 # Checkout MR !101
Requires glab CLI to be installed and authenticated. The --create flag cannot be used with mr: syntax since the branch already exists.
Fork MRs: The local branch uses the MR's branch name directly, so git push works normally. If a local branch with that name already exists tracking something else, rename it first.
-When wt switch fails
+When wt switch fails
-- Branch doesn't exist — Use --create, or check wt list --branches
+- Branch doesn't exist — Use --create, or check wt list --branches
- Path occupied — Another worktree is at the target path; switch to it or remove it
- Stale directory — Use --clobber to remove a non-worktree directory at the target path
To change which branch a worktree is on, use git switch inside that worktree.
-See also
+See also
- wt select — Interactive worktree selection
- wt list — View all worktrees
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_short.snap b/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
index 68031070a..0f2db09e0 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
@@ -24,13 +24,13 @@ exit_code: 0
----- stderr -----
wt switch - Switch to a worktree
-Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]
+Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]
-Arguments:
+Arguments:
<BRANCH> Branch name or shortcut
[EXECUTE_ARGS]... Additional arguments for --execute command (after --)
-Options:
+Options:
-c, --create Create a new branch
-b, --base <BASE> Base branch
-x, --execute <EXECUTE> Command to run after switch
@@ -39,7 +39,7 @@ Usage: wt switch [OPTIONS] <BRANCH> [--
--no-verify Skip hooks
-h, --help Print help (see more with '--help')
-Global Options:
+Global Options:
-C <path> Working directory for this command
--config <path> User config file path
-v, --verbose... Verbose output (-v: hooks, templates; -vv: debug report)
diff --git a/tests/snapshots/integration__integration_tests__help__nested_subcommand_hook_post_create.snap b/tests/snapshots/integration__integration_tests__help__nested_subcommand_hook_post_create.snap
index 4841591a9..ae2f08837 100644
--- a/tests/snapshots/integration__integration_tests__help__nested_subcommand_hook_post_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__nested_subcommand_hook_post_create.snap
@@ -23,7 +23,7 @@ exit_code: 2
----- stderr -----
error: unrecognized subcommand 'post-create'
-Usage: wt [OPTIONS] [COMMAND]
+Usage: wt [OPTIONS] [COMMAND]
For more information, try '--help'.
diff --git a/tests/snapshots/integration__integration_tests__help__nested_subcommand_hook_pre_merge.snap b/tests/snapshots/integration__integration_tests__help__nested_subcommand_hook_pre_merge.snap
index b442f6913..076308fa8 100644
--- a/tests/snapshots/integration__integration_tests__help__nested_subcommand_hook_pre_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__nested_subcommand_hook_pre_merge.snap
@@ -25,7 +25,7 @@ exit_code: 2
tip: a similar subcommand exists: 'remove'
-Usage: wt [OPTIONS] [COMMAND]
+Usage: wt [OPTIONS] [COMMAND]
For more information, try '--help'.
diff --git a/tests/snapshots/integration__integration_tests__help__nested_subcommand_step_commit.snap b/tests/snapshots/integration__integration_tests__help__nested_subcommand_step_commit.snap
index e08e758ed..fa2a5e96f 100644
--- a/tests/snapshots/integration__integration_tests__help__nested_subcommand_step_commit.snap
+++ b/tests/snapshots/integration__integration_tests__help__nested_subcommand_step_commit.snap
@@ -23,7 +23,7 @@ exit_code: 2
----- stderr -----
error: unrecognized subcommand 'commit'
-Usage: wt [OPTIONS] [COMMAND]
+Usage: wt [OPTIONS] [COMMAND]
For more information, try '--help'.
diff --git a/tests/snapshots/integration__integration_tests__help__nested_subcommand_step_squash.snap b/tests/snapshots/integration__integration_tests__help__nested_subcommand_step_squash.snap
index 88d1449d2..95976f134 100644
--- a/tests/snapshots/integration__integration_tests__help__nested_subcommand_step_squash.snap
+++ b/tests/snapshots/integration__integration_tests__help__nested_subcommand_step_squash.snap
@@ -23,7 +23,7 @@ exit_code: 2
----- stderr -----
error: unrecognized subcommand 'squash'
-Usage: wt [OPTIONS] [COMMAND]
+Usage: wt [OPTIONS] [COMMAND]
For more information, try '--help'.