Skip to content

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.md
index 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 Paths
By default, worktrees live as siblings to the main repo:
diff --git a/src/commands/list/model.rs b/src/commands/list/model.rs
index 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.rs
index 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_content
diff --git a/tests/integration_tests/list.rs b/tests/integration_tests/list.rs
index 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 status
let 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 entry
let 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.snap
new file mode 100644
index 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 -----
+Branch  Status HEAD± main↕ Path Remote↕ Commit  Age  Message
+main  🏠 .  b834638e 10 months ago Initial commit
+branch-only 🌿 b834638e 10 months ago Initial commit
+
+⚪ Showing 1 worktrees, 1 branches
+
+----- 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.snap
index 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: C
LC_ALL: C
SOURCE_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: true
exit_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.snap
index 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: C
LC_ALL: C
SOURCE_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: true
exit_code: 0
----- stdout -----
-Branch Status  HEAD± main↕ Path  Remote↕ Commit  Age  Message
-main  ./test-repo b834638e 10 months ago Initial commit
-emoji  ≡ 🔄 ./emoji  b834638e 10 months ago Initial commit
-multi  ≡ blocked: needs review ./multi  b834638e 10 months ago Initial commit
+Branch Status HEAD± main↕ Path  Remote↕ Commit  Age  Message
+main  ./test-repo b834638e 10 months ago Initial commit
+emoji  ≡🔄 ./emoji  b834638e 10 months ago Initial commit
+multi  ≡👨‍💻 ./multi  b834638e 10 months ago Initial commit
⚪ Showing 3 worktrees
diff --git a/tests/snapshots/integration__integration_tests__list__with_user_status.snap b/tests/snapshots/integration__integration_tests__list__with_user_status.snap
index 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: C
LC_ALL: C
SOURCE_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: true
exit_code: 0
----- stdout -----
-Branch  Status  HEAD± main↕ Path  Remote↕ Commit  Age  Message
-main  ./test-repo  b834638e 10 months ago Initial commit
-clean-no-status  ≡ ./clean-no-status  b834638e 10 months ago Initial commit
-clean-with-status ≡ waiting ./clean-with-status b834638e 10 months ago Initial commit
-dirty-no-status ! +1 -1 ./dirty-no-status b834638e 10 months ago Initial commit
-dirty-with-status ≡? * ./dirty-with-status b834638e 10 months ago Initial commit
+Branch  Status HEAD± main↕ Path  Remote↕ Commit  Age  Message
+main  ./test-repo  b834638e 10 months ago Initial commit
+clean-no-status  ≡ ./clean-no-status  b834638e 10 months ago Initial commit
+clean-with-status ≡⏸️ ./clean-with-status b834638e 10 months ago Initial commit
+dirty-no-status ! +1 -1 ./dirty-no-status b834638e 10 months ago Initial commit
+dirty-with-status ≡?🤖 ./dirty-with-status b834638e 10 months ago Initial commit
⚪ Showing 5 worktrees, 1 with changes