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
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
|
========================================
The Almost Secret Features of xxdiff
========================================
:Author: Martin Blais <blais@furius.ca>
:Last update: 2006-04-12
:Abstract:
A short exposé of some of the least-known or non-obvious features of xxdiff.
.. contents:: Table of Contents
..
1 Introduction
2 Horizontal Diffs
3 Checking for Strict Equality
4 Number of Remaining Hunks
5 Selecting Text
6 Per-Hunk Ignore Whitespace
7 Decision Mode
Introduction
------------
xxdiff has grown a number of little cool features that are not necessarily
obvious from its user interface. This documents aims at presenting some of them
together outside of the general documentation. (All these features are also
documented in the user's manual.)
Horizontal Diffs
----------------
When there are small changes between lines, it can be laborious to quickly
figure out exactly what has changed between them. An extremely addictive
feature of xxdiff is that it can compute the diffs between pairs of matching
lines, i.e. horizontal diffs. The differing parts are highlighted with a
brighter color.
.. figure:: horiz.png
Checking for Strict Equality
----------------------------
When comparing a large number of files for merge review, we want to minimize the
amount of time we spend on useless changes, and you will most likely enable the
"ignore whitespace" features. Sometimes some automated scripts that will launch
xxdiff will be lauching it on two files which have no non-whitespace
differences. It is then impossible to "see" if the files are exactly the same
or not (I mean, byte-for-byte the same or not).
.. figure:: equals.png
Sometimes it is important to know that, for example, before committing changes
to a revision control system. For this purpose, you can check out the label
over the overview area which will contain an equal sign ``(=)`` if there are no
differences at all, not even whitespace differences. If you can see no visible
differences and this marker is not present, this indicates that the files do
differ, probably just in whitespace.
Number of Remaining Hunks
-------------------------
That little number of the overview area is the number of diff hunks that are
unselected. You can save a merged result when all the hunks are selected, so
this indicates the number of remaining hunks to resolve before you can save.
Selecting Text
--------------
In the context of merge reviewing, it is often useful to make comments on the
code that is visible from xxdiff. You can use the ``Control`` key and mouse
button 1 to select an arbitrary set of lines in either file, and that text is
put into the clipboard. You can then cut-n-paste it in a text editor where you
make your comments.
A red line appears to display the selection of text stored in the clipboard.
.. figure:: select.png
How the line is formatted can be configured with the resources to include the
line numbers and some other things.
Per-Hunk Ignore Whitespace
--------------------------
Often in a context of looking at many changes, code reviewers get really annoyed
with having to review formatting changes intermixed with code changes.
Fortunately, some of these changes can be ignored by diff by ignoring the
whitespace characters (and this is also supported by xxdiff) but this does not
help for the cases when reformatting involves breaking lines.
In practice, if you're just re-formatting some code, it is often the case that
only whitespace differences are appearing in a diff hunk. For this purpose,
xxdiff has a special feature that de-emphasizes diff hunks that only differ in
whitespace.
.. figure:: perhunk.png
The algorithm we use is really simple: given a diff hunk with text on both
sides (i.e. a change hunk), we compare all the non-whitespace characters. If
the entire hunks do not differ in that way, we de-emphasize the hunk to make it
look like both regions are the same (using a gray color similar to the color for
non-differing hunks). Those hunks are otherwise still selectable for merging.
Decision Mode
-------------
Sometimes you want to force the user to produce a merged file. There is a
special “decision” mode that does just that. In the toolbar-if you have that
enabled-3 buttons will appear:
.. figure:: rma.png
Decision mode: you must Reject, Accept or Merge.
1. **R**: reject the changes (keep the left file);
2. **M**: merge the selected changes (keep the selections) [#]_;
3. **A**: accept the changes (keep the right file);
Upon exit, xxdiff will print one of following strings on stdout: ``REJECT``,
``MERGED`` or ``ACCEPT``, corresponding to the user's choices. (If you close
xxdiff via your window manager, a special ``NODECISION`` code will be output).
This can be used in collaboration with the ``--merged-filename`` option to write
scripts that will invoke xxdiff to get a merged file, and then do something with
that merged file (for example, this could be used to resolve conflicts).
In addition, there is a Python xxdiff package that supports calling xxdiff in
this way. See the ``xxdiff.invoke`` module in the Python xxdiff scripts code.
.. [#] Note that if you exit with **M**, xxdiff will make sure that all diff
hunks have had a decision made for them, and ask you what to do with the
unselected hunks if any have been forgotten.
--------------------------------------------------------------------------------
.. (FIXME finish documenting other features here)
|
