/usr/share/doc/xxdiff/html/xxdiff-integration.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 164 165 166 167 168 169 170 171 172 173 174 175 176 177 | <?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>Integrating xxdiff with scripts</title>
<meta name="author" content="Martin Blais <blais@furius.ca>" />
<meta name="date" content="2004-01-21" />
<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="integrating-xxdiff-with-scripts">
<h1 class="title">Integrating xxdiff with scripts</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><th class="docinfo-name">Date:</th>
<td>2004-01-21</td></tr>
</tbody>
</table>
<div class="abstract topic">
<p class="topic-title first">Abstract</p>
<p>A summary of some of the features and techniques that can be used to
integrate xxdiff with your own homegrown programs.</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="id1">Introduction</a></li>
<li><a class="reference internal" href="#features-and-techniques" id="id2">Features and Techniques</a><ul>
<li><a class="reference internal" href="#automatic-maximizing" id="id3">Automatic Maximizing</a></li>
<li><a class="reference internal" href="#reading-files-from-stdin" id="id4">Reading Files from Stdin</a></li>
<li><a class="reference internal" href="#adding-arbitraty-information-to-filenames" id="id5">Adding Arbitraty Information to Filenames</a></li>
<li><a class="reference internal" href="#setting-the-output-filename" id="id6">Setting the Output Filename</a></li>
<li><a class="reference internal" href="#requesting-accept-merge-reject-decision" id="id7">Requesting Accept/Merge/Reject Decision</a></li>
<li><a class="reference internal" href="#indication-of-input-processing-completion" id="id8">Indication of Input Processing Completion</a></li>
<li><a class="reference internal" href="#return-value" id="id9">Return Value</a></li>
<li><a class="reference internal" href="#conditional-display" id="id10">Conditional Display</a></li>
</ul>
</li>
<li><a class="reference internal" href="#examples" id="id11">Examples</a></li>
</ul>
</div>
<div class="section" id="introduction">
<h1><a class="toc-backref" href="#id1">Introduction</a></h1>
<p>xxdiff is built with integration in mind since the first version. It does not
include builtin support for specific source control systems, such as CVS or
ClearCase. Instead, its command-line interface is built so that it can easily
be called in various ways within a workflow of file comparison, policing and
review, and interactive merging of changes.</p>
<p>This approach has been used with success by the author in a variety of
environments, with various revision control systems (CVS, ClearCase, others).
This document aims at introducing these features and explaining how they are
meant to be used.</p>
</div>
<div class="section" id="features-and-techniques">
<h1><a class="toc-backref" href="#id2">Features and Techniques</a></h1>
<div class="section" id="automatic-maximizing">
<h2><a class="toc-backref" href="#id3">Automatic Maximizing</a></h2>
<p>Often xxdiff is used in a policing context, where the reviewer/"merge cop" will
have to visualize a series of files one-by-one and make comments on each. Many
people like to maximize their xxdiff to perform this arduous task. You can set
the <tt class="docutils literal">Geometry</tt> resource to special value <tt class="docutils literal">Maximize</tt> for that purpose. (Note
that you can also specify arbitraty resource strings on the command-line with
the <tt class="docutils literal"><span class="pre">--resource</span></tt> option).</p>
</div>
<div class="section" id="reading-files-from-stdin">
<h2><a class="toc-backref" href="#id4">Reading Files from Stdin</a></h2>
<p>Sometimes it can be convenient to use the output of a process directly as input
for comparison, for example, something like this:</p>
<pre class="literal-block">
cat foo.c | sed -e 's/get_instance/getInstance/g' | xxdiff foo.c -
</pre>
<p>You can specify <tt class="docutils literal">-</tt> in lieu of a filename on the xxdiff command-line to let it
know to read standard input for that file position. (Internally, xxdiff will
have to create a temporary file by itself to spawn GNU diff on it but you don't
really need to know that.)</p>
<p>Note that xxdiff currently cannot read different files from different file
descriptors, i.e. it can only read from stdin or files.</p>
</div>
<div class="section" id="adding-arbitraty-information-to-filenames">
<h2><a class="toc-backref" href="#id5">Adding Arbitraty Information to Filenames</a></h2>
<p>In the xxdiff interface, the filename is shown over the corresponding file.</p>
<p>Often when calling xxdiff from a wrapper script, you will run xxdiff on a
temporary file, or accepting input from stdin. It can also be that there is a
special semantic associated with a particular file (e.g. "old" or "new" file),
or that the file has been somehow manipulated automatically before being
compared, or that it represents a specific revision. It is only natural that you
would want to show this information in the graphical comparison program.</p>
<p>To that extent, xxdiff allows you to specify what information you want displayed
over the file. Use the <tt class="docutils literal"><span class="pre">--title1</span></tt>, <tt class="docutils literal"><span class="pre">--title2</span></tt> or <tt class="docutils literal"><span class="pre">--title3</span></tt> options to
have xxdiff display what you want it to.</p>
</div>
<div class="section" id="setting-the-output-filename">
<h2><a class="toc-backref" href="#id6">Setting the Output Filename</a></h2>
<p>Sometimes you may be invoking xxdiff with the intent of maybe getting a merged
output file as a result. In order to specify where this result should lie,
xxdiff provides the concept of "merged filename", which is the default location
where it will save the results of user selections, the merged file. You can
provide this filename on the command-line with the <tt class="docutils literal"><span class="pre">--merged-filename</span></tt> option.</p>
<p>Note that when a merged filename is specific on the command-line, xxdiff will
not warn when overwriting that file. We assume that since you specify a
particular file to be used for merged output, you expect it to be potentially
overwritten.</p>
</div>
<div class="section" id="requesting-accept-merge-reject-decision">
<h2><a class="toc-backref" href="#id7">Requesting Accept/Merge/Reject Decision</a></h2>
<p>Sometimes you may want to <strong>force</strong> the user to produce a merged file as the
result of file comparison. For this purpose, we provide the Decision or
Accept/Merge/Reject mode in xxdiff, triggered with the <tt class="docutils literal"><span class="pre">--decision</span></tt> option.</p>
<p>In this mode, xxdiff will not let you exit normally. Instead:</p>
<ul class="simple">
<li>if you press 'A', the file on the right will be saved as the merged file and
<tt class="docutils literal">ACCEPT</tt> will be printed on stdout;</li>
<li>if you press 'R', the file on the left will be saved as the merged file and
<tt class="docutils literal">REJECT</tt> will be printed on stdout;</li>
<li>if you press 'M', the results of user selections will be saved as the merged
file and <tt class="docutils literal">MERGED</tt> will be printed on stdout;</li>
</ul>
<p>In all three cases, the merged file will be saved with the appropriate contents.
Note that if xxdiff gets terminated otherwise (e.g. by the window manager), it
will print out the string <tt class="docutils literal">NODECISION</tt>.</p>
<p>The calling script can invoke xxdiff (specifying <tt class="docutils literal"><span class="pre">--merged-filename</span></tt>) and read
its stdout to find out the result of the decision, and then pick up the merged
file and do whatever is desired with it.</p>
<p>If you prefer to work with the mouse, three distinct buttons will appear on the
toolbar for that purpose.</p>
</div>
<div class="section" id="indication-of-input-processing-completion">
<h2><a class="toc-backref" href="#id8">Indication of Input Processing Completion</a></h2>
<p>In some circumstances, a calling script will generate temporary files for a
short time, just to pass them on to xxdiff as input. If you want to delete
those files as soon as possible, you may use the <tt class="docutils literal"><span class="pre">--indicate-input-processed</span></tt>
option to xxdiff which will make it print the string 'INPUT-PROCESSED` as soon
as it does not need its inputs anymore.</p>
<p>Thus you would do something like this:</p>
<ol class="arabic simple">
<li>invoke xxdiff asynchrously (e.g. in a child process);</li>
<li>read from its output (from a pipe), until the INPUT-PROCESSED string is seen;</li>
<li>delete the input files;</li>
<li>wait for xxdiff to complete.</li>
</ol>
</div>
<div class="section" id="return-value">
<h2><a class="toc-backref" href="#id9">Return Value</a></h2>
<p>By default, xxdiff returns the same return value that GNU diff does (see
diff(1)).</p>
<p>This behaviour is altered if you use the <tt class="docutils literal"><span class="pre">--exit-with-merge-status</span></tt> option:
if all diff hunks are selected and no unsaved selections exist, only then xxdiff
will exit with code of 0.</p>
</div>
<div class="section" id="conditional-display">
<h2><a class="toc-backref" href="#id10">Conditional Display</a></h2>
<p>If <tt class="docutils literal"><span class="pre">--exit-on-same</span></tt> is selected xxdiff does not show its UI and exits if the
files are have no differences (according to GNU diff).</p>
<p>If <tt class="docutils literal"><span class="pre">--exit-if-no-conflicts</span></tt> is selected xxdiff does not show its UI and exits
if automatic merging would result in no conflicts.</p>
</div>
</div>
<div class="section" id="examples">
<h1><a class="toc-backref" href="#id11">Examples</a></h1>
<p>You can look at the various scripts available in the distribution in the <tt class="docutils literal">bin</tt>
directory or the <tt class="docutils literal">tools</tt> directory. They are working examples of integration
between xxdiff and Bourne-shell and Python scripts.</p>
</div>
</div>
</body>
</html>
|