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
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
|
<?xml version="1.0" encoding="iso-8859-1" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
<title>The Almost Secret Features of xxdiff</title>
<meta name="author" content="Martin Blais <blais@furius.ca>" />
<link rel="stylesheet" href="../style.css" type="text/css" />
</head>
<body>
<div id="project-header">
<a href="/"><img src="/home/furius-logo-w.png" id="logo"></a>
<div id="project-home"><a href="..">Project Home</a></div>
</div>
<div class="document" id="the-almost-secret-features-of-xxdiff">
<h1 class="title">The Almost Secret Features of xxdiff</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Author:</th>
<td>Martin Blais <<a class="reference" href="mailto:blais@furius.ca">blais@furius.ca</a>></td></tr>
<tr class="field"><th class="docinfo-name">Last update:</th><td class="field-body">2006-04-12</td>
</tr>
</tbody>
</table>
<div class="abstract topic">
<p class="topic-title first">Abstract</p>
<p>A short expos of some of the least-known or non-obvious features of xxdiff.</p>
</div>
<div class="contents topic">
<p class="topic-title first"><a id="table-of-contents" name="table-of-contents">Table of Contents</a></p>
<ul class="simple">
<li><a class="reference" href="#introduction" id="id3" name="id3">Introduction</a></li>
<li><a class="reference" href="#horizontal-diffs" id="id4" name="id4">Horizontal Diffs</a></li>
<li><a class="reference" href="#checking-for-strict-equality" id="id5" name="id5">Checking for Strict Equality</a></li>
<li><a class="reference" href="#number-of-remaining-hunks" id="id6" name="id6">Number of Remaining Hunks</a></li>
<li><a class="reference" href="#selecting-text" id="id7" name="id7">Selecting Text</a></li>
<li><a class="reference" href="#per-hunk-ignore-whitespace" id="id8" name="id8">Per-Hunk Ignore Whitespace</a></li>
<li><a class="reference" href="#decision-mode" id="id9" name="id9">Decision Mode</a></li>
</ul>
</div>
<!-- 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 -->
<div class="section">
<h1><a class="toc-backref" href="#id3" id="introduction" name="introduction">Introduction</a></h1>
<p>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.)</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id4" id="horizontal-diffs" name="horizontal-diffs">Horizontal Diffs</a></h1>
<p>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.</p>
<div class="figure">
<img alt="horiz.png" src="horiz.png" />
</div>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id5" id="checking-for-strict-equality" name="checking-for-strict-equality">Checking for Strict Equality</a></h1>
<p>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).</p>
<div class="figure">
<img alt="equals.png" src="equals.png" />
</div>
<p>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 <tt class="docutils literal"><span class="pre">(=)</span></tt> 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.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id6" id="number-of-remaining-hunks" name="number-of-remaining-hunks">Number of Remaining Hunks</a></h1>
<p>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.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id7" id="selecting-text" name="selecting-text">Selecting Text</a></h1>
<p>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 <tt class="docutils literal"><span class="pre">Control</span></tt> 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.</p>
<p>A red line appears to display the selection of text stored in the clipboard.</p>
<div class="figure">
<img alt="select.png" src="select.png" />
</div>
<p>How the line is formatted can be configured with the resources to include the
line numbers and some other things.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id8" id="per-hunk-ignore-whitespace" name="per-hunk-ignore-whitespace">Per-Hunk Ignore Whitespace</a></h1>
<p>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.</p>
<p>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.</p>
<div class="figure">
<img alt="perhunk.png" src="perhunk.png" />
</div>
<p>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.</p>
</div>
<div class="section">
<h1><a class="toc-backref" href="#id9" id="decision-mode" name="decision-mode">Decision Mode</a></h1>
<p>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:</p>
<div class="figure">
<img alt="rma.png" src="rma.png" />
<p class="caption">Decision mode: you must Reject, Accept or Merge.</p>
</div>
<ol class="arabic simple">
<li><strong>R</strong>: reject the changes (keep the left file);</li>
<li><strong>M</strong>: merge the selected changes (keep the selections) <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>;</li>
<li><strong>A</strong>: accept the changes (keep the right file);</li>
</ol>
<p>Upon exit, xxdiff will print one of following strings on stdout: <tt class="docutils literal"><span class="pre">REJECT</span></tt>,
<tt class="docutils literal"><span class="pre">MERGED</span></tt> or <tt class="docutils literal"><span class="pre">ACCEPT</span></tt>, corresponding to the user's choices. (If you close
xxdiff via your window manager, a special <tt class="docutils literal"><span class="pre">NODECISION</span></tt> code will be output).
This can be used in collaboration with the <tt class="docutils literal"><span class="pre">--merged-filename</span></tt> 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).</p>
<p>In addition, there is a Python xxdiff package that supports calling xxdiff in
this way. See the <tt class="docutils literal"><span class="pre">xxdiff.invoke</span></tt> module in the Python xxdiff scripts code.</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>Note that if you exit with <strong>M</strong>, 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.</td></tr>
</tbody>
</table>
<hr class="docutils" />
<!-- (FIXME finish documenting other features here) -->
</div>
</div>
</body>
</html>
|
