Skip to content

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

feat: restore visual hierarchy and add section dividers

Maximilian Roos46827d2d4e4b
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index 091977ecc..ab007411f 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -35,8 +35,10 @@ wt config show
| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |
| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |
+---
+
<!-- USER_CONFIG_START -->
-# Worktrunk User Configuration
+## Worktrunk User Configuration
Create with `wt config create`.
@@ -247,6 +249,8 @@ Combine these commits into a single commit message.
<!-- DEFAULT_SQUASH_TEMPLATE_END -->
<!-- USER_CONFIG_END -->
+---
+
## 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,6 +290,8 @@ platform = "github" # or "gitlab"
By default, the platform is detected from the remote URL. Use this when URL detection fails (e.g., `git.mycompany.com` instead of `github.mycompany.com`).
+---
+
## Shell integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
diff --git a/.claude-plugin/skills/worktrunk/reference/list.md b/.claude-plugin/skills/worktrunk/reference/list.md
index 5ff549294..60dc5d3c7 100644
--- a/.claude-plugin/skills/worktrunk/reference/list.md
+++ b/.claude-plugin/skills/worktrunk/reference/list.md
@@ -110,6 +110,8 @@ 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
Query structured data with `--format=json`:
diff --git a/dev/config.example.toml b/dev/config.example.toml
index 9ec13f3ed..014d621a9 100644
--- a/dev/config.example.toml
+++ b/dev/config.example.toml
@@ -1,4 +1,4 @@
-# # Worktrunk User Configuration
+# ## Worktrunk User Configuration
#
# Create with `wt config create`.
#
diff --git a/docs/content/config.md b/docs/content/config.md
index 8fa285552..cccf4c59e 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -43,8 +43,10 @@ wt config show
| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |
| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |
+---
+
<!-- USER_CONFIG_START -->
-# Worktrunk User Configuration
+## Worktrunk User Configuration
Create with `wt config create`.
@@ -255,6 +257,8 @@ Combine these commits into a single commit message.
<!-- DEFAULT_SQUASH_TEMPLATE_END -->
<!-- USER_CONFIG_END -->
+---
+
## 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,6 +298,8 @@ platform = "github" # or "gitlab"
By default, the platform is detected from the remote URL. Use this when URL detection fails (e.g., `git.mycompany.com` instead of `github.mycompany.com`).
+---
+
## Shell integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
diff --git a/docs/content/list.md b/docs/content/list.md
index a26f86965..7b33a440c 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -143,6 +143,8 @@ 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
Query structured data with `--format=json`:
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 8fd412c7e..025f69b9f 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -477,6 +477,8 @@ 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
Query structured data with `--format=json`:
@@ -1433,8 +1435,10 @@ wt config show
| **User config** | `~/.config/worktrunk/config.toml` | Personal settings, command defaults, approved project commands |
| **Project config** | `.config/wt.toml` | Lifecycle hooks, checked into version control |
+---
+
<!-- USER_CONFIG_START -->
-# Worktrunk User Configuration
+## Worktrunk User Configuration
Create with `wt config create`.
@@ -1645,6 +1649,8 @@ Combine these commits into a single commit message.
<!-- DEFAULT_SQUASH_TEMPLATE_END -->
<!-- USER_CONFIG_END -->
+---
+
## Project config
The project config defines lifecycle hooks and project-specific settings. This file is checked into version control and shared across the team.
@@ -1684,6 +1690,8 @@ platform = "github" # or "gitlab"
By default, the platform is detected from the remote URL. Use this when URL detection fails (e.g., `git.mycompany.com` instead of `github.mycompany.com`).
+---
+
## Shell integration
Worktrunk needs shell integration to change directories when switching worktrees. Install with:
diff --git a/src/md_help.rs b/src/md_help.rs
index 163846b84..14037ffa2 100644
--- a/src/md_help.rs
+++ b/src/md_help.rs
@@ -87,14 +87,27 @@ pub(crate) fn render_markdown_in_help_with_width(help: &str, width: Option<usize
continue;
}
+ // Horizontal rules (---, ***, ___) render as blank line for visual separation
+ if trimmed == "---" || trimmed == "***" || trimmed == "___" {
+ result.push('\n');
+ i += 1;
+ continue;
+ }
+
// 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("### ") {
- let bold = Style::new().bold();
- result.push_str(&format!("{bold}{header_text}{bold:#}\n"));
- } else 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("## ") {
+ let bold_green = Style::new()
+ .bold()
+ .fg_color(Some(Color::Ansi(AnsiColor::Green)));
+ result.push_str(&format!("{bold_green}{header_text}{bold_green:#}\n"));
} else if let Some(header_text) = trimmed.strip_prefix("# ") {
- result.push_str(&format!("{green}{header_text}{green:#}\n"));
+ result.push_str(&format!("{green}{}{green:#}\n", header_text.to_uppercase()));
} else {
// Prose text - wrap if width is specified
let formatted = render_inline_formatting(line);
@@ -480,24 +493,36 @@ mod tests {
#[test]
fn test_render_markdown_in_help_h1() {
let result = render_markdown_in_help("# Header");
- // H1 should be green
- assert!(result.contains("Header"));
- assert!(result.contains("\u{1b}[")); // Has color codes
+ // H1 should be UPPERCASE green
+ assert!(result.contains("HEADER")); // Uppercase
+ assert!(result.contains("\u{1b}[32m")); // Green
}
#[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}[")); // Has color codes
+ assert!(result.contains("\u{1b}[1m")); // Bold
+ assert!(result.contains("\u{1b}[32m")); // Green
}
#[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"));
- // H3 is bold
- assert!(result.contains("\u{1b}[1m")); // Bold
+ assert!(result.contains("\u{1b}[32m")); // Green
+ assert!(!result.contains("\u{1b}[1m")); // Not bold
+ }
+
+ #[test]
+ fn test_render_markdown_in_help_horizontal_rule() {
+ let result = render_markdown_in_help("before\n\n---\n\n## Section");
+ // Horizontal rule becomes blank line, not literal ---
+ assert!(!result.contains("---"));
+ assert!(result.contains("before"));
+ assert!(result.contains("Section"));
}
#[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 2517a4c6c..6f7443af8 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_create.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_create.snap
@@ -42,11 +42,11 @@ 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:
- # # Worktrunk User Configuration
+ # ## Worktrunk User Configuration
#
# Create with `wt config create`.
#
@@ -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 fd3ab2bd8..facbd9f07 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,16 @@ 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 +82,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 +111,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 +120,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 +138,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 +148,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 +166,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 +175,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 +221,7 @@ Default template:

