Jump to >

Reviewing Diffs

Overview

Diffs can be reviewed in the Review Board diff viewer by clicking View Diff on the review request action bar.

The diff viewer provides a side-by-side view of the old and new versions of each modified file, complete with color coding and syntax highlighting. Lines can be commented on directly, allowing the developer to see exactly what part of code you’re talking about in a review.

The top of the diff viewer shows the review request box, for reference. Inside that box toward the bottom is an indicator showing the current diff revision, sometimes followed by a listing of other revisions (if more than one diff was uploaded to this review request), then a file listing, and then the diffs.

Depending on the number of files modified, the diff viewer may be split across multiple pages. You can jump to the pages using the paginator above or below the diffs.

Commenting on Lines

To comment on a line on a diff, simply click the line number. A comment dialog will appear giving you a text entry for writing your comment. When you’re done, you can click Save to save the comment.

Furthermore you can assign a comment to multiple code lines. This option is especially useful to provide additional code context to discussions as all commented code will appear on the review request page.

To create a multiple line comment click and drag on the beginning line number down the column until you’ve selected all the lines needed for your comment.

../../../_images/comment-box.png

The diff comment dialog supports issue tracking. See the section on Issue Tracking for more information.

After saving a comment, a green comment flag will appear next to the first line in your selection, indicating that you have an unpublished comment. Click the line number or comment flag to pop open the comment box for your existing comment again.

Reading Existing Comments

The diff viewer will show blue comment flags along the left-hand side next to the line numbers that were already reviewed. The number inside the comment flag indicates how many comments were made on that line.

If you move the mouse cursor over the comment flag, a tooltip will appear showing a summary of the comments made.

If you click on the comment flag or the line number, the comment dialog will appear, along with a blue side panel on the left showing those existing comments. You can still write new comments in the green area of the comment box.

../../../_images/full-comment-box.png

It’s important to note that this is meant to be used as a reference to see if other people have already said what you plan to say. The comment box is not the place to reply to those comments. Instead, you can click the Reply link next to the particular comment, which will take you back to the review request page and open a reply box.

Viewing Other Diff Revisions

Every public revision of a diff that was posted is available for review. You can click the box for the diff revision next to the Jump to revision label below the current diff revision indicator.

../../../_images/diff-revision-selector.png

This is sometimes useful when you’re in the middle of a review of a particular diff, go away for a bit, and then come back to discover that a new diff revision has been uploaded. In this case, a warning box will appear telling you that you have additional comments on an older revision, with a helpful link to jump back to that revision.

Viewing Interdiffs

The diff viewer supports showing and commenting on interdiffs. An interdiff is the difference between two uploaded diff revisions. In other words, it lets you see what changes the developer has made since the previous version of the diff you looked at, which is very useful for large changes which require several iterations of review.

To view an interdiff between the current revision you’re looking at and another revision, click the box for the diff revision next to the Changes between r# and: label.

Note

Due to the way that the diff viewer works, if a newer diff is based on a newer revision of a file, you may see other changes made to that file between those revisions that has nothing to do with the review itself.

If you’re a developer posting code and you want to sync your source tree, it’s best to try to keep as many revisions of your change based on the same revision of the source tree as possible, in order to minimize the impact of this on your reviewers.

Keyboard Shortcuts

There are many keyboard shortcuts for navigating around the diff viewer:

  • Previous file: a, A, K, P:, <, or m
  • Next file: f, F, J, N, >
  • Previous change: s, S, k, p, ,
  • Next change: d, D, j, n, .
  • Previous comment: [, x
  • Next comment: ], c