¶Review

Reading a pull request means leaving the terminal for a browser, and gh pr diff gives you somewhere to read one but nowhere to say anything about it. cmd-r opens a window on the repository the focused session is standing in.

¶Turning it on

Two things: the switch, and a token.

cmd-, → Review turns the feature on — it is on by default — and off again, and off means the command does not exist and the window cannot be opened.

The token is a personal access token from github.com/settings, pasted into Set key… on the same pane. A fine-grained token needs pull requests: read and write — write is what sends the review — and contents: read to fetch the diff of a private repository. A classic token needs the repo scope.

It goes into the login keychain, never into settings.toml, for the same reason the model key does: that file is plain text and is the first thing anyone attaches when asking for help with a config. The row shows the ends of the token and nothing in the middle, so you can see that it saved.

¶Reading

Opened in a repository where your branch has a pull request, it goes straight to that one, because that is almost always the one you meant. Otherwise it lists what is open and return picks one.

The code is coloured as code — comments, strings, numbers and the language's own keywords, told apart by the file's extension for Rust, TypeScript and JavaScript, PHP, Python, Go, shell, TOML, JSON and CSS — and added and removed lines are a tint behind it rather than a colour on it, the way a diff reads on the web. There is no grammar behind this and no parser: a diff shows one line at a time with no idea what came before it, so a comment that opened on an earlier line is not known to be one. Four things a reader's eye uses to find its way, and nothing that pretends to more. A file it does not know comes out plain.

The files are listed down the left with what each change adds and removes. A filled dot marks a file you have commented on, an open one a file somebody else has. Long paths are cut from the left, because the end of a path is the part that tells files apart; the full one is above the diff.

¶What has already been said

Comments other people have left are shown under the lines they are about, with who said them. Without this a reviewer is the only person in the room: they leave a comment somebody else left an hour ago, or miss that their question was answered in a thread they never saw.

A comment on a line that has changed since it was written has nowhere to be drawn — GitHub's word for it is outdated — and the header says how many of those a file has rather than pretending to know where they go.

r on a line with a thread answers in it, rather than starting a new one beside it. A reply is held with the rest of your comments until you send, and then goes into the thread it answers — after the review itself, so that if anything fails it is a reply that did not land and not your verdict. Replies are drawn set in a little under what they answer, and one you have written but not sent says so. The general conversation under the pull request, as opposed to on its lines, is not shown; this window is about the diff.

¶Asking the model

cmd-e on a line or a selection sends those lines — with a little context, in diff notation — to the model set up for AI mode, and asks what is worth saying about them as a review comment. The answer does not become a comment. It opens the comment field with itself already typed, and the person reads it, changes it, and presses return — or presses escape and it is gone.

That is this window's version of the approval gate. The model gets the first word and the person gets the last, and nothing reaches the author of the change without a human having read it. A model that finds nothing worth saying says so in a line, and that is shown rather than turned into an empty comment.

¶The conversation

d puts the conversation where the diff was, and d again puts the diff back. The description comes first, because it is why the change exists; then everything said about the whole in the order it was said — the comments under the pull request, and the summary of every review with what it decided, approved and requested changes in the accent colour. A review that said nothing and decided nothing is left out: it is the container GitHub put somebody's line comments in, and the line comments are already on their lines.

Nothing here is written to from this window except the summary you send with your own review. Answering in the conversation is a browser's job for now.

¶Selecting a range

shift-↓ from a line selects downwards, shift-↑ upwards, and c then comments on the whole run. Moving without shift lets the selection go, the way every editor does, and escape does too.

The comment is addressed to the side the cursor is on. A selection that straddles a removed block and the lines that replaced it is two comments in GitHub's model, and the lines on the other side are left out rather than mixed in. It comes out the same whichever direction it was made in, because GitHub wants the start below the end.

¶Comments wait for the review

Nothing is sent until you send the whole thing. That is the difference between a review and eleven interruptions: whoever wrote the branch gets one conversation and one notification, and you can change your mind about a comment before anyone has read it.

A comment on a removed line is left on the old file, one on an added or unchanged line on the new file — which is what GitHub's own interface does when you click a line. Where exactly it lands is decided before it is sent, from the hunk headers, and it is the part of this worth being careful about: a comment that arrives one line above the thing it is about is worse than no comment.

¶Nothing is installed for this

No gh, and no git either. Which repository a session is in and which branch it is on are two files — .git/config and .git/HEAD — and eterm reads them itself. A .git that is a file rather than a directory, which is what a worktree or a submodule has, is followed to the real one.

Only the origin remote counts, and only when it points at GitHub. A checkout with several remotes is a question this cannot answer on its own, and answering it wrongly would send your review to somebody else's fork.

¶What it does not do yet

• The model sees one hunk at a time. It is not shown the whole pull request, so it cannot tell you the change in one file breaks a caller in another.
• Nothing is written back to the branch. No suggested changes, no approving from a notification.
• The conversation is read-only. You see it, and your review's summary joins it when you send; a comment in it that is not a review is a browser's job.