"""
-Squash template
+Squash template
Available variables (in addition to commit template variables):
@@ -257,7 +259,9 @@ 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 +276,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 +285,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 +294,9 @@ 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 +315,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 +325,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 +343,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 +357,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 99e3986a5..43e18010a 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 4bea8735c..95a441929 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 df2a6e7ba..0500e6f05 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 1e6ac9326..9ce34f833 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 a7e44b196..95c3735da 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 ee3f24bc7..e78a3fbf9 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 8e223c221..f9d1d7a9c 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 a38c77109..c29968df0 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 9af45c6d5..47eaa3d97 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,9 @@ 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 +203,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 +212,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 +223,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 +231,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 +240,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 +248,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 +257,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 e46a2045c..15d357a87 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,9 @@ 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 +225,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 +234,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 +245,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 +253,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 +262,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 +271,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 +280,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 46352aa31..c1e12dbe4 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 a85ed827d..bb3776d27 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 430372df9..7ccbedf23 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,7 +70,7 @@ Manual merge workflow with review between steps:
- copy-ignored — Copy gitignored files between worktrees
- for-each — [experimental] Run a command in every worktree
-See also
+See also
- wt merge — Runs commit → squash → rebase → hooks → push → cleanup automatically
- wt hook — Run configured hooks
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
index 14ad9bbdc..20dc161c4 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