Merge git://ozlabs.org/~paulus/gitk
[git] / contrib / diff-highlight / README
1 diff-highlight
2 ==============
3
4 Line oriented diffs are great for reviewing code, because for most
5 hunks, you want to see the old and the new segments of code next to each
6 other. Sometimes, though, when an old line and a new line are very
7 similar, it's hard to immediately see the difference.
8
9 You can use "--color-words" to highlight only the changed portions of
10 lines. However, this can often be hard to read for code, as it loses
11 the line structure, and you end up with oddly formatted bits.
12
13 Instead, this script post-processes the line-oriented diff, finds pairs
14 of lines, and highlights the differing segments.  It's currently very
15 simple 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
34 The goal of the script is therefore not to be exact about highlighting
35 changes, but to call attention to areas of interest without being
36 visually distracting.  Non-diff lines and existing diff coloration is
37 preserved; the intent is that the output should look exactly the same as
38 the input, except for the occasional highlight.
39
40 Use
41 ---
42
43 You can try out the diff-highlight program with:
44
45 ---------------------------------------------
46 git log -p --color | /path/to/diff-highlight
47 ---------------------------------------------
48
49 If you want to use it all the time, drop it in your $PATH and put the
50 following in your git configuration:
51
52 ---------------------------------------------
53 [pager]
54         log = diff-highlight | less
55         show = diff-highlight | less
56         diff = diff-highlight | less
57 ---------------------------------------------