Skip to content

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

docs(step): link Operations index to subcommand sections (#1495)

Maximilian Roosf2ea4d65f7db
diff --git a/docs/content/step.md b/docs/content/step.md
index 03ea78702..970d9d158 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -30,17 +30,17 @@ wt step push
## Operations
-- `commit` — Stage and commit with [LLM-generated message](@/llm-commits.md)
-- `squash` — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
+- [`commit`](#wt-step-commit) — Stage and commit with [LLM-generated message](@/llm-commits.md)
+- [`squash`](#wt-step-squash) — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
- `rebase` — Rebase onto target branch
- `push` — Fast-forward target to current branch
-- `diff` — Show all changes since branching (committed, staged, unstaged, untracked)
-- `copy-ignored` — Copy gitignored files between worktrees
-- `for-each` — [experimental] Run a command in every worktree
+- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
+- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
+- [`for-each`](#wt-step-for-each) — [experimental] Run a command in every worktree
- `promote` — [experimental] Put a branch into the main worktree
-- `prune` — Remove worktrees and branches merged into the default branch
-- `relocate` — [experimental] Move worktrees to expected paths
-- `<alias>` — [experimental] Run a configured command alias
+- [`prune`](#wt-step-prune) — Remove worktrees and branches merged into the default branch
+- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
+- [`<alias>`](#aliases) — [experimental] Run a configured command alias
## Aliases
@@ -280,6 +280,73 @@ Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span>
Verbose output (-v: hooks, templates; -vv: debug report)
{% end %}
+## wt step diff
+
+Show all changes since branching. Includes committed, staged, unstaged, and untracked files.
+
+This is what `wt merge` would include — a single diff against the merge base.
+
+### Extra git diff arguments
+
+Arguments after `--` are forwarded to `git diff`:
+
+```bash
+wt step diff -- --stat
+wt step diff -- --name-only
+wt step diff -- -- '*.rs'
+```
+
+The diff is pipeable to tools like `delta`:
+
+```bash
+wt step diff | delta
+```
+
+### How it works
+
+Equivalent to:
+
+```bash
+cp "$(git rev-parse --git-dir)/index" /tmp/idx
+GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .
+GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))
+```
+
+`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.
+
+### Command reference
+
+{% terminal() %}
+wt step diff - Show all changes since branching
+
+Includes committed, staged, unstaged, and untracked files.
+
+Usage: <b><span class=c>wt step diff</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span> <b><span class=c>[--</span></b> <span class=c>&lt;EXTRA_ARGS&gt;...</span><b><span class=c>]</span></b>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[TARGET]</span>
+ Target branch
+
+ Defaults to default branch.
+
+ <span class=c>[EXTRA_ARGS]...</span>
+ Extra arguments forwarded to <b>git diff</b>
+
+<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 step copy-ignored
Copy gitignored files to another worktree. Eliminates cold starts by copying build caches and dependencies.
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 97d49349c..f10f092a0 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -21,17 +21,17 @@ wt step push
## Operations
-- `commit` — Stage and commit with [LLM-generated message](https://worktrunk.dev/llm-commits/)
-- `squash` — Squash all branch commits into one with [LLM-generated message](https://worktrunk.dev/llm-commits/)
+- [`commit`](#wt-step-commit) — Stage and commit with [LLM-generated message](https://worktrunk.dev/llm-commits/)
+- [`squash`](#wt-step-squash) — Squash all branch commits into one with [LLM-generated message](https://worktrunk.dev/llm-commits/)
- `rebase` — Rebase onto target branch
- `push` — Fast-forward target to current branch
-- `diff` — Show all changes since branching (committed, staged, unstaged, untracked)
-- `copy-ignored` — Copy gitignored files between worktrees
-- `for-each` — [experimental] Run a command in every worktree
+- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
+- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
+- [`for-each`](#wt-step-for-each) — [experimental] Run a command in every worktree
- `promote` — [experimental] Put a branch into the main worktree
-- `prune` — Remove worktrees and branches merged into the default branch
-- `relocate` — [experimental] Move worktrees to expected paths
-- `<alias>` — [experimental] Run a configured command alias
+- [`prune`](#wt-step-prune) — Remove worktrees and branches merged into the default branch
+- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
+- [`<alias>`](#aliases) — [experimental] Run a configured command alias
## Aliases
@@ -260,6 +260,71 @@ Usage: <b><span class=c>wt step squash</span></b> <span class=c>[OPTIONS]</span>
<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)
+## wt step diff
+
+Show all changes since branching. Includes committed, staged, unstaged, and untracked files.
+
+This is what `wt merge` would include — a single diff against the merge base.
+
+### Extra git diff arguments
+
+Arguments after `--` are forwarded to `git diff`:
+
+```bash
+wt step diff -- --stat
+wt step diff -- --name-only
+wt step diff -- -- '*.rs'
+```
+
+The diff is pipeable to tools like `delta`:
+
+```bash
+wt step diff | delta
+```
+
+### How it works
+
+Equivalent to:
+
+```bash
+cp "$(git rev-parse --git-dir)/index" /tmp/idx
+GIT_INDEX_FILE=/tmp/idx git add --intent-to-add .
+GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state default-branch))
+```
+
+`git diff` ignores untracked files. `git add --intent-to-add .` registers them in the index without staging their content, making them visible to `git diff`. This runs against a copy of the real index so the original is never modified.
+
+### Command reference
+
+wt step diff - Show all changes since branching
+
+Includes committed, staged, unstaged, and untracked files.
+
+Usage: <b><span class=c>wt step diff</span></b> <span class=c>[OPTIONS]</span> <span class=c>[TARGET]</span> <b><span class=c>[--</span></b> <span class=c>&lt;EXTRA_ARGS&gt;...</span><b><span class=c>]</span></b>
+
+<b><span class=g>Arguments:</span></b>
+ <span class=c>[TARGET]</span>
+ Target branch
+
+ Defaults to default branch.
+
+ <span class=c>[EXTRA_ARGS]...</span>
+ Extra arguments forwarded to <b>git diff</b>
+
+<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)
+
## wt step copy-ignored
Copy gitignored files to another worktree. Eliminates cold starts by copying build caches and dependencies.
diff --git a/src/cli/mod.rs b/src/cli/mod.rs
index 124fd1589..a25bc7dba 100644
--- a/src/cli/mod.rs
+++ b/src/cli/mod.rs
@@ -1030,17 +1030,17 @@ wt step push
## Operations
-- `commit` — Stage and commit with [LLM-generated message](@/llm-commits.md)
-- `squash` — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
+- [`commit`](#wt-step-commit) — Stage and commit with [LLM-generated message](@/llm-commits.md)
+- [`squash`](#wt-step-squash) — Squash all branch commits into one with [LLM-generated message](@/llm-commits.md)
- `rebase` — Rebase onto target branch
- `push` — Fast-forward target to current branch
-- `diff` — Show all changes since branching (committed, staged, unstaged, untracked)
-- `copy-ignored` — Copy gitignored files between worktrees
-- `for-each` — [experimental] Run a command in every worktree
+- [`diff`](#wt-step-diff) — Show all changes since branching (committed, staged, unstaged, untracked)
+- [`copy-ignored`](#wt-step-copy-ignored) — Copy gitignored files between worktrees
+- [`for-each`](#wt-step-for-each) — [experimental] Run a command in every worktree
- `promote` — [experimental] Put a branch into the main worktree
-- `prune` — Remove worktrees and branches merged into the default branch
-- `relocate` — [experimental] Move worktrees to expected paths
-- `<alias>` — [experimental] Run a configured command alias
+- [`prune`](#wt-step-prune) — Remove worktrees and branches merged into the default branch
+- [`relocate`](#wt-step-relocate) — [experimental] Move worktrees to expected paths
+- [`<alias>`](#aliases) — [experimental] Run a configured command alias
## Aliases
@@ -1070,6 +1070,7 @@ Alias names that match a built-in step command (`commit`, `squash`, etc.) are sh
- [`wt hook`](@/hook.md) — Run configured hooks
<!-- subdoc: commit -->
<!-- subdoc: squash -->
+<!-- subdoc: diff -->
<!-- subdoc: copy-ignored -->
<!-- subdoc: for-each -->
<!-- subdoc: prune -->
diff --git a/src/cli/step.rs b/src/cli/step.rs
index d63684b21..12a41cf7b 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -174,7 +174,7 @@ wt step rebase develop # Rebase onto develop
///
/// Includes committed, staged, unstaged, and untracked files.
#[command(
- after_long_help = r#"Shows all changes that `wt merge` would include: committed, staged, unstaged, and untracked files — in a single diff against the merge base.
+ after_long_help = r#"This is what `wt merge` would include — a single diff against the merge base.
## Extra git diff arguments