Skip to content

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

Refactor help output to use inline markdown renderer

Maximilian Roosd6d371a34fbc
diff --git a/src/cli.rs b/src/cli.rs
index 48041bf1c..8d60ff113 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -43,20 +43,13 @@ fn help_styles() -> Styles {
/// Default command name for worktrunk
const DEFAULT_COMMAND_NAME: &str = "wt";
-/// Help template for commands without subcommands
+/// Help template for commands
const HELP_TEMPLATE: &str = "\
{before-help}{name} - {about-with-newline}\
Usage: {usage}
{all-args}{after-help}";
-/// Help template for commands with subcommands
-const HELP_TEMPLATE_WITH_SUBCOMMANDS: &str = "\
-{before-help}{name} - {about-with-newline}\
-Usage: {usage}
-
-{all-args}{after-help}";
-
/// Build a clap Command for Cli with the shared help template applied recursively.
pub fn build_command() -> Command {
let cmd = Cli::command();
@@ -64,12 +57,7 @@ pub fn build_command() -> Command {
}
fn apply_help_template_recursive(mut cmd: Command, path: &str) -> Command {
- let template = if cmd.get_subcommands().next().is_some() {
- HELP_TEMPLATE_WITH_SUBCOMMANDS
- } else {
- HELP_TEMPLATE
- };
- cmd = cmd.help_template(template).display_name(path);
+ cmd = cmd.help_template(HELP_TEMPLATE).display_name(path);
for sub in cmd.get_subcommands_mut() {
let sub_cmd = std::mem::take(sub);
@@ -109,12 +97,7 @@ pub enum OutputFormat {
#[command(disable_help_subcommand = true)]
#[command(styles = help_styles())]
#[command(
- after_long_help = r#"-C <path>: Run as if started in <path> instead of current directory.
-
---config <path>: Override user config file location. Without this flag,
-config is loaded from (in order of precedence):
-1. WORKTRUNK_CONFIG_PATH environment variable
-2. ~/.config/worktrunk/config.toml (Linux/macOS) or %APPDATA%\worktrunk\config.toml (Windows)"#
+ after_long_help = r#"See `wt config --help` for configuration file locations and setup."#
)]
pub struct Cli {
/// Change working directory
@@ -158,22 +141,28 @@ pub struct Cli {
#[derive(Subcommand)]
pub enum ConfigShellCommand {
/// Generate shell integration code
- #[command(after_long_help = r#"MANUAL SETUP:
+ #[command(after_long_help = r#"## Manual Setup
Add one line to your shell config:
Bash (~/.bash_profile):
- eval "$(wt config shell init bash)"
+```bash
+eval "$(wt config shell init bash)"
+```
Fish (~/.config/fish/config.fish):
- wt config shell init fish | source
+```fish
+wt config shell init fish | source
+```
Zsh (~/.zshrc):
- eval "$(wt config shell init zsh)"
+```zsh
+eval "$(wt config shell init zsh)"
+```
-AUTO SETUP:
+## Auto Setup
-Use 'wt config shell install' to automatically add to your shell config."#)]
+Use `wt config shell install` to automatically add to your shell config."#)]
Init {
/// Shell to generate code for
#[arg(value_enum)]
@@ -185,16 +174,22 @@ Use 'wt config shell install' to automatically add to your shell config."#)]
},
/// Write shell integration to config files
- #[command(after_long_help = r#"AUTO SETUP:
+ #[command(after_long_help = r#"## Auto Setup
Detects existing shell config files and adds integration:
- wt config shell install
+```
+wt config shell install
+```
Install for specific shell only:
- wt config shell install zsh
+```
+wt config shell install zsh
+```
Skip confirmation prompt:
- wt config shell install --force"#)]
+```
+wt config shell install --force
+```"#)]
Install {
/// Shell to install (default: auto-detect)
#[arg(value_enum)]
@@ -213,6 +208,12 @@ Skip confirmation prompt:
#[derive(Subcommand)]
pub enum ApprovalsCommand {
/// Store approvals in config
+ #[command(
+ after_long_help = r#"Prompts for approval of all project commands and saves them to user config.
+
+By default, shows only unapproved commands. Use `--all` to review all commands
+including previously approved ones. Use `--force` to approve without prompts."#
+ )]
Ask {
/// Skip approval prompts
#[arg(short, long)]
@@ -224,6 +225,12 @@ pub enum ApprovalsCommand {
},
/// Clear approved commands from config
+ #[command(
+ after_long_help = r#"Removes saved approvals, requiring re-approval on next command run.
+
+By default, clears approvals for the current project. Use `--global` to clear
+all approvals across all projects."#
+ )]
Clear {
/// Clear global approvals
#[arg(short, long)]
@@ -240,12 +247,31 @@ pub enum ConfigCommand {
},
/// Create global configuration file
+ #[command(
+ after_long_help = concat!(
+ "Creates `~/.config/worktrunk/config.toml` with the following content:\n\n```\n",
+ include_str!("../dev/config.example.toml"),
+ "```"
+ )
+ )]
Create,
/// List configuration files & locations
+ #[command(
+ after_long_help = r#"Shows location and contents of global config (`~/.config/worktrunk/config.toml`)
+and project config (`.config/wt.toml`).
+
+If a config file doesn't exist, shows defaults that would be used."#
+ )]
List,
/// Refresh default branch from remote
+ #[command(
+ after_long_help = r#"Queries the remote to determine the default branch and caches the result.
+
+Use when the remote default branch has changed. The cached value is used by
+`wt merge`, `wt list`, and other commands that reference the default branch."#
+ )]
RefreshCache,
/// Manage branch status markers
@@ -255,7 +281,7 @@ pub enum ConfigCommand {
},
/// Manage command approvals
- #[command(after_long_help = r#"## HOW APPROVALS WORK
+ #[command(after_long_help = r#"## How Approvals Work
Commands from project hooks (.config/wt.toml) and LLM configuration require
approval on first run. This prevents untrusted projects from running arbitrary
@@ -274,7 +300,7 @@ commands.
- `--force` flag on individual commands (e.g., `wt merge --force`)
- Useful for CI/automation where prompts aren't possible
-## EXAMPLES
+## Examples
Pre-approve all commands for current project:
```
@@ -299,6 +325,12 @@ wt config approvals clear --global
#[derive(Subcommand)]
pub enum StatusAction {
/// Set status emoji for branch
+ #[command(
+ after_long_help = r#"Sets a custom status marker that appears in `wt list` output.
+
+Use emojis or short text to indicate work state (e.g., 🚧 WIP, ✅ ready, 🔒 blocked).
+Stored in git config under `worktrunk.status.<branch>`."#
+ )]
Set {
/// Status emoji to display
value: String,
@@ -309,6 +341,9 @@ pub enum StatusAction {
},
/// Clear status emoji
+ #[command(
+ after_long_help = r#"Removes status marker from branch(es). Use `*` to clear all statuses."#
+ )]
Unset {
/// Branch or "*" for all
#[arg(default_value = "", add = crate::completion::branch_value_completer())]
@@ -436,87 +471,61 @@ pub enum Commands {
/// Manage configuration and shell integration
#[command(
about = "Manage configuration and shell integration",
- after_long_help = r#"SETUP GUIDE:
+ after_long_help = r#"## Setup Guide
1. Set up shell integration
-
+ ```
wt config shell install
+ ```
Or manually add to your shell config:
+ ```
eval "$(wt config shell init bash)"
+ ```
2. (Optional) Create config file
-
+ ```
wt config create
+ ```
This creates ~/.config/worktrunk/config.toml with examples.
3. (Optional) Enable LLM commit messages
- Install: uv tool install -U llm
- Configure: llm keys set anthropic
+ Install: `uv tool install -U llm`
+ Configure: `llm keys set anthropic`
Add to config.toml:
- [commit-generation]
- command = "llm"
+ ```toml
+ [commit-generation]
+ command = "llm"
+ ```
-LLM SETUP DETAILS:
+## LLM Setup Details
For Claude:
- llm install llm-anthropic
- llm keys set anthropic
- llm models default claude-3.5-sonnet
+```
+llm install llm-anthropic
+llm keys set anthropic
+llm models default claude-3.5-sonnet
+```
For OpenAI:
- llm keys set openai
+```
+llm keys set openai
+```
-Use 'wt config list' to view your current configuration
+Use `wt config list` to view your current configuration.
Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
-CONFIGURATION FILES:
-
-Global config (loaded in order of precedence):
-1. WORKTRUNK_CONFIG_PATH environment variable
-2. ~/.config/worktrunk/config.toml (Linux/macOS)
- %APPDATA%\worktrunk\config.toml (Windows)
-
-Global config contents:
-- worktree-path: Path template (see CUSTOM WORKTREE PATHS below)
-- [list]: Default display options for 'wt list'
-- [commit-generation]: LLM command and prompt templates
-- [projects."project-id"]: Per-project approved commands (auto-populated)
-
-Project config (.config/wt.toml in repository root):
-- [post-create-command]: Commands after worktree creation
-- [post-start-command]: Background commands after creation
-- [pre-commit-command]: Validation before committing
-- [pre-merge-command]: Validation before merge
-- [post-merge-command]: Cleanup after merge
-
-CUSTOM WORKTREE PATHS:
-
-By default, worktrees live as siblings to the main repo:
-
- myapp/ # main worktree
- myapp.feature-x/ # secondary worktree
- myapp.bugfix-y/ # secondary worktree
-
-Customize the pattern in ~/.config/worktrunk/config.toml:
-
- # Inside the repo (keeps everything contained)
- worktree-path = ".worktrees/{{ branch }}"
-
- # Shared directory with multiple repos
- worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"
-
-Available variables: {{ main_worktree }}, {{ branch }}, {{ repo }}
-Default: "../{{ main_worktree }}.{{ branch }}"
+## Configuration Files
-CUSTOM PROMPT TEMPLATES:
+**Global config** (user settings):
+- Location: `~/.config/worktrunk/config.toml` (or `WORKTRUNK_CONFIG_PATH`)
+- Run `wt config create` to generate with documented examples
-Customize commit message prompts using minijinja templates.
-Available variables: diff, files, commits, commit_count, branch, target.
-Run 'wt config create' to generate example config with template examples.
-Docs: https://docs.rs/minijinja/latest/minijinja/syntax/
+**Project config** (repository hooks):
+- Location: `.config/wt.toml` in repository root
+- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks
"#
)]
Config {
@@ -542,7 +551,7 @@ Docs: https://docs.rs/minijinja/latest/minijinja/syntax/
#[command(after_long_help = "## Columns
- **Branch:** Branch name
-- **Status:** Quick status symbols (see STATUS SYMBOLS below)
+- **Status:** Quick status symbols (see Status Symbols below)
- **HEAD±:** Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
- **main↕:** Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
- **main…±** (`--full`): Line diffs in commits ahead of main (+added -deleted)
@@ -590,7 +599,7 @@ Order: `?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠`
## JSON Output
Use `--format=json` for structured data. Each object contains two status maps
-with the same fields in the same order as STATUS SYMBOLS above:
+with the same fields in the same order as Status Symbols above:
**`status`** - variant names for querying:
- `working_tree`: `{untracked, modified, staged, renamed, deleted}` booleans
@@ -606,20 +615,22 @@ Note: `locked` and `prunable` are top-level fields on worktree objects, not in s
**Query examples:**
- # Find worktrees with conflicts
- jq '.[] | select(.status.branch_state == \"Conflicts\")'
+```bash
+# Find worktrees with conflicts
+jq '.[] | select(.status.branch_state == \"Conflicts\")'
- # Find worktrees with untracked files
- jq '.[] | select(.status.working_tree.untracked)'
+# Find worktrees with untracked files
+jq '.[] | select(.status.working_tree.untracked)'
- # Find worktrees in rebase or merge
- jq '.[] | select(.status.git_operation != \"\")'
+# Find worktrees in rebase or merge
+jq '.[] | select(.status.git_operation != \"\")'
- # Get branches ahead of main
- jq '.[] | select(.status.main_divergence == \"Ahead\")'
+# Get branches ahead of main
+jq '.[] | select(.status.main_divergence == \"Ahead\")'
- # Find locked worktrees
- jq '.[] | select(.locked != null)'")]
+# Find locked worktrees
+jq '.[] | select(.locked != null)'
+```")]
List {
/// Output format (table, json)
#[arg(long, value_enum, default_value = "table", hide_possible_values = true)]
diff --git a/src/md_help.rs b/src/md_help.rs
index 752178451..d0652cc92 100644
--- a/src/md_help.rs
+++ b/src/md_help.rs
@@ -1,21 +1,85 @@
-//! Markdown rendering for CLI help text using termimad.
+//! Minimal markdown rendering for CLI help text.
-use termimad::{MadSkin, crossterm::style::Color};
+use anstyle::{AnsiColor, Color, Style};
/// Render markdown in help text to ANSI with minimal styling (green headers only)
pub fn render_markdown_in_help(help: &str) -> String {
- let mut skin = MadSkin::no_style();
- skin.headers[0].set_fg(Color::Green);
- skin.headers[1].set_fg(Color::Green);
+ let green = Style::new().fg_color(Some(Color::Ansi(AnsiColor::Green)));
+ let dimmed = Style::new().dimmed();
- let width = terminal_size::terminal_size()
- .map(|(w, _)| w.0 as usize)
- .unwrap_or(80);
+ let mut result = String::new();
+ let mut in_code_block = false;
- let rendered = format!("{}", skin.text(help, Some(width)));
+ for line in help.lines() {
+ let trimmed = line.trim_start();
+
+ // Track code block state
+ if trimmed.starts_with("```") {
+ in_code_block = !in_code_block;
+ // Skip the fence markers themselves
+ continue;
+ }
+
+ // Inside code blocks, render dimmed with indent
+ if in_code_block {
+ result.push_str(&format!(" {dimmed}{line}{dimmed:#}\n"));
+ continue;
+ }
+
+ // Outside code blocks, render markdown headers
+ if let Some(header_text) = trimmed.strip_prefix("## ") {
+ result.push_str(&format!("{green}{header_text}{green:#}\n"));
+ } else if let Some(header_text) = trimmed.strip_prefix("# ") {
+ result.push_str(&format!("{green}{header_text}{green:#}\n"));
+ } else {
+ // Render inline formatting (bold, inline code)
+ let formatted = render_inline_formatting(line);
+ result.push_str(&formatted);
+ result.push('\n');
+ }
+ }
// Color status symbols to match their descriptions
- colorize_status_symbols(&rendered)
+ colorize_status_symbols(&result)
+}
+
+/// Render inline markdown formatting (bold, inline code)
+fn render_inline_formatting(line: &str) -> String {
+ let bold = Style::new().bold();
+ let code = Style::new().dimmed();
+
+ let mut result = String::new();
+ let mut chars = line.chars().peekable();
+
+ while let Some(ch) = chars.next() {
+ if ch == '`' {
+ // Inline code
+ let mut code_content = String::new();
+ for c in chars.by_ref() {
+ if c == '`' {
+ break;
+ }
+ code_content.push(c);
+ }
+ result.push_str(&format!("{code}{code_content}{code:#}"));
+ } else if ch == '*' && chars.peek() == Some(&'*') {
+ // Bold
+ chars.next(); // consume second *
+ let mut bold_content = String::new();
+ while let Some(c) = chars.next() {
+ if c == '*' && chars.peek() == Some(&'*') {
+ chars.next(); // consume closing **
+ break;
+ }
+ bold_content.push(c);
+ }
+ result.push_str(&format!("{bold}{bold_content}{bold:#}"));
+ } else {
+ result.push(ch);
+ }
+ }
+
+ result
}
/// Add colors to status symbols in help text (matching wt list output colors)
diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rs
index 5475a36fb..fbed9f634 100644
--- a/tests/integration_tests/help.rs
+++ b/tests/integration_tests/help.rs
@@ -56,3 +56,58 @@ fn help_remove() {
fn help_merge() {
snapshot_help("help_merge", &["merge", "--help"]);
}
+
+#[test]
+fn help_config_create() {
+ snapshot_help("help_config_create", &["config", "create", "--help"]);
+}
+
+#[test]
+fn help_config_list() {
+ snapshot_help("help_config_list", &["config", "list", "--help"]);
+}
+
+#[test]
+fn help_config_refresh_cache() {
+ snapshot_help(
+ "help_config_refresh_cache",
+ &["config", "refresh-cache", "--help"],
+ );
+}
+
+#[test]
+fn help_config_status_set() {
+ snapshot_help(
+ "help_config_status_set",
+ &["config", "status", "set", "--help"],
+ );
+}
+
+#[test]
+fn help_config_status_unset() {
+ snapshot_help(
+ "help_config_status_unset",
+ &["config", "status", "unset", "--help"],
+ );
+}
+
+#[test]
+fn help_config_approvals() {
+ snapshot_help("help_config_approvals", &["config", "approvals", "--help"]);
+}
+
+#[test]
+fn help_config_approvals_ask() {
+ snapshot_help(
+ "help_config_approvals_ask",
+ &["config", "approvals", "ask", "--help"],
+ );
+}
+
+#[test]
+fn help_config_approvals_clear() {
+ snapshot_help(
+ "help_config_approvals_clear",
+ &["config", "approvals", "clear", "--help"],
+ );
+}
diff --git a/tests/snapshots/integration__integration_tests__help__help_beta.snap b/tests/snapshots/integration__integration_tests__help__help_beta.snap
index 747f8ddc0..6259d0623 100644
--- a/tests/snapshots/integration__integration_tests__help__help_beta.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_beta.snap
@@ -9,6 +9,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
success: true
exit_code: 0
@@ -21,16 +22,16 @@ Commands:
Options:
-h, --help
- Print help
+ Print help
Global Options:
-C <path>
- Change working directory
+ Change working directory
- --config <path>
- User config file path
+ --config <path>
+ User config file path
-v, --verbose
- Show commands and debug info
+ Show commands and debug info
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config.snap b/tests/snapshots/integration__integration_tests__help__help_config.snap
index 50ca2b43a..af065aa3f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config.snap
@@ -27,98 +27,60 @@ Commands:
Options:
-h, --help
- Print help (see a summary with '-h')
+ Print help (see a summary with '-h')
Global Options:
-C <path>
- Change working directory
+ Change working directory
- --config <path>
- User config file path
+ --config <path>
+ User config file path
-v, --verbose
- Show commands and debug info
+ Show commands and debug info
-SETUP GUIDE:
+Setup Guide
1. Set up shell integration
-
- wt config shell install
+  wt config shell install
Or manually add to your shell config:
- eval "$(wt config shell init bash)"
+  eval "$(wt config shell init bash)"
2. (Optional) Create config file
-
- wt config create
+  wt config create
This creates ~/.config/worktrunk/config.toml with examples.
3. (Optional) Enable LLM commit messages
- Install: uv tool install -U llm
- Configure: llm keys set anthropic
+ Install: uv tool install -U llm
+ Configure: llm keys set anthropic
Add to config.toml:
- [commit-generation]
- command = "llm"
+  [commit-generation]
+  command = "llm"
-LLM SETUP DETAILS:
+LLM Setup Details
For Claude:
- llm install llm-anthropic
- llm keys set anthropic
- llm models default claude-3.5-sonnet
+ llm install llm-anthropic
+ llm keys set anthropic
+ llm models default claude-3.5-sonnet
For OpenAI:
- llm keys set openai
+ llm keys set openai
-Use 'wt config list' to view your current configuration
+Use wt config list to view your current configuration.
Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
-CONFIGURATION FILES:
-
-Global config (loaded in order of precedence):
-1. WORKTRUNK_CONFIG_PATH environment variable
-2. ~/.config/worktrunk/config.toml (Linux/macOS)
- %APPDATA%\worktrunk\config.toml (Windows)
-
-Global config contents:
-- worktree-path: Path template (see CUSTOM WORKTREE PATHS below)
-- [list]: Default display options for 'wt list'
-- [commit-generation]: LLM command and prompt templates
-- [projects."project-id"]: Per-project approved commands (auto-populated)
-
-Project config (.config/wt.toml in repository root):
-- [post-create-command]: Commands after worktree creation
-- [post-start-command]: Background commands after creation
-- [pre-commit-command]: Validation before committing
-- [pre-merge-command]: Validation before merge
-- [post-merge-command]: Cleanup after merge
-
-CUSTOM WORKTREE PATHS:
-
-By default, worktrees live as siblings to the main repo:
-
- myapp/ # main worktree
- myapp.feature-x/ # secondary worktree
- myapp.bugfix-y/ # secondary worktree
-
-Customize the pattern in ~/.config/worktrunk/config.toml:
-
- # Inside the repo (keeps everything contained)
- worktree-path = ".worktrees/{{ branch }}"
-
- # Shared directory with multiple repos
- worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"
-
-Available variables: {{ main_worktree }}, {{ branch }}, {{ repo }}
-Default: "../{{ main_worktree }}.{{ branch }}"
+Configuration Files
-CUSTOM PROMPT TEMPLATES:
+Global config (user settings):
+- Location: ~/.config/worktrunk/config.toml (or WORKTRUNK_CONFIG_PATH)
+- Run wt config create to generate with documented examples
-Customize commit message prompts using minijinja templates.
-Available variables: diff, files, commits, commit_count, branch, target.
-Run 'wt config create' to generate example config with template examples.
-Docs: https://docs.rs/minijinja/latest/minijinja/syntax/
+Project config (repository hooks):
+- Location: .config/wt.toml in repository root
+- Contains: post-create, post-start, pre-commit, pre-merge, post-merge hooks
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_approvals.snap b/tests/snapshots/integration__integration_tests__help__help_config_approvals.snap
new file mode 100644
index 000000000..670243bdc
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_approvals.snap
@@ -0,0 +1,69 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - approvals
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt config approvals - Manage command approvals
+Usage: wt config approvals [OPTIONS] <COMMAND>
+
+Commands:
+ ask Store approvals in config
+ clear Clear approved commands from config
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Change working directory
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+How Approvals Work
+
+Commands from project hooks (.config/wt.toml) and LLM configuration require
+approval on first run. This prevents untrusted projects from running arbitrary
+commands.
+
+Approval flow:
+1. Command is shown with expanded template variables
+2. User approves or denies
+3. Approved commands are saved to user config under [projects."project-id"]
+
+When re-approval is required:
+- Command template changes (not just variable values)
+- Project ID changes (repository moves)
+
+Bypassing prompts:
+- --force flag on individual commands (e.g., wt merge --force)
+- Useful for CI/automation where prompts aren't possible
+
+Examples
+
+Pre-approve all commands for current project:
+ wt config approvals ask
+
+Clear approvals for current project:
+ wt config approvals clear
+
+Clear global approvals:
+ wt config approvals clear --global
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_approvals_ask.snap b/tests/snapshots/integration__integration_tests__help__help_config_approvals_ask.snap
new file mode 100644
index 000000000..38e738f5c
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_approvals_ask.snap
@@ -0,0 +1,47 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - approvals
+ - ask
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt config approvals ask - Store approvals in config
+Usage: wt config approvals ask [OPTIONS]
+
+Options:
+ -f, --force
+ Skip approval prompts
+
+ --all
+ Show all commands
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Change working directory
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Prompts for approval of all project commands and saves them to user config.
+
+By default, shows only unapproved commands. Use --all to review all commands
+including previously approved ones. Use --force to approve without prompts.
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_approvals_clear.snap b/tests/snapshots/integration__integration_tests__help__help_config_approvals_clear.snap
new file mode 100644
index 000000000..62bb5d24f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_approvals_clear.snap
@@ -0,0 +1,44 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - approvals
+ - clear
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt config approvals clear - Clear approved commands from config
+Usage: wt config approvals clear [OPTIONS]
+
+Options:
+ -g, --global
+ Clear global approvals
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Change working directory
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Removes saved approvals, requiring re-approval on next command run.
+
+By default, clears approvals for the current project. Use --global to clear
+all approvals across all projects.
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_create.snap b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
new file mode 100644
index 000000000..a1f14f654
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -0,0 +1,214 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - create
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt config create - Create global configuration file
+Usage: wt config create [OPTIONS]
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Change working directory
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Creates ~/.config/worktrunk/config.toml with the following content:
+
+ # Worktrunk Global Configuration
+ # Location (XDG Base Directory spec):
+ # macOS/Linux: ~/.config/worktrunk/config.toml (or $XDG_CONFIG_HOME/worktrunk/config.toml)
+ # Windows: %APPDATA%\worktrunk\config.toml
+ #
+ # Generate with: wt config create
+ #
+ # NOTE: This file is the source of truth for default configuration.
+ # The commented templates below match src/llm.rs constants:
+ # - DEFAULT_TEMPLATE (lines 41-76)
+ # - DEFAULT_SQUASH_TEMPLATE (lines 109-118)
+ # When changing these constants, update the commented sections here to match.
+ 
+ # Worktree Path Template
+ # Variables: {{ main_worktree }} = main worktree directory name, {{ branch }} = branch name
+ # Branch slashes are replaced with dashes (feature/auth → feature-auth)
+ # Paths are relative to the main worktree root (original repository directory)
+ worktree-path = "../{{ main_worktree }}.{{ branch }}"
+ 
+ # Alternative: Inside repo (useful for bare repos)
+ # worktree-path = ".worktrees/{{ branch }}"
+ 
+ # Alternative: Shared directory for multiple repos
+ # worktree-path = "../worktrees/{{ main_worktree }}/{{ branch }}"
+ 
+ # Commit Message Generation (Optional)
+ # For generating commit messages during merge operations (wt merge)
+ [commit-generation]
+ # Example: Simon Willison's llm CLI (https://github.com/simonw/llm)
+ # Install: pip install llm llm-anthropic
+ # command = "llm"
+ # args = ["-m", "claude-haiku-4.5"]
+ 
+ # Alternative: AIChat - Rust-based, supports 20+ providers
+ # Install from: https://github.com/sigoden/aichat
+ # command = "aichat"
+ # args = ["-m", "claude:claude-haiku-4.5"]
+ 
+ # Optional: Custom prompt template (inline) - Uses minijinja syntax
+ # Available variables: {{ git_diff }}, {{ branch }}, {{ recent_commits }}, {{ repo }}
+ # If not specified, uses the default template shown below:
+ # template = """
+ # Format
+ # - First line: <50 chars, present tense, describes WHAT and WHY (not HOW).
+ # - Blank line after first line.
+ # - Optional details with proper line breaks explaining context. Commits with more substantial changes should have more details.
+ # - Return ONLY the formatted message without quotes, code blocks, or preamble.
+ #
+ # Style
+ # - Do not give normative statements or otherwise speculate on why the change was made.
+ # - Broadly match the style of the previous commit messages.
+ # - For example, if they're in conventional commit format, use conventional commits; if they're not, don't use conventional commits.
+ #
+ # The context contains:
+ # - <git-diff> with the staged changes. This is the ONLY content you should base your message on.
+ # - <git-info> with branch name and recent commit message titles for style reference ONLY. DO NOT use their content to inform your message.
+ #
+ # ---
+ # The following is the context for your task:
+ # ---
+ # <git-diff>
+ # ```
+ # {{ git_diff }}
+ # ```
+ # </git-diff>
+ #
+ # <git-info>
+ # <current-branch>{{ branch }}</current-branch>
+ # {% if recent_commits %}
+ # <previous-commit-message-titles>
+ # {% for commit in recent_commits %}
+ # <previous-commit-message-title>{{ commit }}</previous-commit-message-title>
+ # {% endfor %}
+ # </previous-commit-message-titles>
+ # {% endif %}
+ # </git-info>
+ # """
+ #
+ # Example alternative template with different style:
+ # template = """
+ # Generate a commit message for {{ repo | upper }}.
+ #
+ # Branch: {{ branch }}
+ # {%- if recent_commits %}
+ #
+ # Recent commit style ({{ recent_commits | length }} commits):
+ # {%- for commit in recent_commits %}
+ # {{ loop.index }}. {{ commit }}
+ # {%- endfor %}
+ # {%- endif %}
+ #
+ # Changes to commit:
+ # ```
+ # {{ git_diff }}
+ # ```
+ #
+ # Requirements:
+ # - Follow the style of recent commits above
+ # - First line under 50 chars
+ # - Focus on WHY, not HOW
+ # """
+ 
+ # Optional: Load template from file (mutually exclusive with 'template')
+ # Supports ~ expansion: ~/.config/worktrunk/commit-template.txt
+ # template-file = "~/.config/worktrunk/commit-template.txt"
+ 
+ # Optional: Custom squash commit message template (inline) - Uses minijinja syntax
+ # Available variables: {{ commits }}, {{ target_branch }}, {{ branch }}, {{ repo }}
+ # If not specified, uses the default template:
+ # squash-template = """
+ # Generate a commit message that combines these changes into one cohesive message. Output only the commit message without any explanation.
+ #
+ # Format
+ # - First line: <50 chars, present tense, describes WHAT and WHY (not HOW).
+ # - Blank line after first line.
+ # - Optional details with proper line breaks explaining context.
+ # - Match the style of the existing commits being squashed (e.g., if they use conventional commits, use conventional commits).
+ #
+ # Squashing commits from {{ branch }} to merge into {{ target_branch }}
+ #
+ # Commits being combined:
+ # {% for commit in commits %}
+ # - {{ commit }}
+ # {% endfor %}
+ # """
+ #
+ # Example alternative template:
+ # squash-template = """
+ # Squashing {{ commits | length }} commit(s) from {{ branch }} to {{ target_branch }}.
+ #
+ # {% if commits | length > 1 -%}
+ # Commits being combined:
+ # {%- for c in commits %}
+ # {{ loop.index }}/{{ loop.length }}: {{ c }}
+ # {%- endfor %}
+ # {%- else -%}
+ # Single commit: {{ commits[0] }}
+ # {%- endif %}
+ #
+ # Generate one cohesive commit message that captures the overall change.
+ # Use conventional commit format (feat/fix/docs/refactor).
+ # """
+ 
+ # Optional: Load squash template from file (mutually exclusive with 'squash-template')
+ # Supports ~ expansion: ~/.config/worktrunk/squash-template.txt
+ # squash-template-file = "~/.config/worktrunk/squash-template.txt"
+ 
+ # NOTE: For project-specific commands (post-create, post-start, pre-merge, etc.),
+ # use a separate PROJECT config file at <repo>/.config/wt.toml
+ # See: .config/wt.example.toml for project configuration examples
+ 
+ # List Command Defaults
+ # Configure default behavior for `wt list`
+ # [list]
+ # full = false # Show CI, conflicts, diffs by default
+ # branches = false # Include branches without worktrees by default
+ # remotes = false # Include remote branches by default
+ 
+ # Commit Defaults (shared by `wt beta commit`, `wt beta squash`, and `wt merge`)
+ # [commit]
+ # stage = "all" # What to stage: "all", "tracked", or "none"
+ 
+ # Merge Command Defaults
+ # Note: `stage` defaults from [commit] section above
+ # [merge]
+ # squash = true # Squash commits when merging
+ # commit = true # Create commit after merge
+ # remove = true # Remove worktree after merge
+ # verify = true # Run project hooks
+ 
+ # Approved Commands
+ # Commands approved for automatic execution after switching worktrees
+ # Auto-populated when you use: wt switch --execute "command" --force
+ # [[approved-commands]]
+ # project = "github.com/user/repo"
+ # command = "npm install"
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_list.snap b/tests/snapshots/integration__integration_tests__help__help_config_list.snap
new file mode 100644
index 000000000..3b8b5b244
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_list.snap
@@ -0,0 +1,40 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - list
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt config list - List configuration files & locations
+Usage: wt config list [OPTIONS]
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Change working directory
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Shows location and contents of global config (~/.config/worktrunk/config.toml)
+and project config (.config/wt.toml).
+
+If a config file doesn't exist, shows defaults that would be used.
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_refresh_cache.snap b/tests/snapshots/integration__integration_tests__help__help_config_refresh_cache.snap
new file mode 100644
index 000000000..378277ece
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_refresh_cache.snap
@@ -0,0 +1,40 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - refresh-cache
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt config refresh-cache - Refresh default branch from remote
+Usage: wt config refresh-cache [OPTIONS]
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Change working directory
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Queries the remote to determine the default branch and caches the result.
+
+Use when the remote default branch has changed. The cached value is used by
+wt merge, wt list, and other commands that reference the default branch.
+
+----- stderr -----
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 97e2ed5ab..9c1085327 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
@@ -10,6 +10,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
success: true
exit_code: 0
@@ -23,16 +24,16 @@ Commands:
Options:
-h, --help
- Print help
+ Print help
Global Options:
-C <path>
- Change working directory
+ Change working directory
- --config <path>
- User config file path
+ --config <path>
+ User config file path
-v, --verbose
- Show commands and debug info
+ Show commands and debug info
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_status_set.snap b/tests/snapshots/integration__integration_tests__help__help_config_status_set.snap
new file mode 100644
index 000000000..f24cba97a
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_status_set.snap
@@ -0,0 +1,48 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - status
+ - set
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt config status set - Set status emoji for branch
+Usage: wt config status set [OPTIONS] <VALUE>
+
+Arguments:
+ <VALUE>
+ Status emoji to display
+
+Options:
+ --branch <BRANCH>
+ Target branch (defaults to current)
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Change working directory
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Sets a custom status marker that appears in wt list output.
+
+Use emojis or short text to indicate work state (e.g., 🚧 WIP, ✅ ready, 🔒 blocked).
+Stored in git config under worktrunk.status.<branch>.
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_status_unset.snap b/tests/snapshots/integration__integration_tests__help__help_config_status_unset.snap
new file mode 100644
index 000000000..2df6ab322
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config_status_unset.snap
@@ -0,0 +1,44 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - status
+ - unset
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt config status unset - Clear status emoji
+Usage: wt config status unset [OPTIONS] [TARGET]
+
+Arguments:
+ [TARGET]
+ Branch or "*" for all
+
+ [default: ]
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Change working directory
+
+ --config <path>
+ User config file path
+
+ -v, --verbose
+ Show commands and debug info
+
+Removes status marker from branch(es). Use * to clear all statuses.
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_list.snap b/tests/snapshots/integration__integration_tests__help__help_list.snap
index dfbba024d..d9b238035 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list.snap
@@ -18,125 +18,118 @@ wt list - List worktrees and optionally branches
Usage: wt list [OPTIONS]
Options:
- --format <FORMAT>
- Output format (table, json)
-
- [default: table]
+ --format <FORMAT>
+ Output format (table, json)
+
+ [default: table]
- --branches
- Include branches without worktrees
+ --branches
+ Include branches without worktrees
- --remotes
- Include remote branches
+ --remotes
+ Include remote branches
- --full
- Show CI, conflicts, diffs
+ --full
+ Show CI, conflicts, diffs
- --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.
+ --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')
+ Print help (see a summary with '-h')
Global Options:
-C <path>
- Change working directory
+ Change working directory
- --config <path>
- User config file path
+ --config <path>
+ User config file path
-v, --verbose
- Show commands and debug info
-
-Columns
-
-- Branch: Branch name
-- Status: Quick status symbols (see STATUS SYMBOLS below)
-- HEAD±: Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
-- main↕: Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
-- main…± (--full): Line diffs in commits ahead of main (+added -deleted)
-- Path: Worktree directory location
-- Remote⇅: Commits ahead↑/behind↓ relative to tracking branch (e.g.
-origin/branch)
-- CI (--full): CI pipeline status (tries PR/MR checks first, falls back to
-branch workflows)
- - ● passed (green) - All checks passed
- - ● running (blue) - Checks in progress
- - ● failed (red) - Checks failed
- - ● conflicts (yellow) - Merge conflicts with base
- - ● no-ci (gray) - PR/MR or workflow found but no checks configured
- - (blank) - No PR/MR or workflow found, or gh/glab CLI unavailable
+ Show commands and debug info
+
+Columns
+
+- Branch: Branch name
+- Status: Quick status symbols (see Status Symbols below)
+- HEAD±: Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
+- main↕: Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
+- main…± (--full): Line diffs in commits ahead of main (+added -deleted)
+- Path: Worktree directory location
+- Remote⇅: Commits ahead↑/behind↓ relative to tracking branch (e.g. origin/branch)
+- CI (--full): CI pipeline status (tries PR/MR checks first, falls back to branch workflows)
+ - ● passed (green) - All checks passed
+ - ● running (blue) - Checks in progress
+ - ● failed (red) - Checks failed
+ - ● conflicts (yellow) - Merge conflicts with base
+ - ● no-ci (gray) - PR/MR or workflow found but no checks configured
+ - (blank) - No PR/MR or workflow found, or gh/glab CLI unavailable
- (dimmed) - Stale: unpushed local changes differ from PR/MR head
-- Commit: Short commit hash (8 chars)
-- Age: Time since last commit (relative)
-- Message: Last commit message (truncated)
-
-Status Symbols
-
-Order: ?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠
-
-- ? Untracked files present
-- ! Modified files (unstaged changes)
-- + Staged files (ready to commit)
-- » Renamed files
-- ✘ Deleted files
-- ✖ Merge conflicts - unresolved conflicts in working tree (fix before
-continuing)
-- ⚠ Would conflict - merging into main would fail
-- ≡ Working tree matches main (identical contents, regardless of commit history)
-- ∅ No commits (no commits ahead AND no uncommitted changes)
-- ↻ Rebase in progress
-- ⋈ Merge in progress
-- ↑ Ahead of main branch
-- ↓ Behind main branch
-- ↕ Diverged (both ahead and behind main)
-- ⇡ Ahead of remote tracking branch
-- ⇣ Behind remote tracking branch
-- ⇅ Diverged (both ahead and behind remote)
-- ⎇ Branch indicator (shown for branches without worktrees)
-- ⌫ Prunable worktree (directory missing, can be pruned)
-- ⊠ Locked worktree (protected from auto-removal)
-
-Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).
-
-JSON Output
-
-Use --format=json for structured data. Each object contains two status maps
-with the same fields in the same order as STATUS SYMBOLS above:
-
-status - variant names for querying:
-- working_tree: {untracked, modified, staged, renamed, deleted} booleans
-- branch_state: "" | "Conflicts" | "MergeTreeConflicts" | "MatchesMain" |
-"NoCommits"
-- git_operation: "" | "Rebase" | "Merge"
-- main_divergence: "" | "Ahead" | "Behind" | "Diverged"
-- upstream_divergence: "" | "Ahead" | "Behind" | "Diverged"
-- user_status: string (optional)
-
-status_symbols - Unicode symbols for display (same fields, plus worktree_attrs:
-⎇/⌫/⊠)
+- Commit: Short commit hash (8 chars)
+- Age: Time since last commit (relative)
+- Message: Last commit message (truncated)
-Note: locked and prunable are top-level fields on worktree objects, not in
-status.
+Status Symbols
-Query examples:
+Order: ?!+»✘ ✖⚠≡∅ ↻⋈ ↑↓↕ ⇡⇣⇅ ⎇⌫⊠
- # Find worktrees with conflicts
- jq '.[] | select(.status.branch_state == "Conflicts")'
-
- # Find worktrees with untracked files
- jq '.[] | select(.status.working_tree.untracked)'
-
- # Find worktrees in rebase or merge
- jq '.[] | select(.status.git_operation != "")'
-
- # Get branches ahead of main
- jq '.[] | select(.status.main_divergence == "Ahead")'
-
- # Find locked worktrees
- jq '.[] | select(.locked != null)'
+- ? Untracked files present
+- ! Modified files (unstaged changes)
+- + Staged files (ready to commit)
+- » Renamed files
+- ✘ Deleted files
+- ✖ Merge conflicts - unresolved conflicts in working tree (fix before continuing)
+- ⚠ Would conflict - merging into main would fail
+- ≡ Working tree matches main (identical contents, regardless of commit history)
+- ∅ No commits (no commits ahead AND no uncommitted changes)
+- ↻ Rebase in progress
+- ⋈ Merge in progress
+- ↑ Ahead of main branch
+- ↓ Behind main branch
+- ↕ Diverged (both ahead and behind main)
+- ⇡ Ahead of remote tracking branch
+- ⇣ Behind remote tracking branch
+- ⇅ Diverged (both ahead and behind remote)
+- ⎇ Branch indicator (shown for branches without worktrees)
+- ⌫ Prunable worktree (directory missing, can be pruned)
+- ⊠ Locked worktree (protected from auto-removal)
+
+*Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).*
+
+JSON Output
+
+Use --format=json for structured data. Each object contains two status maps
+with the same fields in the same order as Status Symbols above:
+
+`status` - variant names for querying:
+- working_tree: {untracked, modified, staged, renamed, deleted} booleans
+- branch_state: "" | "Conflicts" | "MergeTreeConflicts" | "MatchesMain" | "NoCommits"
+- git_operation: "" | "Rebase" | "Merge"
+- main_divergence: "" | "Ahead" | "Behind" | "Diverged"
+- upstream_divergence: "" | "Ahead" | "Behind" | "Diverged"
+- user_status: string (optional)
+
+`status_symbols` - Unicode symbols for display (same fields, plus worktree_attrs: ⎇/⌫/⊠)
+
+Note: locked and prunable are top-level fields on worktree objects, not in status.
+
+Query examples:
+
+ # Find worktrees with conflicts
+ jq '.[] | select(.status.branch_state == "Conflicts")'
+ 
+ # Find worktrees with untracked files
+ jq '.[] | select(.status.working_tree.untracked)'
+ 
+ # Find worktrees in rebase or merge
+ jq '.[] | select(.status.git_operation != "")'
+ 
+ # Get branches ahead of main
+ jq '.[] | select(.status.main_divergence == "Ahead")'
+ 
+ # Find locked worktrees
+ jq '.[] | select(.locked != null)'
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snap
index 6bd05b5a3..da68a7f50 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge.snap
@@ -19,98 +19,96 @@ Usage: wt merge [OPTIONS] [TARGET]
Arguments:
[TARGET]
- Target branch
-
- Defaults to default branch.
+ Target branch
+
+ Defaults to default branch.
Options:
- --no-squash
- Skip commit squashing
+ --no-squash
+ Skip commit squashing
- --no-commit
- Skip commit, squash, and rebase
+ --no-commit
+ Skip commit, squash, and rebase
- --no-remove
- Keep worktree after merge
+ --no-remove
+ Keep worktree after merge
- --no-verify
- Skip all project hooks
+ --no-verify
+ Skip all project hooks
-f, --force
- Skip approval prompts
+ Skip approval prompts
- --stage <STAGE>
- What to stage before committing [default: all]
+ --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
+ 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')
+ Print help (see a summary with '-h')
Global Options:
-C <path>
- Change working directory
+ Change working directory
- --config <path>
- User config file path
+ --config <path>
+ User config file path
-v, --verbose
- Show commands and debug info
+ Show commands and debug info
-Operation
+Operation
Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
-Commit
+### Commit
Uncommitted changes are staged and committed with LLM message.
-Use --stage=tracked to stage only tracked files, or --stage=none to commit only
-what's already staged.
+Use --stage=tracked to stage only tracked files, or --stage=none to commit only what's already staged.
-Squash
+### Squash
Multiple commits are squashed into one with LLM message.
-Skip with --no-squash. Safety backup: git reflog show refs/wt-backup/<branch>
+Skip with --no-squash. Safety backup: git reflog show refs/wt-backup/<branch>
-Rebase
+### Rebase
Branch is rebased onto target. Conflicts abort the merge immediately.
-Hooks
+### Hooks
Pre-merge commands run after rebase (failures abort). Post-merge commands
-run after cleanup (failures logged). Skip all with --no-verify.
+run after cleanup (failures logged). Skip all with --no-verify.
-Push
+### Push
Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
-Cleanup
+### Cleanup
-Worktree and branch are removed. Skip with --no-remove.
+Worktree and branch are removed. Skip with --no-remove.
-Template variables: {{ repo }}, {{ branch }}, {{ worktree }}, {{ repo_root }},
-{{ target }}
+Template variables: {{ repo }}, {{ branch }}, {{ worktree }}, {{ repo_root }}, {{ target }}
-Security: Commands from project hooks require approval on first run.
-Approvals are saved to user config. Use --force to bypass prompts.
-See wt config approvals --help.
+Security: Commands from project hooks require approval on first run.
+Approvals are saved to user config. Use --force to bypass prompts.
+See wt config approvals --help.
-Examples
+Examples
Basic merge to main:
-wt merge
+ wt merge
Merge without squashing:
-wt merge --no-squash
+ wt merge --no-squash
Keep worktree after merging:
-wt merge --no-remove
+ wt merge --no-remove
Skip all hooks:
-wt merge --no-verify
+ wt merge --no-verify
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove.snap b/tests/snapshots/integration__integration_tests__help__help_remove.snap
index b18f04bc2..d5061bbc3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove.snap
@@ -19,76 +19,73 @@ Usage: wt remove [OPTIONS] [WORKTREES]...
Arguments:
[WORKTREES]...
- Worktree or branch (@ for current)
+ Worktree or branch (@ for current)
Options:
- --no-delete-branch
- Keep branch after removal
+ --no-delete-branch
+ Keep branch after removal
-D, --force-delete
- Delete unmerged branches
+ Delete unmerged branches
- --no-background
- Run removal in foreground
+ --no-background
+ Run removal in foreground
-h, --help
- Print help (see a summary with '-h')
+ Print help (see a summary with '-h')
Global Options:
-C <path>
- Change working directory
+ Change working directory
- --config <path>
- User config file path
+ --config <path>
+ User config file path
-v, --verbose
- Show commands and debug info
+ Show commands and debug info
-Operation
+Operation
-Removes worktree directory, git metadata, and branch. Requires clean working
-tree.
+Removes worktree directory, git metadata, and branch. Requires clean working tree.
-No arguments (remove current)
+### No arguments (remove current)
- Removes current worktree and switches to main worktree
- In main worktree: switches to default branch
-By name (remove specific)
+### By name (remove specific)
- Removes specified worktree(s) and branches
- Current worktree removed last (switches to main first)
-Background removal (default)
+### Background removal (default)
- Returns immediately so you can continue working
-- Logs: .git/wt-logs/{branch}-remove.log
-- Use --no-background for foreground (blocking)
+- Logs: .git/wt-logs/{branch}-remove.log
+- Use --no-background for foreground (blocking)
-Cleanup
+### Cleanup
-Stops any git fsmonitor daemon for the worktree before removal. This prevents
-orphaned processes when using builtin fsmonitor (core.fsmonitor=true). No effect
-on Watchman users.
+Stops any git fsmonitor daemon for the worktree before removal. This prevents orphaned processes when using builtin fsmonitor (core.fsmonitor=true). No effect on Watchman users.
-Examples
+Examples
Remove current worktree and branch:
-wt remove
+ wt remove
Remove specific worktree and branch:
-wt remove feature-branch
+ wt remove feature-branch
Remove worktree but keep branch:
-wt remove --no-delete-branch feature-branch
+ wt remove --no-delete-branch feature-branch
Remove multiple worktrees:
-wt remove old-feature another-branch
+ wt remove old-feature another-branch
Remove in foreground (blocking):
-wt remove --no-background feature-branch
+ wt remove --no-background feature-branch
Switch to default in main:
-wt remove # (when already in main worktree)
+ wt remove # (when already in main worktree)
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_root.snap b/tests/snapshots/integration__integration_tests__help__help_root.snap
index 723ad0071..2ee0a139b 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root.snap
@@ -8,6 +8,7 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
---
success: true
exit_code: 0
@@ -25,27 +26,21 @@ Commands:
Options:
-h, --help
- Print help (see a summary with '-h')
+ Print help (see a summary with '-h')
-V, --version
- Print version
+ Print version
Global Options:
-C <path>
- Change working directory
+ Change working directory
- --config <path>
- User config file path
+ --config <path>
+ User config file path
-v, --verbose
- Show commands and debug info
+ Show commands and debug info
--C <path>: Run as if started in <path> instead of current directory.
-
---config <path>: Override user config file location. Without this flag,
-config is loaded from (in order of precedence):
-1. WORKTRUNK_CONFIG_PATH environment variable
-2. ~/.config/worktrunk/config.toml (Linux/macOS) or
-%APPDATA%\worktrunk\config.toml (Windows)
+See wt config --help for configuration file locations and setup.
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snap
index af866c832..ab8b799a9 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch.snap
@@ -19,105 +19,104 @@ Usage: wt switch [OPTIONS] <BRANCH>
Arguments:
<BRANCH>
- Branch, path, '@' (HEAD), '-' (previous), or '^' (main)
+ Branch, path, '@' (HEAD), '-' (previous), or '^' (main)
Options:
-c, --create
- Create a new branch
+ Create a new branch
-b, --base <BASE>
- Base branch
-
- Defaults to default branch.
+ Base branch
+
+ Defaults to default branch.
-x, --execute <EXECUTE>
- Command to run after switch
+ Command to run after switch
-f, --force
- Skip approval prompts
+ Skip approval prompts
- --no-verify
- Skip all project hooks
+ --no-verify
+ Skip all project hooks
-h, --help
- Print help (see a summary with '-h')
+ Print help (see a summary with '-h')
Global Options:
-C <path>
- Change working directory
+ Change working directory
- --config <path>
- User config file path
+ --config <path>
+ User config file path
-v, --verbose
- Show commands and debug info
+ Show commands and debug info
-Operation
+Operation
-Switching to Existing Worktree
+### Switching to Existing Worktree
- If worktree exists for branch, changes directory via shell integration
- No hooks run
- No branch creation
-Creating New Worktree (--create)
+### Creating New Worktree (--create)
1. Creates new branch (defaults to current default branch as base)
-2. Creates worktree in configured location (default:
-../{{ main_worktree }}.{{ branch }})
+2. Creates worktree in configured location (default: ../{{ main_worktree }}.{{ branch }})
3. Runs post-create hooks sequentially (blocking)
4. Shows success message
5. Spawns post-start hooks in background (non-blocking)
6. Changes directory to new worktree via shell integration
-Hooks
+Hooks
-post-create (sequential, blocking)
+### post-create (sequential, blocking)
- Run after worktree creation, before success message
-- Typically: npm install, cargo build, setup tasks
+- Typically: npm install, cargo build, setup tasks
- Failures block the operation
-- Skip with --no-verify
+- Skip with --no-verify
-post-start (parallel, background)
+### post-start (parallel, background)
- Spawned after success message shown
- Typically: dev servers, file watchers, editors
- Run in background, failures logged but don't block
-- Logs: .git/wt-logs/{branch}-post-start-{name}.log
-- Skip with --no-verify
+- Logs: .git/wt-logs/{branch}-post-start-{name}.log
+- Skip with --no-verify
-Template variables: {{ repo }}, {{ branch }}, {{ worktree }}, {{ repo_root }}
+Template variables: {{ repo }}, {{ branch }}, {{ worktree }}, {{ repo_root }}
-Security: Commands from project hooks require approval on first run.
-Approvals are saved to user config. Use --force to bypass prompts.
-See wt config approvals --help.
+Security: Commands from project hooks require approval on first run.
+Approvals are saved to user config. Use --force to bypass prompts.
+See wt config approvals --help.
-Examples
+Examples
Switch to existing worktree:
-wt switch feature-branch
+ wt switch feature-branch
Create new worktree from main:
-wt switch --create new-feature
+ wt switch --create new-feature
Switch to previous worktree:
-wt switch -
+ wt switch -
Create from specific base:
-wt switch --create hotfix --base production
+ wt switch --create hotfix --base production
Create and run command:
-wt switch --create docs --execute "code ."
+ wt switch --create docs --execute "code ."
Skip hooks during creation:
-wt switch --create temp --no-verify
+ wt switch --create temp --no-verify
-Shortcuts
+Shortcuts
-Use @ for current HEAD, - for previous, ^ for main:
-wt switch @ # Switch to current branch's worktree
-wt switch - # Switch to previous worktree
-wt switch --create new-feature --base=^ # Branch from main (default)
-wt switch --create bugfix --base=@ # Branch from current HEAD
-wt remove @ # Remove current worktree
+Use @ for current HEAD, - for previous, ^ for main:
+ wt switch @ # Switch to current branch's worktree
+ wt switch - # Switch to previous worktree
+ wt switch --create new-feature --base=^ # Branch from main (default)
+ wt switch --create bugfix --base=@ # Branch from current HEAD
+ wt remove @ # Remove current worktree
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__init__init_fish.snap b/tests/snapshots/integration__integration_tests__init__init_fish.snap
index 4e181c6dd..393c474df 100644
--- a/tests/snapshots/integration__integration_tests__init__init_fish.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_fish.snap
@@ -217,15 +217,15 @@ complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from create" -s C -d 'Change working directory' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from create" -l config -d 'User config file path' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from create" -s v -l verbose -d 'Show commands and debug info'
-complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from create" -s h -l help -d 'Print help'
+complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from create" -s h -l help -d 'Print help (see more with \'--help\')'
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from list" -s C -d 'Change working directory' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from list" -l config -d 'User config file path' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from list" -s v -l verbose -d 'Show commands and debug info'
-complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from list" -s h -l help -d 'Print help'
+complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from list" -s h -l help -d 'Print help (see more with \'--help\')'
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from refresh-cache" -s C -d 'Change working directory' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from refresh-cache" -l config -d 'User config file path' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from refresh-cache" -s v -l verbose -d 'Show commands and debug info'
-complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from refresh-cache" -s h -l help -d 'Print help'
+complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from refresh-cache" -s h -l help -d 'Print help (see more with \'--help\')'
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from status" -s C -d 'Change working directory' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from status" -l config -d 'User config file path' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from status" -s v -l verbose -d 'Show commands and debug info'
diff --git a/tests/snapshots/integration__integration_tests__init__init_zsh.snap b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
index 0c83b23f9..aa3d98416 100644
--- a/tests/snapshots/integration__integration_tests__init__init_zsh.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
@@ -272,8 +272,8 @@ _arguments "${_arguments_options[@]}" : \
'--config=[User config file path]:path:_files' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
&& ret=0
;;
(list)
@@ -282,8 +282,8 @@ _arguments "${_arguments_options[@]}" : \
'--config=[User config file path]:path:_files' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
&& ret=0
;;
(refresh-cache)
@@ -292,8 +292,8 @@ _arguments "${_arguments_options[@]}" : \
'--config=[User config file path]:path:_files' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
&& ret=0
;;
(status)
@@ -321,8 +321,8 @@ _arguments "${_arguments_options[@]}" : \
'--config=[User config file path]:path:_files' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
':value -- Status emoji to display:_default' \
&& ret=0
;;
@@ -332,8 +332,8 @@ _arguments "${_arguments_options[@]}" : \
'--config=[User config file path]:path:_files' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
'::target -- Branch or "*" for all:_default' \
&& ret=0
;;
@@ -368,8 +368,8 @@ _arguments "${_arguments_options[@]}" : \
'--all[Show all commands]' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
&& ret=0
;;
(clear)
@@ -380,8 +380,8 @@ _arguments "${_arguments_options[@]}" : \
'--global[Clear global approvals]' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
&& ret=0
;;
esac