Documentation Incremental Diff

Sublime Text includes a built-in diff functionality that tracks changes to files being edited. The diff calculation is incremental, tracking each buffer modification as it is performed. It does not require the file be stored in a version control system, such as Git.

The exact location of each addition, modification and deletion is tracked. This is used to display markers in the gutter, allow navigation between each change, display inline diffs and allow for reverting changes.

Diffs are calculated against the version of the file on disk, but Git repositories can be configured to diff against HEAD, and the API allows files to be diffed against any content.

Diff Markers

The following is an example of diff markers displayed when using the Mariana color scheme:

27
28 A line that was added
29
30 A modified line
31 followed by another modified line
32
33 The line before this was deleted
34

See the color schemes documentation for information on customizing the colors and width of the diff markers.

Users can jump to the next or previous modification using the following methods:

  • Ctrl+.
  • Ctrl+,
  • Goto ▶ Next Modification
  • Goto ▶ Previous Modification

The keyboard shortcuts tend to be a very natural way to jump around a file being edited.

Inline Diffs

In addition to tracking which lines have been modified, the incremental diff also tracks the exact changes. This allows displaying the original version of the text.

Toggling

When right-clicking on a modified region of a file, a menu entry Show Diff Hunk will be available. This menu item will display the previous content inline beneath the current content. Right-clicking again will show a menu item Hide Diff Hunk to hide the inline diff.

Toggling an inline diff may be performed via the Edit ▶ Text ▶ Toggle Hunk Diff menu.

In addition to menu-based activation, diffs may also be toggled via keyboard shortcut:

  • Windows/Linux: Ctrl+K, Ctrl+/
  • Mac: +K, +/

To toggle the diff for a region, while hiding all other diffs, press:

  • Windows/Linux: Ctrl+K, Ctrl+;
  • Mac: +K, +;

Styling

The styles used for displaying inline diffs are automatically generated for color schemes that have not created their own rules. For custom styles, add rules with the following selectors:

  • diff.deleted
  • diff.deleted.char
  • diff.inserted
  • diff.inserted.char

Generally each rule will set the background and foreground_adjust properties.

Reverting

A modification may be reverted to the original text by the keyboard shortcut:

  • Windows/Linux: Ctrl+K, Ctrl+Z
  • Mac: +K, +Z

Alternatively, the menu Edit ▶ Text ▶ Revert Modification may be used.

Settings

The incremental diff functionality may be controlled via the mini_diff setting. Valid values include:

  • true – always enable incremental diff (DEFAULT)
  • "auto" – enable incremental diff for files in a Git repository
  • false – disable incremental diff

The behavior of incremental diff for files in a Git repository can be controlled via the git_diff_target setting. Valid values include:

  • "index" – diff against the Git index, the default
  • "head" – diff against the file at HEAD