code.delx.au - gnu-emacs-elpa/blob - README.md

   1 About
   2 =====
   3
   4 `diff-hl-mode` highlights uncommitted changes on the left side of the window,
   5 allows you to jump between and revert them selectively.
   6
   7 For the usage instructions and the list of commands, see the Commentary section
   8 inside the file.
   9
  10 Tested with Git, Mercurial, Bazaar and SVN. May work with other VC backends, too.
  11
  12 The package also contains auxiliary modes:
  13
  14 * `diff-hl-dired-mode` provides similar functionality in Dired.
  15 * `diff-hl-margin-mode` changes the highlighting function to
  16   use the margin instead of the fringe.
  17 * `diff-hl-amend-mode` shifts the reference revision back by one.
  18 * `diff-hl-flydiff-mode` implements highlighting changes on the fly.
  19   It requires Emacs 24.4 or newer.
  20
  21 Check out the Commentary section in each respective file for the usage
  22 instructions.
  23
  24 Screenshots
  25 =====
  26
  27 diff-hl-mode
  28 -----
  29 Top window: a buffer in this minor mode, bottom window: the corresponding diff.
  30
  31 ![screenie](screenshot.png)
  32
  33 diff-hl-dired-mode
  34 -----
  35
  36 ![screenie](screenshot-dired.png)
  37
  38 diff-hl-margin-mode
  39 -----
  40
  41 ![screenie](screenshot-margin.png)
  42
  43 Requirements
  44 =====
  45
  46 Emacs 24+. On OS X, Emacs 24.3 or higher is recommended.
  47
  48 Notes
  49 =====
  50
  51 * By default `diff-hl-mode` uses the corresponding VC diff command, so
  52   it's only accurate when the buffer is in saved state. Check out
  53   `diff-hl-flydiff-mode`, it aims to handle unsaved buffers as well.
  54
  55 * To use an
  56   [alternative diff algorithm](http://stackoverflow.com/questions/32365271/whats-the-difference-between-git-diff-patience-and-git-diff-histogram)
  57   with Git, add a corresponding argument to `vc-git-diff-switches`,
  58   e.g. `(setq vc-git-diff-switches '("--histogram"))`. Using the
  59   `diff.algorithm` option doesn't work
  60   [because](http://article.gmane.org/gmane.comp.version-control.git/294622)
  61   `vc-git-diff` calls `git diff-index`. `diff-hl-flydiff-mode` does
  62   not support alternative algorithms, because it uses the external
  63   `diff` program.
  64
  65 * We conflict with other modes when they put indicators on the fringe,
  66   such as [Flycheck](https://github.com/flycheck/flycheck). This is
  67   rarely a significant problem, since if you're using such a mode,
  68   you'd usually want to fix all errors and warnings before continuing,
  69   and then the conflicting indicators go away.
  70
  71 * There's no fringe when Emacs is running in the console, but the navigation
  72   and revert commands still work. Consider turning `diff-hl-margin-mode` on,
  73   to show the indicators in the margin instead.
  74
  75 * Frame-local and buffer-local values of `line-spacing` are not supported.
  76
  77 * Fringe width up to 16 works best (because we can't define a bitmap
  78   with width above that number).
  79
  80 * [emacs-git-gutter](https://github.com/syohex/emacs-git-gutter) shows
  81   indicators in the margin by default, allows you to customize how the
  82   indicators look more easily, and has a "stage hunk" command.
  83
  84 Integration
  85 =====
  86
  87 If you're using some package other than `vc` to commit changes, it might
  88 not run `vc-checkin-hook` after commits. In that case, you'll need to
  89 either add `diff-hl-update` to the hook it does run, or advise some
  90 function that's called in the buffer after its state has changed.
  91
  92 psvn
  93 -----
  94
  95 ```lisp
  96 (defadvice svn-status-update-modeline (after svn-update-diff-hl activate)
  97   (diff-hl-update))
  98 ```
  99
 100 Magit
 101 -----
 102
 103 If you're using a version before 2.4.0, it defines `magit-revert-buffer-hook`
 104 (or `magit-not-reverted-hook`), which we use.
 105
 106 When using Magit 2.4 or newer, add this to your init script:
 107
 108 ```lisp
 109 (add-hook 'magit-post-refresh-hook 'diff-hl-magit-post-refresh)
 110 ```