Skip to content

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

docs: improve clarity of CLI help text (#410)

Maximilian Roosa5722e2c045f
diff --git a/docs/content/config.md b/docs/content/config.md
index 79d0d6c0f..80c228390 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -261,7 +261,7 @@ Usage: <b><span class=c>wt config</span></b> <span class=c>[OPTIONS]</span> <spa
<b><span class=c>shell</span></b> Shell integration setup
<b><span class=c>create</span></b> Create configuration file
<b><span class=c>show</span></b> Show configuration files &amp; locations
- <b><span class=c>state</span></b> Get, set, or clear stored state
+ <b><span class=c>state</span></b> Manage internal data and cache
<b><span class=g>Options:</span></b>
<b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
@@ -723,7 +723,7 @@ wt config state clear
### Command reference
{% terminal() %}
-wt config state - Get, set, or clear stored state
+wt config state - Manage internal data and cache
Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
diff --git a/docs/content/list.md b/docs/content/list.md
index 1a21234c8..59937a43a 100644
--- a/docs/content/list.md
+++ b/docs/content/list.md
@@ -266,7 +266,7 @@ Missing a field that would be generally useful? [Open an issue](https://github.c
## Command reference
{% terminal() %}
-wt list - List worktrees and optionally branches
+wt list - List worktrees and their status
Usage: <b><span class=c>wt list</span></b> <span class=c>[OPTIONS]</span>
<b><span class=c>wt list</span></b> <span class=c>&lt;COMMAND&gt;</span>
@@ -287,7 +287,7 @@ Usage: <b><span class=c>wt list</span></b> <span class=c>[OPTIONS]</span>
Include remote branches
<b><span class=c>--full</span></b>
- Show CI, merge-base diffstat, and working tree conflict check
+ Include CI status and diff analysis (slower)
<b><span class=c>--progressive</span></b>
Show fast info immediately, update with slow info
diff --git a/docs/content/step.md b/docs/content/step.md
index a2fd0fde5..248e95f77 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -33,7 +33,7 @@ wt step push
- `commit` — Stage and commit with [LLM-generated message](@/llm-commits.md)
- `squash` — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
- `rebase` — Rebase onto target branch
-- `push` — Push to target branch (defaults to the default branch)
+- `push` — Fast-forward target to current branch
- `for-each` — [experimental] Run a command in every worktree
## See also
@@ -51,7 +51,7 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
<b><span class=g>Commands:</span></b>
<b><span class=c>commit</span></b> Commit changes with LLM commit message
<b><span class=c>squash</span></b> Squash commits since target
- <b><span class=c>push</span></b> Push changes to local target branch
+ <b><span class=c>push</span></b> Fast-forward target to current branch
<b><span class=c>rebase</span></b> Rebase onto target
<b><span class=c>for-each</span></b> [experimental] Run command in each worktree
diff --git a/src/cli.rs b/src/cli.rs
index 6b0f708b4..c80e1aad8 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -129,7 +129,7 @@ pub enum OutputFormat {
#[derive(Parser)]
#[command(name = "wt")]
-#[command(about = "Git worktree management", long_about = None)]
+#[command(about = "Git worktree management for parallel AI agent workflows", long_about = None)]
#[command(version = version_str())]
#[command(disable_help_subcommand = true)]
#[command(styles = help_styles())]
@@ -379,7 +379,7 @@ This tests:
full: bool,
},
- /// Get, set, or clear stored state
+ /// Manage internal data and cache
#[command(
after_long_help = r#"State is stored in `.git/` (config entries and log files), separate from configuration files.
Use `wt config show` to view file-based configuration.
@@ -917,9 +917,10 @@ pub enum StepCommand {
show_prompt: bool,
},
- /// Push changes to local target branch
+ /// Fast-forward target to current branch
///
- /// Fast-forwards the target branch to include current commits.
+ /// Updates the local target branch (e.g., main) to include current commits.
+ /// Equivalent to `git push . HEAD:main`.
Push {
/// Target branch
///
@@ -1466,7 +1467,7 @@ wt step push
- `commit` — Stage and commit with [LLM-generated message](@/llm-commits.md)
- `squash` — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
- `rebase` — Rebase onto target branch
-- `push` — Push to target branch (defaults to the default branch)
+- `push` — Fast-forward target to current branch
- `for-each` — [experimental] Run a command in every worktree
## See also
@@ -2005,7 +2006,7 @@ Branches without worktrees are included — selecting one creates a worktree. (`
)]
Select,
- /// List worktrees and optionally branches
+ /// List worktrees and their status
#[command(
after_long_help = r#"Show all worktrees with their status. The table includes uncommitted changes, divergence from the default branch and remote, and optional CI status.
<!-- demo: wt-list.gif 1600x900 -->
@@ -2249,7 +2250,7 @@ Missing a field that would be generally useful? Open an issue at https://github.
#[arg(long)]
remotes: bool,
- /// Show CI, merge-base diffstat, and working tree conflict check
+ /// Include CI status and diff analysis (slower)
#[arg(long)]
full: bool,
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 eef9c303e..dee6d64d3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_long.snap
@@ -12,6 +12,7 @@ info:
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
success: true
exit_code: 0
@@ -26,7 +27,7 @@ Usage: wt config [OPTIONS] <COMMAND>
shell Shell integration setup
create Create configuration file
show Show configuration files & locations
- state Get, set, or clear stored state
+ state Manage internal data and cache
Options:
-h, --help
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_short.snap b/tests/snapshots/integration__integration_tests__help__help_config_short.snap
index cea8b49c2..4f24d21fb 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_short.snap
@@ -9,8 +9,10 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
success: true
exit_code: 0
@@ -25,7 +27,7 @@ Usage: wt config [OPTIONS] <COMMAND>
shell Shell integration setup
create Create configuration file
show Show configuration files & locations
- state Get, set, or clear stored state
+ state Manage internal data and cache
Options:
-h, --help Print help (see more with '--help')
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 020b4f397..75e5b8f18 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
@@ -9,17 +9,18 @@ info:
env:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
- GIT_CONFIG_GLOBAL: ""
+ GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
success: true
exit_code: 0
----- stdout -----
----- stderr -----
-wt config state - Get, set, or clear stored state
+wt config state - Manage internal data and cache
Usage: wt config state [OPTIONS] <COMMAND>
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 8f4918833..4c240aab6 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_long.snap
@@ -19,7 +19,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt list - List worktrees and optionally branches
+wt list - List worktrees and their status
Usage: wt list [OPTIONS]
wt list <COMMAND>
@@ -40,7 +40,7 @@ Usage: wt list [OPTIONS]
Include remote branches
--full
- Show CI, merge-base diffstat, and working tree conflict check
+ Include CI status and diff analysis (slower)
--progressive
Show fast info immediately, update with slow info
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 0adb66f7d..8aa48a5cd 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
@@ -19,7 +19,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt list - List worktrees and optionally branches
+wt list - List worktrees and their status
Usage: wt list [OPTIONS]
wt list <COMMAND>
@@ -40,7 +40,7 @@ Usage: wt list [OPTIONS]
Include remote branches
--full
- Show CI, merge-base diffstat, and working tree conflict check
+ Include CI status and diff analysis (slower)
--progressive
Show fast info immediately, update with slow info
diff --git a/tests/snapshots/integration__integration_tests__help__help_list_short.snap b/tests/snapshots/integration__integration_tests__help__help_list_short.snap
index c77afca3e..13b8a7245 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list_short.snap
@@ -12,13 +12,14 @@ info:
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
success: true
exit_code: 0
----- stdout -----
----- stderr -----
-wt list - List worktrees and optionally branches
+wt list - List worktrees and their status
Usage: wt list [OPTIONS]
wt list <COMMAND>
@@ -30,7 +31,7 @@ Usage: wt list [OPTIONS]
--format <FORMAT> Output format (table, json) [default: table]
--branches Include branches without worktrees
--remotes Include remote branches
- --full Show CI, merge-base diffstat, and working tree conflict check
+ --full Include CI status and diff analysis (slower)
--progressive Show fast info immediately, update with slow info
-h, --help Print help (see more with '--help')
diff --git a/tests/snapshots/integration__integration_tests__help__help_md_root.snap b/tests/snapshots/integration__integration_tests__help__help_md_root.snap
index 86db0d108..0470ea804 100644
--- a/tests/snapshots/integration__integration_tests__help__help_md_root.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_md_root.snap
@@ -16,7 +16,7 @@ info:
success: true
exit_code: 0
----- stdout -----
-wt - Git worktree management
+wt - Git worktree management for parallel AI agent workflows
Usage: wt [OPTIONS] [COMMAND]
@@ -25,7 +25,7 @@ Commands:
step Run individual workflow operations
hook Run hooks independently
select Interactive worktree selector
- list List worktrees and optionally branches
+ list List worktrees and their status
switch Switch to a worktree
remove Remove worktree and branch (if merged)
merge Merge worktree into target branch
diff --git a/tests/snapshots/integration__integration_tests__help__help_no_args.snap b/tests/snapshots/integration__integration_tests__help__help_no_args.snap
index a099a5ead..6bd167591 100644
--- a/tests/snapshots/integration__integration_tests__help__help_no_args.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_no_args.snap
@@ -17,7 +17,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt - Git worktree management
+wt - Git worktree management for parallel AI agent workflows
Usage: wt [OPTIONS] [COMMAND]
@@ -26,7 +26,7 @@ Usage: wt [OPTIONS] [COMMAND]
step Run individual workflow operations
hook Run hooks independently
select Interactive worktree selector
- list List worktrees and optionally branches
+ list List worktrees and their status
switch Switch to a worktree
remove Remove worktree and branch (if merged)
merge Merge worktree into target branch
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_long.snap b/tests/snapshots/integration__integration_tests__help__help_root_long.snap
index cc853e12e..155fbf5cf 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root_long.snap
@@ -18,7 +18,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt - Git worktree management
+wt - Git worktree management for parallel AI agent workflows
Usage: wt [OPTIONS] [COMMAND]
@@ -27,7 +27,7 @@ Usage: wt [OPTIONS] [COMMAND]
step Run individual workflow operations
hook Run hooks independently
select Interactive worktree selector
- list List worktrees and optionally branches
+ list List worktrees and their status
switch Switch to a worktree
remove Remove worktree and branch (if merged)
merge Merge worktree into target branch
diff --git a/tests/snapshots/integration__integration_tests__help__help_root_short.snap b/tests/snapshots/integration__integration_tests__help__help_root_short.snap
index 9134845b5..e39a042c3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root_short.snap
@@ -18,7 +18,7 @@ exit_code: 0
----- stdout -----
----- stderr -----
-wt - Git worktree management
+wt - Git worktree management for parallel AI agent workflows
Usage: wt [OPTIONS] [COMMAND]
@@ -27,7 +27,7 @@ Usage: wt [OPTIONS] [COMMAND]
step Run individual workflow operations
hook Run hooks independently
select Interactive worktree selector
- list List worktrees and optionally branches
+ list List worktrees and their status
switch Switch to a worktree
remove Remove worktree and branch (if merged)
merge Merge worktree into target branch
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 d56e92ebf..ed475a930 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -8,10 +8,11 @@ info:
env:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
- GIT_CONFIG_GLOBAL: ""
+ GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
success: true
exit_code: 0
@@ -25,7 +26,7 @@ Usage: wt step [OPTIONS] <COMMAND>
Commands:
commit Commit changes with LLM commit message
squash Squash commits since target
- push Push changes to local target branch
+ push Fast-forward target to current branch
rebase Rebase onto target
for-each [experimental] Run command in each worktree
@@ -64,7 +65,7 @@ Manual merge workflow with review between steps:
- commit — Stage and commit with LLM-generated message
- squash — Squash all branch commits into one with LLM-generated message
- rebase — Rebase onto target branch
-- push — Push to target branch (defaults to the default branch)
+- push — Fast-forward target to current branch
- for-each — [experimental] Run a command in every worktree
See also
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_short.snap b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
index a5f57dfff..3e6a03969 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
@@ -9,8 +9,10 @@ info:
CLICOLOR_FORCE: "1"
COLUMNS: "150"
GIT_EDITOR: ""
+ RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
success: true
exit_code: 0
@@ -24,7 +26,7 @@ Usage: wt step [OPTIONS] <COMMAND>
Commands:
commit Commit changes with LLM commit message
squash Squash commits since target
- push Push changes to local target branch
+ push Fast-forward target to current branch
rebase Rebase onto target
for-each [experimental] Run command in each worktree