Skip to content

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

cli: document subcommand ordering policy and align step/state (#2043)

Maximilian Roos254d7aa14cc2
diff --git a/docs/content/config.md b/docs/content/config.md
index b6d012b94..ce6e93a63 100644
--- a/docs/content/config.md
+++ b/docs/content/config.md
@@ -577,10 +577,10 @@ State is stored in `.git/` (config entries and log files), separate from configu
- **default-branch**: [The repository's default branch (`main`, `master`, etc.)](@/config.md#wt-config-state-default-branch)
- **previous-branch**: Previous branch for `wt switch -`
+- **logs**: [Operation and debug logs](@/config.md#wt-config-state-logs)
- **ci-status**: [CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)](@/config.md#wt-config-state-ci-status)
- **marker**: [Custom status marker for a branch (shown in `wt list`)](@/config.md#wt-config-state-marker)
- **vars**: <span class="badge-experimental"></span> [Custom variables per branch](@/config.md#wt-config-state-vars)
-- **logs**: [Operation and debug logs](@/config.md#wt-config-state-logs)
### Examples
@@ -613,15 +613,15 @@ wt config state - Manage internal data and cache
Usage: <b><span class=c>wt config state</span></b> <span class=c>[OPTIONS]</span> <span class=c>&lt;COMMAND&gt;</span>
<b><span class=g>Commands:</span></b>
+ <b><span class=c>get</span></b> Get all stored state
+ <b><span class=c>clear</span></b> Clear all stored state
<b><span class=c>default-branch</span></b> Default branch detection and override
<b><span class=c>previous-branch</span></b> Previous branch (for <b>wt switch -</b>)
- <b><span class=c>ci-status</span></b> CI status cache
- <b><span class=c>marker</span></b> Branch markers
<b><span class=c>logs</span></b> Operation and debug logs
<b><span class=c>hints</span></b> One-time hints shown in this repo
+ <b><span class=c>ci-status</span></b> CI status cache
+ <b><span class=c>marker</span></b> Branch markers
<b><span class=c>vars</span></b> [experimental] Custom variables per branch
- <b><span class=c>get</span></b> Get all stored state
- <b><span class=c>clear</span></b> Clear all stored state
<b><span class=g>Options:</span></b>
<b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
@@ -692,6 +692,95 @@ Usage: <b><span class=c>wt config state default-branch</span></b> <span class=c>
Verbose output (-v: hooks, templates; -vv: debug report)
{% end %}
+## wt config state logs
+
+Operation and debug logs.
+
+View and manage log files — hook output, command audit trail, and debug diagnostics.
+
+### What's logged
+
+Three kinds of logs live in `.git/wt/logs/`:
+
+#### Command log (`commands.jsonl`)
+
+All hook executions and LLM commands are recorded automatically — one JSON object per line. Rotates to `commands.jsonl.old` at 1MB (~2MB total). Fields:
+
+| Field | Description |
+|-------|-------------|
+| `ts` | ISO 8601 timestamp |
+| `wt` | The `wt` command that triggered this (e.g., `wt hook pre-merge --yes`) |
+| `label` | What ran (e.g., `pre-merge user:lint`, `commit.generation`) |
+| `cmd` | Shell command executed |
+| `exit` | Exit code (`null` for background commands) |
+| `dur_ms` | Duration in milliseconds (`null` for background commands) |
+
+The command log appends entries and is not branch-specific — it records all activity across all worktrees.
+
+#### Hook output logs
+
+Hook output lives in per-branch subtrees under `.git/wt/logs/{branch}/`:
+
+| Operation | Log path |
+|-----------|----------|
+| Background hooks | `{branch}/{source}/{hook-type}/{name}.log` |
+| Background removal | `{branch}/internal/remove.log` |
+
+All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety (invalid characters → `-`; short collision-avoidance hash appended). Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.
+
+#### Diagnostic files
+
+| File | Created when |
+|------|-------------|
+| `verbose.log` | Running with `-vv` |
+| `diagnostic.md` | Running with `-vv` when warnings occur |
+
+`verbose.log` is overwritten on each `-vv` run. `diagnostic.md` is a markdown report for pasting into GitHub issues — written only when warnings occur.
+
+### Location
+
+All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory. Top-level files are shared logs (command audit + diagnostics); top-level directories are per-branch log trees.
+
+### Examples
+
+List all log files:
+{{ terminal(cmd="wt config state logs get") }}
+
+Query the command log:
+{{ terminal(cmd="tail -5 .git/wt/logs/commands.jsonl | jq .") }}
+
+View a specific hook log:
+{{ terminal(cmd="cat __WT_QUOT__$(git rev-parse --git-dir)/wt/logs/feature/project/post-start/build.log__WT_QUOT__") }}
+
+Clear all logs:
+{{ terminal(cmd="wt config state logs clear") }}
+
+### Command reference
+
+{% terminal() %}
+wt config state logs - Operation and debug logs
+
+Usage: <b><span class=c>wt config state logs</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>
+
+<b><span class=g>Commands:</span></b>
+ <b><span class=c>get</span></b> Get log file paths
+ <b><span class=c>clear</span></b> Clear all log files
+
+<b><span class=g>Options:</span></b>
+ <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
+ Print help (see a summary with &#39;-h&#39;)
+
+<b><span class=g>Global Options:</span></b>
+ <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
+ Working directory for this command
+
+ <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
+ User config file path
+
+ <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
+ Verbose output (-v: hooks, templates; -vv: debug report)
+{% end %}
+
## wt config state ci-status
CI status cache.
@@ -881,93 +970,4 @@ Usage: <b><span class=c>wt config state vars</span></b> <span class=c>[OPTIONS]<
Verbose output (-v: hooks, templates; -vv: debug report)
{% end %}
-## wt config state logs
-
-Operation and debug logs.
-
-View and manage log files — hook output, command audit trail, and debug diagnostics.
-
-### What's logged
-
-Three kinds of logs live in `.git/wt/logs/`:
-
-#### Command log (`commands.jsonl`)
-
-All hook executions and LLM commands are recorded automatically — one JSON object per line. Rotates to `commands.jsonl.old` at 1MB (~2MB total). Fields:
-
-| Field | Description |
-|-------|-------------|
-| `ts` | ISO 8601 timestamp |
-| `wt` | The `wt` command that triggered this (e.g., `wt hook pre-merge --yes`) |
-| `label` | What ran (e.g., `pre-merge user:lint`, `commit.generation`) |
-| `cmd` | Shell command executed |
-| `exit` | Exit code (`null` for background commands) |
-| `dur_ms` | Duration in milliseconds (`null` for background commands) |
-
-The command log appends entries and is not branch-specific — it records all activity across all worktrees.
-
-#### Hook output logs
-
-Hook output lives in per-branch subtrees under `.git/wt/logs/{branch}/`:
-
-| Operation | Log path |
-|-----------|----------|
-| Background hooks | `{branch}/{source}/{hook-type}/{name}.log` |
-| Background removal | `{branch}/internal/remove.log` |
-
-All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety (invalid characters → `-`; short collision-avoidance hash appended). Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.
-
-#### Diagnostic files
-
-| File | Created when |
-|------|-------------|
-| `verbose.log` | Running with `-vv` |
-| `diagnostic.md` | Running with `-vv` when warnings occur |
-
-`verbose.log` is overwritten on each `-vv` run. `diagnostic.md` is a markdown report for pasting into GitHub issues — written only when warnings occur.
-
-### Location
-
-All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory. Top-level files are shared logs (command audit + diagnostics); top-level directories are per-branch log trees.
-
-### Examples
-
-List all log files:
-{{ terminal(cmd="wt config state logs get") }}
-
-Query the command log:
-{{ terminal(cmd="tail -5 .git/wt/logs/commands.jsonl | jq .") }}
-
-View a specific hook log:
-{{ terminal(cmd="cat __WT_QUOT__$(git rev-parse --git-dir)/wt/logs/feature/project/post-start/build.log__WT_QUOT__") }}
-
-Clear all logs:
-{{ terminal(cmd="wt config state logs clear") }}
-
-### Command reference
-
-{% terminal() %}
-wt config state logs - Operation and debug logs
-
-Usage: <b><span class=c>wt config state logs</span></b> <span class=c>[OPTIONS]</span> <span class=c>[COMMAND]</span>
-
-<b><span class=g>Commands:</span></b>
- <b><span class=c>get</span></b> Get log file paths
- <b><span class=c>clear</span></b> Clear all log files
-
-<b><span class=g>Options:</span></b>
- <b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
- Print help (see a summary with &#39;-h&#39;)
-
-<b><span class=g>Global Options:</span></b>
- <b><span class=c>-C</span></b><span class=c> &lt;path&gt;</span>
- Working directory for this command
-
- <b><span class=c>--config</span></b><span class=c> &lt;path&gt;</span>
- User config file path
-
- <b><span class=c>-v</span></b>, <b><span class=c>--verbose</span></b><span class=c>...</span>
- Verbose output (-v: hooks, templates; -vv: debug report)
-{% end %}
-
<!-- END AUTO-GENERATED from `wt config --help-page` -->
diff --git a/docs/content/step.md b/docs/content/step.md
index 5543bd363..1e98fd7e3 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -53,8 +53,8 @@ Usage: <b><span class=c>wt step</span></b> <span class=c>[OPTIONS]</span> <span
<b><span class=g>Commands:</span></b>
<b><span class=c>commit</span></b> Stage and commit with LLM-generated message
<b><span class=c>squash</span></b> Squash commits since branching
- <b><span class=c>push</span></b> Fast-forward target to current branch
<b><span class=c>rebase</span></b> Rebase onto target
+ <b><span class=c>push</span></b> Fast-forward target to current branch
<b><span class=c>diff</span></b> Show all changes since branching
<b><span class=c>copy-ignored</span></b> Copy gitignored files to another worktree
<b><span class=c>eval</span></b> [experimental] Evaluate a template expression
diff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.md
index 7f6ea936a..2f51076d1 100644
--- a/skills/worktrunk/reference/config.md
+++ b/skills/worktrunk/reference/config.md
@@ -582,10 +582,10 @@ State is stored in `.git/` (config entries and log files), separate from configu
- **default-branch**: [The repository's default branch (`main`, `master`, etc.)](https://worktrunk.dev/config/#wt-config-state-default-branch)
- **previous-branch**: Previous branch for `wt switch -`
+- **logs**: [Operation and debug logs](https://worktrunk.dev/config/#wt-config-state-logs)
- **ci-status**: [CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)](https://worktrunk.dev/config/#wt-config-state-ci-status)
- **marker**: [Custom status marker for a branch (shown in `wt list`)](https://worktrunk.dev/config/#wt-config-state-marker)
- **vars**: [experimental] [Custom variables per branch](https://worktrunk.dev/config/#wt-config-state-vars)
-- **logs**: [Operation and debug logs](https://worktrunk.dev/config/#wt-config-state-logs)
### Examples
@@ -632,15 +632,15 @@ wt config state - Manage internal data and cache
Usage: wt config state [OPTIONS] <COMMAND>
Commands:
+ get Get all stored state
+ clear Clear all stored state
default-branch Default branch detection and override
previous-branch Previous branch (for wt switch -)
- ci-status CI status cache
- marker Branch markers
logs Operation and debug logs
hints One-time hints shown in this repo
+ ci-status CI status cache
+ marker Branch markers
vars [experimental] Custom variables per branch
- get Get all stored state
- clear Clear all stored state
Options:
-h, --help
@@ -713,6 +713,103 @@ Global Options:
Verbose output (-v: hooks, templates; -vv: debug report)
```
+## wt config state logs
+
+Operation and debug logs.
+
+View and manage log files — hook output, command audit trail, and debug diagnostics.
+
+### What's logged
+
+Three kinds of logs live in `.git/wt/logs/`:
+
+#### Command log (`commands.jsonl`)
+
+All hook executions and LLM commands are recorded automatically — one JSON object per line. Rotates to `commands.jsonl.old` at 1MB (~2MB total). Fields:
+
+| Field | Description |
+|-------|-------------|
+| `ts` | ISO 8601 timestamp |
+| `wt` | The `wt` command that triggered this (e.g., `wt hook pre-merge --yes`) |
+| `label` | What ran (e.g., `pre-merge user:lint`, `commit.generation`) |
+| `cmd` | Shell command executed |
+| `exit` | Exit code (`null` for background commands) |
+| `dur_ms` | Duration in milliseconds (`null` for background commands) |
+
+The command log appends entries and is not branch-specific — it records all activity across all worktrees.
+
+#### Hook output logs
+
+Hook output lives in per-branch subtrees under `.git/wt/logs/{branch}/`:
+
+| Operation | Log path |
+|-----------|----------|
+| Background hooks | `{branch}/{source}/{hook-type}/{name}.log` |
+| Background removal | `{branch}/internal/remove.log` |
+
+All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety (invalid characters → `-`; short collision-avoidance hash appended). Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.
+
+#### Diagnostic files
+
+| File | Created when |
+|------|-------------|
+| `verbose.log` | Running with `-vv` |
+| `diagnostic.md` | Running with `-vv` when warnings occur |
+
+`verbose.log` is overwritten on each `-vv` run. `diagnostic.md` is a markdown report for pasting into GitHub issues — written only when warnings occur.
+
+### Location
+
+All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory. Top-level files are shared logs (command audit + diagnostics); top-level directories are per-branch log trees.
+
+### Examples
+
+List all log files:
+```bash
+$ wt config state logs get
+```
+
+Query the command log:
+```bash
+$ tail -5 .git/wt/logs/commands.jsonl | jq .
+```
+
+View a specific hook log:
+```bash
+$ cat "$(git rev-parse --git-dir)/wt/logs/feature/project/post-start/build.log"
+```
+
+Clear all logs:
+```bash
+$ wt config state logs clear
+```
+
+### Command reference
+
+```
+wt config state logs - Operation and debug logs
+
+Usage: wt config state logs [OPTIONS] [COMMAND]
+
+Commands:
+ get Get log file paths
+ clear Clear all log files
+
+Options:
+ -h, --help
+ Print help (see a summary with '-h')
+
+Global Options:
+ -C <path>
+ Working directory for this command
+
+ --config <path>
+ User config file path
+
+ -v, --verbose...
+ Verbose output (-v: hooks, templates; -vv: debug report)
+```
+
## wt config state ci-status
CI status cache.
@@ -905,100 +1002,3 @@ Global Options:
-v, --verbose...
Verbose output (-v: hooks, templates; -vv: debug report)
```
-
-## wt config state logs
-
-Operation and debug logs.
-
-View and manage log files — hook output, command audit trail, and debug diagnostics.
-
-### What's logged
-
-Three kinds of logs live in `.git/wt/logs/`:
-
-#### Command log (`commands.jsonl`)
-
-All hook executions and LLM commands are recorded automatically — one JSON object per line. Rotates to `commands.jsonl.old` at 1MB (~2MB total). Fields:
-
-| Field | Description |
-|-------|-------------|
-| `ts` | ISO 8601 timestamp |
-| `wt` | The `wt` command that triggered this (e.g., `wt hook pre-merge --yes`) |
-| `label` | What ran (e.g., `pre-merge user:lint`, `commit.generation`) |
-| `cmd` | Shell command executed |
-| `exit` | Exit code (`null` for background commands) |
-| `dur_ms` | Duration in milliseconds (`null` for background commands) |
-
-The command log appends entries and is not branch-specific — it records all activity across all worktrees.
-
-#### Hook output logs
-
-Hook output lives in per-branch subtrees under `.git/wt/logs/{branch}/`:
-
-| Operation | Log path |
-|-----------|----------|
-| Background hooks | `{branch}/{source}/{hook-type}/{name}.log` |
-| Background removal | `{branch}/internal/remove.log` |
-
-All `post-*` hooks (post-start, post-switch, post-commit, post-merge) run in the background and produce log files. Source is `user` or `project`. Branch and hook names are sanitized for filesystem safety (invalid characters → `-`; short collision-avoidance hash appended). Same operation on same branch overwrites the previous log. Removing a branch clears its subtree; orphans from deleted branches can be swept with `wt config state logs clear`.
-
-#### Diagnostic files
-
-| File | Created when |
-|------|-------------|
-| `verbose.log` | Running with `-vv` |
-| `diagnostic.md` | Running with `-vv` when warnings occur |
-
-`verbose.log` is overwritten on each `-vv` run. `diagnostic.md` is a markdown report for pasting into GitHub issues — written only when warnings occur.
-
-### Location
-
-All logs are stored in `.git/wt/logs/` (in the main worktree's git directory). All worktrees write to the same directory. Top-level files are shared logs (command audit + diagnostics); top-level directories are per-branch log trees.
-
-### Examples
-
-List all log files:
-```bash
-$ wt config state logs get
-```
-
-Query the command log:
-```bash
-$ tail -5 .git/wt/logs/commands.jsonl | jq .
-```
-
-View a specific hook log:
-```bash
-$ cat "$(git rev-parse --git-dir)/wt/logs/feature/project/post-start/build.log"
-```
-
-Clear all logs:
-```bash
-$ wt config state logs clear
-```
-
-### Command reference
-
-```
-wt config state logs - Operation and debug logs
-
-Usage: wt config state logs [OPTIONS] [COMMAND]
-
-Commands:
- get Get log file paths
- clear Clear all log files
-
-Options:
- -h, --help
- Print help (see a summary with '-h')
-
-Global Options:
- -C <path>
- Working directory for this command
-
- --config <path>
- User config file path
-
- -v, --verbose...
- Verbose output (-v: hooks, templates; -vv: debug report)
-```
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index bb7b1d685..b5a625538 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -46,8 +46,8 @@ Usage: wt step [OPTIONS] <COMMAND>
Commands:
commit Stage and commit with LLM-generated message
squash Squash commits since branching
- push Fast-forward target to current branch
rebase Rebase onto target
+ push Fast-forward target to current branch
diff Show all changes since branching
copy-ignored Copy gitignored files to another worktree
eval [experimental] Evaluate a template expression
diff --git a/src/cli/config.rs b/src/cli/config.rs
index 4e47e1cd3..9a87a3064 100644
--- a/src/cli/config.rs
+++ b/src/cli/config.rs
@@ -3,6 +3,9 @@ use clap::Subcommand;
use super::SwitchFormat;
use crate::commands::Shell;
+// Ordering: primitive (init prints the code) → convenience (install writes
+// it) → inverse (uninstall removes it), then unrelated utilities. Hidden
+// commands last.
#[derive(Subcommand)]
pub enum ConfigShellCommand {
/// Generate shell integration code
@@ -156,6 +159,7 @@ Detects various forms of the integration pattern regardless of:
},
}
+// Ordering: action + inverse adjacent (install, uninstall).
#[derive(Subcommand)]
pub enum ConfigPluginsOpencodeCommand {
/// Install the activity tracking plugin
@@ -197,6 +201,7 @@ $ wt config plugins opencode uninstall
},
}
+// Ordering: action + inverse adjacent (add, clear).
#[derive(Subcommand)]
pub enum ApprovalsCommand {
/// Store approvals in approvals.toml
@@ -226,6 +231,8 @@ all approvals across all projects."#
},
}
+// Ordering: alphabetical. Equal-weight sibling plugins with no natural
+// precedence.
#[derive(Subcommand)]
pub enum ConfigPluginsCommand {
/// Claude Code plugin
@@ -273,6 +280,8 @@ Written to `~/.config/opencode/plugins/worktrunk.ts` (or `$OPENCODE_CONFIG_DIR/p
},
}
+// Ordering: action + inverse adjacent (install, uninstall), then related
+// extras.
#[derive(Subcommand)]
pub enum ConfigPluginsClaudeCommand {
/// Install the Worktrunk plugin
@@ -326,6 +335,9 @@ Skips gracefully if the statusline is already configured."#
},
}
+// Ordering: user journey — shell (install integration), create (bootstrap
+// config files), show (inspect), update (migrate deprecations), plugins
+// (optional add-ons), state (advanced diagnostics).
#[derive(Subcommand)]
pub enum ConfigCommand {
/// Shell integration setup
@@ -435,10 +447,10 @@ $ wt config plugins opencode install
- **default-branch**: [The repository's default branch (`main`, `master`, etc.)](@/config.md#wt-config-state-default-branch)
- **previous-branch**: Previous branch for `wt switch -`
+- **logs**: [Operation and debug logs](@/config.md#wt-config-state-logs)
- **ci-status**: [CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)](@/config.md#wt-config-state-ci-status)
- **marker**: [Custom status marker for a branch (shown in `wt list`)](@/config.md#wt-config-state-marker)
- **vars**: [experimental] [Custom variables per branch](@/config.md#wt-config-state-vars)
-- **logs**: [Operation and debug logs](@/config.md#wt-config-state-logs)
## Examples
@@ -477,10 +489,10 @@ Clear all stored state:
$ wt config state clear
```
<!-- subdoc: default-branch -->
+<!-- subdoc: logs -->
<!-- subdoc: ci-status -->
<!-- subdoc: marker -->
-<!-- subdoc: vars -->
-<!-- subdoc: logs -->"#
+<!-- subdoc: vars -->"#
)]
State {
#[command(subcommand)]
@@ -488,8 +500,47 @@ $ wt config state clear
},
}
+// Ordering: aggregate operations first (get, clear) — entry points for
+// exploring or wiping all state. Then primary state managed by wt
+// (default-branch, previous-branch, logs, hints), then per-branch display
+// annotations shown in `wt list` (ci-status, marker), then experimental keys
+// (vars).
#[derive(Subcommand)]
pub enum StateCommand {
+ /// Get all stored state
+ #[command(after_long_help = r#"Shows all stored state including:
+
+- **Default branch**: Cached result of querying remote for default branch
+- **Previous branch**: Previous branch for `wt switch -`
+- **Branch markers**: User-defined branch notes
+- **Vars**: Custom variables per branch
+- **CI status**: Cached GitHub/GitLab CI status per branch (30s TTL)
+- **Hints**: One-time hints that have been shown
+- **Log files**: Operation and debug logs
+
+CI cache entries show status, age, and the commit SHA they were fetched for."#)]
+ Get {
+ /// Output format (table, json)
+ #[arg(long, value_enum, default_value = "table", hide_possible_values = true)]
+ format: super::OutputFormat,
+ },
+
+ /// Clear all stored state
+ #[command(after_long_help = r#"Clears all stored state:
+
+- Default branch cache
+- Previous branch
+- All branch markers
+- All variables
+- All CI status cache
+- All hints
+- All log files
+- Stale trash from worktree removal (`.git/wt/trash/`)
+
+Use individual subcommands (`default-branch clear`, `ci-status clear --all`, etc.)
+to clear specific state."#)]
+ Clear,
+
/// Default branch detection and override
#[command(
name = "default-branch",
@@ -539,71 +590,6 @@ Without a subcommand, runs `get`. Use `set` to override or `clear` to reset."#
action: Option<PreviousBranchAction>,
},
- /// CI status cache
- #[command(
- name = "ci-status",
- after_long_help = r#"Caches GitHub/GitLab CI status for display in [`wt list`](@/list.md#ci-status).
-
-Requires `gh` (GitHub) or `glab` (GitLab) CLI, authenticated. Platform auto-detects from remote URL; override with `forge.platform = "github"` in `.config/wt.toml` for SSH host aliases or self-hosted instances. For GitHub Enterprise or self-hosted GitLab, also set `forge.hostname`.
-
-Checks open PRs/MRs first, then branch pipelines for branches with upstream. Local-only branches (no remote tracking) show blank.
-
-Results cache for 30-60 seconds. Indicators dim when local changes haven't been pushed.
-
-## Status values
-
-| Status | Meaning |
-|--------|---------|
-| `passed` | All checks passed |
-| `running` | Checks in progress |
-| `failed` | Checks failed |
-| `conflicts` | PR has merge conflicts |
-| `no-ci` | No checks configured |
-| `error` | Fetch error (rate limit, network, auth) |
-
-See [`wt list` CI status](@/list.md#ci-status) for display symbols and colors.
-
-Without a subcommand, runs `get` for the current branch. Use `clear` to reset cache for a branch or `clear --all` to reset all."#
- )]
- CiStatus {
- #[command(subcommand)]
- action: Option<CiStatusAction>,
- },
-
- /// Branch markers
- #[command(
- after_long_help = r#"Custom status text or emoji shown in the `wt list` Status column.
-
-## Display
-
-Markers appear at the end of the Status column, after git symbols:
-
-<!-- wt list (markers) -->
-```console
-wt list
-```
-
-## Use cases
-
-- **Work status** — `🚧` WIP, `✅` ready for review, `🔥` urgent
-- **Agent tracking** — The [Claude Code](@/claude-code.md) plugin sets markers automatically
-- **Notes** — Any short text: `"blocked"`, `"needs tests"`
-
-## Storage
-
-Stored in git config as `worktrunk.state.<branch>.marker`. Set directly with:
-
-```console
-$ git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
-```
-
-Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`."#
- )]
- Marker {
- #[command(subcommand)]
- action: Option<MarkerAction>,
- },
-
/// Operation and debug logs
#[command(
after_long_help = r#"View and manage log files — hook output, command audit trail, and debug diagnostics.
@@ -702,6 +688,71 @@ $ wt config state hints clear NAME # re-show specific hint
action: Option<HintsAction>,
},
+ /// CI status cache
+ #[command(
+ name = "ci-status",
+ after_long_help = r#"Caches GitHub/GitLab CI status for display in [`wt list`](@/list.md#ci-status).
+
+Requires `gh` (GitHub) or `glab` (GitLab) CLI, authenticated. Platform auto-detects from remote URL; override with `forge.platform = "github"` in `.config/wt.toml` for SSH host aliases or self-hosted instances. For GitHub Enterprise or self-hosted GitLab, also set `forge.hostname`.
+
+Checks open PRs/MRs first, then branch pipelines for branches with upstream. Local-only branches (no remote tracking) show blank.
+
+Results cache for 30-60 seconds. Indicators dim when local changes haven't been pushed.
+
+## Status values
+
+| Status | Meaning |
+|--------|---------|
+| `passed` | All checks passed |
+| `running` | Checks in progress |
+| `failed` | Checks failed |
+| `conflicts` | PR has merge conflicts |
+| `no-ci` | No checks configured |
+| `error` | Fetch error (rate limit, network, auth) |
+
+See [`wt list` CI status](@/list.md#ci-status) for display symbols and colors.
+
+Without a subcommand, runs `get` for the current branch. Use `clear` to reset cache for a branch or `clear --all` to reset all."#
+ )]
+ CiStatus {
+ #[command(subcommand)]
+ action: Option<CiStatusAction>,
+ },
+
+ /// Branch markers
+ #[command(
+ after_long_help = r#"Custom status text or emoji shown in the `wt list` Status column.
+
+## Display
+
+Markers appear at the end of the Status column, after git symbols:
+
+<!-- wt list (markers) -->
+```console
+wt list
+```
+
+## Use cases
+
+- **Work status** — `🚧` WIP, `✅` ready for review, `🔥` urgent
+- **Agent tracking** — The [Claude Code](@/claude-code.md) plugin sets markers automatically
+- **Notes** — Any short text: `"blocked"`, `"needs tests"`
+
+## Storage
+
+Stored in git config as `worktrunk.state.<branch>.marker`. Set directly with:
+
+```console
+$ git config worktrunk.state.feature.marker '{"marker":"🚧","set_at":0}'
+```
+
+Without a subcommand, runs `get` for the current branch. For `--branch`, use `get --branch=NAME`."#
+ )]
+ Marker {
+ #[command(subcommand)]
+ action: Option<MarkerAction>,
+ },
+
/// \[experimental\] Custom variables per branch
#[command(
name = "vars",
@@ -757,42 +808,9 @@ Stored in git config as `worktrunk.state.<branch>.vars.<key>`. Keys must contain
#[command(subcommand)]
action: VarsAction,
},
-
- /// Get all stored state
- #[command(after_long_help = r#"Shows all stored state including:
-
-- **Default branch**: Cached result of querying remote for default branch
-- **Previous branch**: Previous branch for `wt switch -`
-- **Branch markers**: User-defined branch notes
-- **Vars**: Custom variables per branch
-- **CI status**: Cached GitHub/GitLab CI status per branch (30s TTL)
-- **Hints**: One-time hints that have been shown
-- **Log files**: Operation and debug logs
-
-CI cache entries show status, age, and the commit SHA they were fetched for."#)]
- Get {
- /// Output format (table, json)
- #[arg(long, value_enum, default_value = "table", hide_possible_values = true)]
- format: super::OutputFormat,
- },
-
- /// Clear all stored state
- #[command(after_long_help = r#"Clears all stored state:
-
-- Default branch cache
-- Previous branch
-- All branch markers
-- All variables
-- All CI status cache
-- All hints
-- All log files
-- Stale trash from worktree removal (`.git/wt/trash/`)
-
-Use individual subcommands (`default-branch clear`, `ci-status clear --all`, etc.)
-to clear specific state."#)]
- Clear,
}
+// Ordering: CRUD — get, set, clear.
#[derive(Subcommand)]
pub enum DefaultBranchAction {
/// Get the default branch
@@ -826,6 +844,7 @@ $ wt config state default-branch set main
Clear,
}
+// Ordering: CRUD — get, set, clear.
#[derive(Subcommand)]
pub enum PreviousBranchAction {
/// Get the previous branch
@@ -854,6 +873,7 @@ $ wt config state previous-branch set feature
Clear,
}
+// Ordering: CRUD — get, clear.
#[derive(Subcommand)]
pub enum CiStatusAction {
/// Get CI status for a branch
@@ -915,6 +935,7 @@ $ wt config state ci-status clear --all
},
}
+// Ordering: CRUD — get, set, clear.
#[derive(Subcommand)]
pub enum MarkerAction {
/// Get marker for a branch
@@ -988,6 +1009,7 @@ $ wt config state marker clear --all
},
}
+// Ordering: CRUD — get, clear.
#[derive(Subcommand)]
pub enum LogsAction {
/// Get log file paths
@@ -1048,6 +1070,7 @@ $ wt config state logs get --hook=user:post-start:server --branch=feature
Clear,
}
+// Ordering: CRUD — get, clear.
#[derive(Subcommand)]
pub enum HintsAction {
/// List hints that have been shown
@@ -1089,6 +1112,7 @@ $ wt config state hints clear worktree-path
},
}
+// Ordering: CRUD — get, set, list, clear.
#[derive(Subcommand)]
pub enum VarsAction {
/// Get a value
diff --git a/src/cli/hook.rs b/src/cli/hook.rs
index 517804b59..cd7b5c65a 100644
--- a/src/cli/hook.rs
+++ b/src/cli/hook.rs
@@ -2,6 +2,10 @@ use clap::Subcommand;
use super::config::ApprovalsCommand;
+// Ordering: worktree lifecycle phases (switch → start → commit → merge →
+// remove), with each phase's `pre-` immediately before its `post-`. `show`
+// first (read-only introspection), `approvals` last (administration). Hidden
+// commands last.
/// Run configured hooks
#[derive(Subcommand)]
pub enum HookCommand {
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 49999f106..478341ef0 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -526,6 +526,10 @@ pub(crate) struct MergeArgs {
pub(crate) format: SwitchFormat,
}
+// Ordering: by "core-ness". Primitive worktree operations first (switch, list,
+// remove), then composites built on top (merge), then subcommand namespaces
+// (step, hook, config). `remove` is a primitive and more core than `merge`,
+// which wraps it. Hidden commands last.
#[derive(Subcommand)]
pub(crate) enum Commands {
/// Switch to a worktree; create if needed
diff --git a/src/cli/step.rs b/src/cli/step.rs
index a580c4230..4253e22e6 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -60,6 +60,11 @@ pub struct SquashArgs {
pub(crate) show_prompt: bool,
}
+// Ordering: `wt merge` pipeline steps first (commit → squash → rebase → push),
+// then standalone utilities (diff, copy-ignored), then experimentals
+// (alphabetical: eval, for-each, promote, prune, relocate). Keep this enum,
+// the `## Operations` bullet list in `src/cli/mod.rs`, and the
+// `<!-- subdoc: -->` markers in the same relative order.
/// Run individual operations
#[derive(Subcommand)]
#[command(allow_external_subcommands = true)]
@@ -146,54 +151,54 @@ $ wt step squash --show-prompt | less
)]
Squash(SquashArgs),
- /// Fast-forward target to current branch
+ /// Rebase onto target
#[command(
- after_long_help = r#"Updates the local target branch (e.g., `main`) to include current commits.
+ after_long_help = r#"Rebases the current branch onto the target branch. Conflicts abort immediately; use `git rebase --abort` to recover.
## Examples
```console
-$ wt step push # Fast-forward main to current branch
-$ wt step push develop # Fast-forward develop instead
+$ wt step rebase # Rebase onto default branch
+$ wt step rebase develop # Rebase onto develop
```
-
-Similar to `git push . HEAD:<target>`, but uses `receive.denyCurrentBranch=updateInstead` internally.
"#
)]
- Push {
+ Rebase {
/// Target branch
///
/// Defaults to default branch.
#[arg(add = crate::completion::branch_value_completer())]
target: Option<String>,
-
- /// Create a merge commit (no fast-forward)
- #[arg(long = "no-ff", overrides_with = "ff")]
- no_ff: bool,
-
- /// Allow fast-forward (default)
- #[arg(long, overrides_with = "no_ff", hide = true)]
- ff: bool,
},
- /// Rebase onto target
+ /// Fast-forward target to current branch
#[command(
- after_long_help = r#"Rebases the current branch onto the target branch. Conflicts abort immediately; use `git rebase --abort` to recover.
+ after_long_help = r#"Updates the local target branch (e.g., `main`) to include current commits.
## Examples
```console
-$ wt step rebase # Rebase onto default branch
-$ wt step rebase develop # Rebase onto develop
+$ wt step push # Fast-forward main to current branch
+$ wt step push develop # Fast-forward develop instead
```
+
+Similar to `git push . HEAD:<target>`, but uses `receive.denyCurrentBranch=updateInstead` internally.
"#
)]
- Rebase {
+ Push {
/// Target branch
///
/// Defaults to default branch.
#[arg(add = crate::completion::branch_value_completer())]
target: Option<String>,
+
+ /// Create a merge commit (no fast-forward)
+ #[arg(long = "no-ff", overrides_with = "ff")]
+ no_ff: bool,
+
+ /// Allow fast-forward (default)
+ #[arg(long, overrides_with = "no_ff", hide = true)]
+ ff: bool,
},
/// Show all changes since branching
diff --git a/tests/snapshots/integration__integration_tests__help__help_config_state.snap b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
index 592efd540..3bbd2c10f 100644
--- a/tests/snapshots/integration__integration_tests__help__help_config_state.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_config_state.snap
@@ -38,15 +38,15 @@ wt config state - Manage internal data and cache
Usage: wt config state [OPTIONS] <COMMAND>
Commands:
+ get Get all stored state
+ clear Clear all stored state
default-branch Default branch detection and override
previous-branch Previous branch (for wt switch -)
- ci-status CI status cache
- marker Branch markers
logs Operation and debug logs
hints One-time hints shown in this repo
+ ci-status CI status cache
+ marker Branch markers
vars [experimental] Custom variables per branch
- get Get all stored state
- clear Clear all stored state
Options:
-h, --help
@@ -68,10 +68,10 @@ State is stored in .git/ (config entries and log files), separate from c
- default-branch: The repository's default branch (main, master, etc.)
- previous-branch: Previous branch for wt switch -
+- logs: Operation and debug logs
- ci-status: CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)
- marker: Custom status marker for a branch (shown in wt list)
- vars: [experimental] Custom variables per branch
-- logs: Operation and debug logs
Examples
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
index e31e644ee..b8d4ae008 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_long.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_long.snap
@@ -41,8 +41,8 @@ Usage: wt step [OPTIONS] <COMMAND>
Commands:
commit Stage and commit with LLM-generated message
squash Squash commits since branching
- push Fast-forward target to current branch
rebase Rebase onto target
+ push Fast-forward target to current branch
diff Show all changes since branching
copy-ignored Copy gitignored files to another worktree
eval [experimental] Evaluate a template expression
diff --git a/tests/snapshots/integration__integration_tests__help__help_step_short.snap b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
index 68e706a7d..99a627881 100644
--- a/tests/snapshots/integration__integration_tests__help__help_step_short.snap
+++ b/tests/snapshots/integration__integration_tests__help__help_step_short.snap
@@ -39,8 +39,8 @@ Usage: wt step [OPTIONS] <COMMAND>
Commands:
commit Stage and commit with LLM-generated message
squash Squash commits since branching
- push Fast-forward target to current branch
rebase Rebase onto target
+ push Fast-forward target to current branch
diff Show all changes since branching
copy-ignored Copy gitignored files to another worktree
eval [experimental] Evaluate a template expression