About\r
=====\r
\r
-`diff-hl-mode` highlights uncommitted changes on the left fringe of the window,\r
+`diff-hl-mode` highlights uncommitted changes on the left side of the window,\r
allows you to jump between and revert them selectively.\r
\r
-For the usage instructions and the list of commands, see the header comment.\r
+For the usage instructions and the list of commands, see the Commentary section\r
+inside the file.\r
\r
Tested with Git, Mercurial, Bazaar and SVN. May work with other VC backends, too.\r
\r
-Screenshot\r
+The package also contains auxiliary modes:\r
+\r
+* `diff-hl-dired-mode` provides similar functionality in Dired.\r
+* `diff-hl-margin-mode` changes the highlighting function to\r
+ use the margin instead of the fringe.\r
+* `diff-hl-amend-mode` shifts the reference revision back by one.\r
+* `diff-hl-flydiff-mode` implements highlighting changes on the fly.\r
+ It requires Emacs 24.4 or newer.\r
+\r
+Check out the Commentary section in each respective file for the usage\r
+instructions.\r
+\r
+Screenshots\r
=====\r
\r
+diff-hl-mode\r
+-----\r
+Top window: a buffer in this minor mode, bottom window: the corresponding diff.\r
+\r
\r
\r
-Top window: a buffer in this minor mode, bottom window: the corresponding diff.\r
+diff-hl-dired-mode\r
+-----\r
+\r
+\r
+\r
+diff-hl-margin-mode\r
+-----\r
+\r
+\r
\r
Requirements\r
=====\r
Notes\r
=====\r
\r
-* Since it uses the corresponding VC diff command, it's only accurate when the\r
- buffer is in saved state. Highlighting changes "on the fly" might be better,\r
- maybe we can do something similar to `highlight-markup-buffers` with a hidden\r
- buffer containing the unmodified copy.\r
+* By default `diff-hl-mode` uses the corresponding VC diff command, so\r
+ it's only accurate when the buffer is in saved state. Check out\r
+ `diff-hl-flydiff-mode`, it aims to handle unsaved buffers as well.\r
+\r
+* To use an\r
+ [alternative diff algorithm](http://stackoverflow.com/questions/32365271/whats-the-difference-between-git-diff-patience-and-git-diff-histogram)\r
+ with Git, add a corresponding argument to `vc-git-diff-switches`,\r
+ e.g. `(setq vc-git-diff-switches '("--histogram"))`. Using the\r
+ `diff.algorithm` option doesn't work\r
+ [because](http://article.gmane.org/gmane.comp.version-control.git/294622)\r
+ `vc-git-diff` calls `git diff-index`. `diff-hl-flydiff-mode` does\r
+ not support alternative algorithms, because it uses the external\r
+ `diff` program.\r
+\r
+* We conflict with other modes when they put indicators on the fringe,\r
+ such as [Flycheck](https://github.com/flycheck/flycheck). This is\r
+ rarely a significant problem, since if you're using such a mode,\r
+ you'd usually want to fix all errors and warnings before continuing,\r
+ and then the conflicting indicators go away.\r
+\r
+* There's no fringe when Emacs is running in the console, but the navigation\r
+ and revert commands still work. Consider turning `diff-hl-margin-mode` on,\r
+ to show the indicators in the margin instead.\r
+\r
+* Frame-local and buffer-local values of `line-spacing` are not supported.\r
+\r
+* Fringe width up to 16 works best (because we can't define a bitmap\r
+ with width above that number).\r
+\r
+* [emacs-git-gutter](https://github.com/syohex/emacs-git-gutter) shows\r
+ indicators in the margin by default, allows you to customize how the\r
+ indicators look more easily, and has a "stage hunk" command.\r
+\r
+Integration\r
+=====\r
+\r
+If you're using some package other than `vc` to commit changes, it might\r
+not run `vc-checkin-hook` after commits. In that case, you'll need to\r
+either add `diff-hl-update` to the hook it does run, or advise some\r
+function that's called in the buffer after its state has changed.\r
+\r
+psvn\r
+-----\r
+\r
+```lisp\r
+(defadvice svn-status-update-modeline (after svn-update-diff-hl activate)\r
+ (diff-hl-update))\r
+```\r
+\r
+Magit\r
+-----\r
+\r
+If you're using a version before 2.4.0, it defines `magit-revert-buffer-hook`\r
+(or `magit-not-reverted-hook`), which we use.\r
\r
-* There's no fringe when Emacs is running in the console, but the navigation and\r
- revert commands still work.\r
+When using Magit 2.4 or newer, add this to your init script:\r
\r
-* [git-gutter](https://github.com/syohex/emacs-git-gutter) provides interactive\r
- commands to show/hide/toggle margin indicators for the same information, and\r
- allows you to customize how the indicators look.\r
+```lisp\r
+(add-hook 'magit-post-refresh-hook 'diff-hl-magit-post-refresh)\r
+```\r