Diff().Staged().Between(a, b) and Patch().Staged().Between(a, b) fail with git's usage screen (exit 129) instead of being refused up front

[matt-edmondson]

What's wrong

GitDiffBuilder (GitIntegration/Builders/GitDiffBuilder.cs, --cached added at ~L172) and GitPatchBuilder (GitIntegration/Builders/GitPatchBuilder.cs ~L428-444) add --cached and both Between revisions to the argument vector unconditionally. git rejects that combination:

git diff --cached HEAD~1 HEAD   # exit 129, prints the whole `git diff` usage text

The caller gets a GitCommandException whose Message is git's full usage screen, which says nothing about which builder calls conflict.

Why it matters

The library already refuses contradictory builder combinations before running git. Examples are the checkout guard (closed #91) and the fetch AllRemotes/FromRemote guard. The comment at GitDiffBuilder.cs:88 shows the same intent for Against + Between. Staged() + Between() is the remaining gap. It is also easy to hit, since Staged() reads as an independent modifier.

Acceptance criteria

• Building or executing a diff or patch with both Staged() and Between(a, b) throws InvalidOperationException naming the conflict. Report it the same way the checkout guard does.
• Staged().Against(rev) stays allowed, since --cached <rev> is valid git.
• Fix the Staged() XML doc, which says "against HEAD" even when Against(rev) names a different revision.
• Add tests for both builders.

Not the same as #168, which is about the trailing -- after revisions.

[matt-edmondson]

Triage

• Category: Improvement (API guard / error quality)
• Priority: Low. The call already fails. The issue is only that the error is git's usage screen rather than a clear InvalidOperationException.
• Area / suggested owner: Builders (GitDiffBuilder, GitPatchBuilder).
• Duplicates / related: It follows the existing guard pattern (closed GitCheckoutBuilder does not reject CreatingBranch() + Detach(), which git refuses at runtime #91, and the fetch AllRemotes/FromRemote guard). It is distinct from Log/RevList/Diff/Patch fail with "ambiguous argument" when a branch shares a directory's name, and silently return path-filtered results for a missing revision: no trailing -- after revisions #168 (the trailing --).
• In progress: No open PR covers this.
• Next step: Add a Staged() + Between() conflict guard in both builders, keep Staged().Against(rev) working, and correct the Staged() XML doc. Add tests for both builders.

---

Generated by Claude Code