User guide / Files and buffers

Comparing two files

Development reference · View source

CommandEffect
:diff-this (:difft, :dt)Mark this buffer, or compare it with the one marked before
:diff-this in the marked bufferTake the mark back
:diff-off (:do)Close the comparison
:diff-disk, Space b dCompare with a fresh disk snapshot
:diff-remoteCompare a provider document with a fresh remote snapshot
Space g DCompare the active file’s Git versions; see Git

Example:

  1. Open old.rs and run :dt.
  2. Open new.rs and run :dt again.

old.rs appears on the left and new.rs on the right. If old.rs was not on screen, the second command splits for it. If both were already in panes, those panes are used.

Alignment:

  • Corresponding lines sit level. Where one side has lines the other lacks, the other side shows a hatched filler row. It belongs to no line: it cannot be clicked, labelled by goto-word, or moved onto, like the blank area past the last line.
  • The two sides scroll together. The pane you are in leads and the other follows the line facing it, which is not the same line number once the files have drifted apart.

Live changes. Both files stay editable, and the comparison follows what you type.

Shown asMeaning
AddedLines only the right side has
RemovedLines only the left side has
ChangedLines that answer to different lines on the other side
  • Lines replaced by an unequal number of lines are one change, not a deletion plus an addition — the same folding the Git gutter does.
  • The gutter shows the comparison instead of Git marks while the comparison is open.
  • Large buffers are compared in the background after an edit. Until it catches up, change colours pause and the panes keep the known alignment, adjusting for inserted or removed rows. A whole-buffer replacement without an edit transaction may align rows by number meanwhile.

Display:

  • Soft wrap is off while a comparison is open, whatever editor.soft_wrap says, and returns afterwards: a wrapped line would take different numbers of rows on each side.
  • Folded regions are expanded for the same reason.

Ending it. A comparison needs both panes and both buffers. Closing either pane, or showing a different buffer in one, ends it. The Git comparison from Space g D also owns the split it created, so closing either side or :diff-off collapses it and restores the previous buffer or the explorer.