Skip to content

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

feat: Improve help output and command readability

Maximilian Roosfae284b15de5
diff --git a/.claude-plugin/skills/worktrunk/reference/README.md b/.claude-plugin/skills/worktrunk/reference/README.md
index b2ef3e1ea..62c8e13e3 100644
--- a/.claude-plugin/skills/worktrunk/reference/README.md
+++ b/.claude-plugin/skills/worktrunk/reference/README.md
@@ -46,8 +46,6 @@ $ wt merge
# Shell back in main
```
-See [`wt merge`](#wt-merge-target) for all options.
-
**See all active worktrees:**
<!-- Output from: tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap -->
@@ -62,8 +60,6 @@ feature-x + ↑ +5 ↑3 ./feature-x 7fd821aa 10 months a
⚪ Showing 3 worktrees, 1 with changes, 2 ahead
```
-See [`wt list`](#wt-list) for all options.
-
## Installation
```bash
@@ -71,8 +67,6 @@ cargo install worktrunk
wt config shell # Sets up shell integration
```
-See [Shell Integration](#shell-integration) for details.
-
## Design Philosophy
Worktrunk is opinionated! It's not designed to be all things to all people. The choices optimize for agent workflows:
@@ -88,6 +82,153 @@ Worktrunk is opinionated! It's not designed to be all things to all people. The
Adopting Worktrunk for a portion of a workflow doesn't require adopting it for
everything — standard `git worktree` commands continue working fine.
+## Automation Features
+
+### LLM-Authored Commit Messages
+
+Worktrunk can invoke an external commands during merge operations to generate
+commit messages. Simon Willison's [llm](https://llm.datasette.io/) tool reads
+the diff and a configurable prompt, then returns a formatted commit message.
+
+Add to `~/.config/worktrunk/config.toml`:
+
+```toml
+[commit-generation]
+command = "llm"
+args = ["-m", "claude-haiku-4-5-20251001"]
+```
+
+Then `wt merge` will generate commit messages automatically:
+
+<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap -->
+
+```bash
+$ wt merge
+🔄 Squashing 3 commits into 1 (3 files, +33)...
+🔄 Generating squash commit message...
+ feat(auth): Implement JWT authentication system
+
+ Add comprehensive JWT token handling including validation, refresh logic,
+ and authentication tests. This establishes the foundation for secure
+ API authentication.
+
+ - Implement token refresh mechanism with expiry handling
+ - Add JWT encoding/decoding with signature verification
+ - Create test suite covering all authentication flows
+✅ Squashed @ a1b2c3d
+```
+
+To set up integration: run `wt config --help` to see the setup guide, or `wt config init` to create an example config file.
+
+<details>
+<summary>Advanced: Custom Prompt Templates</summary>
+
+Worktrunk uses [minijinja
+templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html) for
+commit message prompts. Customize the prompts by setting `template` (inline) or
+`template-file` (external file) in the `[commit-generation]` section. Use
+`squash-template` / `squash-template-file` for squash commits.
+
+See [`config.example.toml`](config.example.toml) for complete template examples
+with all available variables (`git_diff`, `branch`, `recent_commits`, `commits`,
+`target_branch`, `repo`).
+
+</details>
+
+### Project Hooks
+
+Automate common tasks by creating `.config/wt.toml` in the repository root. Install dependencies when creating worktrees, start dev servers automatically, run tests before merging.
+
+```toml
+# Install deps when creating a worktree
+[post-create-command]
+"install" = "uv sync"
+
+# Start dev server automatically
+[post-start-command]
+"dev" = "uv run dev"
+
+# Run tests before merging
+[pre-merge-command]
+"test" = "uv run pytest"
+"lint" = "uv run ruff check"
+```
+
+**Example: Creating a worktree with hooks:**
+
+<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_hooks_post_create.snap -->
+
+```bash
+$ wt switch --create feature-x
+🔄 Running post-create install:
+ uv sync
+✅ Created new worktree for feature-x from main at ../repo.feature-x/
+🔄 Running post-start dev:
+ uv run dev
+
+ Resolved 24 packages in 145ms
+ Installed 24 packages in 1.2s
+```
+
+**Example: Merging with pre-merge hooks:**
+
+<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_hooks_pre_merge.snap -->
+
+```bash
+$ wt merge
+🔄 Squashing 3 commits into 1 (2 files, +45)...
+🔄 Generating squash commit message...
+ feat(api): Add user authentication endpoints
+
+ Implement login and token refresh endpoints with JWT validation.
+ Includes comprehensive test coverage and input validation.
+✅ Squashed @ a1b2c3d
+🔄 Running pre-merge test:
+ uv run pytest
+
+ ============================= test session starts ==============================
+ collected 3 items
+
+ tests/test_auth.py::test_login_success PASSED [ 33%]
+ tests/test_auth.py::test_login_invalid_password PASSED [ 66%]
+ tests/test_auth.py::test_token_validation PASSED [100%]
+
+ ============================== 3 passed in 0.8s ===============================
+
+🔄 Running pre-merge lint:
+ uv run ruff check
+
+ All checks passed!
+
+🔄 Merging 1 commit to main @ a1b2c3d (no rebase needed)
+ * a1b2c3d (HEAD -> feature-auth) feat(api): Add user authentication endpoints
+ api/auth.py | 31 +++++++++++++++++++++++++++++++
+ tests/test_auth.py | 14 ++++++++++++++
+ 2 files changed, 45 insertions(+)
+✅ Merged to main (1 commit, 2 files, +45)
+🔄 Removing worktree & branch...
+✅ Removed worktree & branch for feature-auth, changed directory to ../repo/
+```
+
+<details>
+<summary>All available hooks</summary>
+
+| Hook | When It Runs | Execution | Failure Behavior |
+| ----------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- | ---------------------------- |
+| **post-create-command** | After `git worktree add` completes | Sequential, blocking | Logs warning, continues |
+| **post-start-command** | After post-create completes | Parallel, non-blocking (background processes) | Logs warning, continues |
+| **pre-commit-command** | Before committing changes during `wt merge` (both squash and no-squash modes) | Sequential, blocking, fail-fast | Terminates merge immediately |
+| **pre-merge-command** | After rebase completes during `wt merge` (validates rebased state before push) | Sequential, blocking, fail-fast | Terminates merge immediately |
+| **post-merge-command** | After successful merge and push to target branch, before cleanup | Sequential, blocking | Logs warning, continues |
+
+**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
+
+**Skipping hooks:** `wt switch --no-verify` or `wt merge --no-verify`
+
+**Security:** Commands require approval on first run. Use `--force` to bypass.
+
+</details>
+
## Tips
**Create an alias for an agent** - Shell aliases streamline common workflows. For example, to create a worktree and immediately start Claude:
@@ -111,7 +252,7 @@ Commit Messages](#llm-authored-commit-messages).
**Environment setup with hooks** - Use `post-create-command` (or
`post-start-command` for non-blocking) to run setup for that
-path. See [Project Hooks](#project-hooks) for details:
+path:
```toml
# In .config/wt.toml
@@ -552,153 +693,6 @@ These commands are subject to change:
</details>
-## Automation Features
-
-### LLM-Authored Commit Messages
-
-Worktrunk can invoke an external commands during merge operations to generate
-commit messages. Simon Willison's [llm](https://llm.datasette.io/) tool reads
-the diff and a configurable prompt, then returns a formatted commit message.
-
-Add to `~/.config/worktrunk/config.toml`:
-
-```toml
-[commit-generation]
-command = "llm"
-args = ["-m", "claude-haiku-4-5-20251001"]
-```
-
-Then `wt merge` will generate commit messages automatically:
-
-<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap -->
-
-```bash
-$ wt merge
-🔄 Squashing 3 commits into 1 (3 files, +33)...
-🔄 Generating squash commit message...
- feat(auth): Implement JWT authentication system
-
- Add comprehensive JWT token handling including validation, refresh logic,
- and authentication tests. This establishes the foundation for secure
- API authentication.
-
- - Implement token refresh mechanism with expiry handling
- - Add JWT encoding/decoding with signature verification
- - Create test suite covering all authentication flows
-✅ Squashed @ a1b2c3d
-```
-
-To set up integration: run `wt config --help` to see the setup guide, or `wt config init` to create an example config file.
-
-<details>
-<summary>Advanced: Custom Prompt Templates</summary>
-
-Worktrunk uses [minijinja
-templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html) for
-commit message prompts. Customize the prompts by setting `template` (inline) or
-`template-file` (external file) in the `[commit-generation]` section. Use
-`squash-template` / `squash-template-file` for squash commits.
-
-See [`config.example.toml`](config.example.toml) for complete template examples
-with all available variables (`git_diff`, `branch`, `recent_commits`, `commits`,
-`target_branch`, `repo`).
-
-</details>
-
-### Project Hooks
-
-Automate common tasks by creating `.config/wt.toml` in the repository root. Install dependencies when creating worktrees, start dev servers automatically, run tests before merging.
-
-```toml
-# Install deps when creating a worktree
-[post-create-command]
-"install" = "uv sync"
-
-# Start dev server automatically
-[post-start-command]
-"dev" = "uv run dev"
-
-# Run tests before merging
-[pre-merge-command]
-"test" = "uv run pytest"
-"lint" = "uv run ruff check"
-```
-
-**Example: Creating a worktree with hooks:**
-
-<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_hooks_post_create.snap -->
-
-```bash
-$ wt switch --create feature-x
-🔄 Running post-create install:
- uv sync
-✅ Created new worktree for feature-x from main at ../repo.feature-x/
-🔄 Running post-start dev:
- uv run dev
-
- Resolved 24 packages in 145ms
- Installed 24 packages in 1.2s
-```
-
-**Example: Merging with pre-merge hooks:**
-
-<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_hooks_pre_merge.snap -->
-
-```bash
-$ wt merge
-🔄 Squashing 3 commits into 1 (2 files, +45)...
-🔄 Generating squash commit message...
- feat(api): Add user authentication endpoints
-
- Implement login and token refresh endpoints with JWT validation.
- Includes comprehensive test coverage and input validation.
-✅ Squashed @ a1b2c3d
-🔄 Running pre-merge test:
- uv run pytest
-
- ============================= test session starts ==============================
- collected 3 items
-
- tests/test_auth.py::test_login_success PASSED [ 33%]
- tests/test_auth.py::test_login_invalid_password PASSED [ 66%]
- tests/test_auth.py::test_token_validation PASSED [100%]
-
- ============================== 3 passed in 0.8s ===============================
-
-🔄 Running pre-merge lint:
- uv run ruff check
-
- All checks passed!
-
-🔄 Merging 1 commit to main @ a1b2c3d (no rebase needed)
- * a1b2c3d (HEAD -> feature-auth) feat(api): Add user authentication endpoints
- api/auth.py | 31 +++++++++++++++++++++++++++++++
- tests/test_auth.py | 14 ++++++++++++++
- 2 files changed, 45 insertions(+)
-✅ Merged to main (1 commit, 2 files, +45)
-🔄 Removing worktree & branch...
-✅ Removed worktree & branch for feature-auth, changed directory to ../repo/
-```
-
-<details>
-<summary>All available hooks</summary>
-
-| Hook | When It Runs | Execution | Failure Behavior |
-| ----------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- | ---------------------------- |
-| **post-create-command** | After `git worktree add` completes | Sequential, blocking | Logs warning, continues |
-| **post-start-command** | After post-create completes | Parallel, non-blocking (background processes) | Logs warning, continues |
-| **pre-commit-command** | Before committing changes during `wt merge` (both squash and no-squash modes) | Sequential, blocking, fail-fast | Terminates merge immediately |
-| **pre-merge-command** | After rebase completes during `wt merge` (validates rebased state before push) | Sequential, blocking, fail-fast | Terminates merge immediately |
-| **post-merge-command** | After successful merge and push to target branch, before cleanup | Sequential, blocking | Logs warning, continues |
-
-**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
-
-**Skipping hooks:** `wt switch --no-verify` or `wt merge --no-verify`
-
-**Security:** Commands require approval on first run. Use `--force` to bypass.
-
-</details>
-
## Configuration
```bash
@@ -884,8 +878,8 @@ Run without `--execute` to preview changes first.
Worktrunk executes commands in three contexts:
-1. **[Project hooks](#project-hooks)** (`.config/wt.toml`) - Automation for worktree lifecycle
-2. **[LLM commands](#llm-authored-commit-messages)** (`~/.config/worktrunk/config.toml`) - Commit message generation
+1. **Project hooks** (`.config/wt.toml`) - Automation for worktree lifecycle
+2. **LLM commands** (`~/.config/worktrunk/config.toml`) - Commit message generation
3. **--execute flag** - Commands provided explicitly
Commands from project hooks and LLM configuration require approval on first run. Approved commands are saved to `~/.config/worktrunk/config.toml` under the project's configuration. If a command changes, worktrunk requires new approval.
diff --git a/CLAUDE.md b/CLAUDE.md
index 7dc1fe5d0..fb95e1e9f 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -515,14 +515,14 @@ Use `wt list --format=json` for structured data access. The output is an array o
- `name`: branch name
-### Status Symbols Structure (worktrees only)
+### Status Symbols Structure
-The `status_symbols` object provides structured access to status indicators:
+The `status_symbols` object provides structured access to status indicators (available for both worktrees and branches):
- `has_conflicts`: boolean
- `branch_state`: "" | "≡" (matches main) | "∅" (no commits and clean)
- `git_operation`: "" | "↻" (rebase) | "⋈" (merge)
-- `worktree_attrs`: combination of "◇" (bare), "⊠" (locked), "⚠" (prunable)
+- `worktree_attrs`: "⎇" for branches, or combination of "◇" (bare), "⊠" (locked), "⚠" (prunable) for worktrees
- `main_divergence`: "" | "↑" (ahead) | "↓" (behind) | "↕" (diverged)
- `upstream_divergence`: "" | "⇡" (ahead) | "⇣" (behind) | "⇅" (diverged)
- `working_tree`: combination of "?" (untracked), "!" (modified), "+" (staged), "»" (renamed), "✘" (deleted)
diff --git a/README.md b/README.md
index b2ef3e1ea..62c8e13e3 100644
--- a/README.md
+++ b/README.md
@@ -46,8 +46,6 @@ $ wt merge
# Shell back in main
```
-See [`wt merge`](#wt-merge-target) for all options.
-
**See all active worktrees:**
<!-- Output from: tests/snapshots/integration__integration_tests__list__readme_example_simple_list.snap -->
@@ -62,8 +60,6 @@ feature-x + ↑ +5 ↑3 ./feature-x 7fd821aa 10 months a
⚪ Showing 3 worktrees, 1 with changes, 2 ahead
```
-See [`wt list`](#wt-list) for all options.
-
## Installation
```bash
@@ -71,8 +67,6 @@ cargo install worktrunk
wt config shell # Sets up shell integration
```
-See [Shell Integration](#shell-integration) for details.
-
## Design Philosophy
Worktrunk is opinionated! It's not designed to be all things to all people. The choices optimize for agent workflows:
@@ -88,6 +82,153 @@ Worktrunk is opinionated! It's not designed to be all things to all people. The
Adopting Worktrunk for a portion of a workflow doesn't require adopting it for
everything — standard `git worktree` commands continue working fine.
+## Automation Features
+
+### LLM-Authored Commit Messages
+
+Worktrunk can invoke an external commands during merge operations to generate
+commit messages. Simon Willison's [llm](https://llm.datasette.io/) tool reads
+the diff and a configurable prompt, then returns a formatted commit message.
+
+Add to `~/.config/worktrunk/config.toml`:
+
+```toml
+[commit-generation]
+command = "llm"
+args = ["-m", "claude-haiku-4-5-20251001"]
+```
+
+Then `wt merge` will generate commit messages automatically:
+
+<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap -->
+
+```bash
+$ wt merge
+🔄 Squashing 3 commits into 1 (3 files, +33)...
+🔄 Generating squash commit message...
+ feat(auth): Implement JWT authentication system
+
+ Add comprehensive JWT token handling including validation, refresh logic,
+ and authentication tests. This establishes the foundation for secure
+ API authentication.
+
+ - Implement token refresh mechanism with expiry handling
+ - Add JWT encoding/decoding with signature verification
+ - Create test suite covering all authentication flows
+✅ Squashed @ a1b2c3d
+```
+
+To set up integration: run `wt config --help` to see the setup guide, or `wt config init` to create an example config file.
+
+<details>
+<summary>Advanced: Custom Prompt Templates</summary>
+
+Worktrunk uses [minijinja
+templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html) for
+commit message prompts. Customize the prompts by setting `template` (inline) or
+`template-file` (external file) in the `[commit-generation]` section. Use
+`squash-template` / `squash-template-file` for squash commits.
+
+See [`config.example.toml`](config.example.toml) for complete template examples
+with all available variables (`git_diff`, `branch`, `recent_commits`, `commits`,
+`target_branch`, `repo`).
+
+</details>
+
+### Project Hooks
+
+Automate common tasks by creating `.config/wt.toml` in the repository root. Install dependencies when creating worktrees, start dev servers automatically, run tests before merging.
+
+```toml
+# Install deps when creating a worktree
+[post-create-command]
+"install" = "uv sync"
+
+# Start dev server automatically
+[post-start-command]
+"dev" = "uv run dev"
+
+# Run tests before merging
+[pre-merge-command]
+"test" = "uv run pytest"
+"lint" = "uv run ruff check"
+```
+
+**Example: Creating a worktree with hooks:**
+
+<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_hooks_post_create.snap -->
+
+```bash
+$ wt switch --create feature-x
+🔄 Running post-create install:
+ uv sync
+✅ Created new worktree for feature-x from main at ../repo.feature-x/
+🔄 Running post-start dev:
+ uv run dev
+
+ Resolved 24 packages in 145ms
+ Installed 24 packages in 1.2s
+```
+
+**Example: Merging with pre-merge hooks:**
+
+<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_hooks_pre_merge.snap -->
+
+```bash
+$ wt merge
+🔄 Squashing 3 commits into 1 (2 files, +45)...
+🔄 Generating squash commit message...
+ feat(api): Add user authentication endpoints
+
+ Implement login and token refresh endpoints with JWT validation.
+ Includes comprehensive test coverage and input validation.
+✅ Squashed @ a1b2c3d
+🔄 Running pre-merge test:
+ uv run pytest
+
+ ============================= test session starts ==============================
+ collected 3 items
+
+ tests/test_auth.py::test_login_success PASSED [ 33%]
+ tests/test_auth.py::test_login_invalid_password PASSED [ 66%]
+ tests/test_auth.py::test_token_validation PASSED [100%]
+
+ ============================== 3 passed in 0.8s ===============================
+
+🔄 Running pre-merge lint:
+ uv run ruff check
+
+ All checks passed!
+
+🔄 Merging 1 commit to main @ a1b2c3d (no rebase needed)
+ * a1b2c3d (HEAD -> feature-auth) feat(api): Add user authentication endpoints
+ api/auth.py | 31 +++++++++++++++++++++++++++++++
+ tests/test_auth.py | 14 ++++++++++++++
+ 2 files changed, 45 insertions(+)
+✅ Merged to main (1 commit, 2 files, +45)
+🔄 Removing worktree & branch...
+✅ Removed worktree & branch for feature-auth, changed directory to ../repo/
+```
+
+<details>
+<summary>All available hooks</summary>
+
+| Hook | When It Runs | Execution | Failure Behavior |
+| ----------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- | ---------------------------- |
+| **post-create-command** | After `git worktree add` completes | Sequential, blocking | Logs warning, continues |
+| **post-start-command** | After post-create completes | Parallel, non-blocking (background processes) | Logs warning, continues |
+| **pre-commit-command** | Before committing changes during `wt merge` (both squash and no-squash modes) | Sequential, blocking, fail-fast | Terminates merge immediately |
+| **pre-merge-command** | After rebase completes during `wt merge` (validates rebased state before push) | Sequential, blocking, fail-fast | Terminates merge immediately |
+| **post-merge-command** | After successful merge and push to target branch, before cleanup | Sequential, blocking | Logs warning, continues |
+
+**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
+
+**Skipping hooks:** `wt switch --no-verify` or `wt merge --no-verify`
+
+**Security:** Commands require approval on first run. Use `--force` to bypass.
+
+</details>
+
## Tips
**Create an alias for an agent** - Shell aliases streamline common workflows. For example, to create a worktree and immediately start Claude:
@@ -111,7 +252,7 @@ Commit Messages](#llm-authored-commit-messages).
**Environment setup with hooks** - Use `post-create-command` (or
`post-start-command` for non-blocking) to run setup for that
-path. See [Project Hooks](#project-hooks) for details:
+path:
```toml
# In .config/wt.toml
@@ -552,153 +693,6 @@ These commands are subject to change:
</details>
-## Automation Features
-
-### LLM-Authored Commit Messages
-
-Worktrunk can invoke an external commands during merge operations to generate
-commit messages. Simon Willison's [llm](https://llm.datasette.io/) tool reads
-the diff and a configurable prompt, then returns a formatted commit message.
-
-Add to `~/.config/worktrunk/config.toml`:
-
-```toml
-[commit-generation]
-command = "llm"
-args = ["-m", "claude-haiku-4-5-20251001"]
-```
-
-Then `wt merge` will generate commit messages automatically:
-
-<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_complex.snap -->
-
-```bash
-$ wt merge
-🔄 Squashing 3 commits into 1 (3 files, +33)...
-🔄 Generating squash commit message...
- feat(auth): Implement JWT authentication system
-
- Add comprehensive JWT token handling including validation, refresh logic,
- and authentication tests. This establishes the foundation for secure
- API authentication.
-
- - Implement token refresh mechanism with expiry handling
- - Add JWT encoding/decoding with signature verification
- - Create test suite covering all authentication flows
-✅ Squashed @ a1b2c3d
-```
-
-To set up integration: run `wt config --help` to see the setup guide, or `wt config init` to create an example config file.
-
-<details>
-<summary>Advanced: Custom Prompt Templates</summary>
-
-Worktrunk uses [minijinja
-templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html) for
-commit message prompts. Customize the prompts by setting `template` (inline) or
-`template-file` (external file) in the `[commit-generation]` section. Use
-`squash-template` / `squash-template-file` for squash commits.
-
-See [`config.example.toml`](config.example.toml) for complete template examples
-with all available variables (`git_diff`, `branch`, `recent_commits`, `commits`,
-`target_branch`, `repo`).
-
-</details>
-
-### Project Hooks
-
-Automate common tasks by creating `.config/wt.toml` in the repository root. Install dependencies when creating worktrees, start dev servers automatically, run tests before merging.
-
-```toml
-# Install deps when creating a worktree
-[post-create-command]
-"install" = "uv sync"
-
-# Start dev server automatically
-[post-start-command]
-"dev" = "uv run dev"
-
-# Run tests before merging
-[pre-merge-command]
-"test" = "uv run pytest"
-"lint" = "uv run ruff check"
-```
-
-**Example: Creating a worktree with hooks:**
-
-<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_hooks_post_create.snap -->
-
-```bash
-$ wt switch --create feature-x
-🔄 Running post-create install:
- uv sync
-✅ Created new worktree for feature-x from main at ../repo.feature-x/
-🔄 Running post-start dev:
- uv run dev
-
- Resolved 24 packages in 145ms
- Installed 24 packages in 1.2s
-```
-
-**Example: Merging with pre-merge hooks:**
-
-<!-- Output from: tests/snapshots/integration__integration_tests__merge__readme_example_hooks_pre_merge.snap -->
-
-```bash
-$ wt merge
-🔄 Squashing 3 commits into 1 (2 files, +45)...
-🔄 Generating squash commit message...
- feat(api): Add user authentication endpoints
-
- Implement login and token refresh endpoints with JWT validation.
- Includes comprehensive test coverage and input validation.
-✅ Squashed @ a1b2c3d
-🔄 Running pre-merge test:
- uv run pytest
-
- ============================= test session starts ==============================
- collected 3 items
-
- tests/test_auth.py::test_login_success PASSED [ 33%]
- tests/test_auth.py::test_login_invalid_password PASSED [ 66%]
- tests/test_auth.py::test_token_validation PASSED [100%]
-
- ============================== 3 passed in 0.8s ===============================
-
-🔄 Running pre-merge lint:
- uv run ruff check
-
- All checks passed!
-
-🔄 Merging 1 commit to main @ a1b2c3d (no rebase needed)
- * a1b2c3d (HEAD -> feature-auth) feat(api): Add user authentication endpoints
- api/auth.py | 31 +++++++++++++++++++++++++++++++
- tests/test_auth.py | 14 ++++++++++++++
- 2 files changed, 45 insertions(+)
-✅ Merged to main (1 commit, 2 files, +45)
-🔄 Removing worktree & branch...
-✅ Removed worktree & branch for feature-auth, changed directory to ../repo/
-```
-
-<details>
-<summary>All available hooks</summary>
-
-| Hook | When It Runs | Execution | Failure Behavior |
-| ----------------------- | ------------------------------------------------------------------------------ | --------------------------------------------- | ---------------------------- |
-| **post-create-command** | After `git worktree add` completes | Sequential, blocking | Logs warning, continues |
-| **post-start-command** | After post-create completes | Parallel, non-blocking (background processes) | Logs warning, continues |
-| **pre-commit-command** | Before committing changes during `wt merge` (both squash and no-squash modes) | Sequential, blocking, fail-fast | Terminates merge immediately |
-| **pre-merge-command** | After rebase completes during `wt merge` (validates rebased state before push) | Sequential, blocking, fail-fast | Terminates merge immediately |
-| **post-merge-command** | After successful merge and push to target branch, before cleanup | Sequential, blocking | Logs warning, continues |
-
-**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
-
-**Skipping hooks:** `wt switch --no-verify` or `wt merge --no-verify`
-
-**Security:** Commands require approval on first run. Use `--force` to bypass.
-
-</details>
-
## Configuration
```bash
@@ -884,8 +878,8 @@ Run without `--execute` to preview changes first.
Worktrunk executes commands in three contexts:
-1. **[Project hooks](#project-hooks)** (`.config/wt.toml`) - Automation for worktree lifecycle
-2. **[LLM commands](#llm-authored-commit-messages)** (`~/.config/worktrunk/config.toml`) - Commit message generation
+1. **Project hooks** (`.config/wt.toml`) - Automation for worktree lifecycle
+2. **LLM commands** (`~/.config/worktrunk/config.toml`) - Commit message generation
3. **--execute flag** - Commands provided explicitly
Commands from project hooks and LLM configuration require approval on first run. Approved commands are saved to `~/.config/worktrunk/config.toml` under the project's configuration. If a command changes, worktrunk requires new approval.
diff --git a/src/cli.rs b/src/cli.rs
index 1f5b92258..ab7ddb6f9 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -495,7 +495,7 @@ Use '@' for current HEAD, '-' for previous, '^' for main:
},
/// Remove worktree and branch
- #[command(after_help = r#"BEHAVIOR:
+ #[command(after_help = r#"OPERATION
Remove Current Worktree (no arguments):
- Requires clean working tree (no uncommitted changes)
diff --git a/src/commands/list/collect.rs b/src/commands/list/collect.rs
index 59ce052ab..aac97659f 100644
--- a/src/commands/list/collect.rs
+++ b/src/commands/list/collect.rs
@@ -256,7 +256,7 @@ fn compute_item_status_symbols(item: &mut ListItem, base_branch: Option<&str>) {
has_potential_conflicts: false,
branch_state,
git_operation: GitOperation::None,
- worktree_attrs: String::new(),
+ worktree_attrs: "⎇".to_string(), // Branch indicator
main_divergence,
upstream_divergence,
working_tree: String::new(),
diff --git a/src/commands/list/model.rs b/src/commands/list/model.rs
index b0c71193e..eb94b63b3 100644
--- a/src/commands/list/model.rs
+++ b/src/commands/list/model.rs
@@ -455,7 +455,7 @@ impl PositionMask {
1, // POS_1_MAIN_DIVERGENCE: ↑, ↓, ↕ (1 char)
1, // POS_2_UPSTREAM_DIVERGENCE: ⇡, ⇣, ⇅ (1 char)
1, // POS_0B_BRANCH_STATE: ≡ or ∅ (1 char)
- 2, // POS_0D_WORKTREE_ATTRS: ⊠⚠ (max 2 symbols - bare filtered out)
+ 2, // POS_0D_WORKTREE_ATTRS: ⎇ for branches (1 char), ⊠⚠ for worktrees (max 2)
2, // POS_4_USER_STATUS: single emoji or two chars (allocate 2)
],
};
@@ -472,7 +472,7 @@ impl PositionMask {
/// - Position 0a: Conflicts (=)
/// - Position 0b: Branch state (≡, ∅)
/// - Position 0c: Git operation (↻, ⋈)
-/// - Position 0d: Worktree attributes (⊠, ⚠)
+/// - Position 0d: Item attributes (⎇ for branches, ⊠⚠ for worktrees)
/// - Position 1: Main branch divergence (↑, ↓, ↕)
/// - Position 2: Remote/upstream divergence (⇡, ⇣, ⇅)
/// - Position 3: Working tree symbols (?, !, +, », ✘)
@@ -489,6 +489,7 @@ impl PositionMask {
/// **NOT mutually exclusive (can co-occur):**
/// - = can occur with any other symbol
/// - ⊠, ⚠: Worktree can be locked+prunable (bare is filtered out)
+/// - ⎇: Branch indicator (mutually exclusive with ⊠⚠ as branches can't have worktree attrs)
/// - All working tree symbols (?!+»✘): Can have multiple types of changes
#[derive(Debug, Clone, Default, serde::Serialize)]
pub struct StatusSymbols {
@@ -508,8 +509,8 @@ pub struct StatusSymbols {
/// Position 0c - MUTUALLY EXCLUSIVE (enforced by enum)
pub(crate) git_operation: GitOperation,
- /// Worktree attributes: ⊠, ⚠
- /// Position 0d - NOT mutually exclusive (can combine like "⊠⚠")
+ /// Item type attributes: ⎇ for branches, ⊠⚠ for worktree attrs (locked/prunable)
+ /// Position 0d - NOT mutually exclusive (worktree attrs can combine like "⊠⚠")
pub(crate) worktree_attrs: String,
/// Main branch divergence state
@@ -595,7 +596,12 @@ impl StatusSymbols {
String::new()
};
let worktree_attrs_str = if !self.worktree_attrs.is_empty() {
- format!("{WARNING}{}{WARNING:#}", self.worktree_attrs)
+ // Branch indicator (⎇) is informational (dimmed), worktree attrs (⊠⚠) are warnings (yellow)
+ if self.worktree_attrs == "⎇" {
+ format!("{HINT}{}{HINT:#}", self.worktree_attrs)
+ } else {
+ format!("{WARNING}{}{WARNING:#}", self.worktree_attrs)
+ }
} else {
String::new()
};
diff --git a/tests/snapshots/integration__integration_tests__list__branch_only_with_status.snap b/tests/snapshots/integration__integration_tests__list__branch_only_with_status.snap
index 999bfd71b..497aa4866 100644
--- a/tests/snapshots/integration__integration_tests__list__branch_only_with_status.snap
+++ b/tests/snapshots/integration__integration_tests__list__branch_only_with_status.snap
@@ -16,7 +16,7 @@ info:
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpCgyiR2/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpRLtk2g/test-config.toml
---
success: true
exit_code: 0
@@ -25,6 +25,6 @@ exit_code: 0
----- stderr -----
Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
main . b834638e 10 months ago Initial commit
-branch-only ∅ b834638e 10 months ago Initial commit
+branch-only ∅ ⎇ b834638e 10 months ago Initial commit
⚪ Showing 1 worktrees, 1 branches
diff --git a/tests/snapshots/integration__integration_tests__list__progressive_with_branches.snap b/tests/snapshots/integration__integration_tests__list__progressive_with_branches.snap
index aaf267dc3..8f5389f2a 100644
--- a/tests/snapshots/integration__integration_tests__list__progressive_with_branches.snap
+++ b/tests/snapshots/integration__integration_tests__list__progressive_with_branches.snap
@@ -17,7 +17,7 @@ info:
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpvDVXLQ/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpz3HzJx/test-config.toml
---
success: true
exit_code: 0
@@ -27,7 +27,7 @@ exit_code: 0
Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
main ./test-repo b834638e 10 months ago Initial commit
feature-a ≡ ./feature-a b834638e 10 months ago Initial commit
-orphan-1 ∅ b834638e 10 months ago Initial commit
-orphan-2 ∅ b834638e 10 months ago Initial commit
+orphan-1 ∅ ⎇ b834638e 10 months ago Initial commit
+orphan-2 ∅ ⎇ b834638e 10 months ago Initial commit
⚪ Showing 2 worktrees, 2 branches
diff --git a/tests/snapshots/integration__integration_tests__list__with_branches_flag.snap b/tests/snapshots/integration__integration_tests__list__with_branches_flag.snap
index 12985667b..cf11e28fa 100644
--- a/tests/snapshots/integration__integration_tests__list__with_branches_flag.snap
+++ b/tests/snapshots/integration__integration_tests__list__with_branches_flag.snap
@@ -16,7 +16,7 @@ info:
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmph3KD66/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmppIf8Tj/test-config.toml
---
success: true
exit_code: 0
@@ -26,8 +26,8 @@ exit_code: 0
Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
main ./test-repo b834638e 10 months ago Initial commit
feature-with-worktree ≡ ./feature-with-worktree b834638e 10 months ago Initial commit
-another-branch ∅ b834638e 10 months ago Initial commit
-feature-without-worktree ∅ b834638e 10 months ago Initial commit
-fix-bug ∅ b834638e 10 months ago Initial commit
+another-branch ∅ ⎇ b834638e 10 months ago Initial commit
+feature-without-worktree ∅ ⎇ b834638e 10 months ago Initial commit
+fix-bug ∅ ⎇ b834638e 10 months ago Initial commit
⚪ Showing 2 worktrees, 3 branches
diff --git a/tests/snapshots/integration__integration_tests__list__with_branches_flag_only_branches.snap b/tests/snapshots/integration__integration_tests__list__with_branches_flag_only_branches.snap
index d30db325d..904827629 100644
--- a/tests/snapshots/integration__integration_tests__list__with_branches_flag_only_branches.snap
+++ b/tests/snapshots/integration__integration_tests__list__with_branches_flag_only_branches.snap
@@ -16,7 +16,7 @@ info:
LANG: C
LC_ALL: C
SOURCE_DATE_EPOCH: "1761609600"
- WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmpxsHGTm/test-config.toml
+ WORKTRUNK_CONFIG_PATH: /var/folders/wf/s6ycxvvs4ln8qsdbfx40hnc40000gn/T/.tmplnzpws/test-config.toml
---
success: true
exit_code: 0
@@ -25,8 +25,8 @@ exit_code: 0
----- stderr -----
Branch Status HEAD± main↕ Path Remote⇅ Commit Age Message
main . b834638e 10 months ago Initial commit
-branch-alpha ∅ b834638e 10 months ago Initial commit
-branch-beta ∅ b834638e 10 months ago Initial commit
-branch-gamma ∅ b834638e 10 months ago Initial commit
+branch-alpha ∅ ⎇ b834638e 10 months ago Initial commit
+branch-beta ∅ ⎇ b834638e 10 months ago Initial commit
+branch-gamma ∅ ⎇ b834638e 10 months ago Initial commit
⚪ Showing 1 worktrees, 3 branches