Skip to content

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

docs(cli): Refine help output and update shell completion snapshots

Maximilian Roos28be8ddb4087
diff --git a/src/cli.rs b/src/cli.rs
index df1553856..ab7ddb6f9 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -329,7 +329,17 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
},
/// List worktrees and optionally branches
- #[command(after_help = "COLUMNS:
+ #[command(after_help = "OPERATION
+
+Displays worktrees in a table format with status information, commit details, and optional branch listings.
+
+- By default: Shows only worktrees
+- With --branches: Includes branches without worktrees
+- With --full: Adds CI status, conflict detection, and detailed diffs
+- With --format=json: Outputs structured JSON for scripting
+
+COLUMNS
+
Branch: Branch name
Status: Quick status symbols (see STATUS SYMBOLS below)
HEAD±: Uncommitted changes vs HEAD (+added -deleted lines, staged + unstaged)
@@ -400,7 +410,7 @@ Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).")]
},
/// Switch to a worktree
- #[command(after_help = r#"BEHAVIOR:
+ #[command(after_help = r#"OPERATION
Switching to Existing Worktree:
- If worktree exists for branch, changes directory via shell integration
@@ -415,7 +425,7 @@ Creating New Worktree (--create):
5. Spawns post-start hooks in background (non-blocking)
6. Changes directory to new worktree via shell integration
-HOOKS:
+HOOKS
post-create (sequential, blocking):
- Run after worktree creation, before success message
@@ -430,7 +440,7 @@ post-start (parallel, background):
- Logs: .git/wt-logs/{branch}-post-start-{name}.log
- Skip with --no-verify
-EXAMPLES:
+EXAMPLES
Switch to existing worktree:
wt switch feature-branch
@@ -450,7 +460,7 @@ Create and run command:
Skip hooks during creation:
wt switch --create temp --no-verify
-SHORTCUTS:
+SHORTCUTS
Use '@' for current HEAD, '-' for previous, '^' for main:
wt switch @ # Switch to current branch's worktree
@@ -479,13 +489,13 @@ Use '@' for current HEAD, '-' for previous, '^' for main:
#[arg(short = 'f', long)]
force: bool,
- /// Skip project hooks
+ /// Skip all project hooks
#[arg(long = "no-verify", action = clap::ArgAction::SetFalse, default_value_t = true)]
verify: bool,
},
/// Remove worktree and branch
- #[command(after_help = r#"BEHAVIOR:
+ #[command(after_help = r#"OPERATION
Remove Current Worktree (no arguments):
- Requires clean working tree (no uncommitted changes)
@@ -504,9 +514,7 @@ Remove Multiple Worktrees:
- Prevents deleting directory you're currently in
- Each worktree must have clean working tree
-CLEANUP:
-
-When removing a worktree (by default):
+Removal Process (by default):
1. Validates worktree has no uncommitted changes
2. Changes directory (if removing current worktree)
3. Spawns background removal process (non-blocking)
@@ -517,7 +525,7 @@ When removing a worktree (by default):
4. Returns immediately so you can continue working
- Use --no-background for foreground removal (blocking)
-EXAMPLES:
+EXAMPLES
Remove current worktree and branch:
wt remove
@@ -557,7 +565,7 @@ Switch to default in main:
/// Merge worktree into target branch
#[command(long_about = r#"Merge worktree into target branch
-LIFECYCLE
+OPERATION
The merge operation follows a strict order designed for fail-fast execution:
diff --git a/tests/snapshots/integration__integration_tests__init__init_fish.snap b/tests/snapshots/integration__integration_tests__init__init_fish.snap
index 83f70a328..17080d9f8 100644
--- a/tests/snapshots/integration__integration_tests__init__init_fish.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_fish.snap
@@ -12,10 +12,11 @@ info:
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
GIT_CONFIG_GLOBAL: /dev/null
GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpK4BFVd/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpJDGfxp/test-config.toml
---
success: true
exit_code: 0
@@ -286,7 +287,7 @@ complete -c wt -n "__fish_wt_using_subcommand switch" -s x -l execute -d 'Execut
complete -c wt -n "__fish_wt_using_subcommand switch" -s C -d 'Change working directory' -r -F
complete -c wt -n "__fish_wt_using_subcommand switch" -s c -l create -d 'Create a new branch'
complete -c wt -n "__fish_wt_using_subcommand switch" -s f -l force -d 'Skip approval prompts'
-complete -c wt -n "__fish_wt_using_subcommand switch" -l no-verify -d 'Skip project hooks'
+complete -c wt -n "__fish_wt_using_subcommand switch" -l no-verify -d 'Skip all project hooks'
complete -c wt -n "__fish_wt_using_subcommand switch" -s v -l verbose -d 'Show commands and debug info'
complete -c wt -n "__fish_wt_using_subcommand switch" -s h -l help -d 'Print help'
complete -c wt -n "__fish_wt_using_subcommand remove" -s C -d 'Change working directory' -r -F
diff --git a/tests/snapshots/integration__integration_tests__init__init_zsh.snap b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
index c5c92bb2b..58aba61e2 100644
--- a/tests/snapshots/integration__integration_tests__init__init_zsh.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
@@ -12,10 +12,11 @@ info:
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
GIT_CONFIG_GLOBAL: /dev/null
GIT_CONFIG_SYSTEM: /dev/null
+ GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpSJbP72/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpnXjgUA/test-config.toml
---
success: true
exit_code: 0
@@ -425,7 +426,7 @@ _arguments "${_arguments_options[@]}" : \
'--create[Create a new branch]' \
'-f[Skip approval prompts]' \
'--force[Skip approval prompts]' \
-'--no-verify[Skip project hooks]' \
+'--no-verify[Skip all project hooks]' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
'-h[Print help]' \