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.mdindex 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 cacheUsage: <b><span class=c>wt config state</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 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 '-h')++<b><span class=g>Global Options:</span></b>+ <b><span class=c>-C</span></b><span class=c> <path></span>+ Working directory for this command++ <b><span class=c>--config</span></b><span class=c> <path></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-statusCI 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 '-h')--<b><span class=g>Global Options:</span></b>- <b><span class=c>-C</span></b><span class=c> <path></span>- Working directory for this command-- <b><span class=c>--config</span></b><span class=c> <path></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.mdindex 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 expressiondiff --git a/skills/worktrunk/reference/config.md b/skills/worktrunk/reference/config.mdindex 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 cacheUsage: wt config state [OPTIONS] <COMMAND>Commands:+ get Get all stored state+ clear Clear all stored statedefault-branch Default branch detection and overrideprevious-branch Previous branch (for wt switch -)- ci-status CI status cache- marker Branch markerslogs Operation and debug logshints One-time hints shown in this repo+ ci-status CI status cache+ marker Branch markersvars [experimental] Custom variables per branch- get Get all stored state- clear Clear all stored stateOptions:-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-statusCI 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.mdindex 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 messagesquash Squash commits since branching- push Fast-forward target to current branchrebase Rebase onto target+ push Fast-forward target to current branchdiff Show all changes since branchingcopy-ignored Copy gitignored files to another worktreeeval [experimental] Evaluate a template expressiondiff --git a/src/cli/config.rs b/src/cli/config.rsindex 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 hintaction: 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 mainClear,}+// Ordering: CRUD — get, set, clear.#[derive(Subcommand)]pub enum PreviousBranchAction {/// Get the previous branch@@ -854,6 +873,7 @@ $ wt config state previous-branch set featureClear,}+// 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=featureClear,}+// 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 valuediff --git a/src/cli/hook.rs b/src/cli/hook.rsindex 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.rsindex 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 neededdiff --git a/src/cli/step.rs b/src/cli/step.rsindex 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 branchingdiff --git a/tests/snapshots/integration__integration_tests__help__help_config_state.snap b/tests/snapshots/integration__integration_tests__help__help_config_state.snapindex 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 cacheUsage: [1m[36mwt config state[0m [36m[OPTIONS][0m [36m<COMMAND>[0m[1m[32mCommands:[0m+ [1m[36mget[0m Get all stored state+ [1m[36mclear[0m Clear all stored state[1m[36mdefault-branch[0m Default branch detection and override[1m[36mprevious-branch[0m Previous branch (for [1mwt switch -[0m)- [1m[36mci-status[0m CI status cache- [1m[36mmarker[0m Branch markers[1m[36mlogs[0m Operation and debug logs[1m[36mhints[0m One-time hints shown in this repo+ [1m[36mci-status[0m CI status cache+ [1m[36mmarker[0m Branch markers[1m[36mvars[0m [experimental] Custom variables per branch- [1m[36mget[0m Get all stored state- [1m[36mclear[0m Clear all stored state[1m[32mOptions:[0m[1m[36m-h[0m, [1m[36m--help[0m@@ -68,10 +68,10 @@ State is stored in [2m.git/[0m (config entries and log files), separate from c- [1mdefault-branch[0m: The repository's default branch ([2mmain[0m, [2mmaster[0m, etc.)- [1mprevious-branch[0m: Previous branch for [2mwt switch -[0m+- [1mlogs[0m: Operation and debug logs- [1mci-status[0m: CI/PR status for a branch (passed, running, failed, conflicts, no-ci, error)- [1mmarker[0m: Custom status marker for a branch (shown in [2mwt list[0m)- [1mvars[0m: [experimental] Custom variables per branch-- [1mlogs[0m: Operation and debug logs[1m[32mExamples[0mdiff --git a/tests/snapshots/integration__integration_tests__help__help_step_long.snap b/tests/snapshots/integration__integration_tests__help__help_step_long.snapindex 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: [1m[36mwt step[0m [36m[OPTIONS][0m [36m<COMMAND>[0m[1m[32mCommands:[0m[1m[36mcommit[0m Stage and commit with LLM-generated message[1m[36msquash[0m Squash commits since branching- [1m[36mpush[0m Fast-forward target to current branch[1m[36mrebase[0m Rebase onto target+ [1m[36mpush[0m Fast-forward target to current branch[1m[36mdiff[0m Show all changes since branching[1m[36mcopy-ignored[0m Copy gitignored files to another worktree[1m[36meval[0m [experimental] Evaluate a template expressiondiff --git a/tests/snapshots/integration__integration_tests__help__help_step_short.snap b/tests/snapshots/integration__integration_tests__help__help_step_short.snapindex 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: [1m[36mwt step[0m [36m[OPTIONS][0m [36m<COMMAND>[0m[1m[32mCommands:[0m[1m[36mcommit[0m Stage and commit with LLM-generated message[1m[36msquash[0m Squash commits since branching- [1m[36mpush[0m Fast-forward target to current branch[1m[36mrebase[0m Rebase onto target+ [1m[36mpush[0m Fast-forward target to current branch[1m[36mdiff[0m Show all changes since branching[1m[36mcopy-ignored[0m Copy gitignored files to another worktree[1m[36meval[0m [experimental] Evaluate a template expression