Comment on unchanged lines and untouched files during review

[flazouh]

The pain

Commenting on a pull request is bound to the lines GitHub put in the diff. You cannot leave a review comment on an unchanged line, or on a file the PR did not touch, even when that is exactly where the change should have happened.

This is the single most-upvoted review request on GitHub's own community board.

• community #9099 "Allow PR reviewers to comment on unchanged files" — 1303 upvotes (read 2026-08-31)

"There are situations where a change needs to be made in another file that was overlooked. (e.g. 'This file needs to be updated in a similar fashion to file B which you updated.')"

Where GitQuiet is today

GitQuiet already expands unchanged context (the context / expansion knobs), and it posts each comment immediately rather than holding a pending batch. But a comment still has to land on a line that is part of the rendered diff, so an unchanged file that the PR never touched has nowhere to receive one.

Proposed direction

• Let a reviewer open any file in the repository at the PR's head from inside review, and leave a line comment there, carried back through GitHub's review API as a comment anchored to that path and line.
• At minimum, let a reviewer comment on any expanded context line, not only added/removed lines.

Scope and API limits to confirm: GitHub's review-comment API anchors to a position in the diff; commenting on a file outside the diff may need a top-level review comment that references the path, rather than an inline thread.

Source: research/review-mode-pain-points.md and research/ai-pr-review-pain-points in gitquiet-notes.

[flazouh]

Step 0 of docs/plan/comment-anywhere.md is built, in 30f556e on stand-on-body.

The plan's sharpest finding needed no new write at all. Colleagues using GitHub's own Files changed page comment on any line of a changed file today; GitHub still sends only that file's hunks, so those threads arrive naming a line nothing here drew. They were handed to the renderer with no row to hang in, and the file read as though nobody had said anything about it.

threadsOn in src/ui/threads.ts now splits a file's threads by whether its diff holds the line they hang on. Out-of-reach ones are drawn above the file with their line said in words, in the dress the note rows already wear. The judgement is made on the last line of a range, because that is where a row hangs, and nothing is claimed until the diff has landed. Out of Reach is in CONTEXT.md, and the QA mock carries one such thread so it stays visible.

Also re-read while there: step 1 was already built. NewComment carries a side, Shell.tsx sends anchorSideOf(note.side), and the gateway writes asTheyNameIt(note.side) rather than a hardcoded "right". The plan's status line now says so. The endSide half is still open: a drag crossing the two halves still collapses to one side.

What this does not do, and what it waits on: steps 3, 4 and 5 all need step 2, one hour against a scratch pull request to settle three things GitHub's routes have never been asked here — whether create_review_comment takes a line below the hunks, how the file-level subject type is spelled, and the refusal for a path outside the comparison.

Gates: typecheck, lint, fixture scrub, 4329 tests, production build, QA shot. Both new pane tests were run against the old behaviour first and failed.

[flazouh]

Step 2 is done, in 5471bf0. Run against flazouh/ghpro-scratch#14 (private, now closed) from a signed-in browser: one line changed near the top of a 200-line file, so its only hunk covers lines 1 to 6.

Sent	Answer	Marker
line: 150, far below the hunks	200, real thread	R150, with ctx: [147, 153]
subjectType: "file", no line	200, thread says "file"	FILE
subjectType: "FILE", no line	200, thread says "file"	FILE
path the PR did not change	200, real thread	none, the file has no diffSummaries entry
path in no tree	422 {"error":"Path could not be resolved."}	—

Q1, answered yes, with a bonus. The route was never the obstacle. Every out-of-hunk marker carries ctx, GitHub's own answer to how far to reveal around it: three lines either side. That is the hint step 3 needs, and it means step 3 is unblocked. No per-repository rollout was involved; the route took the line on a repository whose own page offers no such gesture.

Q2, both spellings work and both come back as "file". Send lower case. The marker is upper-case FILE, which spotAt already drops.

Q3, the surprise: the route accepts a path the pull request never touched. GitHub's changelog says these comments "can only be added to files already changed" — that describes their client, not their server. So section 3 of the plan was wrong and is corrected in place.

The conclusion it drew survives on a weaker reason. Such a thread is real and every reader finds it on the Conversation page, but the file gets no diffSummaries entry, so it is drawn in no diff, and the Conversation page never says which file it is about. Not invisible; unplaceable. Section 5 is flagged for a re-read before it is built.

Everything is recorded in docs/spec/github-write-api.md under "What create_review_comment takes, measured", in the style of the verification tables already there.

[flazouh]

