Skip to content

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

Revert "feat: add visual hierarchy to help headers (#623)"

Maximilian Roos276dfbc6dcfa
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index 9cc6c34d7..091977ecc 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -28,7 +28,7 @@ Show current configuration and file locations:
wt config show
```
-# Configuration files
+## Configuration files
| File | Location | Purpose |
|------|----------|---------|
@@ -247,7 +247,7 @@ Combine these commits into a single commit message.
<!-- DEFAULT_SQUASH_TEMPLATE_END -->
<!-- USER_CONFIG_END -->
-# Project config
+## Project config
The project config defines lifecycle hooks and project-specific settings. This file is checked into version control and shared across the team.
@@ -286,7 +286,7 @@ 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:
diff --git a/.claude-plugin/skills/worktrunk/reference/list.md b/.claude-plugin/skills/worktrunk/reference/list.md
index ef9a113fc..5ff549294 100644
--- a/.claude-plugin/skills/worktrunk/reference/list.md
+++ b/.claude-plugin/skills/worktrunk/reference/list.md
@@ -110,7 +110,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
Rows are dimmed when [safe to delete](https://worktrunk.dev/remove/#branch-cleanup) (`_` same commit with clean working tree or `⊂` content integrated).
-# JSON output
+## JSON output
Query structured data with `--format=json`:
diff --git a/docs/content/config.md b/docs/content/config.md
index a33f4c8f8..8fa285552 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -36,7 +36,7 @@ Show current configuration and file locations:
wt config show
```
-# Configuration files
+## Configuration files
| File | Location | Purpose |
|------|----------|---------|
@@ -255,7 +255,7 @@ Combine these commits into a single commit message.
<!-- DEFAULT_SQUASH_TEMPLATE_END -->
<!-- USER_CONFIG_END -->
-# Project config
+## Project config
The project config defines lifecycle hooks and project-specific settings. This file is checked into version control and shared across the team.
@@ -294,7 +294,7 @@ 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:
diff --git a/docs/content/list.md b/docs/content/list.md
index 795718181..a26f86965 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -143,7 +143,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
Rows are dimmed when [safe to delete](@/remove.md#branch-cleanup) (`_` same commit with clean working tree or `⊂` content integrated).
-# JSON output
+## JSON output
Query structured data with `--format=json`:
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 4a1e466cf..b260eb101 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -176,11 +176,11 @@ pub enum ConfigCommand {
/// Create configuration file
#[command(
after_long_help = concat!(
- "# User config\n\n",
+ "## User config\n\n",
"Creates `~/.config/worktrunk/config.toml` with the following content:\n\n```\n",
include_str!("../../dev/config.example.toml"),
"```\n\n",
- "# Project config\n\n",
+ "## Project config\n\n",
"With `--project`, creates `.config/wt.toml` in the current repository:\n\n```\n",
include_str!("../../dev/wt.example.toml"),
"```"
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index e3b6d3029..95ae3ca4a 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -477,7 +477,7 @@ The Status column has multiple subcolumns. Within each, only the first matching
Rows are dimmed when [safe to delete](@/remove.md#branch-cleanup) (`_` same commit with clean working tree or `⊂` content integrated).
-# JSON output
+## JSON output
Query structured data with `--format=json`:
@@ -1460,7 +1460,7 @@ Show current configuration and file locations:
wt config show
```
-# Configuration files
+## Configuration files
| File | Location | Purpose |
|------|----------|---------|
@@ -1679,7 +1679,7 @@ Combine these commits into a single commit message.
<!-- DEFAULT_SQUASH_TEMPLATE_END -->
<!-- USER_CONFIG_END -->
-# Project config
+## Project config
The project config defines lifecycle hooks and project-specific settings. This file is checked into version control and shared across the team.
@@ -1718,7 +1718,7 @@ 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:
diff --git a/src/md_help.rs b/src/md_help.rs
index cc7ead4e4..163846b84 100644
--- a/src/md_help.rs
+++ b/src/md_help.rs
@@ -88,19 +88,13 @@ pub(crate) fn render_markdown_in_help_with_width(help: &str, width: Option<usize
}
// Outside code blocks, render markdown headers (never wrapped)
- // Visual hierarchy: H1 > H2 > H3
- // - H1: UPPERCASE green (most prominent, rarely used)
- // - H2: Bold green (major sections like "Examples", "Columns")
- // - H3: Normal green (subsections like "CI status", "commit object")
if let Some(header_text) = trimmed.strip_prefix("### ") {
- result.push_str(&format!("{green}{header_text}{green:#}\n"));
+ let bold = Style::new().bold();
+ result.push_str(&format!("{bold}{header_text}{bold:#}\n"));
} else if let Some(header_text) = trimmed.strip_prefix("## ") {
- let bold_green = Style::new()
- .bold()
- .fg_color(Some(Color::Ansi(AnsiColor::Green)));
- result.push_str(&format!("{bold_green}{header_text}{bold_green:#}\n"));
+ result.push_str(&format!("{green}{header_text}{green:#}\n"));
} else if let Some(header_text) = trimmed.strip_prefix("# ") {
- result.push_str(&format!("{green}{}{green:#}\n", header_text.to_uppercase()));
+ result.push_str(&format!("{green}{header_text}{green:#}\n"));
} else {
// Prose text - wrap if width is specified
let formatted = render_inline_formatting(line);
@@ -486,27 +480,24 @@ mod tests {
#[test]
fn test_render_markdown_in_help_h1() {
let result = render_markdown_in_help("# Header");
- // H1 should be UPPERCASE green
- assert!(result.contains("HEADER")); // Uppercase
- assert!(result.contains("\u{1b}[32m")); // Green
+ // H1 should be green
+ assert!(result.contains("Header"));
+ assert!(result.contains("\u{1b}[")); // Has color codes
}
#[test]
fn test_render_markdown_in_help_h2() {
let result = render_markdown_in_help("## Section");
- // H2 should be bold green (anstyle emits separate codes)
assert!(result.contains("Section"));
- assert!(result.contains("\u{1b}[1m")); // Bold
- assert!(result.contains("\u{1b}[32m")); // Green
+ assert!(result.contains("\u{1b}[")); // Has color codes
}
#[test]
fn test_render_markdown_in_help_h3() {
let result = render_markdown_in_help("### Subsection");
- // H3 should be green (no bold)
assert!(result.contains("Subsection"));
- assert!(result.contains("\u{1b}[32m")); // Green
- assert!(!result.contains("\u{1b}[1m")); // Not bold
+ // H3 is bold
+ assert!(result.contains("\u{1b}[1m")); // Bold
}
#[test]
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 ccc04e2ed..2517a4c6c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -42,7 +42,7 @@ Usage: wt config create [OPTIONS]
-v, --verbose...
Show debug info (-v), or also write diagnostic report (-vv)
-USER CONFIG
+User config
Creates ~/.config/worktrunk/config.toml with the following content:
@@ -236,7 +236,7 @@ Creates ~/.config/worktrunk/config.toml with the following content:
# """
# <!-- DEFAULT_SQUASH_TEMPLATE_END -->
-PROJECT CONFIG
+Project config
With --project, creates .config/wt.toml in the current repository:
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 0d84a6604..fd3ab2bd8 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -46,7 +46,7 @@ Usage: wt config [OPTIONS] <COMMAND>
Manages configuration, shell integration, and runtime settings.
-Examples
+Examples
Install shell integration (required for directory switching):
@@ -64,14 +64,14 @@ Show current configuration and file locations:
wt config show
-CONFIGURATION FILES
+Configuration files
File Location Purpose
────────────── ─────────────────────────────── ──────────────────────────────────────────────────────────────
User config ~/.config/worktrunk/config.toml Personal settings, command defaults, approved project commands
Project config .config/wt.toml Lifecycle hooks, checked into version control
-WORKTRUNK USER CONFIGURATION
+Worktrunk User Configuration
Create with wt config create.
@@ -80,7 +80,7 @@ Location:
- macOS/Linux: ~/.config/worktrunk/config.toml (or $XDG_CONFIG_HOME if set)
- Windows: %APPDATA%\worktrunk\config.toml
-Worktree path template
+Worktree path template
Controls where new worktrees are created. Paths are relative to the repository root.
@@ -109,7 +109,7 @@ Controls where new worktrees are created. Paths are relative to the repository r
# Creates: ~/code/project/feature-auth (sibling to .git)
worktree-path = "../{{ branch | sanitize }}"
-List command defaults
+List command defaults
Persistent flag values for wt list. Override on command line as needed.
@@ -118,14 +118,14 @@ Persistent flag values for wt list. Override on command line as needed.
branches = false # Include branches without worktrees (--branches)
remotes = false # Include remote-only branches (--remotes)
-Commit defaults
+Commit defaults
Shared by wt step commit, wt step squash, and wt merge.
[commit]
stage = "all" # What to stage before commit: "all", "tracked", or "none"
-Merge command defaults
+Merge command defaults
All flags are on by default. Set to false to change default behavior.
@@ -136,7 +136,7 @@ All flags are on by default. Set to false to change default behavior.
remove = true # Remove worktree after merge (--no-remove to keep)
verify = true # Run project hooks (--no-verify to skip)
-Select command defaults
+Select command defaults
Pager behavior for wt select diff previews.
@@ -146,7 +146,7 @@ Pager behavior for wt select diff previews.
# Example:
# pager = "delta --paging=never"
-LLM commit messages
+LLM commit messages
Generate commit messages automatically during merge. Requires an external CLI tool. See <https://worktrunk.dev/llm-commits/> for setup details and template customization.
@@ -164,7 +164,7 @@ Using aichat:
See Custom Prompt Templates for inline template options.
-Approved commands
+Approved commands
Commands approved for project hooks. Auto-populated when approving hooks on first run, or via wt hook approvals add.
@@ -173,11 +173,11 @@ Commands approved for project hooks. Auto-populated when approving hooks on firs
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 <https://worktrunk.dev/hook/>.
-Custom prompt templates
+Custom prompt templates
Templates use minijinja syntax.
-Commit template
+Commit template
Available variables:
@@ -219,7 +219,7 @@ Default template:

"""
-Squash template
+Squash template
Available variables (in addition to commit template variables):
@@ -257,7 +257,7 @@ Default template:

"""
-PROJECT CONFIG
+Project config
The project config defines lifecycle hooks and project-specific settings. This file is checked into version control and shared across the team.
@@ -272,7 +272,7 @@ Create .config/wt.toml in the repository root:
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:
@@ -281,7 +281,7 @@ The [list] section adds a URL column to wt list:
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:
@@ -290,7 +290,7 @@ The [ci] section overrides CI platform detection for GitHub Enterprise o
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:
@@ -309,7 +309,7 @@ Or manually add to the shell config:
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:
@@ -319,11 +319,11 @@ Or via environment variable:
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.
@@ -337,13 +337,13 @@ 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"
-Example: CI/testing override
+Example: CI/testing override
Override the LLM command in CI to use a mock:
@@ -351,7 +351,7 @@ Override the LLM command in CI to use a mock:
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_show.snap b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
index 43e18010a..99e3986a5 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_show.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_show.snap
@@ -47,7 +47,7 @@ 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:
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 95a441929..4bea8735c 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
@@ -52,7 +52,7 @@ Usage: wt config state [OPTIONS] <COMMAND>
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 -
@@ -60,7 +60,7 @@ Use wt config show to view file-based configuration.
- 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
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 0500e6f05..df2a6e7ba 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
@@ -46,14 +46,14 @@ Usage: wt config state ci-status [OPTIONS] [COMMAND]
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_default_branch.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
index 9ce34f833..1e6ac9326 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
@@ -51,7 +51,7 @@ Useful in scripts to avoid hardcoding main or master:
Without a subcommand, runs get. Use set to override, or clear then get to re-detect.
-Detection
+Detection
Worktrunk detects the default branch automatically:
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 95c3735da..a7e44b196 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
@@ -46,7 +46,7 @@ Usage: wt config state logs [OPTIONS] [COMMAND]
View and manage logs from background operations.
-What's logged
+What's logged
Operation Log file
────────────────── ───────────────────────────────────────
@@ -55,17 +55,17 @@ 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
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 e78a3fbf9..ee3f24bc7 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
@@ -47,7 +47,7 @@ Usage: wt config state marker [OPTIONS] [COMMAND]
Custom status text or emoji shown in the wt list Status column.
-Display
+Display
Markers appear at the start of the Status column:
@@ -56,13 +56,13 @@ Markers appear at the start of the Status column:
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"
-Storage
+Storage
Stored in git config as worktrunk.state.<branch>.marker. Set directly with:
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 f9d1d7a9c..8e223c221 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
@@ -47,7 +47,7 @@ Usage: wt config state previous-branch [OPTIONS] [COM
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_hook_approvals.snap b/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
index c29968df0..a38c77109 100644
--- a/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
@@ -45,7 +45,7 @@ Usage: wt hook approvals [OPTIONS] <COMMAND>
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
@@ -56,6 +56,6 @@ Clear approvals for current project:
Clear global approvals:
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_list_long.snap b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
index 09c6d0699..9af45c6d5 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -65,7 +65,7 @@ Show all worktrees with their status. The table includes uncommitted changes, di
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:
@@ -83,7 +83,7 @@ Output as JSON for scripting:
$ wt list --format=json
-Columns
+Columns
Column Shows
─────── ─────────────────────────────────────────────────────────────────
@@ -102,7 +102,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:
@@ -118,7 +118,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):
@@ -149,7 +149,7 @@ 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:
@@ -201,7 +201,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
───────── ────── ───────────────────────────
@@ -210,7 +210,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
───────── ─────── ───────────────────────────────────────
@@ -221,7 +221,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
────── ────── ─────────────────────────────────────────────────────
@@ -229,7 +229,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
────── ────── ────────────────────────────
@@ -238,7 +238,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
──────── ─────── ─────────────────────────────────────────────────────────────────────
@@ -246,7 +246,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
────── ─────── ─────────────────────────────────────────────────
@@ -255,22 +255,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 relation to the default branch.
"is_main" "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"
-ci.status values
+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
+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 6a7bbf92c..e46a2045c 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
@@ -70,7 +70,7 @@ 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:
@@ -88,7 +88,7 @@ Output as JSON for scripting:
$ wt list --format=json
-Columns
+Columns
Column Shows
─────── ─────────────────────────────────────────────────────────────────
@@ -108,7 +108,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:
@@ -128,7 +128,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):
@@ -164,7 +164,7 @@ 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:
@@ -223,7 +223,7 @@ Query structured data with --format=json:
symbols string Raw status symbols without colors (e.g.,
"!?↓")
-Commit object
+Commit object
Field Type Description
───────── ────── ───────────────────────────
@@ -232,7 +232,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
───────── ─────── ───────────────────────────────────────
@@ -243,7 +243,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
────── ────── ─────────────────────────────────────────────────────
@@ -251,7 +251,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
────── ────── ────────────────────────────
@@ -260,7 +260,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
──────── ─────── ───────────────────────────────────────────────────────────
@@ -269,7 +269,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
────── ─────── ─────────────────────────────────────────────────
@@ -278,25 +278,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 relation to the default branch.
"is_main" "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"
-ci.status values
+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
+See also
- wt select — Interactive worktree picker with live preview
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 c1e12dbe4..46352aa31 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge_long.snap
@@ -74,7 +74,7 @@ Usage: wt merge [OPTIONS] [TARGET]
Merge the current branch into the target branch, defaulting to the main branch. Unlike git merge, this merges the current branch into a target (rather than a target into the current branch). Similar to clicking "Merge pull request" on GitHub.
-Examples
+Examples
Merge to the default branch:
@@ -96,7 +96,7 @@ Skip committing/squashing (rebase still runs unless --no-rebase):
wt merge --no-commit
-Pipeline
+Pipeline
wt merge runs these steps:
@@ -110,7 +110,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.
@@ -122,7 +122,7 @@ The full workflow: start an agent (one of many) on a task, work elsewhere, retur
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_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index bb3776d27..a85ed827d 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -64,7 +64,7 @@ Usage: wt remove [OPTIONS] [BRANCHES]...
Removes worktrees and their branches (if merged), returning to the main worktree. Defaults to removing the current worktree.
-Examples
+Examples
Remove current worktree:
@@ -83,7 +83,7 @@ Force-delete an unmerged branch:
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.
@@ -99,7 +99,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:
@@ -114,11 +114,11 @@ Worktrunk has two force flags for different situations:
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_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index 0524d68cb..83de59791 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -48,7 +48,7 @@ Usage: wt step [OPTIONS] <COMMAND>
Run individual git workflow operations: commits, squashes, rebases, and pushes.
-Examples
+Examples
Commit with LLM-generated message:
@@ -61,7 +61,7 @@ Manual merge workflow with review between steps:
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
@@ -70,9 +70,9 @@ Manual merge workflow with review between steps:
- copy-ignored — Copy gitignored files between worktrees
- for-each — [experimental] Run a command in every worktree
-Options
+Options
-`--stage`
+`--stage`
Controls what to stage before committing. Available for commit and squash:
@@ -90,7 +90,7 @@ Configure the default in user config:
[commit]
stage = "tracked"
-`--show-prompt`
+`--show-prompt`
Output the rendered LLM prompt to stdout without running the command. Useful for inspecting prompt templates or piping to other tools:
@@ -100,7 +100,7 @@ Output the rendered LLM prompt to stdout without running the command. Useful for
# Pipe to a different LLM
wt step commit --show-prompt | llm -m gpt-5-nano
-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_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 20dc161c4..14ad9bbdc 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -86,18 +86,18 @@ Usage: wt switch [OPTIONS] <BRANCH> [--
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
-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.
-Creating worktrees
+Creating worktrees
If the branch already has a worktree, wt switch changes directories to it. Otherwise, it creates one, running hooks.
@@ -113,7 +113,7 @@ When creating a worktree, worktrunk:
wt switch --create fix --base release # New branch from release
wt switch --create temp --no-verify # Skip hooks
-Shortcuts
+Shortcuts
Shortcut Meaning
──────── ─────────────────────────────
@@ -125,7 +125,7 @@ When creating a worktree, worktrunk:
wt switch ^ # Default branch worktree
wt switch --create fix --base=@ # Branch from current HEAD
-When wt switch fails
+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
@@ -133,7 +133,7 @@ When creating a worktree, worktrunk:
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