Jump to >

Reviewing Diffs

Any review request that introduces changes to code will have a Diff tab at the top-right of the review request page that provides access to the diff viewer. This is where developers will spend a lot of their time, and to help save you time we’ve provided a lot of functionality to give you a better view of the code, and to help you navigate around.

Reading Diffs

Diffs are displayed using a side-by-side format. This means that the old version of the file is displayed on the left, and the new version of the file is displayed on the right. The differences between the two versions are highlighted using colors:

  • Green for added lines
  • Red for removed lines
  • Yellow for changed lines

These are pretty standard across most diff viewing products, but Review Board’s diff viewer expands on this with other special indicators showing how code has evolved.

Moved Line Indicators

If you move one or more lines of code within a file, instead of just showing those lines as deleted from one location and added to another, Review Board will detect that the lines have been moved and show an indicator. These indicators can be clicked to jump to the other end of the move.

../../../_images/moved-lines.png

Indentation Change Indicators

Historically, Review Board would show lines that differed only in their indentation as being equal. This is nice in most cases, but can hide important information, especially in languages like Python where the indentation is crucial to the meaning of the code.

Review Board will now show indentation changes with small indicators at the beginning of the line. Dedents will be shown on the left-hand side of the diff, and indents will be shown on the right.

../../../_images/diff-indentation.png

Highlighted Changes in Replaced Lines

Edits which change only one or two characters in a long line can be difficult to read, so when the original and new lines are very similar, Review Board will highlight which characters changed. This is shown with a slightly darker yellow background.

../../../_images/diff-replace-highlighting.png

Seeing More of a File

Expanding Lines of Context

The diff viewer shows a few unchanged lines around any modified lines in a file, helping you to see some context to the changes, but sometimes that’s not enough. Instead of opening the original file in an editor or a browser to see more, you can expand the number of lines of context with a simple click.

../../../_images/diff-expand-context.png

These headers appear above any group of modified lines, and at the bottom of the diff viewer (if not otherwise showing the last lines in the file).

Clicking expand-20-lines-icon above the line numbers on the left will expand 20 lines at a time.

Clicking expand-all-lines-icon at the top of the header will expand all the lines hidden by that header.

Clicking expand-header-icon beside the function or class shown will expand all the lines up to the line shown beside the icon.

Expanded context can be re-collapsed by clicking the floating collapse icon shown.

../../../_images/diff-collapse-context.png

Viewing Deleted File Content

New in version 3.0.

By default, the diff viewer doesn’t show the content of any files deleted in a diff, as this code often doesn’t need to be reviewed. Instead, you’ll see a simple message stating that the file was deleted.

../../../_images/diff-show-deleted.png

For those times that you do need to see more, you can click Show content to load in the content of the deleted file.

../../../_images/diff-show-deleted-contents.png

Deleted files can be commented on and will appear in reviews. It’s important to note though that deleted files that contain comments are not automatically expanded in the diff viewer.

Downloading File Content

The entirety of the file on either side of the diff can be downloaded by clicking the download-icon icon beside the revision in the diff header. This can be useful if you just want to pull down the entire file and view it in your editor.

Working with Comments

The diff viewer supports leaving comments that pertain to lines of code. Each comment can span multiple lines, providing a lot of flexibility in what the author of a comment may want to show. Commented lines are shown in the review along with the comment text.

Lines of code that have been commented on are indicated by a bar floating to the left of the line numbers. Commented lines that are part of published reviews are shown with a blue bar, while lines that are part of your draft review are shown with a green bar.

../../../_images/diff-comments.png

Comments support rich text using Markdown and provide issue tracking capabilities.

Commenting on Lines

Creating a comment is easy. To comment on a single line, 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.

To leave a comment across multiple lines, click-and-drag down multiple line numbers. Each will highlight and be made a part of your comment.

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

After saving a comment, you can re-edit it by clicking the green comment bar, or by editing it in the review dialog.

Reading Published Comments

While reviewing code, you may have something to say about a line of code, but want to check first that someone else hasn’t already said it. Before leaving a comment, check if there’s a blue comment bar alongside the code. If there is, you can mouse over and read snippets of the discussion in a tooltip, or click the bar to read more.

Clicking the bar will display the comment dialog with a side pane showing any other comments for that line, along with links for viewing or replying to the full comment on the review request page.

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

If you have something new to say as part of your own review, you can write a new comment in the comment dialog.

Note

It’s important to note that this is not the place to reply to those comments. When you add a comment from the diff viewer, it’s creating a new top-level review (akin to a new thread). If you want to reply to existing comments, you can do so from the Reviews page. The Reply link here is a shortcut to jump directly to the relevant comment on the Reviews page.

The view here is meant to be used only as a reference to see if other people have already said what you plan to say.