Step 3 is built, in 58cc46e. A reader can now reveal the lines GitHub leaves out between the hunks, which is what discussion #4452 (2,352 upvotes) asks for.

How it is put together. src/domain/revealing.ts says which halves a file needs: both for an edit, the new one alone for an addition, none for a deletion. src/app/revealing.ts fetches them off the raw route, keyed by commit so a file revealed twice is read once, and fails rather than answering with half of one — before: null for a file that had an old half redraws the whole of it as an addition. src/diff/engine.ts hands Pierre a loadDiffFiles it calls on the press, so a file nobody reveals costs no request. Reveal is in CONTEXT.md.

Two things the QA stage caught that no unit test could, because the tests stub the renderer:

1. expandUnchanged is not the switch for this. It renders every line of every file from the first paint, and turning it on took the shots stage from ten seconds to over ten minutes on a seven-file pull request. The separators between the hunks already carry the expansion; loadDiffFiles is what they call. The option stays off.
2. Pierre throws deletionLine and additionLine are null when the halves it is handed do not reconcile with the patch it parsed. The QA mock now builds its halves from each file's own patch, so the stage keeps exercising the real renderer rather than a stub.

Verified end to end in a browser against the stage, not only by unit test: pressing a separator's down arrow drew exactly expansionLineCount lines, and Expand all drew the remaining 2,416.

Gates: typecheck, lint, 4343 tests, production build, QA shot.

Left for later: steps 4 and 5. Step 2 settled both of their unknowns, and step 5 in particular needs a re-read against what it found — the route accepts a comment on an untouched file, but the file gets no diffSummaries entry, so it is drawn in no diff.

[flazouh]

Step 4 is built, in 516aee8 and df45199 on the file-remarks branch.

A thread can be about a whole file now, both read and written. ThreadAnchor and NewComment nest their lines under the path, and null there is a File Remark; the gateway sends a subject type instead of a line, using the lower-case spelling step 2 measured. The pane draws such a thread above the file, in the section that already held what GitHub leaves out of a diff, and a quiet line there opens a box to write one.

The plan said the reading half needed nothing. It did. spotAt dropped a FILE marker and threw away the path beside it, so a File Remark reached the conversation naming no file at all. It keeps the path now.

One thing worth recording for anyone touching these types. lines was written optional at first, the way LookingAt has it. That quietly accepted every anchor still written the old flat way — {path, side, line, startLine} satisfies {path, lines?}, because the required field is there and the rest are excess — so each one read as a File Remark and every thread in the shots stage drew as one. The type checker was happy and 4,374 tests passed. bun run qa caught it in a picture. It is required-and-nullable now, and making it strict found the mock that caused it plus eight other sites that would have been wrong.

A second, smaller one: Note had a Save draft button a File Remark cannot honour, since a draft hangs on the lines it is about. Hidden rather than left to discard quietly.

Gates: lint, compile, compile:desktop, 4374 tests, production build, QA shot.

Only step 5 is left, and it needs a decision rather than a build.

[flazouh]

Step 5's foundation is built and its premise is measured, in f679d05 on the quoting branch.

The premise was worth checking and it holds. I posted a permalink into flazouh/ghpro-scratch#14 and read GitHub's own HTML back. The address is server-rendered into a box carrying the file's name, Line 120 in b11a958 with the commit linked, and the line itself quoted. A range quotes the run. So the form this interface can offer for an unchanged file names the file, the line and the commit, where the review comment GitHub does accept names none of them. Recorded in docs/spec/github-write-api.md.

quoting lives in src/domain/fileAt.ts rather than the new quoting.ts the plan named: that file already owns every other address of a file, and a second module would have duplicated its escaping. It replaced the shape Shell.tsx built inline for its log links.

What is left is a UI shape question, not a technical one. Two ways to let a reader reach an untouched file and quote it, and they land in different places:

1. A path picker in the conversation's box. Type to filter every path (one treePaths request), pick one, name a line range, and the permalink goes into what you are writing. Smaller, about 3 hours. The cost is threading one prop through Shell, About, Conversation and Saying, four components that otherwise do not care.
2. An untouched file opened in the review's own rail. The plan's version. The rail gains a way to add any path, the file draws whole through the machinery step 3 built, and marking lines there posts a Remark quoting them. About a day, but it lands almost entirely inside Files/FileBrowser, which already hold the drawing and the picking, and the reader gets to read the file rather than type its path.

I would take 2. It is more work but it is where the reader already is, and it avoids carrying a prop through four layers to reach a text box.