contrib / diff-highlight / READMEon commit Merge branch 'jc/maint-diff-patch-header' into maint (fce8b5d)
   1diff-highlight
   2==============
   3
   4Line oriented diffs are great for reviewing code, because for most
   5hunks, you want to see the old and the new segments of code next to each
   6other. Sometimes, though, when an old line and a new line are very
   7similar, it's hard to immediately see the difference.
   8
   9You can use "--color-words" to highlight only the changed portions of
  10lines. However, this can often be hard to read for code, as it loses
  11the line structure, and you end up with oddly formatted bits.
  12
  13Instead, this script post-processes the line-oriented diff, finds pairs
  14of lines, and highlights the differing segments.  It's currently very
  15simple and stupid about doing these tasks. In particular:
  16
  17  1. It will only highlight a pair of lines if they are the only two
  18     lines in a hunk.  It could instead try to match up "before" and
  19     "after" lines for a given hunk into pairs of similar lines.
  20     However, this may end up visually distracting, as the paired
  21     lines would have other highlighted lines in between them. And in
  22     practice, the lines which most need attention called to their
  23     small, hard-to-see changes are touching only a single line.
  24
  25  2. It will find the common prefix and suffix of two lines, and
  26     consider everything in the middle to be "different". It could
  27     instead do a real diff of the characters between the two lines and
  28     find common subsequences. However, the point of the highlight is to
  29     call attention to a certain area. Even if some small subset of the
  30     highlighted area actually didn't change, that's OK. In practice it
  31     ends up being more readable to just have a single blob on the line
  32     showing the interesting bit.
  33
  34The goal of the script is therefore not to be exact about highlighting
  35changes, but to call attention to areas of interest without being
  36visually distracting.  Non-diff lines and existing diff coloration is
  37preserved; the intent is that the output should look exactly the same as
  38the input, except for the occasional highlight.
  39
  40Use
  41---
  42
  43You can try out the diff-highlight program with:
  44
  45---------------------------------------------
  46git log -p --color | /path/to/diff-highlight
  47---------------------------------------------
  48
  49If you want to use it all the time, drop it in your $PATH and put the
  50following in your git configuration:
  51
  52---------------------------------------------
  53[pager]
  54        log = diff-highlight | less
  55        show = diff-highlight | less
  56        diff = diff-highlight | less
  57---------------------------------------------