Skip to content

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

Simplify documentation and CLI help text

Maximilian Roos5e1320798792
diff --git a/.claude-plugin/skills/worktrunk/reference/config.md b/.claude-plugin/skills/worktrunk/reference/config.md
index 923d24633..ba9ebbe3c 100644
--- a/.claude-plugin/skills/worktrunk/reference/config.md
+++ b/.claude-plugin/skills/worktrunk/reference/config.md
@@ -744,6 +744,14 @@ Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span
## wt config state default-branch
+Useful in scripts to avoid hardcoding `main` or `master`:
+
+```bash
+git rebase $(wt config state default-branch)
+```
+
+Without a subcommand, runs `get`. Use `set` to override, `get --refresh` to re-detect, or `clear` to reset.
+
### Detection
Worktrunk detects the default branch automatically:
@@ -761,18 +769,6 @@ The local inference fallback uses these heuristics in order:
- Checks `git config init.defaultBranch`
- Looks for common names: main, master, develop, trunk
-### When to use
-
-Most users never need this command — default branch detection is automatic.
-Use it to:
-
-- **Debug** — See what worktrunk thinks the default branch is
-- **Override** — Set a non-standard default branch with `set`
-- **Refresh** — Force re-query with `get --refresh` after remote changes
-- **Clear** — Remove cached value with `clear`
-
-Without a subcommand, runs `get`. For `--refresh`, use `get --refresh`.
-
### Command reference
wt config state default-branch - Default branch setting
diff --git a/.claude-plugin/skills/worktrunk/reference/hook.md b/.claude-plugin/skills/worktrunk/reference/hook.md
index 77359251c..7650630cf 100644
--- a/.claude-plugin/skills/worktrunk/reference/hook.md
+++ b/.claude-plugin/skills/worktrunk/reference/hook.md
@@ -486,23 +486,7 @@ Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span
## wt hook approvals
-### How Approvals Work
-
-Commands from project hooks (`.config/wt.toml`) require approval on first run.
-This prevents untrusted projects from running arbitrary commands.
-
-**Approval flow:**
-1. Command is shown as a template (variables not expanded)
-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:**
-- `--yes` flag on individual commands (e.g., `wt merge --yes`)
-- Useful for CI/automation where prompts aren't possible
+Project hooks require approval on first run to prevent untrusted projects from running arbitrary commands.
### Examples
@@ -521,6 +505,10 @@ Clear global approvals:
wt hook approvals clear --global
```
+### How approvals work
+
+Approved commands are saved to user config. Re-approval is required when the command template changes or the project moves. Use `--yes` to bypass prompts in CI.
+
### Command reference
wt hook approvals - Manage command approvals
diff --git a/docs/content/config.md b/docs/content/config.md
index dc68a5c3d..30dea7f75 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -762,6 +762,14 @@ Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span
## wt config state default-branch
+Useful in scripts to avoid hardcoding `main` or `master`:
+
+```bash
+git rebase $(wt config state default-branch)
+```
+
+Without a subcommand, runs `get`. Use `set` to override, `get --refresh` to re-detect, or `clear` to reset.
+
### Detection
Worktrunk detects the default branch automatically:
@@ -779,18 +787,6 @@ The local inference fallback uses these heuristics in order:
- Checks `git config init.defaultBranch`
- Looks for common names: main, master, develop, trunk
-### When to use
-
-Most users never need this command — default branch detection is automatic.
-Use it to:
-
-- **Debug** — See what worktrunk thinks the default branch is
-- **Override** — Set a non-standard default branch with `set`
-- **Refresh** — Force re-query with `get --refresh` after remote changes
-- **Clear** — Remove cached value with `clear`
-
-Without a subcommand, runs `get`. For `--refresh`, use `get --refresh`.
-
### Command reference
{% terminal() %}
diff --git a/docs/content/hook.md b/docs/content/hook.md
index abda845a9..53a6cc9a8 100644
--- a/docs/content/hook.md
+++ b/docs/content/hook.md
@@ -502,23 +502,7 @@ Usage: <b><span class=c>wt hook</span></b> <span class=c>[OPTIONS]</span> <span
## wt hook approvals
-### How Approvals Work
-
-Commands from project hooks (`.config/wt.toml`) require approval on first run.
-This prevents untrusted projects from running arbitrary commands.
-
-**Approval flow:**
-1. Command is shown as a template (variables not expanded)
-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:**
-- `--yes` flag on individual commands (e.g., `wt merge --yes`)
-- Useful for CI/automation where prompts aren't possible
+Project hooks require approval on first run to prevent untrusted projects from running arbitrary commands.
### Examples
@@ -537,6 +521,10 @@ Clear global approvals:
wt hook approvals clear --global
```
+### How approvals work
+
+Approved commands are saved to user config. Re-approval is required when the command template changes or the project moves. Use `--yes` to bypass prompts in CI.
+
### Command reference
{% terminal() %}
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 186e42172..eea4d64a9 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -116,14 +116,15 @@ Detects various forms of the integration pattern regardless of:
},
/// Show output theme samples
- #[command(after_long_help = r#"## Output Theme
+ #[command(
+ after_long_help = r#"Displays samples of all output message types to preview how worktrunk output will appear in the terminal.
+
+## Message types
-Displays samples of all output message types:
- Progress, success, error, warning, hint, info
- Gutter formatting for quoted content
-- Prompts for user input
-
-Use this to preview how worktrunk output will appear in the terminal."#)]
+- Prompts for user input"#
+ )]
ShowTheme,
}
@@ -272,7 +273,15 @@ pub enum StateCommand {
/// Default branch setting
#[command(
name = "default-branch",
- after_long_help = r#"## Detection
+ after_long_help = r#"Useful in scripts to avoid hardcoding `main` or `master`:
+
+```bash
+git rebase $(wt config state default-branch)
+```
+
+Without a subcommand, runs `get`. Use `set` to override, `get --refresh` to re-detect, or `clear` to reset.
+
+## Detection
Worktrunk detects the default branch automatically:
@@ -287,19 +296,7 @@ The local inference fallback uses these heuristics in order:
- If only one local branch exists, uses it
- For bare repos or empty repos, checks `symbolic-ref HEAD`
- Checks `git config init.defaultBranch`
-- Looks for common names: main, master, develop, trunk
-
-## When to use
-
-Most users never need this command — default branch detection is automatic.
-Use it to:
-
-- **Debug** — See what worktrunk thinks the default branch is
-- **Override** — Set a non-standard default branch with `set`
-- **Refresh** — Force re-query with `get --refresh` after remote changes
-- **Clear** — Remove cached value with `clear`
-
-Without a subcommand, runs `get`. For `--refresh`, use `get --refresh`."#
+- Looks for common names: main, master, develop, trunk"#
)]
DefaultBranch {
#[command(subcommand)]
diff --git a/src/cli/hook.rs b/src/cli/hook.rs
index 542f4f149..fe66f8fe6 100644
--- a/src/cli/hook.rs
+++ b/src/cli/hook.rs
@@ -167,23 +167,8 @@ pub enum HookCommand {
},
/// Manage command approvals
- #[command(after_long_help = r#"## How Approvals Work
-
-Commands from project hooks (`.config/wt.toml`) require approval on first run.
-This prevents untrusted projects from running arbitrary commands.
-
-**Approval flow:**
-1. Command is shown as a template (variables not expanded)
-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:**
-- `--yes` flag on individual commands (e.g., `wt merge --yes`)
-- Useful for CI/automation where prompts aren't possible
+ #[command(
+ after_long_help = r#"Project hooks require approval on first run to prevent untrusted projects from running arbitrary commands.
## Examples
@@ -200,7 +185,12 @@ wt hook approvals clear
Clear global approvals:
```console
wt hook approvals clear --global
-```"#)]
+```
+
+## How approvals work
+
+Approved commands are saved to user config. Re-approval is required when the command template changes or the project moves. Use `--yes` to bypass prompts in CI."#
+ )]
Approvals {
#[command(subcommand)]
action: ApprovalsCommand,
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
index 7dfccb049..0e689c009 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state_default_branch.snap
@@ -13,6 +13,7 @@ info:
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
+ TERM: alacritty
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
@@ -44,6 +45,12 @@ Usage: wt config state default-branch [OPTIONS] [COMM
-v, --verbose
Show commands and debug info
+Useful in scripts to avoid hardcoding main or master:
+
+ git rebase $(wt config state default-branch)
+
+Without a subcommand, runs get. Use set to override, get --refresh to re-detect, or clear to reset.
+
Detection
Worktrunk detects the default branch automatically:
@@ -60,15 +67,3 @@ The local inference fallback uses these heuristics in order:
- For bare repos or empty repos, checks symbolic-ref HEAD
- Checks git config init.defaultBranch
- Looks for common names: main, master, develop, trunk
-
-When to use
-
-Most users never need this command — default branch detection is automatic.
-Use it to:
-
-- Debug — See what worktrunk thinks the default branch is
-- Override — Set a non-standard default branch with set
-- Refresh — Force re-query with get --refresh after remote changes
-- Clear — Remove cached value with clear
-
-Without a subcommand, runs get. For --refresh, use get --refresh.
diff --git a/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap b/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
index fc427bd91..6bb6f69f8 100644
--- a/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_hook_approvals.snap
@@ -12,6 +12,7 @@ info:
GIT_EDITOR: ""
RUST_LOG: warn
SOURCE_DATE_EPOCH: "1735776000"
+ TERM: alacritty
WORKTRUNK_CONFIG_PATH: /nonexistent/test/config.toml
WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
---
@@ -42,23 +43,7 @@ Usage: wt hook approvals [OPTIONS] <COMMAND>
-v, --verbose
Show commands and debug info
-How Approvals Work
-
-Commands from project hooks (.config/wt.toml) require approval on first run.
-This prevents untrusted projects from running arbitrary commands.
-
-Approval flow:
-1. Command is shown as a template (variables not expanded)
-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:
-- --yes flag on individual commands (e.g., wt merge --yes)
-- Useful for CI/automation where prompts aren't possible
+Project hooks require approval on first run to prevent untrusted projects from running arbitrary commands.
Examples
@@ -70,3 +55,8 @@ Clear approvals for current project:
Clear global approvals:
wt hook approvals clear --global
+
+How approvals work
+
+Approved commands are saved to user config. Re-approval is required when the command template changes or the project moves. Use --yes to bypass
+prompts in CI.