Skip to content

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

feat: Improve help output and visual consistency

Maximilian Roos8547d172ca1b
diff --git a/src/cli.rs b/src/cli.rs
index d097919b3..e09f63f80 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -49,19 +49,14 @@ const HELP_TEMPLATE: &str = "\
{before-help}{name} - {about-with-newline}\
Usage: {usage}
-Options:
-{options}{after-help}";
+{all-args}{after-help}";
/// Help template for commands with subcommands
const HELP_TEMPLATE_WITH_SUBCOMMANDS: &str = "\
{before-help}{name} - {about-with-newline}\
Usage: {usage}
-Commands:
-{subcommands}
-
-Options:
-{options}{after-help}";
+{all-args}{after-help}";
/// Build a clap Command for Cli with the shared help template applied recursively.
pub fn build_command() -> Command {
@@ -114,25 +109,43 @@ pub enum OutputFormat {
#[command(version = version_str())]
#[command(disable_help_subcommand = true)]
#[command(styles = help_styles())]
-#[command(after_long_help = r#"## GLOBAL OPTIONS
-
-**-C <path>**: Run as if started in `<path>` instead of current directory.
+#[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 <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)"#)]
+1. WORKTRUNK_CONFIG_PATH environment variable
+2. ~/.config/worktrunk/config.toml (Linux/macOS) or %APPDATA%\worktrunk\config.toml (Windows)"#
+)]
pub struct Cli {
/// Change working directory
- #[arg(short = 'C', global = true, value_name = "path", display_order = 100)]
+ #[arg(
+ short = 'C',
+ global = true,
+ value_name = "path",
+ display_order = 100,
+ help_heading = "Global Options"
+ )]
pub directory: Option<std::path::PathBuf>,
/// User config file path
- #[arg(long, global = true, value_name = "path", display_order = 101)]
+ #[arg(
+ long,
+ global = true,
+ value_name = "path",
+ display_order = 101,
+ help_heading = "Global Options"
+ )]
pub config: Option<std::path::PathBuf>,
/// Show commands and debug info
- #[arg(long, short = 'v', global = true, display_order = 102)]
+ #[arg(
+ long,
+ short = 'v',
+ global = true,
+ display_order = 102,
+ help_heading = "Global Options"
+ )]
pub verbose: bool,
/// Use internal mode (outputs directives for shell wrapper)
diff --git a/tests/snapshots/integration__integration_tests__help__help_beta.snap b/tests/snapshots/integration__integration_tests__help__help_beta.snap
index b7dc65a54..0d14dc12e 100644
--- a/tests/snapshots/integration__integration_tests__help__help_beta.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_beta.snap
@@ -25,6 +25,10 @@ Commands:
select Interactive worktree selector
Options:
+ -h, --help
+ Print help
+
+Global Options:
-C <path>
Change working directory
@@ -34,7 +38,4 @@ Options:
-v, --verbose
Show commands and debug info
- -h, --help
- Print help
-
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_config.snap b/tests/snapshots/integration__integration_tests__help__help_config.snap
index d286ceb61..9474741ea 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config.snap
@@ -25,6 +25,10 @@ Commands:
approvals Manage command approvals
Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
-C <path>
Change working directory
@@ -34,9 +38,6 @@ Options:
-v, --verbose
Show commands and debug info
- -h, --help
- Print help (see a summary with '-h')
-
SETUP GUIDE:
1. Set up shell integration
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 d0e6f7fb1..97e2ed5ab 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_shell.snap
@@ -22,6 +22,10 @@ Commands:
install Write shell integration to config files
Options:
+ -h, --help
+ Print help
+
+Global Options:
-C <path>
Change working directory
@@ -31,7 +35,4 @@ Options:
-v, --verbose
Show commands and debug info
- -h, --help
- Print help
-
----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_list.snap b/tests/snapshots/integration__integration_tests__help__help_list.snap
index 4aba617f8..a2c8cfa33 100644
--- a/tests/snapshots/integration__integration_tests__help__help_list.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_list.snap
@@ -34,6 +34,10 @@ Options:
--progressive
Force progressive (or --no-progressive)
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
-C <path>
Change working directory
@@ -43,9 +47,6 @@ Options:
-v, --verbose
Show commands and debug info
- -h, --help
- Print help (see a summary with '-h')
-
COLUMNS
- Branch: Branch name
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snap
index e34ba194e..0138cba5a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge.snap
@@ -16,6 +16,12 @@ exit_code: 0
wt merge - Merge worktree into target branch
Usage: wt merge [OPTIONS] [TARGET]
+Arguments:
+ [TARGET]
+ Target branch
+
+ Defaults to default branch.
+
Options:
--no-squash
Skip commit squashing
@@ -35,6 +41,10 @@ Options:
--tracked-only
Stage tracked files only
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
-C <path>
Change working directory
@@ -44,9 +54,6 @@ Options:
-v, --verbose
Show commands and debug info
- -h, --help
- Print help (see a summary with '-h')
-
OPERATION
Commit → Squash → Rebase → Pre-merge hooks → Push → Cleanup → Post-merge hooks
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove.snap b/tests/snapshots/integration__integration_tests__help__help_remove.snap
index c6b7dbc6e..0ba10eac6 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove.snap
@@ -16,6 +16,10 @@ exit_code: 0
wt remove - Remove worktree and branch
Usage: wt remove [OPTIONS] [WORKTREES]...
+Arguments:
+ [WORKTREES]...
+ Worktree or branch (@ for current)
+
Options:
--no-delete-branch
Keep branch after removal
@@ -26,6 +30,10 @@ Options:
--no-background
Run removal in foreground
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
-C <path>
Change working directory
@@ -35,9 +43,6 @@ Options:
-v, --verbose
Show commands and debug info
- -h, --help
- Print help (see a summary with '-h')
-
OPERATION
Removes worktree directory, git metadata, and branch. Requires clean working
diff --git a/tests/snapshots/integration__integration_tests__help__help_root.snap b/tests/snapshots/integration__integration_tests__help__help_root.snap
index 2909cc5b4..c7f00bd52 100644
--- a/tests/snapshots/integration__integration_tests__help__help_root.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_root.snap
@@ -23,6 +23,13 @@ Commands:
merge Merge worktree into target branch
Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+ -V, --version
+ Print version
+
+Global Options:
-C <path>
Change working directory
@@ -32,14 +39,6 @@ Options:
-v, --verbose
Show commands and debug info
- -h, --help
- Print help (see a summary with '-h')
-
- -V, --version
- Print version
-
-GLOBAL OPTIONS
-
-C <path>: Run as if started in <path> instead of current directory.
--config <path>: Override user config file location. Without this flag,
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snap
index 43cbd77bc..bf53f4083 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch.snap
@@ -16,6 +16,10 @@ exit_code: 0
wt switch - Switch to a worktree
Usage: wt switch [OPTIONS] <BRANCH>
+Arguments:
+ <BRANCH>
+ Branch, path, '@' (HEAD), '-' (previous), or '^' (main)
+
Options:
-c, --create
Create a new branch
@@ -34,6 +38,10 @@ Options:
--no-verify
Skip all project hooks
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
-C <path>
Change working directory
@@ -43,9 +51,6 @@ Options:
-v, --verbose
Show commands and debug info
- -h, --help
- Print help (see a summary with '-h')
-
OPERATION
Switching to Existing Worktree:
diff --git a/tests/snapshots/integration__integration_tests__init__init_fish.snap b/tests/snapshots/integration__integration_tests__init__init_fish.snap
index 96bd0df32..146c3d56f 100644
--- a/tests/snapshots/integration__integration_tests__init__init_fish.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_fish.snap
@@ -12,13 +12,13 @@ info:
COLUMNS: "150"
GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
- GIT_CONFIG_GLOBAL: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpEYPsxm/test-gitconfig
+ GIT_CONFIG_GLOBAL: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmp1suEFj/test-gitconfig
GIT_CONFIG_SYSTEM: /dev/null
GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpEYPsxm/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmp1suEFj/test-config.toml
---
success: true
exit_code: 0
diff --git a/tests/snapshots/integration__integration_tests__init__init_zsh.snap b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
index b7cb4ae18..e8ddf93ec 100644
--- a/tests/snapshots/integration__integration_tests__init__init_zsh.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
@@ -12,13 +12,13 @@ info:
COLUMNS: "150"
GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
- GIT_CONFIG_GLOBAL: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpm9QNFk/test-gitconfig
+ GIT_CONFIG_GLOBAL: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpzDD4PX/test-gitconfig
GIT_CONFIG_SYSTEM: /dev/null
GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpm9QNFk/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpzDD4PX/test-config.toml
---
success: true
exit_code: 0