Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows
feat: Add custom worktree status markers and fix rustdoc warnings
Maximilian Roos3269c968dd6f
diff --git a/README.md b/README.mdindex 40bbc45fe..e2559dc00 100644--- a/README.md+++ b/README.md@@ -388,6 +388,141 @@ test result: ok. 18 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; fin</details>+### Custom Worktree Status++Add emoji status markers to worktrees that appear in `wt list`. Perfect for tracking work-in-progress states, CI status, or team coordination.++**Set status manually:**++```bash+# Set an emoji status for a branch (works everywhere)+git config worktrunk.status.feature-x "🚧"++# Clear the status+git config --unset worktrunk.status.feature-x+```++**Status appears in the Status column:**++```+Branch Status Working ± Main ↕ Path+feature-a ≡↓!🚧 ↓2 ./feature-a/+feature-b ↑!✅ +2 -1 ↑1 ./feature-b/+feature-c 🤖 ./feature-c/+```++The custom emoji appears directly after the git status symbols.++<details>+<summary><b>Automation with Claude Code Hooks</b></summary>++Claude Code can automatically set/clear emoji status when coding sessions start and end. This shows which branches have active AI sessions.++Add to `~/.claude/settings.json`:++```json+{+ "hooks": {+ "UserPromptSubmit": [+ {+ "hooks": [+ {+ "type": "command",+ "command": "git branch --show-current 2>/dev/null | xargs -I {} git config worktrunk.status.{} 🤖"+ }+ ]+ }+ ],+ "Stop": [+ {+ "matcher": "",+ "hooks": [+ {+ "type": "command",+ "command": "git branch --show-current 2>/dev/null | xargs -I {} git config --unset worktrunk.status.{} 2>/dev/null || true"+ }+ ]+ }+ ]+ }+}+```++Now when you use Claude:+- Sets status to `🤖` for the current branch when you submit a prompt+- Clears the status when the session stops++**Status from other terminal:**++```bash+$ wt list+Branch Status Working ± Path+main ./myapp/+feature-x ↑!🤖 +5 -2 ./myapp.feature-x/+```++**How it works:**++- Status is stored as `worktrunk.status.<branch>` in `.git/config`+- Each branch can have its own status emoji+- The hooks automatically detect the current branch and set/clear its status+- Status is shared across all worktrees on the same branch (by design)+- Works with any git repository, no special configuration needed++<details>+<summary><b>Alternative: Per-Worktree Status (Advanced)</b></summary>++For true per-worktree isolation (different status for multiple worktrees on the same branch), use worktree-specific config:++**One-time setup (enables per-worktree config for the repo):**+```bash+git config extensions.worktreeConfig true+```++**Set status from within a worktree:**+```bash+# From within the worktree+git config --worktree worktrunk.status "🚧"++# Clear status+git config --worktree --unset worktrunk.status+```++**Claude Code hooks for per-worktree:**+```json+{+ "hooks": {+ "UserPromptSubmit": [+ {+ "hooks": [+ {+ "type": "command",+ "command": "git rev-parse --is-inside-work-tree >/dev/null 2>&1 && git config extensions.worktreeConfig true 2>/dev/null; git config --worktree worktrunk.status 🤖 2>/dev/null || true"+ }+ ]+ }+ ],+ "Stop": [+ {+ "matcher": "",+ "hooks": [+ {+ "type": "command",+ "command": "git config --worktree --unset worktrunk.status 2>/dev/null || true"+ }+ ]+ }+ ]+ }+}+```++**Priority:** Worktree-specific config takes precedence over branch-keyed config when both exist.++</details>++</details>+### Worktree PathsBy default, worktrees live as siblings to the main repo:diff --git a/src/commands/list/model.rs b/src/commands/list/model.rsindex 15a40f59f..01b648728 100644--- a/src/commands/list/model.rs+++ b/src/commands/list/model.rs@@ -68,6 +68,9 @@ pub struct BranchInfo {pub upstream: UpstreamStatus,pub pr_status: Option<PrStatus>,pub has_conflicts: bool,+ /// User-defined status from `worktrunk.status.<branch>` git config+ #[serde(skip_serializing_if = "Option::is_none")]+ pub user_status: Option<String>,// Display fields for json-pretty format (with ANSI colors)#[serde(flatten)]@@ -258,6 +261,20 @@ impl ListItem {ListItem::Branch(info) => info.pr_status.as_ref(),}}++ /// Get combined status (git symbols + user status)+ /// For worktrees: uses WorktreeInfo.combined_status()+ /// For branches: returns user status (branches have no git status symbols)+ pub fn combined_status(&self) -> String {+ match self {+ ListItem::Worktree(info) => info.combined_status(),+ ListItem::Branch(info) => {+ // Branch-only entries show just the user status (no git symbols)+ // If no user status, show "·" to indicate "branch without worktree"+ info.user_status.clone().unwrap_or_else(|| "·".to_string())+ }+ }+ }}impl BranchInfo {@@ -293,6 +310,9 @@ impl BranchInfo {false};+ // Read user-defined status from git config (branch-keyed only, no worktree)+ let user_status = read_branch_keyed_status(repo, branch);+Ok(BranchInfo {name: branch.to_string(),head,@@ -302,19 +322,39 @@ impl BranchInfo {upstream,pr_status,has_conflicts,+ user_status,display: DisplayFields::default(),})}}-/// Read user-defined status from worktrunk.status git config-fn read_user_status(repo: &Repository) -> Option<String> {- repo.run_command(&["config", "--worktree", "--get", "worktrunk.status"])+/// Read user-defined status from branch-keyed config only (`worktrunk.status.<branch>`)+/// Used for branch-only entries that don't have a worktree+fn read_branch_keyed_status(repo: &Repository, branch: &str) -> Option<String> {+ let config_key = format!("worktrunk.status.{}", branch);+ repo.run_command(&["config", "--get", &config_key]).ok().map(|output| output.trim().to_string()).filter(|s| !s.is_empty())}+/// Read user-defined status from git config+/// Tries worktree-specific config first (`worktrunk.status`), then falls back to branch-keyed (`worktrunk.status.<branch>`)+/// Used for worktree entries+fn read_user_status(repo: &Repository, branch: Option<&str>) -> Option<String> {+ // Try worktree-specific config first (requires extensions.worktreeConfig)+ if let Ok(output) = repo.run_command(&["config", "--worktree", "--get", "worktrunk.status"]) {+ let status = output.trim().to_string();+ if !status.is_empty() {+ return Some(status);+ }+ }++ // Fall back to branch-keyed config (works everywhere)+ let branch = branch?;+ read_branch_keyed_status(repo, branch)+}+/// Git status information parsed from `git status --porcelain`// TODO: Consider using a struct with bool fields instead of String for symbols// (has_untracked, has_modified, has_staged, has_renamed, has_deleted, has_conflicts,@@ -574,8 +614,8 @@ impl WorktreeInfo {symbols.insert_str(insert_pos, &state_symbols);- // Read user-defined status from git config- let user_status = read_user_status(&wt_repo);+ // Read user-defined status from git config (worktree-specific or branch-keyed)+ let user_status = read_user_status(&wt_repo, wt.branch.as_deref());Ok(WorktreeInfo {worktree: wt.clone(),@@ -597,11 +637,11 @@ impl WorktreeInfo {}/// Combine git status symbols and user-defined status- /// Returns the combined string with a space separator if both are present+ /// Returns the combined string (no separator - tools can add spaces if needed)pub fn combined_status(&self) -> String {if !self.status_symbols.is_empty() {if let Some(ref user_status) = self.user_status {- format!("{} {}", self.status_symbols, user_status)+ format!("{}{}", self.status_symbols, user_status)} else {self.status_symbols.clone()}diff --git a/src/commands/list/render.rs b/src/commands/list/render.rsindex 05914759f..0d9036785 100644--- a/src/commands/list/render.rs+++ b/src/commands/list/render.rs@@ -309,11 +309,7 @@ pub fn format_list_item_line(}(ColumnKind::Status, _) => {// Combine git status symbols + user-defined status from worktrunk.status- let status_content = if let Some(info) = worktree_info {- info.combined_status()- } else {- "·".to_string()- };+ let status_content = item.combined_status();let status_text = if is_last {status_contentdiff --git a/tests/integration_tests/list.rs b/tests/integration_tests/list.rsindex 9e96ec0c9..98973de82 100644--- a/tests/integration_tests/list.rs+++ b/tests/integration_tests/list.rs@@ -619,40 +619,24 @@ fn test_list_with_user_status() {repo.commit("Initial commit");// Worktree with user status only (no git changes)- let clean_wt = repo.add_worktree("clean-with-status", "clean-with-status");+ repo.add_worktree("clean-with-status", "clean-with-status");- // Enable worktree config+ // Set user status (emoji only, branch-keyed)let mut cmd = Command::new("git");repo.configure_git_cmd(&mut cmd);- cmd.args(["config", "extensions.worktreeConfig", "true"])- .current_dir(&clean_wt)- .output()- .expect("Failed to enable worktree config");-- // Set user status- let mut cmd = Command::new("git");- repo.configure_git_cmd(&mut cmd);- cmd.args(["config", "--worktree", "worktrunk.status", "waiting"])- .current_dir(&clean_wt)+ cmd.args(["config", "worktrunk.status.clean-with-status", "⏸️"])+ .current_dir(repo.root_path()).output().expect("Failed to set user status");// Worktree with both git status and user statuslet dirty_wt = repo.add_worktree("dirty-with-status", "dirty-with-status");- // Enable worktree config+ // Set user status (emoji only, branch-keyed)let mut cmd = Command::new("git");repo.configure_git_cmd(&mut cmd);- cmd.args(["config", "extensions.worktreeConfig", "true"])- .current_dir(&dirty_wt)- .output()- .expect("Failed to enable worktree config");-- // Set user status- let mut cmd = Command::new("git");- repo.configure_git_cmd(&mut cmd);- cmd.args(["config", "--worktree", "worktrunk.status", "*"])- .current_dir(&dirty_wt)+ cmd.args(["config", "worktrunk.status.dirty-with-status", "🤖"])+ .current_dir(repo.root_path()).output().expect("Failed to set user status");@@ -674,22 +658,14 @@ fn test_list_json_with_user_status() {let mut repo = TestRepo::new();repo.commit("Initial commit");- // Worktree with user status- let with_status_wt = repo.add_worktree("with-status", "with-status");+ // Worktree with user status (emoji only)+ repo.add_worktree("with-status", "with-status");- // Enable worktree config+ // Set user status (branch-keyed)let mut cmd = Command::new("git");repo.configure_git_cmd(&mut cmd);- cmd.args(["config", "extensions.worktreeConfig", "true"])- .current_dir(&with_status_wt)- .output()- .expect("Failed to enable worktree config");-- // Set user status- let mut cmd = Command::new("git");- repo.configure_git_cmd(&mut cmd);- cmd.args(["config", "--worktree", "worktrunk.status", "processing..."])- .current_dir(&with_status_wt)+ cmd.args(["config", "worktrunk.status.with-status", "🔧"])+ .current_dir(repo.root_path()).output().expect("Failed to set user status");@@ -700,48 +676,71 @@ fn test_list_json_with_user_status() {}#[test]-fn test_list_user_status_with_special_characters() {- let mut repo = TestRepo::new();+fn test_list_branch_only_ignores_main_worktree_status() {+ // Regression test for bug where branch-only entries incorrectly inherited+ // main worktree's worktree-specific status+ let repo = TestRepo::new();repo.commit("Initial commit");- // Test with emoji- let emoji_wt = repo.add_worktree("emoji", "emoji");-+ // Set worktree-specific status on main worktree (requires extensions.worktreeConfig)let mut cmd = Command::new("git");repo.configure_git_cmd(&mut cmd);cmd.args(["config", "extensions.worktreeConfig", "true"])- .current_dir(&emoji_wt)+ .current_dir(repo.root_path()).output()- .expect("Failed to enable worktree config");+ .expect("Failed to enable worktreeConfig");let mut cmd = Command::new("git");repo.configure_git_cmd(&mut cmd);- cmd.args(["config", "--worktree", "worktrunk.status", "🔄"])- .current_dir(&emoji_wt)+ cmd.args(["config", "--worktree", "worktrunk.status", "🏠"])+ .current_dir(repo.root_path()).output()- .expect("Failed to set user status");+ .expect("Failed to set main worktree status");- // Test with multiple characters- let multi_wt = repo.add_worktree("multi", "multi");+ // Create a branch-only entry (no worktree)+ let mut cmd = Command::new("git");+ repo.configure_git_cmd(&mut cmd);+ cmd.args(["branch", "branch-only"])+ .current_dir(repo.root_path())+ .output()+ .expect("Failed to create branch");+ // Set branch-keyed status for the branch-only entrylet mut cmd = Command::new("git");repo.configure_git_cmd(&mut cmd);- cmd.args(["config", "extensions.worktreeConfig", "true"])- .current_dir(&multi_wt)+ cmd.args(["config", "worktrunk.status.branch-only", "🌿"])+ .current_dir(repo.root_path()).output()- .expect("Failed to enable worktree config");+ .expect("Failed to set branch status");++ // Use --branches flag to show branch-only entries+ snapshot_list_with_branches("branch_only_ignores_main_worktree_status", &repo);+}++#[test]+fn test_list_user_status_with_special_characters() {+ let mut repo = TestRepo::new();+ repo.commit("Initial commit");++ // Test with single emoji+ repo.add_worktree("emoji", "emoji");++ let mut cmd = Command::new("git");+ repo.configure_git_cmd(&mut cmd);+ cmd.args(["config", "worktrunk.status.emoji", "🔄"])+ .current_dir(repo.root_path())+ .output()+ .expect("Failed to set user status");++ // Test with compound emoji (multi-codepoint)+ repo.add_worktree("multi", "multi");let mut cmd = Command::new("git");repo.configure_git_cmd(&mut cmd);- cmd.args([- "config",- "--worktree",- "worktrunk.status",- "blocked: needs review",- ])- .current_dir(&multi_wt)- .output()- .expect("Failed to set user status");+ cmd.args(["config", "worktrunk.status.multi", "👨💻"])+ .current_dir(repo.root_path())+ .output()+ .expect("Failed to set user status");snapshot_list("user_status_special_chars", &repo);}diff --git a/tests/snapshots/integration__integration_tests__list__branch_only_ignores_main_worktree_status.snap b/tests/snapshots/integration__integration_tests__list__branch_only_ignores_main_worktree_status.snapnew file mode 100644index 000000000..8761debf4--- /dev/null+++ b/tests/snapshots/integration__integration_tests__list__branch_only_ignores_main_worktree_status.snap@@ -0,0 +1,30 @@+---+source: tests/integration_tests/list.rs+info:+ program: wt+ args:+ - list+ - "--branches"+ env:+ CLICOLOR_FORCE: "1"+ COLUMNS: "150"+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"+ 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/.tmpm2HhcU/test-config.toml+---+success: true+exit_code: 0+----- stdout -----+[1mBranch [0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mPath[0m [1mRemote↕[0m [1mCommit [0m [1mAge [0m [1mMessage[0m+[1m[35mmain [0m 🏠 [1m[35m. [0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+[2mbranch-only[0m 🌿 [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m++⚪ [2mShowing 1 worktrees, 1 branches[0m++----- stderr -----diff --git a/tests/snapshots/integration__integration_tests__list__json_with_user_status.snap b/tests/snapshots/integration__integration_tests__list__json_with_user_status.snapindex 0c01a4e91..45be8aac4 100644--- a/tests/snapshots/integration__integration_tests__list__json_with_user_status.snap+++ b/tests/snapshots/integration__integration_tests__list__json_with_user_status.snap@@ -16,7 +16,7 @@ info:LANG: CLC_ALL: CSOURCE_DATE_EPOCH: "1761609600"- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpaI32iL/test-config.toml+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpoMhttK/test-config.toml---success: trueexit_code: 0@@ -93,7 +93,7 @@ exit_code: 0"pr_status": null,"has_conflicts": false,"status_symbols": "≡",- "user_status": "processing..."+ "user_status": "🔧"},{"type": "worktree",diff --git a/tests/snapshots/integration__integration_tests__list__user_status_special_chars.snap b/tests/snapshots/integration__integration_tests__list__user_status_special_chars.snapindex 86e96d7af..021eadac1 100644--- a/tests/snapshots/integration__integration_tests__list__user_status_special_chars.snap+++ b/tests/snapshots/integration__integration_tests__list__user_status_special_chars.snap@@ -15,15 +15,15 @@ info:LANG: CLC_ALL: CSOURCE_DATE_EPOCH: "1761609600"- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpb9KQOD/test-config.toml+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpcgru4Y/test-config.toml---success: trueexit_code: 0----- stdout ------[1mBranch[0m [1mStatus [0m [1mHEAD±[0m [1mmain↕[0m [1mPath [0m [1mRemote↕[0m [1mCommit [0m [1mAge [0m [1mMessage[0m-[1m[35mmain [0m [1m[35m./test-repo[0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m-[2memoji [0m ≡ 🔄 [2m./emoji [0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m-[2mmulti [0m ≡ blocked: needs review [2m./multi [0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+[1mBranch[0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mPath [0m [1mRemote↕[0m [1mCommit [0m [1mAge [0m [1mMessage[0m+[1m[35mmain [0m [1m[35m./test-repo[0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+[2memoji [0m ≡🔄 [2m./emoji [0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+[2mmulti [0m ≡👨💻 [2m./multi [0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m⚪ [2mShowing 3 worktrees[0mdiff --git a/tests/snapshots/integration__integration_tests__list__with_user_status.snap b/tests/snapshots/integration__integration_tests__list__with_user_status.snapindex 0f9a32cb1..c290b77fe 100644--- a/tests/snapshots/integration__integration_tests__list__with_user_status.snap+++ b/tests/snapshots/integration__integration_tests__list__with_user_status.snap@@ -15,17 +15,17 @@ info:LANG: CLC_ALL: CSOURCE_DATE_EPOCH: "1761609600"- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmp8yDaqT/test-config.toml+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpucPrNK/test-config.toml---success: trueexit_code: 0----- stdout ------[1mBranch [0m [1mStatus [0m [1mHEAD±[0m [1mmain↕[0m [1mPath [0m [1mRemote↕[0m [1mCommit [0m [1mAge [0m [1mMessage[0m-[1m[35mmain [0m [1m[35m./test-repo [0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m-[2mclean-no-status [0m ≡ [2m./clean-no-status [0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m-[2mclean-with-status[0m ≡ waiting [2m./clean-with-status[0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m-dirty-no-status ! [32m+1[0m [31m-1[0m ./dirty-no-status [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m-[2mdirty-with-status[0m ≡? * [2m./dirty-with-status[0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+[1mBranch [0m [1mStatus[0m [1mHEAD±[0m [1mmain↕[0m [1mPath [0m [1mRemote↕[0m [1mCommit [0m [1mAge [0m [1mMessage[0m+[1m[35mmain [0m [1m[35m./test-repo [0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+[2mclean-no-status [0m ≡ [2m./clean-no-status [0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+[2mclean-with-status[0m ≡⏸️ [2m./clean-with-status[0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+dirty-no-status ! [32m+1[0m [31m-1[0m ./dirty-no-status [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m+[2mdirty-with-status[0m ≡?🤖 [2m./dirty-with-status[0m [2mb834638e[0m [2m10 months ago[0m [2mInitial commit[0m⚪ [2mShowing 5 worktrees, 1 with changes[0m