Skip to content

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

refactor: Use consistent help template and update CLI parsing

Maximilian Roosfdc1085a12ba
diff --git a/src/cli.rs b/src/cli.rs
index dfeeffa04..4cc21b36b 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -1,5 +1,5 @@
use clap::builder::styling::{AnsiColor, Color, Styles};
-use clap::{Parser, Subcommand};
+use clap::{Command, CommandFactory, Parser, Subcommand};
use std::sync::OnceLock;
use worktrunk::HookType;
@@ -43,6 +43,28 @@ fn help_styles() -> Styles {
/// Default command name for worktrunk
const DEFAULT_COMMAND_NAME: &str = "wt";
+const HELP_TEMPLATE: &str = "\
+{before-help}{name} - {about-with-newline}\
+Usage: {usage}
+
+Options:
+{options}{after-help}";
+
+/// Build a clap Command for Cli with the shared help template applied recursively.
+pub fn build_command() -> Command {
+ let cmd = Cli::command();
+ apply_help_template_recursive(cmd)
+}
+
+fn apply_help_template_recursive(mut cmd: Command) -> Command {
+ cmd = cmd.help_template(HELP_TEMPLATE);
+ for sub in cmd.get_subcommands_mut() {
+ let sub_cmd = std::mem::take(sub);
+ let sub_cmd = apply_help_template_recursive(sub_cmd);
+ *sub = sub_cmd;
+ }
+ cmd
+}
fn version_str() -> &'static str {
static VERSION: OnceLock<String> = OnceLock::new();
@@ -439,23 +461,21 @@ Use `--format=json` for structured data. Each object contains two status maps:
#[arg(long)]
branches: bool,
- /// Show CI, conflicts, and full diffs
+ /// Show CI, conflicts, diffs
///
- /// Adds columns: CI (pipeline status), main…± (line diffs).
- /// Enables conflict detection (shows "=" symbol in Status column).
- /// Requires network requests and git merge-tree operations.
+ /// Adds CI column, main…± diffs, and conflict detection (merge-tree + network).
#[arg(long, verbatim_doc_comment)]
full: bool,
- /// Enable progressive rendering (show rows as data arrives)
+ /// Progressive rendering
///
- /// When enabled, worktree names appear immediately and details fill in
- /// progressively. Default: auto (enabled for TTY, disabled for pipes).
- #[arg(long, verbatim_doc_comment, conflicts_with = "no_progressive")]
+ /// Use --progressive or --no-progressive to force rendering mode.
+ /// Default: auto (enabled for TTY, disabled for pipes).
+ #[arg(long, overrides_with = "no_progressive", verbatim_doc_comment)]
progressive: bool,
- /// Disable progressive rendering (collect all data before displaying)
- #[arg(long)]
+ /// Force buffered rendering
+ #[arg(long = "no-progressive", overrides_with = "progressive", hide = true)]
no_progressive: bool,
},
diff --git a/src/commands/list/progressive.rs b/src/commands/list/progressive.rs
index 6e476ac2b..fb23a4b36 100644
--- a/src/commands/list/progressive.rs
+++ b/src/commands/list/progressive.rs
@@ -12,19 +12,17 @@ impl RenderMode {
///
/// # Arguments
///
- /// * `progressive_flag` - Explicit --progressive flag
- /// * `no_progressive_flag` - Explicit --no-progressive flag
+ /// * `progressive` - Rendering mode (Some(true) = --progressive, Some(false) = --no-progressive, None = auto)
/// * `directive_mode` - True if in directive mode (--internal), affects which stream to check
///
/// In directive mode, table output goes to stderr, so we check stderr's TTY status.
/// In interactive mode, table output goes to stdout, so we check stdout's TTY status.
- pub fn detect(progressive_flag: bool, no_progressive_flag: bool, directive_mode: bool) -> Self {
- // Priority 1: Explicit CLI flags
- if progressive_flag {
- return RenderMode::Progressive;
- }
- if no_progressive_flag {
- return RenderMode::Buffered;
+ pub fn detect(progressive: Option<bool>, directive_mode: bool) -> Self {
+ // Priority 1: Explicit CLI flag
+ match progressive {
+ Some(true) => return RenderMode::Progressive,
+ Some(false) => return RenderMode::Buffered,
+ None => {} // Fall through to auto-detection
}
// Priority 2: Auto-detect based on TTY
@@ -53,16 +51,20 @@ mod tests {
#[test]
fn test_render_mode_detect_explicit_flags() {
- // Explicit flags should work regardless of directive mode
+ // --progressive (Some(true)) should force progressive mode
assert_eq!(
- RenderMode::detect(true, false, false),
+ RenderMode::detect(Some(true), false),
RenderMode::Progressive
);
- assert_eq!(RenderMode::detect(false, true, false), RenderMode::Buffered);
assert_eq!(
- RenderMode::detect(true, false, true),
+ RenderMode::detect(Some(true), true),
RenderMode::Progressive
);
- assert_eq!(RenderMode::detect(false, true, true), RenderMode::Buffered);
+
+ // --no-progressive (Some(false)) should force buffered mode
+ assert_eq!(RenderMode::detect(Some(false), false), RenderMode::Buffered);
+ assert_eq!(RenderMode::detect(Some(false), true), RenderMode::Buffered);
+
+ // None should auto-detect (tested via TTY checks in runtime)
}
}
diff --git a/src/completion.rs b/src/completion.rs
index 8e7bb1aa7..b0a5c627d 100644
--- a/src/completion.rs
+++ b/src/completion.rs
@@ -1,11 +1,11 @@
use std::cell::RefCell;
use std::ffi::{OsStr, OsString};
-use clap::{Command, CommandFactory};
+use clap::Command;
use clap_complete::engine::{ArgValueCompleter, CompletionCandidate, ValueCompleter};
use clap_complete::env::CompleteEnv;
-use crate::cli::Cli;
+use crate::cli;
use worktrunk::git::Repository;
/// Handle shell-initiated completion requests via `COMPLETE=$SHELL wt`
@@ -99,7 +99,7 @@ thread_local! {
}
fn completion_command() -> Command {
- adjust_completion_command(Cli::command())
+ adjust_completion_command(cli::build_command())
}
// Mark positional args as `.last(true)` to allow them after all flags.
diff --git a/src/main.rs b/src/main.rs
index 776f5c912..be1023183 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1,5 +1,5 @@
use anstyle::Style;
-use clap::{CommandFactory, Parser};
+use clap::FromArgMatches;
use std::process;
use worktrunk::config::WorktrunkConfig;
use worktrunk::git::{GitError, GitResultExt, Repository, set_base_path};
@@ -38,7 +38,7 @@ fn maybe_handle_help_with_pager() -> bool {
use clap::ColorChoice;
use clap::error::ErrorKind;
- let mut cmd = Cli::command();
+ let mut cmd = cli::build_command();
cmd = cmd.color(ColorChoice::Always); // Force clap to always emit ANSI codes
// DON'T render markdown yet - let clap generate help first
@@ -94,7 +94,9 @@ fn main() {
// Clap doesn't support this natively yet - see https://github.com/clap-rs/clap/issues/3320
// 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 cli = Cli::parse();
+ let cmd = cli::build_command();
+ let matches = cmd.get_matches();
+ let cli = Cli::from_arg_matches(&matches).unwrap_or_else(|e| e.exit());
// Initialize base path from -C flag if provided
if let Some(path) = cli.directory {
@@ -170,7 +172,7 @@ fn main() {
shell,
command_name,
} => {
- let mut cli_cmd = Cli::command();
+ let mut cli_cmd = cli::build_command();
handle_init(shell, command_name, &mut cli_cmd).git_err()
}
Commands::Config { action } => match action {
@@ -270,7 +272,13 @@ fn main() {
no_progressive,
} => {
use commands::list::progressive::RenderMode;
- let render_mode = RenderMode::detect(progressive, no_progressive, cli.internal);
+ // Convert two bools to Option<bool>: Some(true), Some(false), or None
+ let progressive_opt = match (progressive, no_progressive) {
+ (true, _) => Some(true),
+ (_, true) => Some(false),
+ _ => None,
+ };
+ let render_mode = RenderMode::detect(progressive_opt, cli.internal);
handle_list(format, branches, full, render_mode)
}
Commands::Switch {
diff --git a/tests/integration_tests/help.rs b/tests/integration_tests/help.rs
new file mode 100644
index 000000000..aa1bf6acc
--- /dev/null
+++ b/tests/integration_tests/help.rs
@@ -0,0 +1,58 @@
+//! Snapshot tests for top-level `--help` output.
+//!
+//! These ensure our compact help formatting stays stable across releases and
+//! catches accidental regressions in wording or wrapping.
+
+use crate::common::wt_command;
+use insta::Settings;
+use insta_cmd::assert_cmd_snapshot;
+
+fn snapshot_help(test_name: &str, args: &[&str]) {
+ let mut settings = Settings::clone_current();
+ settings.set_snapshot_path("../snapshots");
+ settings.bind(|| {
+ let mut cmd = wt_command();
+ cmd.args(args);
+ assert_cmd_snapshot!(test_name, cmd);
+ });
+}
+
+#[test]
+fn help_root() {
+ snapshot_help("help_root", &["--help"]);
+}
+
+#[test]
+fn help_init() {
+ snapshot_help("help_init", &["init", "--help"]);
+}
+
+#[test]
+fn help_config() {
+ snapshot_help("help_config", &["config", "--help"]);
+}
+
+#[test]
+fn help_beta() {
+ snapshot_help("help_beta", &["beta", "--help"]);
+}
+
+#[test]
+fn help_list() {
+ snapshot_help("help_list", &["list", "--help"]);
+}
+
+#[test]
+fn help_switch() {
+ snapshot_help("help_switch", &["switch", "--help"]);
+}
+
+#[test]
+fn help_remove() {
+ snapshot_help("help_remove", &["remove", "--help"]);
+}
+
+#[test]
+fn help_merge() {
+ snapshot_help("help_merge", &["merge", "--help"]);
+}
diff --git a/tests/integration_tests/mod.rs b/tests/integration_tests/mod.rs
index 3f916557d..b63953792 100644
--- a/tests/integration_tests/mod.rs
+++ b/tests/integration_tests/mod.rs
@@ -19,6 +19,7 @@ pub mod default_branch;
pub mod directives;
pub mod e2e_shell;
pub mod e2e_shell_post_start;
+pub mod help;
pub mod init;
pub mod internal_flag;
pub mod list;
diff --git a/tests/snapshots/integration__integration_tests__help__help_beta.snap b/tests/snapshots/integration__integration_tests__help__help_beta.snap
new file mode 100644
index 000000000..d21c82995
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_beta.snap
@@ -0,0 +1,29 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - beta
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_CONFIG_GLOBAL: ""
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt-beta - Development and testing utilities
+Usage: wt beta [OPTIONS] <COMMAND>
+
+Options:
+ -C <path>
+ Change working directory
+
+ -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
new file mode 100644
index 000000000..f539d76b6
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_config.snap
@@ -0,0 +1,64 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - config
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_CONFIG_GLOBAL: ""
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt-config - Manage configuration. For AI commit setup, run: wt config --help
+(see 'LLM SETUP GUIDE').
+Usage: wt config [OPTIONS] <COMMAND>
+
+Options:
+ -C <path>
+ Change working directory
+
+ -v, --verbose
+ Show commands and debug info
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+LLM SETUP GUIDE:
+Enable AI-generated commit messages
+
+1. Install an LLM tool (llm, aichat)
+
+ uv tool install -U llm
+
+2. Configure a model
+
+For Claude:
+ llm install llm-anthropic
+ llm keys set anthropic
+ # Paste your API key from: https://console.anthropic.com/settings/keys
+ llm models default claude-3.5-sonnet
+
+For OpenAI:
+ llm keys set openai
+ # Paste your API key from: https://platform.openai.com/api-keys
+
+3. Test it works
+
+ llm "say hello"
+
+4. Configure worktrunk
+
+Add to ~/.config/worktrunk/config.toml:
+
+ [commit-generation]
+ command = "llm"
+
+Use 'wt config init' to create the config file if it doesn't exist
+Use 'wt config list' to view your current configuration
+Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_init.snap b/tests/snapshots/integration__integration_tests__help__help_init.snap
new file mode 100644
index 000000000..7d30e2962
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_init.snap
@@ -0,0 +1,34 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - init
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_CONFIG_GLOBAL: ""
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt-init - Generate shell integration code
+Usage: wt init [OPTIONS] <SHELL>
+
+Options:
+ -C <path>
+ Change working directory
+
+ --command-name <COMMAND_NAME>
+ Command name
+
+ [default: wt]
+
+ -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
new file mode 100644
index 000000000..f4869873f
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_list.snap
@@ -0,0 +1,159 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - list
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_EDITOR: ""
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt-list - List worktrees and optionally branches
+Usage: wt list [OPTIONS]
+
+Options:
+ -C <path>
+ Change working directory
+
+ --format <FORMAT>
+ Output format
+
+ Possible values:
+ - table: Human-readable table format
+ - json: JSON output
+
+ [default: table]
+
+ --branches
+ Include branches without worktrees
+
+ -v, --verbose
+ Show commands and debug info
+
+ --full
+ Show CI, conflicts, diffs
+
+ Adds CI column, main…± diffs, and conflict detection (merge-tree +
+network).
+
+ --progressive
+ Progressive rendering
+
+ Use --progressive or --no-progressive to force rendering mode.
+ Default: auto (enabled for TTY, disabled for pipes).
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+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)
+- main↕: Commit count ahead↑/behind↓ relative to main (commits in HEAD vs main)
+- main…± (--full): Line diffs in commits ahead of main (+added -deleted)
+- Path: Worktree directory location
+- Remote⇅: Commits ahead↑/behind↓ relative to tracking branch (e.g.
+origin/branch)
+- CI (--full): CI pipeline status (tries PR/MR checks first, falls back to
+branch workflows)
+ - ● passed (green) - All checks passed
+ - ● running (blue) - Checks in progress
+ - ● failed (red) - Checks failed
+ - ● conflicts (yellow) - Merge conflicts with base
+ - ● no-ci (gray) - PR/MR or workflow found but no checks configured
+ - (blank) - No PR/MR or workflow found, or gh/glab CLI unavailable
+ - (dimmed) - Stale: unpushed local changes differ from PR/MR head
+- Commit: Short commit hash (8 chars)
+- Age: Time since last commit (relative)
+- Message: Last commit message (truncated)
+
+STATUS SYMBOLS
+
+Order: =≠ ≡∅ ↻⋈ ⎇⌫⊠ ↑↓ ⇡⇣ ?!+»✘
+
+- · Branch without worktree (no working directory to check)
+- = Merge conflicts (unmerged paths in working tree)
+- ≠ Potential conflicts with main (--full only, detected via git merge-tree)
+- ≡ Working tree matches main (identical contents, regardless of commit history)
+- ∅ No commits (no commits ahead AND no uncommitted changes)
+- ↻ Rebase in progress
+- ⋈ Merge in progress
+- ⎇ Branch indicator (shown for branches without worktrees)
+- ⌫ Prunable worktree (directory missing, can be pruned)
+- ⊠ Locked worktree (protected from auto-removal)
+- ↑ Ahead of main branch
+- ↓ Behind main branch
+- ⇡ Ahead of remote tracking branch
+- ⇣ Behind remote tracking branch
+- ? Untracked files present
+- ! Modified files (unstaged changes)
+- + Staged files (ready to commit)
+- » Renamed files
+- ✘ Deleted files
+
+Rows are dimmed when no unique work (≡ matches main OR ∅ no commits).
+
+JSON OUTPUT
+
+Use --format=json for structured data. Each object contains two status maps:
+
+status (variant names for querying):
+- branch_state: "" | "Conflicts" | "PotentialConflicts" | "MatchesMain" |
+"NoCommits"
+- git_operation: "" | "Rebase" | "Merge"
+- worktree_attrs: object (worktrees only) with:
+ - locked: null | "reason string"
+ - prunable: null | "reason string"
+- main_divergence: "" | "Ahead" | "Behind" | "Diverged"
+- upstream_divergence: "" | "Ahead" | "Behind" | "Diverged"
+- working_tree: object with booleans
+ - untracked: boolean - untracked files present
+ - modified: boolean - unstaged changes
+ - staged: boolean - staged changes
+ - renamed: boolean - renamed files
+ - deleted: boolean - deleted files
+- user_status: string (optional) - custom status from git config
+
+status_symbols (display symbols for rendering):
+- branch_state: "" | "=" | "≠" | "≡" | "∅"
+- git_operation: "" | "↻" | "⋈"
+- worktree_attrs: "⎇" (branch) | "⌫" (prunable) | "⊠" (locked) | ""
+- main_divergence: "" | "↑" | "↓" | "↕"
+- upstream_divergence: "" | "⇡" | "⇣" | "⇅"
+- working_tree: string - combination of "?!+»✘"
+- user_status: string (optional) - same as status.user_status
+
+Query examples:
+
+ # Find worktrees with conflicts
+ jq '.[] | select(.status.branch_state == "Conflicts")'
+
+ # Find locked worktrees
+ jq '.[] | select(.status.worktree_attrs.locked != null)'
+
+ # Find worktrees with untracked files
+ jq '.[] | select(.status.working_tree.untracked == true)'
+
+ # Find worktrees in rebase or merge
+ jq '.[] | select(.status.git_operation != "")'
+
+ # Get branches ahead of main
+ jq '.[] | select(.status.main_divergence == "Ahead")'
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snap
new file mode 100644
index 000000000..862488718
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_merge.snap
@@ -0,0 +1,125 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - merge
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_CONFIG_GLOBAL: ""
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt-merge - Merge worktree into target branch
+
+OPERATION
+
+The merge operation follows a strict order designed for fail-fast execution:
+
+1. Validate branches
+ Verifies current branch exists (not detached HEAD) and determines target
+branch
+ (defaults to repository's default branch).
+
+2. Auto-commit uncommitted changes
+ If working tree has uncommitted changes, stages changes and commits with
+LLM-generated
+ message. By default stages all changes (git add -A). Use --tracked-only to
+stage only
+ tracked files (git add -u).
+
+3. Squash commits (default)
+ By default, counts commits since merge base with target branch. When multiple
+ commits exist, squashes them into one with LLM-generated message. Skip
+squashing
+ with --no-squash.
+
+ A safety backup is created before squashing if there are working tree
+changes.
+ Recover with: git reflog show refs/wt-backup/<branch>
+
+4. Rebase onto target
+ Rebases current branch onto target branch. Detects conflicts and aborts if
+found.
+ This fails fast before running expensive checks.
+
+5. Run pre-merge commands
+ Runs commands from project config's [pre-merge-command] after rebase
+completes.
+ These receive {{ target }} placeholder for the target branch. Commands run
+sequentially
+ and any failure aborts the merge immediately. Skip with --no-verify.
+
+6. Push to target
+ Fast-forward pushes to target branch. Rejects non-fast-forward pushes
+(ensures
+ linear history). Temporarily stashes non-conflicting local edits in the
+target
+ worktree so they don't block the push, then restores them after success.
+
+7. Clean up worktree and branch
+ Removes current worktree, deletes the branch, and switches main worktree to
+target
+ branch if needed. Skip removal with --no-remove.
+
+8. Run post-merge commands
+ Runs commands from project config's [post-merge-command] in the destination
+worktree
+ after cleanup. These receive {{ target }} placeholder. Commands run
+sequentially,
+ failures are logged but don't abort. Skip with --no-verify.
+
+HOOKS
+
+The --no-verify flag skips all project hooks:
+- Pre-commit hooks (before committing working tree changes)
+- Pre-merge hooks (after rebase, before push)
+- Post-merge hooks (after cleanup)
+
+EXAMPLES
+
+Basic merge to main:
+wt merge
+
+Merge without squashing:
+wt merge --no-squash
+
+Keep worktree after merging:
+wt merge --no-remove
+
+Skip all hooks:
+wt merge --no-verify
+Usage: wt merge [OPTIONS] [TARGET]
+
+Options:
+ -C <path>
+ Change working directory
+
+ --no-squash
+ Skip commit squashing
+
+ --no-commit
+ Skip commit, squash, and rebase
+
+ -v, --verbose
+ Show commands and debug info
+
+ --no-remove
+ Keep worktree after merge
+
+ --no-verify
+ Skip all project hooks
+
+ -f, --force
+ Skip approval prompts
+
+ --tracked-only
+ Stage tracked files only
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove.snap b/tests/snapshots/integration__integration_tests__help__help_remove.snap
new file mode 100644
index 000000000..b8840e7bc
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_remove.snap
@@ -0,0 +1,88 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - remove
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_CONFIG_GLOBAL: ""
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt-remove - Remove worktree and branch
+Usage: wt remove [OPTIONS] [WORKTREES]...
+
+Options:
+ -C <path>
+ Change working directory
+
+ --no-delete-branch
+ Keep branch after removal
+
+ -D, --force-delete
+ Delete unmerged branches
+
+ -v, --verbose
+ Show commands and debug info
+
+ --no-background
+ Run removal in foreground
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+OPERATION
+
+Remove Current Worktree (no arguments):
+- Requires clean working tree (no uncommitted changes)
+- If in worktree: removes it and switches to main worktree
+- If in main worktree: switches to default branch (e.g., main)
+- If already on default branch in main: does nothing
+
+Remove Specific Worktree (by name):
+- Requires target worktree has clean working tree
+- Removes specified worktree(s) and associated branches
+- If removing current worktree, switches to main first
+- Can remove multiple worktrees in one command
+
+Remove Multiple Worktrees:
+- When removing multiple, current worktree is removed last
+- Prevents deleting directory you're currently in
+- Each worktree must have clean working tree
+
+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)
+ - Directory deletion happens in background
+ - Git worktree metadata removed in background
+ - Branch deletion in background (uses git branch -d, safe delete)
+ - Logs: .git/wt-logs/{branch}-remove.log
+4. Returns immediately so you can continue working
+ - Use --no-background for foreground removal (blocking)
+
+EXAMPLES
+
+Remove current worktree and branch:
+wt remove
+
+Remove specific worktree and branch:
+wt remove feature-branch
+
+Remove worktree but keep branch:
+wt remove --no-delete-branch feature-branch
+
+Remove multiple worktrees:
+wt remove old-feature another-branch
+
+Remove in foreground (blocking):
+wt remove --no-background feature-branch
+
+Switch to default in main:
+wt remove # (when already in main worktree)
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_root.snap b/tests/snapshots/integration__integration_tests__help__help_root.snap
new file mode 100644
index 000000000..821cc302d
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_root.snap
@@ -0,0 +1,31 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_CONFIG_GLOBAL: ""
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt - Git worktree management
+Usage: wt [OPTIONS] <COMMAND>
+
+Options:
+ -C <path>
+ Change working directory
+
+ -v, --verbose
+ Show commands and debug info
+
+ -h, --help
+ Print help
+
+ -V, --version
+ Print version
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snap
new file mode 100644
index 000000000..2080889ff
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__help__help_switch.snap
@@ -0,0 +1,104 @@
+---
+source: tests/integration_tests/help.rs
+info:
+ program: wt
+ args:
+ - switch
+ - "--help"
+ env:
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "150"
+ GIT_CONFIG_GLOBAL: ""
+---
+success: true
+exit_code: 0
+----- stdout -----
+wt-switch - Switch to a worktree
+Usage: wt switch [OPTIONS] <BRANCH>
+
+Options:
+ -c, --create
+ Create a new branch
+
+ -C <path>
+ Change working directory
+
+ -b, --base <BASE>
+ Base branch (defaults to default branch)
+
+ -v, --verbose
+ Show commands and debug info
+
+ -x, --execute <EXECUTE>
+ Execute command after switching
+
+ -f, --force
+ Skip approval prompts
+
+ --no-verify
+ Skip all project hooks
+
+ -h, --help
+ Print help (see a summary with '-h')
+
+OPERATION
+
+Switching to Existing Worktree:
+- If worktree exists for branch, changes directory via shell integration
+- No hooks run
+- No branch creation
+
+Creating New Worktree (--create):
+1. Creates new branch (defaults to current default branch as base)
+2. Creates worktree in configured location (default:
+../{{ main_worktree }}.{{ branch }})
+3. Runs post-create hooks sequentially (blocking)
+4. Shows success message
+5. Spawns post-start hooks in background (non-blocking)
+6. Changes directory to new worktree via shell integration
+
+HOOKS
+
+post-create (sequential, blocking):
+- Run after worktree creation, before success message
+- Typically: npm install, cargo build, setup tasks
+- Failures block the operation
+- Skip with --no-verify
+
+post-start (parallel, background):
+- Spawned after success message shown
+- Typically: dev servers, file watchers, editors
+- Run in background, failures logged but don't block
+- Logs: .git/wt-logs/{branch}-post-start-{name}.log
+- Skip with --no-verify
+
+EXAMPLES
+
+Switch to existing worktree:
+wt switch feature-branch
+
+Create new worktree from main:
+wt switch --create new-feature
+
+Switch to previous worktree:
+wt switch -
+
+Create from specific base:
+wt switch --create hotfix --base production
+
+Create and run command:
+wt switch --create docs --execute "code ."
+
+Skip hooks during creation:
+wt switch --create temp --no-verify
+
+SHORTCUTS
+
+Use @ for current HEAD, - for previous, ^ for main:
+wt switch @ # Switch to current branch's worktree
+wt switch - # Switch to previous worktree
+wt switch --create new-feature --base=^ # Branch from main (default)
+wt switch --create bugfix --base=@ # Branch from current HEAD
+wt remove @ # Remove current worktree
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__init__init_fish.snap b/tests/snapshots/integration__integration_tests__init__init_fish.snap
index b6afc9860..d10ad90e9 100644
--- a/tests/snapshots/integration__integration_tests__init__init_fish.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_fish.snap
@@ -10,13 +10,16 @@ info:
COLUMNS: "150"
GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_COUNT: "1"
GIT_CONFIG_GLOBAL: /dev/null
+ GIT_CONFIG_KEY_0: advice.mergeConflict
GIT_CONFIG_SYSTEM: /dev/null
+ GIT_CONFIG_VALUE_0: "false"
GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpFcnCHf/test-config.toml
---
success: true
exit_code: 0
@@ -277,9 +280,9 @@ complete -c wt -n "__fish_wt_using_subcommand list" -l format -d 'Output format'
json\t'JSON output'"
complete -c wt -n "__fish_wt_using_subcommand list" -s C -d 'Change working directory' -r -F
complete -c wt -n "__fish_wt_using_subcommand list" -l branches -d 'Include branches without worktrees'
-complete -c wt -n "__fish_wt_using_subcommand list" -l full -d 'Show CI, conflicts, and full diffs'
-complete -c wt -n "__fish_wt_using_subcommand list" -l progressive -d 'Enable progressive rendering (show rows as data arrives)'
-complete -c wt -n "__fish_wt_using_subcommand list" -l no-progressive -d 'Disable progressive rendering (collect all data before displaying)'
+complete -c wt -n "__fish_wt_using_subcommand list" -l full -d 'Show CI, conflicts, diffs'
+complete -c wt -n "__fish_wt_using_subcommand list" -l progressive -d 'Progressive rendering'
+complete -c wt -n "__fish_wt_using_subcommand list" -l no-progressive -d 'Force buffered rendering'
complete -c wt -n "__fish_wt_using_subcommand list" -s v -l verbose -d 'Show commands and debug info'
complete -c wt -n "__fish_wt_using_subcommand list" -s h -l help -d 'Print help (see more with \'--help\')'
complete -c wt -n "__fish_wt_using_subcommand switch" -s b -l base -f -d 'Base branch (defaults to default branch)' -r
diff --git a/tests/snapshots/integration__integration_tests__init__init_zsh.snap b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
index 7421fbec4..a50e9cfba 100644
--- a/tests/snapshots/integration__integration_tests__init__init_zsh.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
@@ -10,13 +10,16 @@ info:
COLUMNS: "150"
GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_CONFIG_COUNT: "1"
GIT_CONFIG_GLOBAL: /dev/null
+ GIT_CONFIG_KEY_0: advice.mergeConflict
GIT_CONFIG_SYSTEM: /dev/null
+ GIT_CONFIG_VALUE_0: "false"
GIT_EDITOR: ""
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpOSL0P3/test-config.toml
---
success: true
exit_code: 0
@@ -414,9 +417,9 @@ _arguments "${_arguments_options[@]}" : \
json\:"JSON output"))' \
'-C+[Change working directory]:path:_files' \
'--branches[Include branches without worktrees]' \
-'--full[Show CI, conflicts, and full diffs]' \
-'(--no-progressive)--progressive[Enable progressive rendering (show rows as data arrives)]' \
-'--no-progressive[Disable progressive rendering (collect all data before displaying)]' \
+'--full[Show CI, conflicts, diffs]' \
+'--progressive[Progressive rendering]' \
+'--no-progressive[Force buffered rendering]' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
'-h[Print help (see more with '\''--help'\'')]' \