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.mdindex 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.mdindex 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.mdindex 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><BRANCH></span>- Branch or worktree name+ Branch nameShortcuts: '^' (default branch), '-' (previous), '@' (current)diff --git a/docs/content/worktrunk.md b/docs/content/worktrunk.mdindex 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.rsindex 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.mdindex 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.rsindex 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.rsindex 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.rsindex 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(), @"[31m✗[39m [31mCannot merge: [1mwt[22m has uncommitted changes[39m@@ -1138,16 +1138,16 @@ mod tests {// Action onlylet 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 onlylet 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 {// Neitherlet 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.rsindex 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.rsindex 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 statelet result =handle_remove_current(!delete_branch, force_delete, force, background)@@ -1393,17 +1393,17 @@ fn main() {// to avoid deleting the directory we're currently inlet 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.rsindex 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.snapsimilarity index 100%rename from tests/integration_tests/snapshots/integration__integration_tests__git_error_display__uncommitted_changes_with_worktree.snaprename to tests/integration_tests/snapshots/integration__integration_tests__git_error_display__uncommitted_changes_with_branch.snapdiff --git a/tests/snapshots/integration__integration_tests__help__help_page_switch.snap b/tests/snapshots/integration__integration_tests__help__help_page_switch.snapindex 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: 0Change 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: [1m[36mwt switch[0m [36m[OPTIONS][0m [36m<BRANCH>[0m [1m[36m[--[1m[32mArguments:[0m[36m<BRANCH>[0m- Branch or worktree name[0m+ Branch name[0m[0mShortcuts: '^' (default branch), '-' (previous), '@' (current)[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_remove_long.snap b/tests/snapshots/integration__integration_tests__help__help_remove_long.snapindex 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: [1m[36mwt remove[0m [36m[OPTIONS][0m [36m[WORKTREES]...+Usage: [1m[36mwt remove[0m [36m[OPTIONS][0m [36m[BRANCHES]...[1m[32mArguments:- [36m[WORKTREES]...- Worktree or branch [default: current]+ [36m[BRANCHES]...+ Branch name [default: current][1m[32mOptions:[1m[36m--no-delete-branchdiff --git a/tests/snapshots/integration__integration_tests__help__help_remove_short.snap b/tests/snapshots/integration__integration_tests__help__help_remove_short.snapindex 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: [1m[36mwt remove[0m [36m[OPTIONS][0m [36m[WORKTREES]...+Usage: [1m[36mwt remove[0m [36m[OPTIONS][0m [36m[BRANCHES]...[1m[32mArguments:- [36m[WORKTREES]...[0m Worktree or branch [default: current]+ [36m[BRANCHES]...[0m Branch name [default: current][1m[32mOptions:[1m[36m--no-delete-branch[0m Keep branch after removaldiff --git a/tests/snapshots/integration__integration_tests__help__help_switch_long.snap b/tests/snapshots/integration__integration_tests__help__help_switch_long.snapindex 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: [1m[36mwt switch[0m [36m[OPTIONS][0m [36m<BRANCH>[0m [1m[36m[--[1m[32mArguments:[36m<BRANCH>- Branch or worktree name+ Branch nameShortcuts: '^' (default branch), '-' (previous), '@' (current)@@ -80,6 +80,8 @@ Usage: [1m[36mwt switch[0m [36m[OPTIONS][0m [36m<BRANCH>[0m [1m[36m[--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.+[32mExamples[2mwt switch feature-auth # Switch to worktreediff --git a/tests/snapshots/integration__integration_tests__help__help_switch_short.snap b/tests/snapshots/integration__integration_tests__help__help_switch_short.snapindex 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 worktreeUsage: [1m[36mwt switch[0m [36m[OPTIONS][0m [36m<BRANCH>[0m [1m[36m[--[0m [36m<EXECUTE_ARGS>...[0m[1m[36m][1m[32mArguments:- [36m<BRANCH>[0m Branch or worktree name+ [36m<BRANCH>[0m Branch name[36m[EXECUTE_ARGS]...[0m Additional arguments for --execute command (after --)[1m[32mOptions: