Skip to content

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

Reject empty branch-name CLI arguments at the parse boundary (#3179)

Maximilian Roos0e8887fd940b
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 5c733956e..4dfab084e 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -1090,7 +1090,7 @@ $ wt config state default-branch set main
```"#)]
Set {
/// Branch name to set as default
- #[arg(add = crate::completion::branch_value_completer())]
+ #[arg(add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: String,
},
@@ -1119,7 +1119,7 @@ $ wt config state previous-branch set feature
```"#)]
Set {
/// Branch name to set as previous
- #[arg(add = crate::completion::branch_value_completer())]
+ #[arg(add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: String,
},
@@ -1163,7 +1163,7 @@ $ wt config state ci-status clear && wt config state ci-status get
)]
Get {
/// Target branch (defaults to current)
- #[arg(long, add = crate::completion::branch_value_completer())]
+ #[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
},
@@ -1186,7 +1186,7 @@ $ wt config state ci-status clear --all
```"#)]
Clear {
/// Target branch (defaults to current)
- #[arg(long, add = crate::completion::branch_value_completer(), conflicts_with = "all")]
+ #[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch, conflicts_with = "all")]
branch: Option<String>,
/// Clear all CI status cache
@@ -1212,7 +1212,7 @@ $ wt config state marker get --branch=feature
```"#)]
Get {
/// Target branch (defaults to current)
- #[arg(long, add = crate::completion::branch_value_completer())]
+ #[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
},
@@ -1233,7 +1233,7 @@ $ wt config state marker set "✅ ready" --branch=feature
value: String,
/// Target branch (defaults to current)
- #[arg(long, add = crate::completion::branch_value_completer())]
+ #[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
},
@@ -1256,7 +1256,7 @@ $ wt config state marker clear --all
```"#)]
Clear {
/// Target branch (defaults to current)
- #[arg(long, add = crate::completion::branch_value_completer(), conflicts_with = "all")]
+ #[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch, conflicts_with = "all")]
branch: Option<String>,
/// Clear all markers
@@ -1425,7 +1425,7 @@ $ wt config state vars get env --branch=feature
key: String,
/// Target branch (defaults to current)
- #[arg(long, add = crate::completion::branch_value_completer())]
+ #[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
},
@@ -1443,7 +1443,7 @@ $ wt config state vars list --branch=feature
```"#)]
List {
/// Target branch (defaults to current)
- #[arg(long, add = crate::completion::branch_value_completer())]
+ #[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
/// Output format
@@ -1474,7 +1474,7 @@ $ wt config state vars set env=production --branch=main
assignment: (String, String),
/// Target branch (defaults to current)
- #[arg(long, add = crate::completion::branch_value_completer())]
+ #[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
},
@@ -1505,7 +1505,7 @@ $ wt config state vars clear env --branch=feature
all: bool,
/// Target branch (defaults to current)
- #[arg(long, add = crate::completion::branch_value_completer())]
+ #[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
},
}
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index b51911e5e..f8c387124 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -21,6 +21,21 @@ use std::sync::OnceLock;
use crate::commands::Shell;
+/// Reject an empty (or whitespace-only) branch-name argument.
+///
+/// The `value_parser` for every branch-name argument. Without it, `--branch=`
+/// (or a bare empty positional) flows downstream as an empty branch name and
+/// surfaces as a garbled diagnostic — `Branch has no worktree` /
+/// `wt switch ''`. Rejecting it at the parse boundary yields a clear usage
+/// error instead.
+pub(crate) fn non_empty_branch(s: &str) -> Result<String, String> {
+ if s.trim().is_empty() {
+ Err("branch name cannot be empty".to_string())
+ } else {
+ Ok(s.to_string())
+ }
+}
+
/// Parse KEY=VALUE string for `wt config state vars set`.
///
/// Like `parse_key_val`, but without hyphen→underscore canonicalization.
@@ -331,7 +346,7 @@ pub(crate) struct SwitchArgs {
///
/// Opens interactive picker if omitted.
/// Shortcuts: `^` (default branch), `-` (previous), `@` (current), `pr:{N}` (GitHub PR), `mr:{N}` (GitLab MR)
- #[arg(add = crate::completion::worktree_branch_completer())]
+ #[arg(add = crate::completion::worktree_branch_completer(), value_parser = crate::cli::non_empty_branch)]
pub(crate) branch: Option<String>,
/// Include branches without worktrees
@@ -354,7 +369,7 @@ pub(crate) struct SwitchArgs {
///
/// Defaults to default branch. Supports the same shortcuts as the branch
/// argument: `^`, `@`, `-`, `pr:{N}`, `mr:{N}`.
- #[arg(short = 'b', long, requires = "branch", add = crate::completion::branch_value_completer())]
+ #[arg(short = 'b', long, requires = "branch", add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
pub(crate) base: Option<String>,
/// Command to run after switch
@@ -455,7 +470,7 @@ pub(crate) struct ListArgs {
#[derive(Args)]
pub(crate) struct RemoveArgs {
/// Branch name or worktree path [default: current]
- #[arg(add = crate::completion::local_branches_completer())]
+ #[arg(add = crate::completion::local_branches_completer(), value_parser = crate::cli::non_empty_branch)]
pub(crate) branches: Vec<String>,
/// Keep branch after removal
@@ -501,7 +516,7 @@ pub(crate) struct MergeArgs {
/// Target branch
///
/// Defaults to default branch.
- #[arg(add = crate::completion::branch_value_completer())]
+ #[arg(add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
pub(crate) target: Option<String>,
/// Force commit squashing
@@ -2345,7 +2360,14 @@ This composes with aliases — an alias body can invoke `wt --config-set … <co
#[cfg(test)]
mod tests {
- use super::resolve_version;
+ use super::{non_empty_branch, resolve_version};
+
+ #[test]
+ fn non_empty_branch_rejects_blank() {
+ assert_eq!(non_empty_branch("feature").unwrap(), "feature");
+ assert!(non_empty_branch("").is_err());
+ assert!(non_empty_branch(" ").is_err());
+ }
#[test]
fn resolve_version_uses_git_describe_when_available() {
diff --git a/src/cli/step.rs b/src/cli/step.rs
index dcbcf25d8..3c08fc27e 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -3,7 +3,7 @@ use clap::{Args, Subcommand};
#[derive(Args)]
pub struct CommitArgs {
/// Branch to operate on (defaults to current worktree)
- #[arg(short, long, add = crate::completion::worktree_only_completer())]
+ #[arg(short, long, add = crate::completion::worktree_only_completer(), value_parser = crate::cli::non_empty_branch)]
pub(crate) branch: Option<String>,
#[command(flatten)]
@@ -33,7 +33,7 @@ pub struct SquashArgs {
/// Target branch
///
/// Defaults to default branch.
- #[arg(add = crate::completion::branch_value_completer())]
+ #[arg(add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
pub(crate) target: Option<String>,
#[command(flatten)]
@@ -165,7 +165,7 @@ $ wt step rebase develop # Rebase onto develop
/// Target branch
///
/// Defaults to default branch.
- #[arg(add = crate::completion::branch_value_completer())]
+ #[arg(add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
target: Option<String>,
/// Output format
@@ -193,7 +193,7 @@ Similar to `git push . HEAD:<target>`, but uses `receive.denyCurrentBranch=updat
/// Target branch
///
/// Defaults to default branch.
- #[arg(add = crate::completion::branch_value_completer())]
+ #[arg(add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
target: Option<String>,
/// Create a merge commit (no fast-forward)
@@ -260,11 +260,11 @@ $ GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state defau
/// Target branch
///
/// Defaults to default branch.
- #[arg(add = crate::completion::branch_value_completer())]
+ #[arg(add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
target: Option<String>,
/// Branch to operate on (defaults to current worktree)
- #[arg(short, long, add = crate::completion::worktree_only_completer())]
+ #[arg(short, long, add = crate::completion::worktree_only_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
/// Extra arguments forwarded to `git diff`
@@ -372,13 +372,13 @@ The `.worktreeinclude` pattern is shared with [Claude Code on desktop](https://c
/// Source worktree branch
///
/// Defaults to main worktree.
- #[arg(long, add = crate::completion::worktree_only_completer())]
+ #[arg(long, add = crate::completion::worktree_only_completer(), value_parser = crate::cli::non_empty_branch)]
from: Option<String>,
/// Destination worktree branch
///
/// Defaults to current worktree.
- #[arg(long, add = crate::completion::worktree_only_completer())]
+ #[arg(long, add = crate::completion::worktree_only_completer(), value_parser = crate::cli::non_empty_branch)]
to: Option<String>,
/// Show what would be copied
@@ -562,7 +562,7 @@ The swap uses `rename()` for each entry — fast regardless of entry size, since
/// Branch to promote to main worktree
///
/// Defaults to current branch, or default branch from main worktree.
- #[arg(add = crate::completion::worktree_only_completer())]
+ #[arg(add = crate::completion::worktree_only_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
},
@@ -681,7 +681,7 @@ Note: This command is experimental and may change in future versions.
"#)]
Relocate {
/// Worktrees to relocate (defaults to all mismatched)
- #[arg(add = crate::completion::worktree_only_completer())]
+ #[arg(add = crate::completion::worktree_only_completer(), value_parser = crate::cli::non_empty_branch)]
branches: Vec<String>,
/// Show what would be moved
diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md
index c49728175..92b910ef4 100644
--- a/src/commands/CLAUDE.md
+++ b/src/commands/CLAUDE.md
@@ -84,22 +84,26 @@ wt --source -C /path/to/repo switch
3. Add an `after_long_help` attribute — it is the source of truth for `docs/content/{command}.md`.
4. Run `cargo test --test integration test_docs_are_in_sync`.
-## Shell Completion for CLI Arguments
+## Branch Argument Conventions
-Branch and worktree arguments should include shell completion for better UX. Add completion helpers to CLI definitions:
+Every branch-name argument carries a completer (shell completion) and the
+`non_empty_branch` value parser (rejects `--branch=` at the parse boundary, so
+an empty value surfaces as a clear usage error instead of a garbled
+`Branch has no worktree`):
```rust
/// Target branch (defaults to current)
-#[arg(long, add = crate::completion::branch_value_completer())]
+#[arg(long, add = crate::completion::branch_value_completer(), value_parser = crate::cli::non_empty_branch)]
branch: Option<String>,
```
**Available completers:**
- `branch_value_completer()` - Completes with branch names
- `worktree_branch_completer()` - Completes with branch names, suppresses when --create flag present
+- `worktree_only_completer()` - Completes with branches that have a worktree
- `local_branches_completer()` - Completes with local branch names, excludes remote-only
-**Pattern:** All branch arguments should use `branch_value_completer()` for consistency with commands like `wt merge`, `wt switch --base`, `wt rebase`.
+Pick the completer that fits the argument; `value_parser = crate::cli::non_empty_branch` is the same on all of them.
## CLI Flag Descriptions
diff --git a/tests/integration_tests/step_diff.rs b/tests/integration_tests/step_diff.rs
index e1272bcd6..b54dc82a5 100644
--- a/tests/integration_tests/step_diff.rs
+++ b/tests/integration_tests/step_diff.rs
@@ -175,6 +175,21 @@ fn test_step_diff_branch_no_worktree(repo: TestRepo) {
));
}
+/// `--branch=` (empty value) is rejected at the parse boundary with a clear
+/// usage error, not surfaced as a garbled `Branch has no worktree`.
+#[rstest]
+fn test_step_diff_branch_empty(repo: TestRepo) {
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["diff", "--branch="],
+ None,
+ ));
+}
+
fn git_status(repo: &TestRepo, dir: &Path) -> String {
let output = repo
.git_command()
diff --git a/tests/snapshots/integration__integration_tests__step_diff__step_diff_branch_empty.snap b/tests/snapshots/integration__integration_tests__step_diff__step_diff_branch_empty.snap
new file mode 100644
index 000000000..e7f517f02
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_diff__step_diff_branch_empty.snap
@@ -0,0 +1,52 @@
+---
+source: tests/integration_tests/step_diff.rs
+info:
+ program: wt
+ args:
+ - step
+ - diff
+ - "--branch="
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ 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_TERMINAL_PROMPT: "0"
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 2
+----- stdout -----
+
+----- stderr -----
+error: invalid value '' for '--branch <BRANCH>': branch name cannot be empty
+
+For more information, try '--help'.