Skip to content

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

Standardize worktree/branch terminology in CLI and docs (#316)

Maximilian Roos9e27a51d151e
diff --git a/README.md b/README.md
index a918553d5..48e4656e7 100644
--- a/README.md
+++ b/README.md
@@ -39,6 +39,9 @@ worktree requires typing the branch name three times: `git worktree add -b feat
## Worktrunk makes git worktrees as easy as branches
+Each worktree has exactly one branch, so Worktrunk uses branch names to address
+worktrees. The path is derived automatically.
+
> Start with the core commands
**Core commands:**
diff --git a/docs/content/remove.md b/docs/content/remove.md
index e3345a3f7..11f9569c7 100644
--- a/docs/content/remove.md
+++ b/docs/content/remove.md
@@ -73,11 +73,11 @@ Removal runs in the background by default (returns immediately). Logs are writte
{% terminal() %}
wt remove - Remove worktree and branch
-Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <span class=c>[WORKTREES]...</span>
+Usage: <b><span class=c>wt remove</span></b> <span class=c>[OPTIONS]</span> <span class=c>[BRANCHES]...</span>
<b><span class=g>Arguments:</span></b>
- <span class=c>[WORKTREES]...</span>
- Worktree or branch [default: current]
+ <span class=c>[BRANCHES]...</span>
+ Branch name [default: current]
<b><span class=g>Options:</span></b>
<b><span class=c>--no-delete-branch</span></b>
diff --git a/docs/content/switch.md b/docs/content/switch.md
index a49394b87..eb3c05987 100644
--- a/docs/content/switch.md
+++ b/docs/content/switch.md
@@ -10,6 +10,8 @@ group = "Commands"
Change directory to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+Worktrees are addressed by branch name — each worktree has exactly one branch, and the path is derived automatically.
+
## Examples
```bash
@@ -71,7 +73,7 @@ Usage: <b><span class=c>wt switch</span></b> <span class=c>[OPTIONS]</span> <spa
<b><span class=g>Arguments:</span></b>
<span class=c>&lt;BRANCH&gt;</span>
- Branch or worktree name
+ Branch name
Shortcuts: &#39;^&#39; (default branch), &#39;-&#39; (previous), &#39;@&#39; (current)
diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.md
index 5e6cf452b..67dde006f 100644
--- a/docs/content/worktrunk.md
+++ b/docs/content/worktrunk.md
@@ -33,6 +33,9 @@ worktree requires typing the branch name three times: `git worktree add -b feat
## Worktrunk makes git worktrees as easy as branches
+Each worktree has exactly one branch, so Worktrunk uses branch names to address
+worktrees. The path is derived automatically.
+
> Start with the core commands
**Core commands:**
diff --git a/src/cli.rs b/src/cli.rs
index 1a7785363..a5c39f00e 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -2137,6 +2137,8 @@ When `main_state == "integrated"`: `"ancestor"` `"trees_match"` `"no_added_chang
#[command(
after_long_help = r#"Change directory to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+Worktrees are addressed by branch name — each worktree has exactly one branch, and the path is derived automatically.
+
## Examples
```console
@@ -2191,7 +2193,7 @@ wt switch --create fix --base=@ # Branch from current HEAD
"#
)]
Switch {
- /// Branch or worktree name
+ /// Branch name
///
/// Shortcuts: '^' (default branch), '-' (previous), '@' (current)
#[arg(add = crate::completion::worktree_branch_completer())]
@@ -2310,9 +2312,9 @@ Removal runs in the background by default (returns immediately). Logs are writte
"#
)]
Remove {
- /// Worktree or branch [default: current]
+ /// Branch name [default: current]
#[arg(add = crate::completion::local_branches_completer())]
- worktrees: Vec<String>,
+ branches: Vec<String>,
/// Keep branch after removal
#[arg(long = "no-delete-branch", action = clap::ArgAction::SetFalse, default_value_t = true)]
diff --git a/src/commands/CLAUDE.md b/src/commands/CLAUDE.md
index 106150872..aefb5aa73 100644
--- a/src/commands/CLAUDE.md
+++ b/src/commands/CLAUDE.md
@@ -89,7 +89,8 @@ branch: Option<String>,
**Available completers:**
- `branch_value_completer()` - Completes with branch names
-- `worktree_branch_completer()` - Completes with worktree paths and branch names
+- `worktree_branch_completer()` - Completes with branch names, suppresses when --create flag present
+- `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`.
diff --git a/src/commands/merge.rs b/src/commands/merge.rs
index e296a5ef7..60b0f054a 100644
--- a/src/commands/merge.rs
+++ b/src/commands/merge.rs
@@ -107,7 +107,7 @@ pub fn handle_merge(opts: MergeOptions<'_>) -> anyhow::Result<()> {
if !commit && repo.is_dirty()? {
return Err(worktrunk::git::GitError::UncommittedChanges {
action: Some("merge with --no-commit".into()),
- worktree: Some(current_branch.clone()),
+ branch: Some(current_branch.clone()),
}
.into());
}
diff --git a/src/completion.rs b/src/completion.rs
index 335d285df..90280e558 100644
--- a/src/completion.rs
+++ b/src/completion.rs
@@ -145,7 +145,8 @@ pub fn branch_value_completer() -> ArgValueCompleter {
})
}
-/// Branch completion for positional arguments that represent worktrees (switch).
+/// Branch completion for positional arguments (switch, select).
+/// Suppresses completions when --create flag is present.
pub fn worktree_branch_completer() -> ArgValueCompleter {
ArgValueCompleter::new(BranchCompleter {
suppress_with_create: true,
diff --git a/src/git/error.rs b/src/git/error.rs
index b7079d037..7f8f19627 100644
--- a/src/git/error.rs
+++ b/src/git/error.rs
@@ -47,8 +47,8 @@ pub enum GitError {
},
UncommittedChanges {
action: Option<String>,
- /// Branch or worktree identifier (for multi-worktree operations)
- worktree: Option<String>,
+ /// Branch name (for multi-worktree operations)
+ branch: Option<String>,
},
BranchAlreadyExists {
branch: String,
@@ -156,16 +156,16 @@ impl std::fmt::Display for GitError {
)
}
- GitError::UncommittedChanges { action, worktree } => {
- let message = match (action, worktree) {
- (Some(action), Some(wt)) => {
- cformat!("Cannot {action}: <bold>{wt}</> has uncommitted changes")
+ GitError::UncommittedChanges { action, branch } => {
+ let message = match (action, branch) {
+ (Some(action), Some(b)) => {
+ cformat!("Cannot {action}: <bold>{b}</> has uncommitted changes")
}
(Some(action), None) => {
cformat!("Cannot {action}: working tree has uncommitted changes")
}
- (None, Some(wt)) => {
- cformat!("<bold>{wt}</> has uncommitted changes")
+ (None, Some(b)) => {
+ cformat!("<bold>{b}</> has uncommitted changes")
}
(None, None) => cformat!("Working tree has uncommitted changes"),
};
@@ -672,7 +672,7 @@ mod tests {
fn snapshot_uncommitted_with_worktree_display() {
let err = GitError::UncommittedChanges {
action: Some("merge".into()),
- worktree: Some("wt".into()),
+ branch: Some("wt".into()),
};
assert_snapshot!(err.to_string(), @"
✗ Cannot merge: wt has uncommitted changes
@@ -1138,16 +1138,16 @@ mod tests {
// Action only
let err = GitError::UncommittedChanges {
action: Some("push".into()),
- worktree: None,
+ branch: None,
};
let display = err.to_string();
assert!(display.contains("Cannot push"));
assert!(display.contains("working tree"));
- // Worktree only
+ // Branch only
let err = GitError::UncommittedChanges {
action: None,
- worktree: Some("feature".into()),
+ branch: Some("feature".into()),
};
let display = err.to_string();
assert!(display.contains("feature"));
@@ -1156,7 +1156,7 @@ mod tests {
// Neither
let err = GitError::UncommittedChanges {
action: None,
- worktree: None,
+ branch: None,
};
let display = err.to_string();
assert!(display.contains("Working tree"));
diff --git a/src/git/repository/mod.rs b/src/git/repository/mod.rs
index 91c258892..33b1ea3c5 100644
--- a/src/git/repository/mod.rs
+++ b/src/git/repository/mod.rs
@@ -591,16 +591,16 @@ impl Repository {
///
/// Returns an error if there are uncommitted changes.
/// - `action` describes what was blocked (e.g., "remove worktree").
- /// - `worktree` identifies which worktree (e.g., branch name) for multi-worktree operations.
+ /// - `branch` identifies which branch for multi-worktree operations.
pub fn ensure_clean_working_tree(
&self,
action: &str,
- worktree: Option<&str>,
+ branch: Option<&str>,
) -> anyhow::Result<()> {
if self.is_dirty()? {
return Err(GitError::UncommittedChanges {
action: Some(action.into()),
- worktree: worktree.map(String::from),
+ branch: branch.map(String::from),
}
.into());
}
diff --git a/src/main.rs b/src/main.rs
index 702d796ec..3c9857c42 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -1324,7 +1324,7 @@ fn main() {
Ok(())
}),
Commands::Remove {
- worktrees,
+ branches,
delete_branch,
force_delete,
background,
@@ -1378,8 +1378,8 @@ fn main() {
false
};
- if worktrees.is_empty() {
- // No worktrees specified, remove current worktree
+ if branches.is_empty() {
+ // No branches specified, remove current worktree
// Uses path-based removal to handle detached HEAD state
let result =
handle_remove_current(!delete_branch, force_delete, force, background)
@@ -1393,17 +1393,17 @@ fn main() {
// to avoid deleting the directory we're currently in
let current_worktree = repo.worktree_root().ok().map(Path::to_path_buf);
- // Partition worktrees into current, others, and branch-only.
+ // Partition branches into current worktree, others, and branch-only.
// Track all errors (resolution + removal) so we can report them and continue.
let mut others = Vec::new();
let mut branch_only = Vec::new();
let mut current: Option<(PathBuf, Option<String>)> = None;
let mut all_errors: Vec<anyhow::Error> = Vec::new();
- for worktree_name in &worktrees {
+ for branch_name in &branches {
match resolve_worktree_arg(
&repo,
- worktree_name,
+ branch_name,
&config,
ResolutionContext::Remove,
) {
diff --git a/tests/integration_tests/git_error_display.rs b/tests/integration_tests/git_error_display.rs
index 937b8b2d8..6320ad982 100644
--- a/tests/integration_tests/git_error_display.rs
+++ b/tests/integration_tests/git_error_display.rs
@@ -99,20 +99,20 @@ fn display_detached_head_no_action() {
fn display_uncommitted_changes() {
let err = GitError::UncommittedChanges {
action: Some("remove worktree".into()),
- worktree: None,
+ branch: None,
};
assert_snapshot!("uncommitted_changes", err.to_string());
}
#[test]
-fn display_uncommitted_changes_with_worktree() {
+fn display_uncommitted_changes_with_branch() {
let err = GitError::UncommittedChanges {
action: Some("remove worktree".into()),
- worktree: Some("feature-branch".into()),
+ branch: Some("feature-branch".into()),
};
- assert_snapshot!("uncommitted_changes_with_worktree", err.to_string());
+ assert_snapshot!("uncommitted_changes_with_branch", err.to_string());
}
#[test]
diff --git a/tests/integration_tests/snapshots/integration__integration_tests__git_error_display__uncommitted_changes_with_worktree.snap b/tests/integration_tests/snapshots/integration__integration_tests__git_error_display__uncommitted_changes_with_branch.snap
similarity index 100%
rename from tests/integration_tests/snapshots/integration__integration_tests__git_error_display__uncommitted_changes_with_worktree.snap
rename to tests/integration_tests/snapshots/integration__integration_tests__git_error_display__uncommitted_changes_with_branch.snap
diff --git a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
index 8205d2bbe..537f18fc4 100644
--- a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_page_switch.snap
@@ -20,6 +20,8 @@ exit_code: 0
Change directory to a worktree, creating one if needed. Creating a worktree runs [hooks](@/hook.md).
+Worktrees are addressed by branch name — each worktree has exactly one branch, and the path is derived automatically.
+
## Examples
```bash
@@ -81,7 +83,7 @@ Usage: wt switch [OPTIONS] <BRANCH> [--
Arguments:
<BRANCH>
- Branch or worktree name
+ Branch name

Shortcuts: '^' (default branch), '-' (previous), '@' (current)
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
index cc85cce84..c1c06ea8f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_long.snap
@@ -20,11 +20,11 @@ exit_code: 0
----- stderr -----
wt remove - Remove worktree and branch
-Usage: wt remove [OPTIONS] [WORKTREES]...
+Usage: wt remove [OPTIONS] [BRANCHES]...
Arguments:
- [WORKTREES]...
- Worktree or branch [default: current]
+ [BRANCHES]...
+ Branch name [default: current]
Options:
--no-delete-branch
diff --git a/tests/snapshots/integration__integration_tests__help__help_remove_short.snap b/tests/snapshots/integration__integration_tests__help__help_remove_short.snap
index eaf1df207..5a4002023 100644
--- a/tests/snapshots/integration__integration_tests__help__help_remove_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_remove_short.snap
@@ -20,10 +20,10 @@ exit_code: 0
----- stderr -----
wt remove - Remove worktree and branch
-Usage: wt remove [OPTIONS] [WORKTREES]...
+Usage: wt remove [OPTIONS] [BRANCHES]...
Arguments:
- [WORKTREES]... Worktree or branch [default: current]
+ [BRANCHES]... Branch name [default: current]
Options:
--no-delete-branch Keep branch after removal
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 7472cade3..06bd2fa9a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_long.snap
@@ -24,7 +24,7 @@ Usage: wt switch [OPTIONS] <BRANCH> [--
Arguments:
<BRANCH>
- Branch or worktree name
+ Branch name
Shortcuts: '^' (default branch), '-' (previous), '@' (current)
@@ -80,6 +80,8 @@ Usage: wt switch [OPTIONS] <BRANCH> [--
Change directory to a worktree, creating one if needed. Creating a worktree runs hooks.
+Worktrees are addressed by branch name — each worktree has exactly one branch, and the path is derived automatically.
+
Examples
wt switch feature-auth # Switch to worktree
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 b69cdfae2..59d450d2a 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch_short.snap
@@ -23,7 +23,7 @@ wt switch - Switch to a worktree
Usage: wt switch [OPTIONS] <BRANCH> [-- <EXECUTE_ARGS>...]
Arguments:
- <BRANCH> Branch or worktree name
+ <BRANCH> Branch name
[EXECUTE_ARGS]... Additional arguments for --execute command (after --)
Options: