Skip to content

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

Refine `wt switch` help text and argument error

Maximilian Roos64100c241aad
diff --git a/CLAUDE.md b/CLAUDE.md
index 8f83740c7..c0d2a285f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -81,7 +81,6 @@ Keep the first line of flag and argument descriptions brief—aim for 3-6 words.
- `/// Skip approval prompts`
- `/// Show CI, conflicts, and full diffs`
- `/// Target branch (defaults to default branch)`
-- `/// Branch, path, '@' (HEAD), '-' (previous), or '^' (main)`
**Bad examples (too verbose):**
- `/// Auto-approve project commands without saving approvals.`
diff --git a/README.md b/README.md
index e462b37f8..71c74cf63 100644
--- a/README.md
+++ b/README.md
@@ -468,7 +468,9 @@ Usage: wt switch [OPTIONS] <BRANCH>
Arguments:
<BRANCH>
- Branch, path, '@' (HEAD), '-' (previous), or '^' (main)
+ Branch or worktree name
+
+ Shortcuts: '^' (main), '-' (previous), '@' (current)
Options:
-c, --create
diff --git a/src/cli.rs b/src/cli.rs
index 027b0b0ec..ab7e7821a 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -835,7 +835,9 @@ wt switch --create bugfix --base=@ # Branch from current HEAD
wt remove @ # Remove current worktree
```"#)]
Switch {
- /// Branch, path, '@' (HEAD), '-' (previous), or '^' (main)
+ /// Branch or worktree name
+ ///
+ /// Shortcuts: '^' (main), '-' (previous), '@' (current)
#[arg(add = crate::completion::worktree_branch_completer())]
branch: String,
diff --git a/src/main.rs b/src/main.rs
index a671d11db..22ea82358 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -119,6 +119,28 @@ fn maybe_handle_help_with_pager() -> bool {
}
}
+/// Enhance clap errors with command-specific hints, then exit.
+///
+/// For `wt switch` missing the branch argument, adds hints about shortcuts.
+fn enhance_and_exit_error(err: clap::Error) -> ! {
+ use clap::error::ErrorKind;
+ use color_print::ceprintln;
+
+ // Enhance `wt switch` missing argument error with shortcut hints.
+ // Safe in directive mode: hints go to stderr, only stdout is eval'd.
+ if err.kind() == ErrorKind::MissingRequiredArgument && format!("{err}").contains("wt switch") {
+ eprint!("{}", err.render().ansi());
+ ceprintln!("<green,bold>Quick switches:</>");
+ ceprintln!(" <cyan,bold>wt switch ^</> default branch's worktree");
+ ceprintln!(" <cyan,bold>wt switch -</> previous worktree");
+ ceprintln!(" <cyan,bold>wt switch @</> current branch's worktree");
+ ceprintln!(" <cyan,bold>wt select</> interactive picker");
+ process::exit(2);
+ }
+
+ err.exit()
+}
+
fn main() {
// Tell crossterm to always emit ANSI sequences
crossterm::style::force_color_output(true);
@@ -138,7 +160,9 @@ fn main() {
// When available, use built-in setting. Until then, could use try_parse() to intercept
// MissingRequiredArgument errors and print custom messages with ValueEnum::value_variants().
let cmd = cli::build_command();
- let matches = cmd.get_matches();
+ let matches = cmd.try_get_matches().unwrap_or_else(|e| {
+ enhance_and_exit_error(e);
+ });
let cli = Cli::from_arg_matches(&matches).unwrap_or_else(|e| e.exit());
// Initialize base path from -C flag if provided
diff --git a/tests/integration_tests/switch.rs b/tests/integration_tests/switch.rs
index 2ec326c5b..21cdebc85 100644
--- a/tests/integration_tests/switch.rs
+++ b/tests/integration_tests/switch.rs
@@ -684,3 +684,12 @@ fn test_switch_ping_pong_realistic() {
repo.root_path(),
);
}
+
+/// Test that `wt switch` without arguments shows helpful hints about shortcuts.
+#[test]
+fn test_switch_missing_argument_shows_hints() {
+ let repo = setup_switch_repo();
+
+ // Run switch with no arguments - should show clap error plus hints
+ snapshot_switch("switch_missing_argument_hints", &repo, &[]);
+}
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 84bc2ea87..0477f6359 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -22,7 +22,9 @@ Usage: wt switch [OPTIONS] <BRANCH>
Arguments:
<BRANCH>
- Branch, path, '@' (HEAD), '-' (previous), or '^' (main)
+ Branch or worktree name
+ 
+ Shortcuts: '^' (main), '-' (previous), '@' (current)
Options:
-c, --create
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch_short.snap b/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
index b09ea613a..fd30b2d08 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
@@ -21,7 +21,7 @@ wt switch - Switch to a worktree
Usage: wt switch [OPTIONS] <BRANCH>
Arguments:
- <BRANCH> Branch, path, '@' (HEAD), '-' (previous), or '^' (main)
+ <BRANCH> Branch or worktree name
Options:
-c, --create Create a new branch
diff --git a/tests/snapshots/integration__integration_tests__switch__switch_missing_argument_hints.snap b/tests/snapshots/integration__integration_tests__switch__switch_missing_argument_hints.snap
new file mode 100644
index 000000000..d45667756
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__switch__switch_missing_argument_hints.snap
@@ -0,0 +1,36 @@
+---
+source: tests/integration_tests/switch.rs
+info:
+ program: wt
+ args:
+ - switch
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ SOURCE_DATE_EPOCH: "1735776000"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+---
+success: false
+exit_code: 2
+----- stdout -----
+
+----- stderr -----
+error: the following required arguments were not provided:
+ <BRANCH>
+
+Usage: wt switch <BRANCH>
+
+For more information, try '--help'.
+Quick switches:
+ wt switch ^ default branch's worktree
+ wt switch - previous worktree
+ wt switch @ current branch's worktree
+ wt select interactive picker