Skip to content

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

feat(step): add --branch arg to wt step diff (#2995)

Worktrunk Botb41e210f8265
diff --git a/docs/content/step.md b/docs/content/step.md
index 5ad9126e7..543611ea3 100644
--- a/docs/content/step.md
+++ b/docs/content/step.md
@@ -283,6 +283,14 @@ Show all changes since branching. Includes committed, staged, unstaged, and untr
This is what `wt merge` would include — a single diff against the merge base.
+### Operating on another worktree
+
+`--branch` diffs another worktree's branch without leaving the current one:
+
+{{ terminal(cmd="wt step diff --branch feature") }}
+
+The branch must have a checked-out worktree.
+
### Extra git diff arguments
Arguments after `--` are forwarded to `git diff`:
@@ -320,6 +328,9 @@ Usage: <b><span class=c>wt step diff</span></b> <span class=c>[OPTIONS]</span> <
Extra arguments forwarded to <b>git diff</b>
<b><span class=g>Options:</span></b>
+ <b><span class=c>-b</span></b>, <b><span class=c>--branch</span></b><span class=c> &lt;BRANCH&gt;</span>
+ Branch to operate on (defaults to current worktree)
+
<b><span class=c>-h</span></b>, <b><span class=c>--help</span></b>
Print help (see a summary with &#39;-h&#39;)
diff --git a/skills/worktrunk/reference/step.md b/skills/worktrunk/reference/step.md
index 1c894e08b..5d00ccb45 100644
--- a/skills/worktrunk/reference/step.md
+++ b/skills/worktrunk/reference/step.md
@@ -282,6 +282,16 @@ Show all changes since branching. Includes committed, staged, unstaged, and untr
This is what `wt merge` would include — a single diff against the merge base.
+### Operating on another worktree
+
+`--branch` diffs another worktree's branch without leaving the current one:
+
+```bash
+$ wt step diff --branch feature
+```
+
+The branch must have a checked-out worktree.
+
### Extra git diff arguments
Arguments after `--` are forwarded to `git diff`:
@@ -329,6 +339,9 @@ Arguments:
Extra arguments forwarded to git diff
Options:
+ -b, --branch <BRANCH>
+ Branch to operate on (defaults to current worktree)
+
-h, --help
Print help (see a summary with '-h')
diff --git a/src/cli/step.rs b/src/cli/step.rs
index f6d0d29f1..0e0222375 100644
--- a/src/cli/step.rs
+++ b/src/cli/step.rs
@@ -217,6 +217,16 @@ Similar to `git push . HEAD:<target>`, but uses `receive.denyCurrentBranch=updat
#[command(
after_long_help = r#"This is what `wt merge` would include — a single diff against the merge base.
+## Operating on another worktree
+
+`--branch` diffs another worktree's branch without leaving the current one:
+
+```console
+$ wt step diff --branch feature
+```
+
+The branch must have a checked-out worktree.
+
## Extra git diff arguments
Arguments after `--` are forwarded to `git diff`:
@@ -253,6 +263,10 @@ $ GIT_INDEX_FILE=/tmp/idx git diff $(git merge-base HEAD $(wt config state defau
#[arg(add = crate::completion::branch_value_completer())]
target: Option<String>,
+ /// Branch to operate on (defaults to current worktree)
+ #[arg(short, long, add = crate::completion::worktree_only_completer())]
+ branch: Option<String>,
+
/// Extra arguments forwarded to `git diff`
#[arg(last = true)]
extra_args: Vec<String>,
diff --git a/src/commands/step/diff.rs b/src/commands/step/diff.rs
index 8d49d6a53..340d606a9 100644
--- a/src/commands/step/diff.rs
+++ b/src/commands/step/diff.rs
@@ -9,8 +9,28 @@ use worktrunk::git::Repository;
/// and untracked files in a single diff. Stages untracked files into a temp index
/// (`WorkingTree::temp_index`) so they appear in the diff without mutating the
/// real index — git's stat cache stays warm and tracked files aren't re-hashed.
-pub fn step_diff(target: Option<&str>, extra_args: &[String]) -> anyhow::Result<()> {
- let repo = Repository::current()?;
+///
+/// `branch` selects which worktree to diff: when `Some`, the repo is rooted at
+/// that branch's worktree so the diff (and its target resolution) operate there
+/// rather than on the current directory. The branch must have a checked-out
+/// worktree.
+pub fn step_diff(
+ branch: Option<&str>,
+ target: Option<&str>,
+ extra_args: &[String],
+) -> anyhow::Result<()> {
+ let repo = match branch {
+ Some(b) => {
+ let worktree_path =
+ Repository::current()?
+ .worktree_for_branch(b)?
+ .ok_or_else(|| worktrunk::git::GitError::WorktreeNotFound {
+ branch: b.to_string(),
+ })?;
+ Repository::at(&worktree_path)?
+ }
+ None => Repository::current()?,
+ };
let wt = repo.current_worktree();
let integration_target = repo.require_target_ref(target)?;
diff --git a/src/main.rs b/src/main.rs
index 67eaec339..85a1fd658 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -365,7 +365,11 @@ fn handle_step_command(action: StepCommand, yes: bool) -> anyhow::Result<()> {
}
Ok(())
}
- StepCommand::Diff { target, extra_args } => step_diff(target.as_deref(), &extra_args),
+ StepCommand::Diff {
+ target,
+ branch,
+ extra_args,
+ } => step_diff(branch.as_deref(), target.as_deref(), &extra_args),
StepCommand::CopyIgnored {
from,
to,
diff --git a/tests/integration_tests/step_diff.rs b/tests/integration_tests/step_diff.rs
index 8710150ef..e1272bcd6 100644
--- a/tests/integration_tests/step_diff.rs
+++ b/tests/integration_tests/step_diff.rs
@@ -142,6 +142,39 @@ fn test_step_diff_explicit_target(mut repo: TestRepo) {
));
}
+/// `--branch` diffs another worktree's branch from a different worktree
+#[rstest]
+fn test_step_diff_branch_arg(mut repo: TestRepo) {
+ setup_feature_with_commit(&mut repo);
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ // Run from the main worktree (repo root, cwd = None), targeting `feature`.
+ // Output should match `test_step_diff_committed_changes`, which runs the
+ // same diff from inside the feature worktree.
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["diff", "--branch", "feature"],
+ None,
+ ));
+}
+
+/// `--branch` for a branch without a worktree errors
+#[rstest]
+fn test_step_diff_branch_no_worktree(repo: TestRepo) {
+ repo.run_git(&["branch", "lonely"]);
+ let settings = setup_snapshot_settings(&repo);
+ let _guard = settings.bind_to_scope();
+
+ assert_cmd_snapshot!(make_snapshot_cmd(
+ &repo,
+ "step",
+ &["diff", "--branch", "lonely"],
+ None,
+ ));
+}
+
fn git_status(repo: &TestRepo, dir: &Path) -> String {
let output = repo
.git_command()
diff --git a/tests/snapshots/integration__integration_tests__step_diff__step_diff_branch_arg.snap b/tests/snapshots/integration__integration_tests__step_diff__step_diff_branch_arg.snap
new file mode 100644
index 000000000..e68b725dd
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_diff__step_diff_branch_arg.snap
@@ -0,0 +1,67 @@
+---
+source: tests/integration_tests/step_diff.rs
+info:
+ program: wt
+ args:
+ - step
+ - diff
+ - "--branch"
+ - feature
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMON_DIR: ""
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_DIR: ""
+ GIT_EDITOR: ""
+ GIT_INDEX_FILE: ""
+ GIT_OBJECT_DIRECTORY: ""
+ GIT_TERMINAL_PROMPT: "0"
+ GIT_WORK_TREE: ""
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: true
+exit_code: 0
+----- stdout -----
+diff --git a/feature.txt b/feature.txt
+new file mode 100644
+index 0000000..47a4d0c
+--- /dev/null
++++ b/feature.txt
+@@ -0,0 +1 @@
++feature content
+\ No newline at end of file
+
+----- stderr -----
diff --git a/tests/snapshots/integration__integration_tests__step_diff__step_diff_branch_no_worktree.snap b/tests/snapshots/integration__integration_tests__step_diff__step_diff_branch_no_worktree.snap
new file mode 100644
index 000000000..0c215ff32
--- /dev/null
+++ b/tests/snapshots/integration__integration_tests__step_diff__step_diff_branch_no_worktree.snap
@@ -0,0 +1,61 @@
+---
+source: tests/integration_tests/step_diff.rs
+info:
+ program: wt
+ args:
+ - step
+ - diff
+ - "--branch"
+ - lonely
+ env:
+ APPDATA: "[TEST_CONFIG_HOME]"
+ CLICOLOR_FORCE: "1"
+ COLUMNS: "500"
+ GIT_AUTHOR_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMITTER_DATE: "2025-01-01T00:00:00Z"
+ GIT_COMMON_DIR: ""
+ GIT_CONFIG_GLOBAL: "[TEST_GIT_CONFIG]"
+ GIT_CONFIG_SYSTEM: /dev/null
+ GIT_DIR: ""
+ GIT_EDITOR: ""
+ GIT_INDEX_FILE: ""
+ GIT_OBJECT_DIRECTORY: ""
+ GIT_TERMINAL_PROMPT: "0"
+ GIT_WORK_TREE: ""
+ HOME: "[TEST_HOME]"
+ LANG: C
+ LC_ALL: C
+ LLVM_PROFILE_FILE: "[LLVM_PROFILE_FILE]"
+ MOCK_CONFIG_DIR: "[MOCK_CONFIG_DIR]"
+ NO_COLOR: ""
+ OPENCODE_CONFIG_DIR: "[TEST_OPENCODE_CONFIG]"
+ PATH: "[PATH]"
+ PSModulePath: ""
+ SHELL: ""
+ TERM: alacritty
+ USERPROFILE: "[TEST_HOME]"
+ WORKTRUNK_APPROVALS_PATH: "[TEST_APPROVALS]"
+ WORKTRUNK_CONFIG_PATH: "[TEST_CONFIG]"
+ WORKTRUNK_SYSTEM_CONFIG_PATH: "[TEST_SYSTEM_CONFIG]"
+ WORKTRUNK_TEST_BASH_INSTALLED: "0"
+ WORKTRUNK_TEST_CLAUDE_INSTALLED: "0"
+ WORKTRUNK_TEST_CODEX_INSTALLED: "0"
+ WORKTRUNK_TEST_DELAYED_STREAM_MS: "-1"
+ WORKTRUNK_TEST_EPOCH: "1735776000"
+ WORKTRUNK_TEST_FISH_INSTALLED: "0"
+ WORKTRUNK_TEST_GEMINI_INSTALLED: "0"
+ WORKTRUNK_TEST_NUSHELL_ENV: "0"
+ WORKTRUNK_TEST_OPENCODE_INSTALLED: "0"
+ WORKTRUNK_TEST_POWERSHELL_ENV: "0"
+ WORKTRUNK_TEST_POWERSHELL_INSTALLED: "0"
+ WORKTRUNK_TEST_SKIP_URL_HEALTH_CHECK: "1"
+ WORKTRUNK_TEST_ZSH_INSTALLED: "0"
+ XDG_CONFIG_HOME: "[TEST_CONFIG_HOME]"
+---
+success: false
+exit_code: 1
+----- stdout -----
+
+----- stderr -----
+✗ Branch lonely has no worktree
+↳ To create a worktree, run wt switch lonely