Skip to content

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

docs: Update README with improved clarity

Maximilian Rooscbcd9e59e56b
diff --git a/.claude-plugin/skills/worktrunk/reference/README.md b/.claude-plugin/skills/worktrunk/reference/README.md
index b90f91473..65ddff263 100644
--- a/.claude-plugin/skills/worktrunk/reference/README.md
+++ b/.claude-plugin/skills/worktrunk/reference/README.md
@@ -142,15 +142,11 @@ To set up integration: run `wt config --help` to see the setup guide, or `wt con
<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.
+Customize commit message prompts using [minijinja
+templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html).
-See [`config.example.toml`](dev/config.example.toml) for complete template examples
-with all available variables (`git_diff`, `branch`, `recent_commits`, `commits`,
-`target_branch`, `repo`).
+See [`config.example.toml`](dev/config.example.toml) for template examples with all
+available variables.
</details>
@@ -239,11 +235,9 @@ $ wt merge
| **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.
+See `wt switch --help` and `wt merge --help` for template variables and security details.
</details>
@@ -766,16 +760,21 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
</details>
<details>
-<summary><strong>Beta commands</strong> - Experimental commands for advanced workflows</summary>
+<summary><strong>Step commands</strong> - Building blocks for workflows</summary>
+
+Primitive operations that can be composed into custom workflows:
-These commands are subject to change:
+- `wt step commit` - Commit changes with LLM message
+- `wt step squash [target]` - Squash commits with LLM message
+- `wt step push [target]` - Push changes to local target branch
+- `wt step rebase [target]` - Rebase onto target
+- `wt step post-create` - Run post-create hook
+- `wt step post-start` - Run post-start hook
+- `wt step pre-commit` - Run pre-commit hook
+- `wt step pre-merge` - Run pre-merge hook
+- `wt step post-merge` - Run post-merge hook
-- `wt beta run-hook <hook-type>` - Run a project hook for testing
-- `wt beta commit` - Commit changes with LLM message
-- `wt beta squash [target]` - Squash commits with LLM message
-- `wt beta push [target]` - Push changes to local target branch
-- `wt beta rebase [target]` - Rebase onto target
-- `wt beta select` - Interactive worktree selector (WIP)
+See `wt step --help` for details.
</details>
@@ -790,8 +789,11 @@ wt config --help # Show LLM setup guide
<details>
<summary>Configuration details</summary>
-**Global config** (`~/.config/worktrunk/config.toml`):
+**Global config** (loaded in order of precedence):
+1. `WORKTRUNK_CONFIG_PATH` environment variable
+2. `~/.config/worktrunk/config.toml` (Linux/macOS) or `%APPDATA%\worktrunk\config.toml` (Windows)
+Contents:
- `worktree-path` - Path template for new worktrees
- `[list]` - Default display options for `wt list` (full, branches, remotes)
- `[commit-generation]` - LLM command and prompt templates
diff --git a/README.md b/README.md
index b90f91473..65ddff263 100644
--- a/README.md
+++ b/README.md
@@ -142,15 +142,11 @@ To set up integration: run `wt config --help` to see the setup guide, or `wt con
<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.
+Customize commit message prompts using [minijinja
+templates](https://docs.rs/minijinja/latest/minijinja/syntax/index.html).
-See [`config.example.toml`](dev/config.example.toml) for complete template examples
-with all available variables (`git_diff`, `branch`, `recent_commits`, `commits`,
-`target_branch`, `repo`).
+See [`config.example.toml`](dev/config.example.toml) for template examples with all
+available variables.
</details>
@@ -239,11 +235,9 @@ $ wt merge
| **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.
+See `wt switch --help` and `wt merge --help` for template variables and security details.
</details>
@@ -766,16 +760,21 @@ Docs: https://llm.datasette.io/ | https://github.com/sigoden/aichat
</details>
<details>
-<summary><strong>Beta commands</strong> - Experimental commands for advanced workflows</summary>
+<summary><strong>Step commands</strong> - Building blocks for workflows</summary>
+
+Primitive operations that can be composed into custom workflows:
-These commands are subject to change:
+- `wt step commit` - Commit changes with LLM message
+- `wt step squash [target]` - Squash commits with LLM message
+- `wt step push [target]` - Push changes to local target branch
+- `wt step rebase [target]` - Rebase onto target
+- `wt step post-create` - Run post-create hook
+- `wt step post-start` - Run post-start hook
+- `wt step pre-commit` - Run pre-commit hook
+- `wt step pre-merge` - Run pre-merge hook
+- `wt step post-merge` - Run post-merge hook
-- `wt beta run-hook <hook-type>` - Run a project hook for testing
-- `wt beta commit` - Commit changes with LLM message
-- `wt beta squash [target]` - Squash commits with LLM message
-- `wt beta push [target]` - Push changes to local target branch
-- `wt beta rebase [target]` - Rebase onto target
-- `wt beta select` - Interactive worktree selector (WIP)
+See `wt step --help` for details.
</details>
@@ -790,8 +789,11 @@ wt config --help # Show LLM setup guide
<details>
<summary>Configuration details</summary>
-**Global config** (`~/.config/worktrunk/config.toml`):
+**Global config** (loaded in order of precedence):
+1. `WORKTRUNK_CONFIG_PATH` environment variable
+2. `~/.config/worktrunk/config.toml` (Linux/macOS) or `%APPDATA%\worktrunk\config.toml` (Windows)
+Contents:
- `worktree-path` - Path template for new worktrees
- `[list]` - Default display options for `wt list` (full, branches, remotes)
- `[commit-generation]` - LLM command and prompt templates
diff --git a/src/cli.rs b/src/cli.rs
index a5bbcc8f7..1e1478134 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -255,6 +255,41 @@ pub enum ConfigCommand {
},
/// Manage command approvals
+ #[command(after_long_help = r#"## HOW APPROVALS WORK
+
+Commands from project hooks (.config/wt.toml) and LLM configuration require
+approval on first run. This prevents untrusted projects from running arbitrary
+commands.
+
+**Approval flow:**
+1. Command is shown with expanded template variables
+2. User approves or denies
+3. Approved commands are saved to user config under `[projects."project-id"]`
+
+**When re-approval is required:**
+- Command template changes (not just variable values)
+- Project ID changes (repository moves)
+
+**Bypassing prompts:**
+- `--force` flag on individual commands (e.g., `wt merge --force`)
+- Useful for CI/automation where prompts aren't possible
+
+## EXAMPLES
+
+Pre-approve all commands for current project:
+```
+wt config approvals ask
+```
+
+Clear approvals for current project:
+```
+wt config approvals clear
+```
+
+Clear global approvals:
+```
+wt config approvals clear --global
+```"#)]
Approvals {
#[command(subcommand)]
action: ApprovalsCommand,
@@ -601,6 +636,12 @@ Note: `locked` and `prunable` are top-level fields on worktree objects, not in s
- Logs: `.git/wt-logs/{branch}-post-start-{name}.log`
- Skip with `--no-verify`
+**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`
+
+**Security:** Commands from project hooks require approval on first run.
+Approvals are saved to user config. Use `--force` to bypass prompts.
+See `wt config approvals --help`.
+
## Examples
Switch to existing worktree:
@@ -777,6 +818,12 @@ Fast-forward push to local target branch. Non-fast-forward pushes are rejected.
Worktree and branch are removed. Skip with `--no-remove`.
+**Template variables:** `{{ repo }}`, `{{ branch }}`, `{{ worktree }}`, `{{ repo_root }}`, `{{ target }}`
+
+**Security:** Commands from project hooks require approval on first run.
+Approvals are saved to user config. Use `--force` to bypass prompts.
+See `wt config approvals --help`.
+
## Examples
Basic merge to main:
diff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snap
index a4e6423b3..6bd05b5a3 100644
--- a/tests/snapshots/integration__integration_tests__help__help_merge.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_merge.snap
@@ -92,6 +92,13 @@ Cleanup
Worktree and branch are removed. Skip with --no-remove.
+Template variables: {{ repo }}, {{ branch }}, {{ worktree }}, {{ repo_root }},
+{{ target }}
+
+Security: Commands from project hooks require approval on first run.
+Approvals are saved to user config. Use --force to bypass prompts.
+See wt config approvals --help.
+
Examples
Basic merge to main:
diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snap
index 0cc1f196e..af866c832 100644
--- a/tests/snapshots/integration__integration_tests__help__help_switch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_switch.snap
@@ -85,6 +85,12 @@ post-start (parallel, background)
- Logs: .git/wt-logs/{branch}-post-start-{name}.log
- Skip with --no-verify
+Template variables: {{ repo }}, {{ branch }}, {{ worktree }}, {{ repo_root }}
+
+Security: Commands from project hooks require approval on first run.
+Approvals are saved to user config. Use --force to bypass prompts.
+See wt config approvals --help.
+
Examples
Switch to existing worktree:
diff --git a/tests/snapshots/integration__integration_tests__init__init_fish.snap b/tests/snapshots/integration__integration_tests__init__init_fish.snap
index 1ae8f1dae..4e181c6dd 100644
--- a/tests/snapshots/integration__integration_tests__init__init_fish.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_fish.snap
@@ -235,7 +235,7 @@ complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from approvals" -s C -d 'Change working directory' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from approvals" -l config -d 'User config file path' -r -F
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from approvals" -s v -l verbose -d 'Show commands and debug info'
-complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from approvals" -s h -l help -d 'Print help'
+complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from approvals" -s h -l help -d 'Print help (see more with \'--help\')'
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from approvals" -f -a "ask" -d 'Store approvals in config'
complete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from approvals" -f -a "clear" -d 'Clear approved commands from config'
complete -c wt -n "__fish_wt_using_subcommand step; and not __fish_seen_subcommand_from commit squash push rebase post-create post-start pre-commit pre-merge post-merge" -s C -d 'Change working directory' -r -F
diff --git a/tests/snapshots/integration__integration_tests__init__init_zsh.snap b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
index 773396ded..0c83b23f9 100644
--- a/tests/snapshots/integration__integration_tests__init__init_zsh.snap
+++ b/tests/snapshots/integration__integration_tests__init__init_zsh.snap
@@ -347,8 +347,8 @@ _arguments "${_arguments_options[@]}" : \
'--config=[User config file path]:path:_files' \
'-v[Show commands and debug info]' \
'--verbose[Show commands and debug info]' \
-'-h[Print help]' \
-'--help[Print help]' \
+'-h[Print help (see more with '\''--help'\'')]' \
+'--help[Print help (see more with '\''--help'\'')]' \
":: :_wt__config__approvals_commands" \
"*::: :->approvals" \
&& ret=0