Awesome
About
diff-hl-mode
highlights uncommitted changes on the left side of the
window (area also known as the "gutter"), allows you
to jump between and revert them selectively.
In buffers controlled by Git, you can also stage and unstage the changes.
For the usage instructions and the list of commands, see the Commentary section inside the file.
Tested with Git, Mercurial, Bazaar and SVN. May work with other VC backends, too.
The package also contains auxiliary modes:
diff-hl-dired-mode
provides similar functionality in Dired.diff-hl-margin-mode
changes the highlighting function to use the margin instead of the fringe.diff-hl-amend-mode
sets the reference revision to the one before recent one. Also, you could usediff-hl-set-reference-rev
to set it to any revision, see its docstring for details.diff-hl-flydiff-mode
implements highlighting changes on the fly.diff-hl-show-hunk-mouse-mode
makes fringe and margin react to mouse clicks to show the corresponding hunk. That's the alternative to usingdiff-hl-show-hunk
and friends.
Usage
Put this into your init script:
(global-diff-hl-mode)
You must also ensure that VC is enabled (e.g. vc-handled-backends
is
not nil).
Check out the Commentary section in each file for more detailed usage instructions.
Screenshots
diff-hl-mode
Top window: a buffer in this minor mode, bottom window: the corresponding diff.
diff-hl-dired-mode
diff-hl-margin-mode
Requirements
Emacs 25.1+.
Notes
-
By default
diff-hl-mode
uses the corresponding VC diff command, so it's only accurate when the buffer is in saved state. Check outdiff-hl-flydiff-mode
, it aims to handle unsaved buffers as well. -
To use an alternative diff algorithm with Git, add a corresponding argument to
vc-git-diff-switches
, e.g.(setq vc-git-diff-switches '("--histogram"))
. Using thediff.algorithm
option doesn't work becausevc-git-diff
callsgit diff-index
.diff-hl-flydiff-mode
does not support alternative algorithms, because it uses the externaldiff
program. -
We conflict with other modes when they put indicators on the fringe, such as Flycheck. This is rarely a significant problem, since if you're using such a mode, you'd usually want to fix all errors and warnings before continuing, and then the conflicting indicators go away.
-
There's no fringe when Emacs is running in the console, but the navigation and revert commands still work. Consider turning
diff-hl-margin-mode
on, to show the indicators in the margin instead. -
Frame-local and buffer-local values of
line-spacing
are not supported. -
Fringe width up to 16 works best (because we can't define a bitmap with width above that number).
-
emacs-git-gutter shows indicators in the margin by default, allows you to customize how the indicators look more easily, and has a "stage hunk" command.
Integration
If you're using some package other than vc
to commit changes, it might
not run vc-checkin-hook
after commits. In that case, you'll need to
either add diff-hl-update
to the hook it does run, or advise some
function that's called in the buffer after its state has changed.
psvn
(advice-add 'svn-status-update-modeline :after #'diff-hl-update)
Magit
If you're using a version before 2.4.0, it defines magit-revert-buffer-hook
(or magit-not-reverted-hook
), which we use.
When using Magit 2.4 or newer, add this to your init script:
(add-hook 'magit-post-refresh-hook 'diff-hl-magit-post-refresh)
Tramp
diff-hl
should just work with Tramp. But slow or high latency
connections can cause performance problems. If you experience such
issues, customize diff-hl-disable-on-remote
to t
. This will change
the behavior of both turn-on-diff-hl-mode
and global-diff-hl-mode
(whichever you prefer to use).