Diffs

When you view a changelist or code review, the associated files are presented as diffs, short for differences, showing you how they have changed.

initial Diff display

Diff buttons for all files The first row of buttons above the files allow you to (left to right):

  • Toggle the display of comments

  • Show all diffs as inline

  • Show all diffs as side-by-side

  • Toggle show whitespace for all files

  • Toggle ignore whitespace in diffs

  • Collapse all files

  • Expand all files. By default this button is disabled if there are more than 10 files in the review. For details, see Expand All Limit.

Each file is presented with an icon indicating whether the file was:

  • File Added icon Added/branched/imported

  • File Edited/Integrated icon Edited/integrated

  • File Deleted icon Deleted

Diff buttons for a single file

The file's presentation can be controlled with (left to right):

  • Show In-line button, which highlights line additions, modifications, and removals in a single pane.

  • Show Side-by-Side button, which highlights additions, modifications, and removals in two panes, with the older version of the file on the left, and the newer version on the right.

  • Show Whitespace enabledShow Whitespace button, which makes whitespace characters more visible; spaces show up as dots, tabs show up as arrows that point to a bar, and line endings show up as down-pointing arrows.

  • Ignore Whitespace button, which toggles the highlighting of whitespace changes in a file, making it easier to identify non-formatting changes. Normally, whitespace is not ignored; an administrator can change the default. See Diff configuration for details.

  • Show all diffs button toggles between displaying all the diffs for the file and only the first few. The limit of what are shown by default is configurable by the administrator (see Max Diffs) and defaults to 1500 and if there are fewer than that then this button is hidden (edited and integrated files only).

  • Show Full Context button toggles between displaying only the portions of the file that have changed and the full file (edited and integrated files only).

  • Show File button, displayed only for edited or integrated files, opens a new browser tab/window display the full file (where possible), provide access to its history, and a button to download the file.

  • Mark as Read button, displayed only for code reviews, helps you (and others) keep track of which files have been reviewed. This is particularly useful when a code review consists of many files.

    When clicked, the button's colors invert and the associated file is visually muted, to make it easy to distinguish read files from unread files:

    A file marked as read.

    If a file has been marked as read, click the button a second time to reset the status to unread.

The Comments Exist icon

If the file has comments associated, its entry shows a comments exist icon.

Viewing a diff

When you view a diff, the changes are highlighted:

Side-by-Side Diff with an add, edit, and delete

  • Red indicates lines that have been removed

  • Blue indicates lines that have been modified

  • Green indicates lines that have been added

The diff presentation displays a concise view of where changes are made within a file, showing the changed lines and only a few lines before and after each revision. Sometimes, this concise view is insufficient to understand the context of the change. The Show Full Context displays the entire file, but this can be too much detail.

The "Show More Context" row. When there are more lines in a file, either above or below the currently displayed diff, a Show More Context row appears.

Clicking this row attempts to display 10 additional lines adjacent to the row (which may appear between two modifications), allowing up to 20 lines of additional context to be displayed. The row disappears when no additional content is available.

Comments may be presented within the body of a file and appear immediately below the line the commenter targeted for comment. See Comments for more details.

Side-by-Side Diff with a comment displayed

Note

The Comment Exists Here icon The comment(s) exist here icon appears in the line number column whenever comments exist. This is useful when the comment display is toggled off.

When viewing a diff in-line, the line numbers for the old version are first, and the line numbers for the new version are second, followed by the file content. Some users find this view easier to use when locating an area that has changed, but then switch to side-by-side view to help them understand the change better. Swarm maintains the scroll position; you do not lose your place in the file after toggling the diff view.

Inline Diff

Note

Press n on your keyboard to scroll to the next changed area within a file. Press p to scroll to the previous change.

When a diff contains multiple files, the changes may be taller than your browser window. Swarm keeps the per-file toolbar in view for each file as you scroll, so that you can continue to identify the file at the top of the screen and control its presentation.

The per-file toolbars stay in view as you scroll