Rename {git- => git}remote-helpers.txt
[git/mingw.git] / contrib / diff-highlight / README
blob502e03b3058e947835d396540af39c83a45d42aa
1 diff-highlight
2 ==============
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.
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.
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:
17   1. It will only highlight hunks in which the number of removed and
18      added lines is the same, and it will pair lines within the hunk by
19      position (so the first removed line is compared to the first added
20      line, and so forth). This is simple and tends to work well in
21      practice. More complex changes don't highlight well, so we tend to
22      exclude them due to the "same number of removed and added lines"
23      restriction. Or even if we do try to highlight them, they end up
24      not highlighting because of our "don't highlight if the whole line
25      would be highlighted" rule.
27   2. It will find the common prefix and suffix of two lines, and
28      consider everything in the middle to be "different". It could
29      instead do a real diff of the characters between the two lines and
30      find common subsequences. However, the point of the highlight is to
31      call attention to a certain area. Even if some small subset of the
32      highlighted area actually didn't change, that's OK. In practice it
33      ends up being more readable to just have a single blob on the line
34      showing the interesting bit.
36 The goal of the script is therefore not to be exact about highlighting
37 changes, but to call attention to areas of interest without being
38 visually distracting.  Non-diff lines and existing diff coloration is
39 preserved; the intent is that the output should look exactly the same as
40 the input, except for the occasional highlight.
42 Use
43 ---
45 You can try out the diff-highlight program with:
47 ---------------------------------------------
48 git log -p --color | /path/to/diff-highlight
49 ---------------------------------------------
51 If you want to use it all the time, drop it in your $PATH and put the
52 following in your git configuration:
54 ---------------------------------------------
55 [pager]
56         log = diff-highlight | less
57         show = diff-highlight | less
58         diff = diff-highlight | less
59 ---------------------------------------------
61 Bugs
62 ----
64 Because diff-highlight relies on heuristics to guess which parts of
65 changes are important, there are some cases where the highlighting is
66 more distracting than useful. Fortunately, these cases are rare in
67 practice, and when they do occur, the worst case is simply a little
68 extra highlighting. This section documents some cases known to be
69 sub-optimal, in case somebody feels like working on improving the
70 heuristics.
72 1. Two changes on the same line get highlighted in a blob. For example,
73    highlighting:
75 ----------------------------------------------
76 -foo(buf, size);
77 +foo(obj->buf, obj->size);
78 ----------------------------------------------
80    yields (where the inside of "+{}" would be highlighted):
82 ----------------------------------------------
83 -foo(buf, size);
84 +foo(+{obj->buf, obj->}size);
85 ----------------------------------------------
87    whereas a more semantically meaningful output would be:
89 ----------------------------------------------
90 -foo(buf, size);
91 +foo(+{obj->}buf, +{obj->}size);
92 ----------------------------------------------
94    Note that doing this right would probably involve a set of
95    content-specific boundary patterns, similar to word-diff. Otherwise
96    you get junk like:
98 -----------------------------------------------------
99 -this line has some -{i}nt-{ere}sti-{ng} text on it
100 +this line has some +{fa}nt+{a}sti+{c} text on it
101 -----------------------------------------------------
103    which is less readable than the current output.
105 2. The multi-line matching assumes that lines in the pre- and post-image
106    match by position. This is often the case, but can be fooled when a
107    line is removed from the top and a new one added at the bottom (or
108    vice versa). Unless the lines in the middle are also changed, diffs
109    will show this as two hunks, and it will not get highlighted at all
110    (which is good). But if the lines in the middle are changed, the
111    highlighting can be misleading. Here's a pathological case:
113 -----------------------------------------------------
114 -one
115 -two
116 -three
117 -four
118 +two 2
119 +three 3
120 +four 4
121 +five 5
122 -----------------------------------------------------
124    which gets highlighted as:
126 -----------------------------------------------------
127 -one
128 -t-{wo}
129 -three
130 -f-{our}
131 +two 2
132 +t+{hree 3}
133 +four 4
134 +f+{ive 5}
135 -----------------------------------------------------
137    because it matches "two" to "three 3", and so forth. It would be
138    nicer as:
140 -----------------------------------------------------
141 -one
142 -two
143 -three
144 -four
145 +two +{2}
146 +three +{3}
147 +four +{4}
148 +five 5
149 -----------------------------------------------------
151    which would probably involve pre-matching the lines into pairs
152    according to some heuristic.