Diffs

When you view a changelist or code review, the associated files are presented as diffsClosed(noun) A set of lines that do not match when two files, or stream versions, are compared. A conflict is a pair of unequal diffs between each of two files and a base, or between two versions of a stream. (verb) To compare the contents of files or file revisions, or of stream versions. See also conflict., short for differences, showing you how they have changed.

Initial Diff Display

Swarm supports stream specs that are edited in your workspace using the Private editing of streams feature. If a changelist or review contains a stream spec, it will be displayed first in Files with the prefix stream: //, for example: stream://MyStreamDepotName/MyStreamSpecLocationName. A changelist/review can only contain 1 stream spec.

Note

If you append a changelist with a stream spec to a review that already contains a stream spec, the spec in the changelist replaces the original one in the review. If it is a different spec from the original spec in the review, Swarm cannot display the diff between them and displays File content unchanged.

The review revision selectors are used to specify which revisions of a review you want to diffClosed(noun) A set of lines that do not match when two files, or stream versions, are compared. A conflict is a pair of unequal diffs between each of two files and a base, or between two versions of a stream. (verb) To compare the contents of files or file revisions, or of stream versions. See also conflict., they are located in the Files tab above the list of files.

Tip

If a review consists of one or more Swarm-managed changelists. When comparing versions of a review, Swarm is showing any differences between the selected versions, not the review author's personal changelist. See Internal representation for details.

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

Image of Diff Buttons for all Files
  • Show Comments button: toggles the display of comments to inline in files or only in the Comments tab.
  • Show Diffs In-Line button: displays all diffs as inline.
  • Show Diffs Side-by-Side button: displays all diffs as side-by-side.
  • Toggle Show Whitespace button: toggles the display of whitespace characters (such as space, tab, and newline) for all files.
  • Toggle Ignore Whitespace button: toggles the highlighting of whitespace changes in all of the file diffs.
    • Highlight whitespace changes: makes it easier to identify changes in file types where whitespace is important. This is the default value.
    • Ignore whitespace changes: whitespace changes are not highlighted, this makes it easier to see the important changes in file types where whitespace changes are not important.
  • Collapse All button: collapses all files
  • Expand All button: expands all files. By default this button is disabled if there are more than 10 files in the review. For details, see Expand All Limit.
Tip

The default states for the Show Comments, Show Diffs Side-by-Side, Toggle Show Whitespace, and Toggle Ignore Whitespace buttons are set in your user settings, see User Settings.

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

  • File Added/Branched/Imported icon image Added/Branched/Imported
  • File Edited/Integrated icon image Edited/Integrated
  • File Deleted icon image Deleted

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

Tip

Only the Show Full Context button is available for stream specs.

Image of Diff Buttons for a Single File
  • Comments in File icon (only displayed if the file contains comments): indicates that the file contains comments.
  • Show In-line button: highlights line additions, modifications, and removals in a single pane.
  • Show Side-by-Side button: 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 button: 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: toggles the highlighting of whitespace changes in a file, making it easier to identify non-formatting changes. Normally, whitespace is not ignored.
  • Toggle Ignore Whitespace button: toggles the highlighting of whitespace changes in the file diff.
    • Highlight whitespace changes: makes it easier to identify changes in file types where whitespace is important. This is the default value.
    • Ignore whitespace changes: whitespace changes are not highlighted, this makes it easier to see the important changes in file types where whitespace changes are not important.
  • Show all diffs button (edited and integrated files only): 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. If there are fewer than that then this button is hidden.
  • Show Full Context button (edited and integrated files only): toggles between displaying only the portions of the file that have changed and the full file.
  • Open File button (edited or integrated files only): 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 file as read button (displayed for code reviews only): 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 color inverts and the associated file is visually muted, to make it easy to distinguish read files from unread files:

    File Marked as Read image

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

Viewing a diff

When you view a diff, the changes are highlighted:

  • Red indicates lines that have been removed.
  • Blue indicates lines that have been modified.
  • Green indicates lines that have been added.
Image of a Side-by-Side Diff with Changes

 

Image of a Side-by-Side Diff Showing the Final Change in a File

Show more context buttons

The diff presentation displays a concise view of where changes were made within a file, showing the changed lines and only a few lines before and after the change. Sometimes, this concise view needs to be expanded to fully understand the context of the change, use the Show More and Show All buttons to display extra lines around the change:

Note

By default, the number of extra lines displayed when you click the Show More Lines Above and Show More Lines Below buttons is 10. This setting can be changed by your Swarm administrator, see More context lines.

Tip

The following buttons are not available for stream specs.

  • Show All Lines to Start of File Show All Lines Above button image button (only displayed for the first change in the file): click to show all of the lines up to the start of the file.
  • Show More Lines for the Code Below Show More Lines Above button image button: click to show 10 more lines above the change, the extra lines are displayed in the pane below the button.
  • Show Entire Section Show Entire Section button image button: click to show all of the lines between the changes that are above and below the button, the two changes and the lines between them are displayed in a single pane.
  • Show More Lines for the Code Above Show More Lines Below button image button: click to show 10 more lines below the change, the extra lines are displayed in the pane above the button.
  • Show All Lines to End of File Show All Lines Below button image button (only displayed for the last change in the file): click to show all of the lines down to the end of the file.

Comments

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

Image of a Side-by-Side Diff with a Comment Displayed
Note

The comment here icon Comments Here icon image appears in the line number column whenever there is a comment. Click the icon to display the comment and click the icon again to collapse the comment. This is useful when the comment display is toggled off.

Inline diff view

When viewing a diff in-line, the line numbers for the old version are first, the line numbers for the new version are second, and they are followed by the file content. Some users find it easier to use this view to locate an area that has changed, but they then switch to the side-by-side view to 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 image
Note

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

Per-file toolbar

When a diff contains multiple files, the changes can be taller than your browser window. Swarm keeps the per-file toolbar in view for each file as you scroll, this means that you can identify the file and control its presentation with the buttons on the right of the toolbar.

Image of the Per-file Toolbars Stay in View as You Scroll