docs: use exact ranges for last-commit reviews - #347
Merged
Merged
Conversation
(*Jj).translateRef has one broad HasPrefix("HEAD^") branch answering two
different inputs with parents(@-). HEAD^! is git syntax jj does not support and
becomes a grandparent-to-working-copy diff with no error, the only backend that
fails silently. HEAD^N for N>1 is a knowingly approximate parent set.
Found while investigating #335, not caused by it. The fix is left open because
rejecting HEAD^N is a behavior change, not a bug fix.
There was a problem hiding this comment.
🟡 Changes recommended
The pi skill doc still includes a recommended /revdiff HEAD~1 example elsewhere, which can reintroduce the same “last commit” ambiguity this PR is correcting.
Once you've addressed the issues Copilot identified, you can request another Copilot review.
Pull request overview
Updates revdiff documentation and pi skill guidance so “review last N commits” examples use explicit two-ref ranges (HEAD~N HEAD) rather than single-ref forms that diff against the working tree, aligning docs/skill behavior with revdiff’s positional semantics across git/hg/jj.
Changes:
- Replace “last commit / last 3 commits” examples with
HEAD~1 HEAD/HEAD~3 HEADacross site docs, READMEs, and usage references. - Update the pi revdiff skill’s natural-language commit-count mapping to resolve to two refs for exact commit ranges.
- Add a backlog note documenting a jj
HEAD^translation edge case (HEAD^!swallowed by a broadHasPrefix("HEAD^")branch).
File summaries
| File | Description |
|---|---|
| site/index.html | Updates landing-page examples to use exact two-ref ranges for “last commit / last 3 commits”. |
| site/docs.html | Updates documentation examples and adds an explicit “exact last commit” positional form. |
| README.md | Aligns top-level README examples and positional-forms list with two-ref ranges for exact commit review. |
| plugins/pi/skills/revdiff/SKILL.md | Adjusts natural-language commit-count resolution to output HEAD~N HEAD. |
| plugins/pi/README.md | Updates pi package usage examples to use HEAD~1 HEAD. |
| plugins/codex/skills/revdiff/references/usage.md | Updates Codex skill usage reference to use HEAD~1 HEAD. |
| plugins/codex/README.md | Updates Codex README example to use HEAD~3 HEAD. |
| docs/backlog/jj-head-caret-refs-silently-mistranslated.md | Adds a documented backlog item about jj caret-ref mistranslation behavior. |
| .claude-plugin/skills/revdiff/references/usage.md | Updates Claude plugin usage reference to use HEAD~1 HEAD. |
Review details
- Files reviewed: 9/9 changed files
- Comments generated: 1
- Review effort level: Lite
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
19
to
22
| - Accept natural language. Resolve the user's requested target to concrete revdiff args before launching. | ||
| - If the request identifies another working directory (for example `in ~/source/repo`), use that directory for any git/ref/path resolution, omit that directory phrase from the revdiff args, and pass the directory as the `revdiff_review` tool's `cwd` parameter. | ||
| - For commit-count requests, use the matching git rev: `prev commit`, `previous commit`, `last commit` → `HEAD~1`; `head-3`, `head 3`, `HEAD~3`, `previous 3 commits`, `last 3 commits` → `HEAD~3`. | ||
| - For natural-language commit-count requests, use two refs: `prev commit`, `previous commit`, `last commit` → `HEAD~1 HEAD`; `head-3`, `head 3`, `previous 3 commits`, `last 3 commits` → `HEAD~3 HEAD`. | ||
| - For tag requests, resolve the actual tag first. `last tag` or `latest tag` → run `git describe --tags --abbrev=0`, then pass that tag as `args`. |
The natural-language rule above resolves "last commit" to HEAD~1 HEAD, so listing only the bare ref left the same file recommending two different spellings for the same request. The bare form stays: an explicit single ref against the working tree is a legitimate thing to type. Raised by Copilot on #347.
Deploying revdiff with
|
| Latest commit: |
e94566c
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://473faa80.revdiff.pages.dev |
| Branch Preview URL: | https://fix-last-commit-docs.revdiff.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
revdiff HEAD~1compares a ref against the working tree, so it means "the last commit plus whatever is uncommitted", not "the last commit". The docs said otherwise in 14 places across 8 files, and pi's natural-language rule turned "last commit" into that same bare ref.Every claim of the form "review last N commits" now uses the two-ref form,
HEAD~1 HEADandHEAD~3 HEAD, which resolves to exactly those commits on git, hg and jj. The positional-forms lists in README and the site gainrevdiff HEAD~1 HEADas the way to isolate a single commit.pi's mapping is the only executable change: semantic phrases now resolve to two refs, while an explicitly typed
HEAD~3stays on the pass-through rule so its documented meaning is unchanged.Deliberately untouched: the clean-tree-gated detectors already pick a bare
HEAD~1correctly, so all threedetect-ref.sh,plugins/pi/extensions/revdiff.ts, and the Claude and CodexSKILL.mdlines that say "on main + clean" are unchanged. So are the round-trip examples and thegit show HEAD~1:README.mdstdin examples, which genuinely mean ref-versus-working-tree.Second commit files a backlog item found while investigating:
(*Jj).translateRefhas one broadHasPrefix("HEAD^")branch that answers bothHEAD^!andHEAD^Nwithparents(@-), so on jj aHEAD^!review renders a wrong diff and raises nothing. The fix is left open there because rejectingHEAD^Nis a behavior change rather than a bug fix.Docs only, no Go changes. Related to #335.