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.mdindex 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 templatesdiff --git a/README.md b/README.mdindex 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 templatesdiff --git a/src/cli.rs b/src/cli.rsindex 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`.+## ExamplesSwitch 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`.+## ExamplesBasic merge to main:diff --git a/tests/snapshots/integration__integration_tests__help__help_merge.snap b/tests/snapshots/integration__integration_tests__help__help_merge.snapindex 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 @@ CleanupWorktree 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.+[38;5;10mExamples[39mBasic merge to main:diff --git a/tests/snapshots/integration__integration_tests__help__help_switch.snap b/tests/snapshots/integration__integration_tests__help__help_switch.snapindex 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.+[38;5;10mExamples[39mSwitch to existing worktree:diff --git a/tests/snapshots/integration__integration_tests__init__init_fish.snap b/tests/snapshots/integration__integration_tests__init__init_fish.snapindex 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_subcommandcomplete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from approvals" -s C -d 'Change working directory' -r -Fcomplete -c wt -n "__fish_wt_using_subcommand config; and __fish_seen_subcommand_from approvals" -l config -d 'User config file path' -r -Fcomplete -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 -Fdiff --git a/tests/snapshots/integration__integration_tests__init__init_zsh.snap b/tests/snapshots/integration__integration_tests__init__init_zsh.snapindex 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