Noticed while investigating why cat_tools' claude-code-review.yml (a paid AI code-review workflow gated on PR CI) spent 17+ minutes reviewing cat_tools#58 (a pgxntool 2.3.0 sync PR). gh pr view reported a modest 193+56 line change across 7 files, but the raw unified diff (gh pr diff --patch | wc -l) was 8,125 lines -- almost entirely pgxntool/README.html, which gets wholesale-reformatted any time README.asc is rebuilt via asciidoctor, even for small source edits.
This isn't specific to any one review tool: any tool that consumes gh pr diff/the GitHub diff API (the code-review plugin cat_tools uses does exactly this -- confirmed by reading its command source, it never runs local git diff, only gh pr diff/gh pr view) sees the full generated-file diff, and it also just makes the "Files changed" tab noisy for human reviewers on every doc-rebuild PR.
Root cause / fix: .gitattributes already has *.html export-ignore (excludes the generated file from git archive/the pgxn dist tarball), but that's unrelated to diffing. Git has a separate, standard diff attribute -- setting it unset (-diff) tells git to treat the path as binary for diff purposes, emitting Binary files differ instead of the full patch. Confirmed against git's own docs. This is honored by GitHub's server-side diff generation (which backs both the web "Files changed" tab and the API/.diff/.patch payloads that gh pr diff fetches), unlike linguist-generated=true (checked separately) which is purely a web-UI/language-stats convention with zero effect on API-served diffs -- a dead end for this specific problem.
Proposed one-line change to .gitattributes:
-*.html export-ignore
+*.html export-ignore -diff
Since .gitattributes is vendored into every pgxntool-based extension via the sync process, this fixes the generated-doc-diff-noise problem generically, with no per-repo or per-review-tool configuration needed.
Before merging: worth confirming empirically on a canary PR (e.g. a trivial README.asc edit that regenerates README.html) that gh pr diff on that PR actually collapses to Binary files differ for the .html file -- I'm confident in the git-level mechanism per its documentation, but haven't independently confirmed GitHub's diff-serving pipeline honors it end-to-end through the API path specifically (only that it's the standard, documented behavior and that GitHub's web UI is known to render binary-attributed files as "Binary file not shown", implying the same backend).
Noticed while investigating why cat_tools'
claude-code-review.yml(a paid AI code-review workflow gated on PR CI) spent 17+ minutes reviewing cat_tools#58 (a pgxntool 2.3.0 sync PR).gh pr viewreported a modest 193+56 line change across 7 files, but the raw unified diff (gh pr diff --patch | wc -l) was 8,125 lines -- almost entirelypgxntool/README.html, which gets wholesale-reformatted any timeREADME.ascis rebuilt via asciidoctor, even for small source edits.This isn't specific to any one review tool: any tool that consumes
gh pr diff/the GitHub diff API (the code-review plugin cat_tools uses does exactly this -- confirmed by reading its command source, it never runs localgit diff, onlygh pr diff/gh pr view) sees the full generated-file diff, and it also just makes the "Files changed" tab noisy for human reviewers on every doc-rebuild PR.Root cause / fix:
.gitattributesalready has*.html export-ignore(excludes the generated file fromgit archive/the pgxn dist tarball), but that's unrelated to diffing. Git has a separate, standarddiffattribute -- setting it unset (-diff) tells git to treat the path as binary for diff purposes, emittingBinary files differinstead of the full patch. Confirmed against git's own docs. This is honored by GitHub's server-side diff generation (which backs both the web "Files changed" tab and the API/.diff/.patchpayloads thatgh pr difffetches), unlikelinguist-generated=true(checked separately) which is purely a web-UI/language-stats convention with zero effect on API-served diffs -- a dead end for this specific problem.Proposed one-line change to
.gitattributes:Since
.gitattributesis vendored into every pgxntool-based extension via the sync process, this fixes the generated-doc-diff-noise problem generically, with no per-repo or per-review-tool configuration needed.Before merging: worth confirming empirically on a canary PR (e.g. a trivial
README.ascedit that regeneratesREADME.html) thatgh pr diffon that PR actually collapses toBinary files differfor the.htmlfile -- I'm confident in the git-level mechanism per its documentation, but haven't independently confirmed GitHub's diff-serving pipeline honors it end-to-end through the API path specifically (only that it's the standard, documented behavior and that GitHub's web UI is known to render binary-attributed files as "Binary file not shown", implying the same backend).