Chapter 5: Pull requests and review
What this chapter covers
Somebody has asked you to review their change, or you want to get your own change merged. On the website that means a long page of code with comments wedged between the lines, and a merge box that speaks in colours and icons.
In this chapter you find the pull requests that need you, read one as an outline you can walk, read its changes line by line, comment on a line or a range, suggest a change, and send your review. Then you find out whether it can merge, and why not, and merge it, one or several at a time.
By the end you will know how to review a pull request from start to finish without the website, and how to get one merged safely.
Reading works signed out. Everything that writes needs a signed-in account. Merging, re-running and the other changes also need your account’s Workbench level to allow them: Organize or Full. Chapter 13 explains the levels.
In QUILL Lite, which works as a guest, you can read every part of a review. The commands that write say they need a signed-in account.
Finding the pull requests that need you
Pull requests live in three places in the GitHub Workbench’s tree:
- Needs My Attention > Review Requests lists every
pull request someone has asked you to review, in any repository. It
holds two kinds: those that ask you by name, and those that ask a team
you belong to. A team’s row ends in “team review request”, so you know
someone else on the team may take it. The pull request’s own sheet names
the team under Team reviewers.
Ctrl+1goes to Inbox, just above it, which marks them the same way. - Needs My Attention > My Open Pull Requests lists the ones you opened that are still open.
- A repository’s Pull Requests,
Ctrl+Shift+2, lists that repository’s open ones. Its Merge Queue lists the default branch’s merge queue in order, when the repository has one.
View > Quick Filters narrows a list of pull requests without typing: Review Requested from Me, Reviewed by Me, Drafts, Has Conflicts and Checks Failing are there, with the others. Each is checked while it is on, and they combine. Chapter 13 covers filtering in full.
Opening a pull request
Select a pull request and press Enter. That is
Review…, the first row of its context menu, and it
opens the review window described below. A pull request link pasted into
File > Open GitHub Address… (Ctrl+L)
goes straight to it, and so does a pull request in your
notifications.
File Differences… (Ctrl+Shift+D, on the
Item menu) skips the outline and opens the changed files on their own.
More on that below.
The one-sentence summary
The first thing you hear when the review opens is the whole pull request in one sentence:
“Review loaded for pull request #42. Approved, 2 checks failing, 1 open thread, 3 commits behind main.”
The sentence is built from these, in this order, leaving out what does not apply:
- whether it is a draft;
- the review decision: Approved, Changes requested, Review required, or No review decision;
- the checks: how many are failing or still running, or “all 4 checks passing”;
- the open review threads, or “no open threads”;
- how far behind its base branch it is, or “up to date with main”;
- merge conflicts, if there are any;
- auto-merge on, if it is set;
- and whether GitHub says it can merge, it is blocked by branch rules, or QUILL cannot tell. QUILL never guesses “ready”: when it is not sure, it says “merge readiness unknown”.
A merged or closed pull request just says “Merged.” or “Closed
without merging.” The same sentence is the first line of the window,
Pull request in one sentence, so you can read it again.
Copy Review Summary (Alt+S) copies the
fuller summary.
The review window
In Tab order:
- The one-sentence summary, then a status line: the merge readiness, the review decision, the checks, and how many threads are unresolved or outdated.
- Pull request outline, the tree. This is where you spend your time.
- Changed since my last review (
Alt+L), a check box. See below. - The selected node’s details, a read-only text field.
- Review summary, with Check Merge Policy beside it, and the summary and merge readiness in full.
- Checks, a list of the check runs.
- The status line.
- The buttons: Next Unresolved (
Alt+U), Next Unvisited (Alt+V), Open on GitHub (Alt+G), Copy Review Summary (Alt+S), Timeline… (Alt+T), Compose Review… (Alt+C), Reply to Thread… (Alt+R), Request Reviewers… (Alt+W), Mark Ready (Alt+M) on a draft or Convert to Draft (Alt+D) otherwise, Update Branch… (Alt+B), Auto-Merge and Queue… (Alt+A), and Close.
The buttons that write are unavailable when you are signed out or the pull request is closed, and Reply is available only with a thread selected.
The outline
The tree is a real tree: Up and Down move between the rows you can see, Right opens a branch and Left closes it. Tab reads the selected row’s details, and Shift+Tab comes back.
- The top row is the pull request: “PR #42:” and its title.
- Changed files holds one row per file. Each file opens to the review threads on it: “Line 12, alice, 2 replies, unresolved”. A thread on a line that has since changed adds “outdated”.
- General conversations holds threads that are not on a file, when there are any.
- Pending line comments, not sent yet holds comments you have written but not sent. See below.
- Checks holds one row per check, its result first: “success: build”, “failure: test”, or “in progress: lint” while it runs.
Enter on a row does the natural thing: on a file it opens the file’s diff; on a thread it moves you into its details to read every comment and reply; on a check it opens the check on GitHub; on anything else it opens or closes the branch.
Reading or expanding never changes anything. Selecting a thread does not resolve it or mark it read.
Moving between threads
- Next Unresolved (
Alt+U) moves to the next thread that is still open, and says “Moved to unresolved thread by” the author, and the line. It goes round from the end to the start. - Next Unvisited (
Alt+V) moves to the next thread you have not selected in this review. It is how you make sure you have read everything. When you have, it says “You have visited every loaded review thread in this session.”
Neither of these tells GitHub anything. “Visited” lives only in this window.
Files you have viewed
GitHub remembers, for you alone, which of a pull request’s files you have viewed, so a long review can be done in sittings. Signed in, the review window reads that after the review loads, and each row under Changed files ends with its state: “src/status.py, viewed”, “src/status.py, not viewed”, or “src/status.py, changed since you viewed it” when someone pushed to it after you looked. The status line says how many you have viewed, such as “3 of 12 files viewed.”
Shift+F10 on a file has:
- Mark as Viewed, or Mark as Not Viewed on one you have viewed. It is the same mark GitHub’s Files tab shows, and you hear the new count.
- Show Only Files Not Viewed hides the files you have viewed, so the outline holds only what is left; Show All Files brings them back. You hear how many are left.
- Comment on This File… opens the comment window for a comment on the whole file rather than a line: for a file that should not be there, or one to rename. It posts at once, outside any review you have pending.
Changed since my last review
When someone pushes more commits after you have reviewed, you do not
want to read every file again. Check Changed since my last
review (Alt+L). QUILL finds the commit you last
reviewed and keeps only the files that have changed since then. The
tree’s first branch is renamed Files changed since your review
on and the date, and you hear how many:
- “3 files changed since your review on 4 November.”
- “No files changed since your review on 4 November.”
- “You have not reviewed this pull request yet, so every file is new to you.”
If the branch has been force-pushed and the commit you reviewed is gone from GitHub, QUILL says so plainly and shows every file. Uncheck the box to see every file again.
The diff
Enter on a file in the outline, Open File
Differences on a file’s or thread’s context menu, or
File Differences… (Ctrl+Shift+D) on a pull
request in the Workbench, opens the diff window, PR #42
diff: and the title.
- Changed files: one row per file, “modified: src/status.py +12 -3”. Select one to hear its changes.
- Differences reads the changes through the same engine as QUILL’s Compare Documents: “Difference 2 of 5. Text changed at line 41”, with both sides named and the changed words described.
- Selected review hunk shows the part of the file a thread is about, when you came here from a thread.
- Line marks: (
Alt+M) chooses how changed lines are marked in the patch list, from four styles designed by Kelly Ford for GHManage and The Chat Place: Words (“Added line 12”, “Removed line 9”, “Unchanged line 13”), Short words (“Add 12”, “Del 9”, “Same 13”), Diff symbols (“+ 12”, “- 9”, “= 13”), or Diff symbols with changed lines, where a removed line is followed straight away by the line that replaced it, marked “!-” and “!+”, so each change is heard old then new. Symbols are shorter, but your screen reader says them only when it reads punctuation, and QUILL reminds you of that when you choose them. Your choice is kept, and it is the same choice Compare Files, Compare with File and WordPress’s Compare with Site use. - Next and previous change: in the patch list,
Alt+NandAlt+P(the keys Kelly Ford’s GHManage uses), orF8andShift+F8(as in Compare Files), move to the first line of the next or previous change and say where you are: “Change 2 of 5, at new line 41: 1 line removed, 1 added.” When a few lines were replaced by as many, it also says which words changed: “Changed Thursday to Friday.” - Changed Lines Only (
Alt+H) leaves the unchanged lines around each change out of the patch list, so the arrows go from change to change. The hunk headings stay, so each change still says where it is. You hear how many changed lines there are and how many unchanged ones were left out; uncheck it to see them again. - Hide Whitespace Changes (
Alt+W) leaves out changed lines that differ from their partner only in spaces, tabs or blank lines, such as a block that was only reindented, so what is left is what really changed. You hear how many lines it left out. - Choose Commit… (
Alt+T) reviews one commit of the pull request at a time. It lists them oldest first, “3f9a2c1 Fix the parser, by ann”, with “All commits: the whole pull request” at the top to come back. The file list, the differences and the patch lines then show only that commit’s change, against the commit before it, and the summary at the top says which commit you are on. - Patch lines: (
Alt+P), the patch one line to a row. This is where you comment. - Comment on This Line… (
Alt+L), Comment on Lines… (Alt+S), Copy Diff (Alt+C) and Open Diff in Default App (Alt+O). - Under them, how many of your line comments are waiting to be sent.
- Explain Selected Change with AI, beside Close, sends the selected file’s change to the AI connection you chose in QUILL, after asking, and says what it does. The answer names the file and the commit it read. It is greyed until you select a file, and when no AI is set up.
Opened from a thread, the diff goes straight to that thread’s lines and says “Review comment at” the file and line. If the line is no longer in the patch, it says so and suggests the thread may be outdated.
Open Diff in Default App saves the diff as a
.diff file and opens it in whatever program your computer
uses for those, and tells you where the file is.
As you arrow through the patch lines, an added line and a removed line each have a short sound of their own, so you can hear the shape of a change before the words arrive. They are the sounds Arrived on an added line of a diff and Arrived on a removed line of a diff in the Sound Scheme window, where either can be previewed, changed or switched off, and they follow your sound setting like every other QUILL sound. Unchanged lines and headings are silent.
Escape closes the diff and takes you back to where you opened it.
Commenting on a line or a range
In Patch lines:, arrow to a line and press Enter, or
press Comment on This Line… (Alt+L). To
comment on several lines, hold Shift and arrow to select them, then
press Enter or Comment on Lines… (Alt+S).
With one line or none selected, Comment on Lines asks you to type the
range instead, such as 12-15, 12 to 15 or just
12.
GitHub takes a comment only on lines the patch shows, and a range only inside one block of changes. QUILL checks before it sends and tells you which rule the lines broke, such as “Line 30 is not in this file’s changes, so GitHub will not take a comment on it.”
The comment window is titled with where the comment goes, such as “Comment on line 12 of src/status.py”. It has:
- Lines you are commenting on:, read-only, so you can check.
- Suggest a change (
Alt+S), a check box. See below. - Comment: (
Alt+C), where focus starts. - Add to Review (
Alt+A), the default: keep the comment and send it with your review. - Post Now (
Alt+P): send it on its own, straight away. - Comment Window… (
Alt+W): write the comment in the same comment window as everywhere else, with Insert Mention, Insert Reference, Insert Emoji, Insert Saved Reply, Preview and the check before posting. Its button says Use This Text, which puts what you wrote back in the Comment box here. - Cancel.
Most of the time you want Add to Review. GitHub then sends your comments together, with your verdict, as one review, and people are notified once instead of once per comment.
Suggesting a change
Check Suggest a change and QUILL puts the lines you chose into the comment as a suggestion block, ready for you to edit into what they should say. On GitHub, the author can accept a suggestion with one button. Uncheck it to take the block out again. A suggestion replaces lines of the new file, so it works on added and unchanged lines, not removed ones.
Pending comments and sending your review
Comments added to your review are kept on this computer, for your account, until you send them. You hear “Added to your review:” and where, and how many are waiting. They show in the outline under Pending line comments, not sent yet, each with its place and the start of its text.
On a pending comment, Enter or Edit Pending Comment… changes it, and Delete Pending Comment… removes it after asking. It was never sent, so it cannot be got back.
Compose Review
When you are ready, press Compose Review…
(Alt+C). The window Review Pull Request
#42 says how many line comments go with this review, and
has:
- Review action:, a list: Comment, Approve or Request changes.
- Review message: (
Alt+M), your overall comment. Request changes needs one; so does Comment, unless you have line comments. - Comment Window… (
Alt+W) writes the message in the comment window, with mentions, references, emoji, saved replies, the preview and the check; Use This Text brings it back. - Discard Saved Draft, to throw away a saved review message.
- Submit Review, which sends it, and Save Draft and Close, which keeps it. Escape is Save Draft and Close.
The review message saves as you type, so closing the window loses nothing. Submit Review is the only thing that sends. Request changes asks once more before it goes. You hear “Review submitted on pull request #42.” and how many line comments GitHub took with it.
GitHub never lets you approve your own pull request. If you keep a second account for that, see Approving with another of your accounts below.
When the pull request moves under you
Comments are written against one version of the code. If new commits arrive before you send, the lines you commented on may have moved. QUILL will not send a review whose comments were written on an older version: it says how many were, and asks you to delete or rewrite them under Pending line comments first. If the version changes while the Compose window is open, nothing is sent, and QUILL tells you to reopen the draft against the current diff.
Replying and resolving
On a thread in the outline:
Ctrl+R, or Reply to Thread… (Alt+R), replies. It opens the comment window, Reply to Review Thread, with the thread’s author first under Insert Mention, and Preview and the check as everywhere else; Post sends it. You hear “Reply posted to the review thread.”Ctrl+Shift+Rresolves the thread, or reopens a resolved one. It asks first. You hear “Review conversation resolved.” If GitHub does not let you change it, QUILL says so.
The thread’s context menu has these, plus React to a Comment…, Copy Conversation, Copy Thread Link, Open File Differences and Open Thread on GitHub.
Ctrl+R replies only here, in the review window. In the
Workbench it refreshes the list.
Reviews already sent
Reviews…, on a pull request’s context menu in the Workbench (under More), lists every review the pull request has had, with who sent it and its verdict. Choose one, then what to do with it: read its comments, and change or delete one of them; change its summary; dismiss it, when GitHub lets you; or, for a review still pending, submit it or delete it. Anything that changes a review asks first.
Re-request Review… asks people who have already reviewed to look again, after you have pushed changes. Give their GitHub names, separated by commas.
Getting a pull request merged
Reviewers, draft and ready
- Request Reviewers… (
Alt+W) asks for GitHub usernames, separated by commas. You hear “Review requested from” and their names. - On a draft, Mark Ready (
Alt+M) marks it ready for review. On one that is ready, Convert to Draft (Alt+D) turns it back into a draft. Both ask first. - Update Branch… (
Alt+B) merges the base branch into the pull request’s branch, so it is up to date. It asks first, and is unavailable on a draft.
Asking Copilot for a review
Request Copilot Review, on the pull request’s
context menu in the review window (Shift+F10 on the
outline), asks Copilot code review to review the pull request. It has no
button or access key. You hear “Copilot review requested on pull request
#4.” only when GitHub lists Copilot among the reviewers. GitHub
sometimes accepts the request and leaves Copilot off the list, which is
how it answers an account or a repository without Copilot code review;
QUILL says that plainly rather than telling you a request went in when
it did not. Copilot’s review arrives as review comments, like anyone
else’s, and the outline shows them after a refresh.
In the Workbench, Ask Copilot to Review, on a pull request’s context menu under More, does the same from the list. The same menu has Agent Merge, Turn On Agent Merge and Turn Off Agent Merge…, which let Copilot’s cloud agent merge the pull request once its checks and reviews allow. These need a Copilot plan with the cloud agent; Chapter 12 has the rest of Copilot’s commands.
Merging
Merging is in the Workbench, not the review window, because it is the
one thing here that changes the base branch for everyone. Select the
pull request and press Ctrl+Shift+Enter, or choose
Merge… from its context menu or the Item menu.
QUILL first asks GitHub whether the pull request can merge. If it cannot, you hear why, the same answer as Why Can’t I Merge? below, and nothing else happens. If it can, QUILL asks how to merge: Squash and merge, Merge commit, or Rebase, offering only the ways the repository allows. Then it asks you to type the pull request’s number to confirm, not just press Yes, and says what will happen: that it merges into the base branch, as of the commit QUILL checked, for example “as of commit 3f9a2c1”, and that this changes the branch for everyone and cannot be undone from QUILL. You hear “Merged #42” and the start of the new commit.
That commit is the one that merges. If somebody pushes to the pull request between the check and your typing the number, GitHub refuses, nothing is merged, and QUILL says so: “Somebody pushed to #42 after commit 3f9a2c1 was checked, so nothing was merged.” Check again and you are merging what you have actually read.
When the base branch merges only through a merge queue, Merge… does not try to go around it: you hear that the pull request can join the queue, and Add to or Remove from Merge Queue… puts it there.
A merge cannot be taken back with Ctrl+Z. To undo one,
use Revert Pull Request…, below.
Merging several at once
To merge more than one pull request, select them in the list (hold
Shift or Ctrl with the arrow keys), then
choose Merge Selected… from the context menu or the
Item menu. It needs at least two open pull requests selected; anything
else in the selection is left out.
- QUILL asks once how they should merge: Squash and merge, Merge commit, or Rebase. Where a repository does not allow that way, QUILL uses one it does, and the preview says which.
- It asks GitHub about each pull request on its own, with the same question as Why Can’t I Merge?. One that cannot merge does not hold up the others.
- The preview lists every pull request: “#42: will merge into main by squash and merge, commit 3f9a2c1.”, “#43: will join the merge queue for main” when its branch requires a queue, or “#44: will not merge.” and the reasons. The first line sums it up, such as “Of 3 pull requests: merge 2; 1 will not.” Press Enter to go on, or Escape to change nothing, and then type how many will go in.
- QUILL merges them one at a time, about a second apart. Just before each one it asks GitHub again, because merging one can make the next conflict or put it behind its base. A pull request that can no longer merge, or that has new commits since the preview, is left alone, and says why: you agreed to merge the commit you were shown, not a later one. A failure stops nothing else.
At the end you hear one sentence with the counts, such as “Merged 2
of 3 pull requests, 1 not merged.”, and the results list has a line for
each pull request. Copy Results copies them, and
Retry Failed (F8) starts again with only
the ones that failed, preview and all.
Why Can’t I Merge?
Why Can’t I Merge? on a pull request’s context menu in the Workbench answers the question GitHub’s merge box answers with colours and icons. You hear either that it can merge, “#42 can merge into main, as of commit 3f9a2c1.”, or each reason it cannot, each with what to do:
- It is a draft: mark it ready for review first.
- It conflicts with its base: Resolve Conflicts in a Worktree…, in QUILL, takes the conflicts to your computer.
- It is behind its base, and the branch’s rules want it up to date: update the branch.
- A reviewer requested changes, or it needs an approving review.
- A required check failed, or has not finished, named: “Required checks test and lint failed. Re-run or fix it.” A check that failed but is not required is mentioned as not required, and does not stop the merge.
- A rule on the base branch blocks it for another reason: the rule is named, as below.
Each blocking rule is said by name, so you know whom to ask or what to fix. QUILL reads the rules that apply to the base branch (its rulesets, and its branch protection when you can read it) and says:
- which required check failed, has not finished, or has not reported on the commit, and which ruleset wants it: “Check build, which the ruleset “Protect main” requires, failed. Re-run or fix it.”
- how many approving reviews a rule wants, and how many there are;
- when a rule wants a code owner’s review, which line of the CODEOWNERS file is waiting, with its pattern, who could approve, and a changed file it covers: “none from @docs-team has approved: .github/CODEOWNERS line 3, /docs/, owns 2 changed files, such as docs/guide.md.” A team counts as approved when one of its members has;
- which rule makes the branch merge only through its merge queue.
What QUILL could not read, such as branch protection without admin access, is said at the end, so a missing permission never sounds like “no rule”. GitHub’s answer is the one that counts: naming the rules never turns “can merge” into “cannot”. Merge Selected… names the rules the same way in its preview, for each pull request that will not merge.
It also says when auto-merge is on, and its place when the pull request is in the merge queue. The answer is always for one commit, which it names, so you know a push after you asked may change it.
Watch Readiness
Watch Readiness, on an open pull request’s context
menu in the Workbench, adds a watch (under Watches, Ctrl+7)
that tells you once when the pull request becomes able to merge, and
once when it stops, naming the rule that blocks it then. It is checked
with your other watches, on the same interval, and said the same way.
The first check only learns where it stands, and while GitHub is still
working out whether it can merge, nothing is said. You can also add one
from Watches with Add Watch…, choosing “A pull request
becomes able to merge, or stops being able to”. The watch is kept on
this computer only; nothing is changed on GitHub.
Auto-merge and the merge queue
On a pull request’s row in the Workbench, Auto-Merge… turns auto-merge on, after telling you what it would be waiting for and asking how to merge, or offers to turn it off when it is on. A pull request that can merge now has nothing to wait for, and QUILL says so rather than switching it on. Add to or Remove from Merge Queue… adds the pull request to its branch’s queue, naming the commit, or offers to take it out when it is in, saying its place. The repository’s Merge Queue place lists the whole queue in order.
In the review window, Auto-Merge and Queue…
(Alt+A) opens a menu:
- Enable Auto-Merge… tells GitHub to merge the pull request by itself as soon as its required reviews and checks pass. QUILL asks how: Create a merge commit, Squash and merge, or Rebase and merge.
- Disable Auto-Merge… turns it off.
- Add to Merge Queue… puts the pull request in the branch’s merge queue, if it has one. You hear its place in the queue.
- Remove from Merge Queue… takes it out.
- Combined Check Status says all the checks in one sentence, such as “3 of 4 checks pass; failing: test.”
Each asks first, and reports what GitHub confirmed. When GitHub refuses for a reason QUILL knows, it says what to do about it, for example that auto-merge is turned off for the repository and an administrator can turn it on in the repository’s settings, or that GitHub can merge the pull request now, so there is nothing for auto-merge to wait for.
Merge policy
Check Merge Policy, in the review window, reads the rules on the base branch: required reviews, required checks, code owners and the merge queue. It adds them to the review summary, and from then on the readiness and the combined check status count only the checks that are required (“3 of 4 required checks pass”). The rules are read for the current version of the pull request; refresh the review after new commits to check again. GitHub always has the last word, and QUILL says so.
A check that needs another run
On a check in the outline, the context menu has Re-request Check…, which asks GitHub to run that check again. Some checks are older-style commit statuses rather than check runs, and those cannot be re-run from outside; QUILL says so. Chapter 6 covers checks and workflow runs in full.
Approving with another of your accounts
GitHub never lets the author approve their own pull request. If you keep two accounts in QUILL, say a personal one and one for the project, Account > Roles and Access > Act As Another Account… sends one action as the other account. Select the pull request first. QUILL lists your other signed-in accounts, then the actions that fit: Approve this pull request, Comment on it, or Close or reopen it. It checks whose token it really is before sending, names the account in the question, and names it again in the result: “Approved pull request #42 in owner/name as jeff-project.” The other account’s own Workbench level applies, so a Read Only account sends nothing.
Compare Accounts…, on the same submenu, shows two of your accounts side by side on this repository: each one’s role, as GitHub answered that account. Chapter 13 has both in full.
The whole patch, a revert, and conflicts
Three commands on a pull request’s row in the GitHub Workbench do what the web’s Files tab, its Revert button and its conflict editor do.
Open Patch in Editor
Open Patch in Editor opens the pull request’s whole
change as one document: every changed file, one after another, as a
unified diff, the same text the website’s .diff link gives
and the text git apply reads. Each file starts with a line
beginning diff --git, so the editor’s Find moves from file
to file, and each change starts with a line beginning @@,
which names the lines it touches. A removed line starts with a minus
sign and an added line with a plus sign.
A file GitHub sends no text change for, such as an image or a very
large file, is not left out silently: it has a line of its own starting
with #, which names the file and says so. When the patch
opens you hear how many files it has and how many of them have no text,
for example “Opened the patch of #42. The patch has 12 files. 1 of them
has no text change GitHub can send, binary or too large, and each is
named on a line starting with #.”
The patch is saved as
<repository>-pr-<number>.diff in the folder
where the Workbench keeps the documents it opens, so Save As keeps a
copy anywhere you like.
Revert Pull Request
On a merged pull request, Revert Pull Request… opens
a new pull request that undoes it, as the Revert button on the website
does. QUILL asks for the new pull request’s title, which starts as
Revert " and the old title, and then asks whether to open
it as a draft. Yes opens a draft, which nobody can merge until it is
marked ready; No opens it ready for review. Nothing is undone until the
revert is itself merged, so this is a proposal, not a change to the
branch.
You hear “Opened pull request #57, which reverts #42.” A pull request that is not merged has nothing to revert; the command is greyed, and its help says why. You need write access to the repository.
Resolve Conflicts in a Worktree
When a pull request cannot merge because it conflicts with its base branch, Resolve Conflicts in a Worktree… gets the conflicts onto your own computer without touching the folder you are working in:
- QUILL asks which local checkout of the repository to use, if the document you have open is not in one, and finds the remote that is that repository on GitHub.
- It asks first, naming the remote and both branches. This is the one
step that uses the network, and it is your own Git that does it, with
your own sign-in, as
git fetchfrom a terminal would. - It makes a new folder beside your checkout, a Git worktree, on a new
branch called
pr-<number>-conflictsmade from the pull request’s branch, and merges the base branch into it there. Nothing is committed. - You hear how many files conflict and their names, and the editor’s Resolve Conflicts walks each one, the same window as QUILL’s Tools > Git and GitHub > Local Git > Resolve Conflicts…: each conflict in turn, with your version and theirs read out, and a choice for each.
When the files are resolved, commit in that folder and push the
branch to the pull request’s branch; QUILL says the exact command, for
example git push origin pr-42-conflicts:fix-parser. The new
folder stays until you remove it with Tools > Git and GitHub
> Local Git > Worktrees….
A pull request from a fork is the exception: its branch lives in the fork, not in the repository, so QUILL says so and leaves it to a checkout of the fork, or to its author. If the base merges with no conflicts, QUILL says that instead, and the merge is left staged, not committed.
This one is QUILL’s alone. In QUILL Lite, which has no Local Git, the row is greyed and says why.
Dependabot’s pull requests
A pull request Dependabot opened, to update a package, has Dependabot Commands… on its context menu. It lists the commands Dependabot answers in a comment, such as rebase, recreate, merge, or ignore this version, each with what it does. Choosing one posts it as a comment, after asking, and Dependabot does the rest.
Drafts, github.dev and Related
A few more commands on a pull request’s row:
- Draft Description with AI… and Draft Reviewer Brief with AI… send the pull request’s changed files and their patches, at its head commit, to the AI connection you chose in QUILL, and open the draft in the editor. The draft is headed as one, lists its sources (each file at that commit, and the commit itself), and says when part of the change was left out because it was too long. It never claims tests ran unless the evidence says so. QUILL posts nothing: paste what you keep into the description or a comment.
- Draft Release Notes with AI… on selected issues and pull requests drafts notes from those rows only. Draft Release Notes… on a release drafts them without AI.
- Without an AI connection these rows are greyed, and
Shift+F1says why. - Open in github.dev opens the pull request in GitHub’s free web editor, in your browser; nothing is created and nothing costs money.
- Related… lists the issues it closes, what mentioned it, and what its text links to (Chapter 8).
Writing a new pull request
In a repository’s Pull Requests, press
Ctrl+N. To start from a branch, select it in Branches,
press Ctrl+Shift+N and choose Pull Request. The New Pull
Request window has Merge into, Merge from, Title, Description and a
Create as a draft check box. The title and description start from the
commits you are proposing, a branch that already has an open pull
request is taken to that one instead of making a second, and Cancel
keeps your text for the session. Chapter 12 walks
through it.
On an issue, Start Pull Request for This Issue… makes a branch linked to the issue and a draft pull request that closes it, in one step. Chapter 4 has it.
A walk-through: reviewing and merging the practice pull request
The practice repository has a branch, fix-greeting, with
a pull request waiting for you. Make it first with Help >
Practice on GitHub… (Ctrl+Alt+P) if you have not.
Nothing here matters if it goes wrong.
- In the Workbench, press
Ctrl+L, typequill-practiceand press Enter. You arrive on the repository’s own place in the tree. - Press
Ctrl+Shift+2for its Pull Requests, then F6 to the list. You hear the pull request that fixes the greeting. - Press Enter. The review window opens, and you hear “Review loaded for pull request” and the one sentence.
- Arrow down to Changed files, press Right Arrow, and press Enter on the file. The diff opens.
- Press
Alt+Pfor the patch lines andAlt+Hto check Changed Lines Only. Arrow down: an added line and a removed line each have their own sound.F8jumps to the next change. - Press Escape to close the diff, and Escape again to close the review.
- Back on the pull request in the Workbench, press
Shift+F10and choose Why Can’t I Merge?. You hear that it can merge into main, as of a commit it names. The practice run fails on purpose, but it is not a required check, so it does not stop the merge. - Press
Ctrl+Shift+Enter. Choose Squash and merge, type the pull request’s number, and press Enter. You hear “Merged” and the new commit.
You made the pull request yourself, so GitHub would not have let you
approve it. On someone else’s, Compose Review (Alt+C) in
step 6 is where you send Approve.
Learn it with a guided lesson
Help > Tutorials (Ctrl+F2) has
Review and merge a pull request, on the practice
repository: list the pull requests, read the change, ask whether it can
merge, and merge it. Each step says what to press and what you should
hear. Try a command without sending it shows Dry Run,
which lets you try Merge… and see what it would send without sending
it.
- Previous: Chapter 4: Issues
- Next: Chapter 6: Actions and checks
- Contents