/ README.md
README.md
1 About [](https://github.com/dgutov/diff-hl/actions/workflows/ci.yml) 2 ===== 3 4 `diff-hl-mode` highlights uncommitted changes on the side of the window, allows 5 you to jump between and revert them selectively. 6 7 This feature is also known as "source control gutter indicators". 8 9 In buffers controlled by Git, you can stage and unstage the changes. 10 11 For the usage instructions and the list of commands, see the Commentary section 12 inside the file. 13 14 Tested with Git, Mercurial, Bazaar and SVN. May work with other VC backends, too. 15 16 The package also contains auxiliary modes: 17 18 * `diff-hl-dired-mode` provides similar functionality in Dired. 19 * `diff-hl-margin-mode` changes the highlighting function to 20 use the margin instead of the fringe. 21 * But if you use a non-graphical terminal, the package will fall back to using 22 the margins anyway, as long as `diff-hl-fallback-to-margin` is non-nil and the 23 margin width is non-zero. 24 * `diff-hl-amend-mode` sets the reference revision to the one before 25 recent one. Also, you could use `diff-hl-set-reference-rev` to set 26 it to any revision, see its docstring for details. 27 * `diff-hl-flydiff-mode` implements highlighting changes on the fly. 28 * `diff-hl-show-hunk-mouse-mode` makes fringe and margin react to 29 mouse clicks to show the corresponding hunk. That's the alternative 30 to using `diff-hl-show-hunk` and friends. 31 32 Usage 33 ===== 34 35 Put this into your init script: 36 37 ```lisp 38 (global-diff-hl-mode) 39 ``` 40 41 You must also ensure that VC is enabled (e.g. `vc-handled-backends` is 42 not nil). 43 44 Check out the Commentary section in each file for more detailed usage 45 instructions. 46 47 Screenshots 48 ===== 49 50 diff-hl-mode 51 ----- 52 Top window: a buffer in this minor mode, bottom window: the corresponding diff. 53 54  55 56 diff-hl-dired-mode 57 ----- 58 59  60 61 diff-hl-margin-mode 62 ----- 63 64  65 66 Requirements 67 ===== 68 69 Emacs 26.1+. 70 71 Notes 72 ===== 73 74 * By default `diff-hl-mode` only updates the display when the buffer is in 75 saved state. For a different tradeoff, also enable `diff-hl-flydiff-mode`, 76 which makes the updates happen on a timer. 77 78 * To use an 79 [alternative diff algorithm](http://stackoverflow.com/questions/32365271/whats-the-difference-between-git-diff-patience-and-git-diff-histogram) 80 with Git, add a corresponding argument to `vc-git-diff-switches`, 81 e.g. `(setq vc-git-diff-switches '("--histogram"))`. Using the 82 `diff.algorithm` option doesn't work 83 [because](http://article.gmane.org/gmane.comp.version-control.git/294622) 84 `vc-git-diff` calls `git diff-index`. `diff-hl-flydiff-mode` does 85 not support alternative algorithms, because it uses the external 86 `diff` program. 87 88 * We conflict with other modes when they put indicators on the fringe, 89 such as [Flycheck](https://github.com/flycheck/flycheck). This is 90 rarely a significant problem, since if you're using such a mode, 91 you'd usually want to fix all errors and warnings before continuing, 92 and then the conflicting indicators go away. 93 94 * There's no fringe when Emacs is running in the console, but the navigation 95 and revert commands still work. Consider turning `diff-hl-margin-mode` on, 96 to show the indicators in the margin instead. It also helps avoid the conflict 97 with Flycheck/Flymake even on graphical frames. 98 99 * Frame-local and buffer-local values of `line-spacing` are not supported. 100 101 * Fringe width up to 16 works best (because we can't define a bitmap 102 with width above that number). 103 104 Integration 105 ===== 106 107 If you're using some package other than `vc` to commit changes, it might 108 not run `vc-checkin-hook` after commits. In that case, you'll need to 109 either add `diff-hl-update` to the hook it does run, or advise some 110 function that's called in the buffer after its state has changed. 111 112 psvn 113 ----- 114 115 ```lisp 116 (advice-add 'svn-status-update-modeline :after #'diff-hl-update) 117 ``` 118 119 Magit 120 ----- 121 122 If you're using a version before 2.4.0, it defines `magit-revert-buffer-hook` 123 (or `magit-not-reverted-hook`), which we use. 124 125 When using Magit 2.4 or newer, add this to your init script: 126 127 ```lisp 128 (add-hook 'magit-post-refresh-hook 'diff-hl-magit-post-refresh) 129 ``` 130 131 Tramp 132 ----- 133 134 `diff-hl` should just work with Tramp. But slow or high latency 135 connections can cause performance problems. If you experience such 136 issues, customize `diff-hl-disable-on-remote` to `t`. This will change 137 the behavior of both `turn-on-diff-hl-mode` and `global-diff-hl-mode` 138 (whichever you prefer to use).