Comments, threads and drafts

Revue loads every comment, thread and review of a pull request. Nothing gets folded away behind "Load more". Comments you write go into a review as drafts first. They're saved to disk as you go, and nothing is posted until you submit the review, or until you post one straight away with Comment now.

Comment on lines#

You can start a comment in a few ways:

• The + button. Hover over a line in the diff and a + shows up by its line number. Click it to comment on that line, or press it and drag up or down to comment on several lines.
• The line numbers. Drag along the line numbers, or click one line and Shift+click another. A bar at the bottom says Lines 12–18 selected. Click Comment in it, or press c.
• The keyboard. c comments on the selected lines. With nothing selected, it comments on the line at the top of the view (handy after jumping there with n).
• A whole file. The speech-bubble button in a file's header (Comment on this file) starts a comment about the file as a whole.

The comment box opens at the bottom of the diff, with an arrow pointing at your lines. The rest of the page fades a little so you can focus. The view doesn't scroll when you start a comment.

Add to review or Comment now#

The comment box has two ways to send:

Pending comments show in the diff with a dashed, highlighted border and Pending comment. Use the pencil to edit one, or the bin to delete it (Revue asks first, because it was never posted).

To send your pending comments, submit the review: see Reviews, approvals, merging and editing.

Suggest a change#

Suggest change in the comment box puts the lines you selected into a ```suggestion block. Edit them into what you think the code should be. On GitHub, the author can apply the suggestion with one click.

Advanced: commenting details

• Clicking on a line elsewhere, or Esc, clears a selection that you haven't started commenting on yet. The × in the selection bar does the same.
• Shift+↑ / Shift+↓ extend the selection in the diff from the keyboard.
• A comment on the old side of a split diff (a deleted line) shows (old) next to the line numbers.
• Suggest change isn't offered for whole-file comments or while you edit a pending comment.
• If you start a comment on other lines while one is open, the open one isn't lost: if it has text, it becomes a pending comment.
• Opening Submit review does the same with an open comment box, so it goes in with the review.
• Folding a file closes an empty comment box on it, and leaves one that has text alone.
• While you edit one pending comment, Revue won't let another edit take its place: it says Save or cancel the comment you're editing first.

Write in Markdown#

Every comment box (new comments, replies, edits, the conversation comment and the review summary) is the same Markdown editor.

• Write and Preview tabs. Preview shows the comment the way it will look, with links to issues and pull requests (#123) and to tickets.
• A toolbar: Bold (Ctrl+B), Italic (Ctrl+I), Code (Ctrl+E), Link, Quote, Bulleted list, Task list and Image. On macOS the shortcuts use Cmd. With text selected, they wrap or prefix it. Without, they insert a placeholder to type over.
• Fenced code blocks show in the code font as you type, in the syntax colours of the language after the opening fence (```rust), and Tab / Shift+Tab indent and outdent inside them: the line, or every line of a selection.
• Hold Alt (Cmd on macOS) to see each button's shortcut.

Emoji, people and Slack channels#

• Type : and at least two letters (:ro) for a list of matching emoji. Pick one with ↑ / ↓ and Enter or Tab, or click it. Esc closes the list.
• Type @ at the start of a word for people to mention, narrowed as you type their login or name. The pull request's people come first (its author, the reviewers, who commented, who it's assigned to), then the others who can review in the repository. The pick goes in as @login. On Bitbucket it goes in as Bitbucket's own mention of the account, so they're notified. An email address ([email protected]) doesn't open the list.
• With Slack connected, # and a letter suggest your Slack channels. The pick goes in as a link to the channel. A #channel you type out in full becomes a link when the comment is posted.

Images#

Paste a screenshot, drop image files on the editor, or click the Image button to pick files. A placeholder (Uploading image 1…) shows while it uploads, and becomes the image once it's done. PNG, JPEG, GIF and WebP work.

Where images go

