Diff mode is a major mode used for the output of M-x diff and
other similar commands. This kind of output is called a patch,
because it can be passed to the
patch command to
automatically apply the specified changes. To select Diff mode
manually, type M-x diff-mode.
The changes specified in a patch are grouped into hunks, which are contiguous chunks of text that contain one or more changed lines. Hunks can also include unchanged lines to provide context for the changes. Each hunk is preceded by a hunk header, which specifies the old and new line numbers at which the hunk occurs. Diff mode highlights each hunk header, to distinguish it from the actual contents of the hunk.
You can edit a Diff mode buffer like any other buffer. (If it is
read-only, you need to make it writable first. See Misc Buffer.)
Whenever you change a hunk, Diff mode attempts to automatically
correct the line numbers in the hunk headers, to ensure that the patch
remains “correct”. To disable automatic line number correction,
change the variable
Diff mode treats each hunk as an “error message”, similar to Compilation mode. Thus, you can use commands such as C-x ' to visit the corresponding source locations. See Compilation Mode.
In addition, Diff mode provides the following commands to navigate, manipulate and apply parts of patches:
Move to the next hunk-start (
This command has a side effect: it refines the hunk you move to, highlighting its changes with better granularity. To disable this feature, type M-x diff-auto-refine-mode to toggle off the minor mode Diff Auto-Refine mode. To disable Diff Auto Refine mode by default, add this to your init file (see Hooks):
(add-hook 'diff-mode-hook (lambda () (diff-auto-refine-mode -1)))
Move to the previous hunk-start (
M-n, this has the side-effect of refining the hunk you move to,
unless you disable Diff Auto-Refine mode.
Move to the next file-start, in a multi-file patch
Move to the previous file-start, in a multi-file patch
Kill the hunk at point (
In a multi-file patch, kill the current file part.
Apply this hunk to its target file (
diff-apply-hunk). With a
prefix argument of C-u, revert this hunk.
Highlight the changes of the hunk at point with a finer granularity
diff-refine-hunk). This allows you to see exactly which parts
of each changed line were actually changed.
Go to the source file and line corresponding to this hunk
Start an Ediff session with the patch (
See Ediff in The Ediff Manual.
Restrict the view to the current hunk (
See Narrowing. With a prefix argument of C-u, restrict the
view to the current file of a multiple-file patch. To widen again,
use C-x n w (
Reverse the direction of comparison for the entire buffer
Split the hunk at point (
diff-split-hunk). This is for
manually editing patches, and only works with the unified diff
format produced by the -u or --unified options to
diff program. If you need to split a hunk in the
context diff format produced by the -c or
--context options to
diff, first convert the buffer
to the unified diff format with C-c C-u.
Convert the entire buffer to the context diff format
diff-unified->context). With a prefix argument, convert only
the text within the region.
Convert the entire buffer to unified diff format
diff-context->unified). With a prefix argument, convert
unified format to context format. When the mark is active, convert
only the text within the region.
Refine the current hunk so that it disregards changes in whitespace
Generate a ChangeLog entry, like C-x 4 a does (see Change Log), for each one of the hunks
diff-add-change-log-entries-other-window). This creates a
skeleton of the log of changes that you can later fill with the actual
descriptions of the changes. C-x 4 a itself in Diff mode
operates on behalf of the current hunk’s file, but gets the function
name from the patch itself. This is useful for making log entries for
functions that are deleted by the patch.
Patches sometimes include trailing whitespace on modified lines, as an unintentional and undesired change. There are two ways to deal with this problem. Firstly, if you enable Whitespace mode in a Diff buffer (see Useless Whitespace), it automatically highlights trailing whitespace in modified lines. Secondly, you can use the command M-x diff-delete-trailing-whitespace, which searches for trailing whitespace in the lines modified by the patch, and removes that whitespace in both the patch and the patched source file(s). This command does not save the modifications that it makes, so you can decide whether to save the changes (the list of modified files is displayed in the echo area). With a prefix argument, it tries to modify the original source files rather than the patched source files.