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