• Images are uploaded to Revue's server, not to GitHub, Bitbucket or Forgejo (GitHub's API has no way to upload them). The comment gets a normal Markdown image (![image](https://…)), so it shows on every service, on the website too.
• Anyone with the link can see an uploaded image. Don't upload anything secret.
• Revue's server takes images up to 10 MB by default, and limits how many each computer can upload per hour (120 by default). Someone running their own server can change both: see Self-hosting revue-server.
• Uploading needs the server's address (REVUE_SERVER_URL) and an upload token (REVUE_IMAGES_TOKEN). Official releases have both built in. A build without them has no uploads: the Image button then inserts ![image](https://) for you to fill in, and pasting or dropping images does nothing. See Command line and environment variables.
• If you copy something that comes with text as well as a picture, Revue pastes the text.
• If an upload fails, the placeholder goes away and Revue tells you why (Couldn't upload the image: …), for example when the image is too large.

Viewing images#

Images in comments, replies, pending comments, pull request descriptions and Jira tickets show at their own size, scaled down to fit the column and at most 480 pixels tall. Click one to see it big, over the window:

• It's fitted to the window (scaled down, never enlarged). Actual size, or a click on the image, shows it at its own size: scroll to see the rest. Click again to fit it back.
• The buttons next to it open it in the browser or copy its link.
• Esc, a click outside it or the close button closes it.

An image that is a link opens the link instead.

Threads#

A thread is a comment on some lines of code together with its replies. Threads show right in the diff, under the lines they're about.

In a thread you can:

• Reply. Click Reply…, write, then click Reply or press Ctrl+Enter (Cmd+Enter on macOS). The reply shows right away with Sending….
• Resolve a thread when it's dealt with. Revue first shows you what the thread is about and asks Resolve this conversation?. A resolved thread folds up and says Resolved by …. Unresolve reopens it, right from its folded header.
• Fold or unfold a thread by clicking its header.
• Edit or delete your own comments with the pencil and bin next to them. Deleting asks first, because the comment is removed for everyone. You can also turn on Settings → Behavior → Comments → Double-click a pending comment to edit it (off by default; it works in the Files view, on comments not sent yet).
• React with 👍 👎 😄 🎉 😕 ❤️ 🚀 👀. Click a reaction to add yours or take it back, or use the smiley button for the others.
• Open on GitHub (or Bitbucket, Forgejo) with the arrow button by each comment.

Threads that can't sit on a line in what you're looking at (outdated ones, comments on a whole file, comments written on another commit) aren't hidden. They show at the top of their file, under File comments & comments not on a visible line. Threads marked Outdated are on code that has changed since.

Per service: replies, resolving, editing and reactions

	GitHub	Bitbucket Cloud	Forgejo, Codeberg, Gitea
Reply	Yes	Yes	Yes, posted as a one-comment review on the thread's line, as Forgejo's website does
Resolve / Unresolve	Yes, if you're allowed to	Yes	No: the API can't. Revue shows whether a thread is resolved; resolve it on the website
Edit / delete your comments	Yes	Yes	Yes
Reactions	Pull request, comments and reviews	None	Pull request and comments, not review summaries

GitHub only: if you have a pending review on GitHub (one you started on the website and didn't submit), a banner says so. While it's there, a reply or Comment now goes into that review instead of being posted. Revue tells you, and the comment shows Pending: in your review on GitHub. The banner's Submit… sends that review along with your drafts in Revue. Discard deletes it from GitHub (after asking).

Advanced: when sending fails

• A reply that fails to send comes back into its reply box with your text, and Revue shows Reply failed: ….
• A failed edit puts the comment's old text back and shows Couldn't edit comment: ….
• A failed resolve, unresolve or reaction is undone on screen, with Couldn't update thread: … or Couldn't react: ….

The threads panel#

The threads panel beside the diff lists the pull request's threads, with your pending comments on top. Press t or use the diff toolbar button to show or hide it.

• All lists every thread, newest activity first. Visible lists the threads on the files on screen, in the order of the diff. Each tab shows a count, such as 3/7 for 3 open out of 7.
• Show resolved adds resolved threads to the list.
• Show from others adds threads you're not part of. With it off, you only see threads you started, replied in or are @-mentioned in. On your own pull request, everyone's threads are shown unless you switch this off.
• The search field finds threads by what they say, their file, or who's in them.
• Click a thread to jump to it in the diff. If it isn't in the commits you're looking at, Revue switches to all changes, or to the commit it was written on. Comments on a commit that was later force-pushed away open on that old commit, with a warning bar.
• ] and [ jump to the next and previous open thread in the diff.
• The window button at the top right of the panel, or Alt+T (Option+T on macOS), opens the panel in a window of its own, beside the diff or on another screen. It stays up to date, and clicking a thread there still shows it in the diff. Close the window, or press Alt+T or t again, to bring it back. The Conversation, Feedback and Code tabs open in their own windows the same way (Shift+W): see In a separate window. Desktop only.

Settings for the threads panel

All under Settings → Diff. The panel's own toggles change these for one pull request only, and Revue remembers that choice for it.

Setting	Options	Default
Threads panel	Shown / Hidden	Shown
Threads panel opens on	All / Visible	All
Resolved threads (Show resolved threads)	On / off	Off
Threads from others (Show threads from others)	On / off	Off

The Feedback tab#

The Feedback tab is for the person whose code is being reviewed. It shows each of your threads in full, with its code, all comments, a reply box and Resolve. The ones waiting on you come first, under Waiting on you. The reviewers' latest summaries are at the top.

• Filters: Needs reply, Open, Resolved and All, each with a count. A thread needs a reply when it's open and someone else spoke last.
• Show in diff → jumps to the thread in the Files tab.
• The list keeps its order while you reply and resolve, so threads don't jump away as you work. Coming back to the tab sorts it again.

On your own pull request, Feedback is the first tab. When someone is waiting for your reply, the pull request opens on it, and the tab says Feedback 2 waiting. On other people's pull requests, it lists the threads you took part in.

Advanced: tab numbers

The number keys pick tabs by their position. On someone else's pull request, 1 is Files, 2 Conversation, 3 Commits and 4 Feedback. On your own, Feedback moves to the front, so 1 is Feedback, 2 Files, 3 Conversation and 4 Commits. See Keyboard shortcuts.

The Conversation tab#

The Conversation tab (2 on someone else's pull request) is the pull request's whole story on one page, with nothing collapsed:

• the description at the top, then a box to Comment on the pull request as a whole (Ctrl+Enter posts it, Cmd+Enter on macOS);
• then everything else, newest first, under a heading for each day:
  • comments, marked Author when they're by the pull request's author;
  • reviews. Approvals and change requests show as a coloured banner, approved these changes or requested changes;
  • review threads, with the code they're on, replies and Resolve;
  • commits, grouped when nothing happened between them. Click one to see its changes, or Shift+click another for the range;
  • force-pushes, with the old and new commit.

A thread shows the last lines of code it was written on, with their line numbers (the new file's, or the old file's for removed lines). Click a thread's file name to see it in the diff. The tab's title shows how many entries there are, with a badge for open threads.

Find in the conversation#

Press Ctrl+F (Cmd+F on macOS) on the Conversation tab, or click the magnifier at its top right. Type, and Revue highlights every entry that contains your text, and says 2 of 5. Enter and Shift+Enter go to the next and previous one. Esc closes the search.

Advanced: what the search looks at

• The title and description, comments and their authors' logins, review summaries, threads (their file and every comment), and commit messages. Force-pushes aren't searched.
• It ignores upper and lower case.
• Reviews without a summary don't get their own entry (unless they approve or request changes). Their comments show as threads.

Drafts are saved as you type#

Your pending comments, unsent replies and the review summary are saved to disk with every key you press. They survive closing the tab, quitting Revue and restarting the computer.

• If submitting fails, your drafts stay where they were. Revue says Submitting failed — your drafts are safe.
• A reply you were writing reopens with its text when you come back to the thread. The note Draft is saved automatically under it reminds you.

Where drafts are stored

• Each pull request has its own file in the prs folder of Revue's config folder: ~/.config/revue/prs/ on every system ($XDG_CONFIG_HOME/revue/prs/ when that's set). Dev builds use revue-dev instead. See Files, sync and settings for one computer.
• The file is named after the pull request, such as acme__web__12.json for GitHub. Bitbucket files start with bb__, and Forgejo ones with fj__ and the server.
• It holds the pending comments (each with its file, lines, side and the commit it was written on), the review summary, unsent replies, and per-pull-request choices such as viewed files and the threads panel's toggles.
• Because it's in the config folder, drafts follow you when you sync that folder between computers.

Comments written on older commits#

You can comment while looking at any commits: all changes, the changes since your last review, a single commit or a range (see Reviewing the diff). A pending comment written on another commit than the newest one is marked written on a1b2c3d.

When you submit, Revue moves each comment's line forward to the pull request's newest commit, following what changed in between. If the line can't be followed (it was changed or removed since, or it isn't part of the pull request's changes), the comment isn't dropped. It's posted as a comment on the whole file that starts by quoting where it was, like > On lines 12–18 at a1b2c3d:. Revue tells you, for example Comment posted · 1 comment moved to file level (lines changed since).

Advanced: how lines are carried forward

• Comments written on the newest commit are posted as they are.
• For older ones, Revue compares the commit you commented on with the newest commit and maps each line through that change.
• A line range keeps its first line only if that line is still in the pull request's changes too; otherwise it's posted on its last line.
• Comments on the old side (deleted lines) written on an older commit always become file comments, because Revue can't check where those lines are now.

Differences between services#

Most things work the same on every service. These don't:

Per service: how comments are posted

GitHub

• A review is posted in one go, with all its comments.
• Comments on a whole file are GitHub's file comments.
• See the pending review note under Threads.

Bitbucket Cloud

• Bitbucket has no batched reviews. Submitting posts your comments one by one, then the summary as a plain comment, then the approval or change request.
• If a comment fails part-way, the ones already posted leave your drafts and the rest stay drafts: Submitting stopped after 3 comments — the rest are still drafts.
• No reactions.

Forgejo, Codeberg and Gitea

• Comments sit on a single line, so a comment on a range of lines is posted on its last line.
• Comments on a whole file go into the review's summary, each under its file name in bold.
• A reply is posted as a one-comment review on the thread's line.
• Threads can't be resolved from Revue; do it on the website.
• No reactions on review summaries.

Guide: Comment on a range of lines and send it#

1. Open the pull request on the Files tab.
2. Hover over the first line, press the + next to it and drag down to the last line.
3. Write your comment. Click Suggest change to propose new code.
4. Click Preview to check how it looks.
5. Press Ctrl+Enter (Cmd+Enter on macOS) to add it to your review.
6. Repeat for your other comments.
7. Press Ctrl+Enter again, outside a comment box, to open Submit review, and send everything at once.

Guide: Answer the feedback on your pull request#

1. Open your pull request. It opens on the Feedback tab when someone is waiting for you.
2. Read the first thread under Needs reply.
3. Click Reply…, write your answer and press Ctrl+Enter (Cmd+Enter on macOS).
4. Click Resolve when the thread is dealt with, and confirm.
5. Use Show in diff → when you need to see the code around it.
6. Carry on until it says You're all caught up.