/usr/share/doc/xxdiff/html/xxdiff-secrets.html is in xxdiff 1:4.0.1+dfsg-1+b1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <?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.11: 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">
<div id="project-home"><a href="http://furius.ca/xxdiff">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 external" 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" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#introduction" id="id3">Introduction</a></li>
<li><a class="reference internal" href="#horizontal-diffs" id="id4">Horizontal Diffs</a></li>
<li><a class="reference internal" href="#checking-for-strict-equality" id="id5">Checking for Strict Equality</a></li>
<li><a class="reference internal" href="#number-of-remaining-hunks" id="id6">Number of Remaining Hunks</a></li>
<li><a class="reference internal" href="#selecting-text" id="id7">Selecting Text</a></li>
<li><a class="reference internal" href="#per-hunk-ignore-whitespace" id="id8">Per-Hunk Ignore Whitespace</a></li>
<li><a class="reference internal" href="#decision-mode" id="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" id="introduction">
<h1><a class="toc-backref" href="#id3">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" id="horizontal-diffs">
<h1><a class="toc-backref" href="#id4">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" id="checking-for-strict-equality">
<h1><a class="toc-backref" href="#id5">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">(=)</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" id="number-of-remaining-hunks">
<h1><a class="toc-backref" href="#id6">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" id="selecting-text">
<h1><a class="toc-backref" href="#id7">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">Control</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" id="per-hunk-ignore-whitespace">
<h1><a class="toc-backref" href="#id8">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" id="decision-mode">
<h1><a class="toc-backref" href="#id9">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">[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">REJECT</tt>,
<tt class="docutils literal">MERGED</tt> or <tt class="docutils literal">ACCEPT</tt>, corresponding to the user's choices. (If you close
xxdiff via your window manager, a special <tt class="docutils literal">NODECISION</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">xxdiff.invoke</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">[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>
|