<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<title>xxdiff documentation</title>
</head>
<body>
<h1>xxdiff documentation</h1><p>This is the user's manual for xxdiff, version <b>2.9</b>.The official location of xxdiff on the internet is<a href="http://xxdiff.sourceforge.net">http://xxdiff.sourceforge.net</a>.If you're reading this page from the web, note that you can also access thisdocument from the Help menu of xxdiff.</p><!-- ======================================================================= --><h2>Table of Contents</h2><ul><li><a href="#introduction">Introduction</a></li><li><a href="#invocation">Invocation</a></li><li><a href="#general">General operation</a></li><li><a href="#compfiles2">Comparing two files</a></li><li><a href="#compfiles3">Comparing three files</a></li><li><a href="#compdirs2">Comparing two directories</a></li><li><a href="#merging">Merging files and resolving conflicts</a></li><li><a href="#review">Merge review features</a></li><li><a href="#unmerge">Unmerging merge conflicts</a></li><li><a href="#editing">Editing files</a></li><li><a href="#customization">Customization using resource file</a></li><li><a href="#resources">Resource reference</a></li><li><a href="#faq">Frequently Asked Questions (FAQ)</a></li><li><a href="#author">Author</a></li><li><a href="#bugs">Reporting bugs</a></li><li><a href="#history">Project history</a></li></ul><!-- ======================================================================= --><a name="introduction"></a><h2>Introduction</h2><p>xxdiff is a <i>graphical file and directories comparison and mergetool</i>. This program is an essential software development tool that can beused to</p><ul><li> visualize the differences between files or directories;<li> merge files with differences, resolving conflicts and saving output to anew file or patch;<li> assist file changes reviewing and comment production (e.g. approving sourcecode changes before they get merged into a source tree).</ul><p>xxdiff doesn't itself compute the differences between files, it just displaysthem graphically (the rationale behind this is that you can use different toolsto compute the actual diffs (for example using Rational ClearCase's cleardiff,which gives more sensible results than GNU diff in certain cases), there is a relatively standard format for difference output (POSIX diff),so it is easy and efficient to parse diff output from different programs,under the UNIX dataflow paradigm, it is common for graphical tools to bebuilt on top of text tools. There are already many good tools to perform diffs,so there's no need to rewrite them.</p><!-- ======================================================================= --><a name="invocation"></a><h2>Invocation</h2><p>Usage:</p><blockquote><tt>xxdiff [OPTIONS] <file1> <file2> [<file3>]</tt></blockquote><p>You can specify either two files (two-way diff), three files (three-way diff),or two directories (directory diff).</p><p>You can also specify a mix of regular files and directories. If at least one ofthe paths specified on the cmdline is a regular file, all other paths that aredirectories will have the basename of the regular filename appended to them.For example, if you specify:</p><blockquote><tt>xxdiff dir1/bn1 dir2/bn2 dir3</tt></blockquote>xxdiff will be run on <tt>dir1/bn1</tt>, <tt>dir2/bn2</tt>, and<tt>dir3/bn1</tt>.<p>xxdiff can accept one of its inputs from stdin. You must replace the relevantfilename by '<tt>-</tt>' (a dash) to instruct xxdiff to use stdin for that file,e.g.</p><blockquote><tt>cat file2 | sort | xxdiff file1 - file3</tt></blockquote><p>If all the file paths are directories, a directory diff is invoked. Note thatxxdiff doesn't do three-way directory diffs.</p><p>If the "unmerge" option is given, then xxdiff can only be invoked with a singlefile containing the conflicts.</p><!-- ======================================================================= --><h3>Return Value</h3><p>xxdiff returns the same values that diff(1) or diff3(1) return. See therespective man pages of those utilities for details.<!-- ======================================================================= --><a name="options"></a><h3>Command-line Options</h3><h4>Generic options</h4>
<table cellpadding=5 width="100%">
<tr>
<td width="30%"><tt>--help</tt></td>
<td align=left>
Show help about options.
</td>
</tr>
<tr>
<td width="30%"><tt>--help-qt</tt></td>
<td align=left>
Show Qt specific options.
</td>
</tr>
<tr>
<td width="30%"><tt>--help-all</tt></td>
<td align=left>
Show all options.
</td>
</tr>
<tr>
<td width="30%"><tt>--help-html</tt></td>
<td align=left>
Output documentation in HTML.
</td>
</tr>
<tr>
<td width="30%"><tt>--version, -v</tt></td>
<td align=left>
Show version information.
</td>
</tr>
</table>
<h4>Qt options</h4>
<table cellpadding=5 width="100%">
<tr>
<td width="30%"><tt>--qt, -Q <arg></tt></td>
<td align=left>
Set options to be given to Qt application options parser. See Qt manual, class QApplication for a list of supported options.
</td>
</tr>
<tr>
<td width="30%"><tt>--display <arg></tt></td>
<td align=left>
Sets the X display (default is $DISPLAY).
</td>
</tr>
<tr>
<td width="30%"><tt>--style <arg></tt></td>
<td align=left>
Sets the application GUI style. Possible values are motif, windows, and platinum.
</td>
</tr>
<tr>
<td width="30%"><tt>--geometry <arg></tt></td>
<td align=left>
Sets the client geometry of the main widget.
</td>
</tr>
<tr>
<td width="30%"><tt>--font <arg></tt></td>
<td align=left>
Defines the application font (for widgets).
</td>
</tr>
<tr>
<td width="30%"><tt>--textfont <arg></tt></td>
<td align=left>
Defines the text font (for diff text).
</td>
</tr>
<tr>
<td width="30%"><tt>--name</tt></td>
<td align=left>
Sets the application name.
</td>
</tr>
<tr>
<td width="30%"><tt>--visual <arg></tt></td>
<td align=left>
Forces the application to use a particular visual on an 8-bit display (e.g. TrueColor).
</td>
</tr>
<tr>
<td width="30%"><tt>--ncols <arg></tt></td>
<td align=left>
Limits the number of colors allocated in the color cube on a 8-bit display.
</td>
</tr>
<tr>
<td width="30%"><tt>--cmap</tt></td>
<td align=left>
Causes the application to install a private color map on an 8-bit display.
</td>
</tr>
<tr>
<td width="30%"><tt>--nograb</tt></td>
<td align=left>
Tells Qt to never grab the mouse or the keyboard.
</td>
</tr>
<tr>
<td width="30%"><tt>--dograb</tt></td>
<td align=left>
Running under a debugger can cause an implicit -nograb, use -dograb to override.
</td>
</tr>
<tr>
<td width="30%"><tt>--sync</tt></td>
<td align=left>
Switches to synchronous mode for debugging.
</td>
</tr>
</table>
<h4>GNU diff options (2-files only)</h4>
<table cellpadding=5 width="100%">
<tr>
<td width="30%"><tt>--ignore-all-space, -w</tt></td>
<td align=left>
Option passed to 2-files diff(1). Ignore white space when comparing lines.
</td>
</tr>
<tr>
<td width="30%"><tt>--ignore-space-change, -b</tt></td>
<td align=left>
Option passed to 2-files diff(1). Ignore changes in amount of white space.
</td>
</tr>
<tr>
<td width="30%"><tt>--ignore-case, -i</tt></td>
<td align=left>
Option passed to 2-files diff(1). Ignore changes in case; consider upper- and lower-case to be the same.
</td>
</tr>
<tr>
<td width="30%"><tt>--ignore-blank-lines, -B</tt></td>
<td align=left>
Option passed to 2-files diff(1). Ignore changes that just insert or delete blank lines.
</td>
</tr>
<tr>
<td width="30%"><tt>--recursive, -r</tt></td>
<td align=left>
Option passed to 2-files diff(1). This is only meaningful for directory diffs.
</td>
</tr>
<tr>
<td width="30%"><tt>--text, -a</tt></td>
<td align=left>
Option passed to 2-files diff(1). Treat all files as text and compare them line-by-line, even if they do not appear to be text.
</td>
</tr>
<tr>
<td width="30%"><tt>--exclude <arg></tt></td>
<td align=left>
When comparing directories, ignore files and subdirectories whose basenames match pattern.
</td>
</tr>
<tr>
<td width="30%"><tt>--exclude-from <arg></tt></td>
<td align=left>
When comparing directories, ignore files and subdirectories whose basenames match any pattern contained in file.
</td>
</tr>
</table>
<h4>Options</h4>
<table cellpadding=5 width="100%">
<tr>
<td width="30%"><tt>--no-rcfile</tt></td>
<td align=left>
Don't query rcfile resources (.xxdiffrc).
</td>
</tr>
<tr>
<td width="30%"><tt>--list-resources</tt></td>
<td align=left>
Lists all the supported resources and default values.
</td>
</tr>
<tr>
<td width="30%"><tt>--exit-on-same, -D</tt></td>
<td align=left>
If there are no differences then exit quietly with exit code of 0.
</td>
</tr>
<tr>
<td width="30%"><tt>--exit-if-no-conflicts, -E</tt></td>
<td align=left>
If there are no conflicts after making automatic merge selections, then exit quietly with exit code of 0.
</td>
</tr>
<tr>
<td width="30%"><tt>--merge, -m</tt></td>
<td align=left>
Automatically select regions that would end up being selected by an automatic merge.
</td>
</tr>
<tr>
<td width="30%"><tt>--unmerge, -U</tt></td>
<td align=left>
Invoke on a single file with CVS-like merge conflicts, splitting the conflicts into two files for display. If this is specified, only a single file can then be given as argument.
</td>
</tr>
<tr>
<td width="30%"><tt>--unmerge3</tt></td>
<td align=left>
Invoke on a single file with merge conflicts generated by diff3 with the show-all option, splitting the conflicts into three files for display. If this is specified, only a single file can then be given as argument.
</td>
</tr>
<tr>
<td width="30%"><tt>--title1 <arg></tt></td>
<td align=left>
Display 'str' instead of filename in filename label 1 (left).
</td>
</tr>
<tr>
<td width="30%"><tt>--title2 <arg></tt></td>
<td align=left>
Display 'str' instead of filename in filename label 2 (middle).
</td>
</tr>
<tr>
<td width="30%"><tt>--title3 <arg></tt></td>
<td align=left>
Display 'str' instead of filename in filename label 3 (right).
</td>
</tr>
<tr>
<td width="30%"><tt>--titlein, -N <arg></tt></td>
<td align=left>
Display 'str' for filename in given in stdin.
</td>
</tr>
<tr>
<td width="30%"><tt>--resource <arg></tt></td>
<td align=left>
Pass on string 'str' to resource parser. Resources given in this manner on the command line supersede other resource mechanisms. One can specify multiple resource settings by repeating this option.
</td>
</tr>
<tr>
<td width="30%"><tt>--args, -A <arg></tt></td>
<td align=left>
Pass on argument to the subordinate diff program.
</td>
</tr>
<tr>
<td width="30%"><tt>--orig-xdiff</tt></td>
<td align=left>
Use settings as close as possible to original xdiff (for the romantics longing the old days of SGI... snif snif).
</td>
</tr>
<tr>
<td width="30%"><tt>--merged-filename, -M <arg></tt></td>
<td align=left>
Specifies the filename of the merged file for output.
</td>
</tr>
<tr>
<td width="30%"><tt>--output-on-exit, -O</tt></td>
<td align=left>
Forces saving to the merged filename upon exit. Note: If the file exists, no warning is given about overwriting the file. If there are unresolved conflicts, a popup dialog will appear.
</td>
</tr>
</table>
<p>Note that the last few options are provided compatible with common GNU diffoptions that the user might want to use, as a mere convenience. Note also thatxxdiff options are a superset of the original xdiff options, so that xxdiff iscompatible with old SGI scripts that use xdiff. xxdiff options follow the GNUconventions for command-line options.</p><!-- ======================================================================= --><h3>Using xxdiff as a short-lived application</h3> <p>xxdiff has not been designed with the intent of being used over multiple sets offiles over the course of one execution---that is, it has been built around theidea that you would execute it once over a single set of inputs, use it, thenexit, rather than to open new files again using the `file' menu features withoutexiting. The `file' menu features are provided as a convenience, to allow oneto occasionally replace one of the files during an execution. That is thereason why you can't open xxdiff with just one file. It is just not useful thatway.</p><!-- ======================================================================= --><a name="general"></a><h2>General operation</h2><p>This section describes general features and operation of xxdiff.</p><!-- ======================================================================= --><h3>The text area</h3><p>xxdiff shows up with two or three text regions that display the text of thefiles to compare, with color-coded blocks that indicate regions of text (lines)that have changes (specific sections contain a list and descriptions on whattypes of change can appear). Each of these regions of text is called a "hunk"in diff terminology (for more about this, see the GNU diff manual). The textarea can be scrolled vertically and horizontally, when necessary.</p><p>Corresponding regions of text are aligned between the files. Since changedregions do not necessarily contains the same number of lines, empty alignmentlines are appended to the shorter regions in order to keep the correspondinglines aligned (this is a simple way of solving the alignment problem; analternate solution would have been to implement a smart type of scrolling withlines indicating correspondance of regions between them). </p><p>All the colors can be individually configured using the display options dialogor resources. The display dialog contains a legend of all the colors. Notethat the default colors for different regions are often set to be the same toother types of lines when it is not necessary to dissociate them, to avoidvisual clutter. You could however, customize every region to be of a differentcolor, for example, perhaps you would want to have the dummy lines drawn of aspecial color to indicate that they are not really part of the text.</p><p>In the text area, there is a cursor that in indicates the current line of textbeing worked on. This cursor can be optionally hidden.<p><h4>Horizontal diffs</h4><p>Each of the diff hunks is normally displayed in one color, but if horizontaldiffs is enabled, for each line, xxdiff find the smallest differing part of theline that differs and displays that in a different, highlighted color. Thisallows the user to more quickly visualize exactly what has changed between thetwo lines of text. No need to mention, this is highly addictive and is nowenabled by default. This is the "single horizontal diffs" mode.</p><p>When there are no more than two pieces of text on a single line, if thediffering parts of the lines are not too long (e.g. less than 100 chars), thehorizontal diffs can isolate the differences within the line. This is the"multiple horizontal diffs" mode. In this mode, we require that betweenhorizontal changes, inserts or deletes, there be a minimal number of commoncontext characters, so that the eye can make out what has change between thelines. This value is configurable (see resources section).</p><p>When computing horizontal diffs, <b>changes</b> in whitespace can be optionallyignored. However, if whitespace has been added in the middle of a word, it willstill be highlighted.</p><h4>Per-hunk ignore whitespace</h4><p>Diff Hunks with text on all sides but with just whitespace or line breakdifferences will be detected by xxdiff and marked with a special flag. If thefeature is enabled, those hunks will be drawn of a different color, thusenabling the reviewer to quickly ignore those hunks. See the merge reviewfeatures section for more details.</p><h4>Navigation</h4><p>xxdiff supports a subset of the emacs bindings, as well as support for most ofthe standard keys found on AT keyboards (PgUp, PgDown, arrow keys, Home, End).</p><p>Default bindings include:</p><ul><li>Ctrl-V, Alt-V: scroll up/down;</li><li>Ctrl-N, Ctrl-P: move cursor one line up/down;</li><li>Home, End: move cursor to beginning/end of files;</li><li>N, P: move to next/previous diff hunk;</li><li>B, O: mov the next/previous <b>unselected</b> diff hunk.</li></ul><p>Explore the menus to find out about the other default bindings. You cancustomize all the key bindings using the resources.</p><h4>Pop-up menu</h4><p>Using the third mouse button in the text area brings a popup menu that containscursor-sensitive commands, as well as the common commands to navigate betweenhunks.</p><h4>Searching</h4><p>You can search the text by bringing up the search dialog. Type your searchquery and press enter, which will apply the search and display diamond shapedmatch locations in the overview area. You can then navigate the search resultsusing Ctrl-F and Ctrl-B. Searching will occur in all files simultaneously. Youhave to reapply the search to search for something else.</p><p>You can also move the cursor and display to a particular line from the searchdialog.</p><h4>Other options</h4><p>Carriage returns (CR) characters in DOS files can be hidden in the text area.</p><p>Tabs by default are rendered aligned at each 8 characters, but can be set to anyvalue by changing the tab width option.</p><h4>Display options</h4><p>The display options can be fully customized by bringing up the options dialogwith the "Display -> Display Options..." menu item. From that dialog you canalso customize the colors and fonts.</p><h3>Redoing the diffs</h3> <p>If a file has changed while xxdiff is up, and there is need to recompute thediffs, invoke the "redo diff" command from the edit menu. The arguments usedwith the surrogate diff command can be changed by using the dialog provided bythe "diff arguments" command. One can also replace a loaded file with adifferent one by using the "open" commands from the "file" menu.</p><!-- ======================================================================= --><h3>Other UI elements</h3><p>The following other UI elements can be optionally hidden or displayed from theWindows menu or Display menu (use the resource file to display or hide them onstartup):</p><ul><li><b>Overview area.</b> On the right side, an area that shows a color-codedpictorial rendering of the diff hunks for the whole files, with correspondances.This area also shows the as a rectangle the currently visible portion of textfor each of the files. This rectangle can also be used as a scrollbar. Inaddition, a marker indicates the location of the line cursor.</li><li><b>Toolbar.</b> A toolbar that gives access to the common motion and selectioncommands.</li><li><b>Filenames.</b> For each file, a region at the top that displays the filename.You can customize what shows up in this region from the command-line. Clickingon the filename puts it in the clipboard for cut-n-paste. (This label willintelligently display the end part of the filename if it is too long to fit.)This region also display the text line that the line cursor is in, for eachfile. You can customize what gets displayed in this labeled by using acommand-line option.</li><li><b>Line numbers.</b> For each file, a thin window that display the number ofeach line (dummy alignment lines don't have any number).</li><li><b>Vertical line.</b> A vertical line can be drawn in the text area, at aspecified column. This can be used for alignment purposes or for verifying thata line doesn't extend beyond a specified number of characters (many people liketo limit their source code to fit in e.g. 80 characters).</li><li><b>Merged view</b>. A view of the file resulting from the currently selectedregions (see section on <a href="#mergedview">merged view</a> below).</li></ul><!-- ======================================================================= --><a name="compfiles2"></a><h2>Comparing two files</h2><p>When invoking xxdiff with two files, we normally think of an old and a new file,where</p><blockquote><tt>xxdiff old new</tt></blockquote><p>The default colors used here are symmetrical, so invoking the files in adifferent order will result in regions being assigned the same colors.</p><h3>Types of hunks</h3><p>The following hunk types can appear when comparing two files:</p><ul><li> <b>Same</b>: no change in that region;</li><li> <b>Insert</b>: text has been added to the new file;</li><li> <b>Delete</b>: text has been deleted from the new file;</li><li> <b>Diff</b>: text has changed between the files.</li></ul><p>Note that each Diff or Insert hunk is always separated by a Same hunk (if it wasnot the case, then two different contiguous hunks would necessarily get mergedinto a single Diff hunk).</p><h3>Options</h3><p>You can ignore trailing blanks, whitespace, or case for two-way diffs. See GNUdiff(1) manual for information these features. xxdiff provides menu items toaccess these diff options. Those items simply add or remove switches to the diffprogram command-line and call the diff program again to regenerate the diffs.</p><p>Switches for GNU diff algorithm quality are also provided in the UI as aconvenience.</p><!-- ======================================================================= --><a name="compfiles3"></a><h2>Comparing three files</h2><p>When invoking xxdiff with three files, we think of an ancestor file, a "mine"file, which the current user has been working on, and a "yours" file whichsomeone else has merged in the main tree. They are normally specified in thefollowing order:</p><blockquote><tt>xxdiff mine older yours</tt></blockquote><p>The default colors used here are symmetrical, so invoking the files in adifferent order will result in regions being assigned the same colors.</p><h3>Types of hunks</h3><p>The following hunk types can appear when comparing two files:</p><ul><li> <b>Same</b>: no change in that region;</li><li> <b>Insert</b>: text has been added one of the files;</li><li> <b>Delete</b>: text has been deleted from one of the files;</li><li> <b>DiffOne</b>: text is different in one of the three files but the twoother files are the same.</li><li> <b>DiffAll</b>: text is different in all of the three files.</li><li> <b>DiffDel</b>: text is different in two files and is absent in thethird.</li></ul><h3>Ignoring one file</h3><p>In three-way mode, it can be useful to temporarily ignore one of the three filesto concentrate on the differences between the other two. This feature isavailable from the Display menu and is performed by simply remapping colors atdisplay time and doesn't require xxdiff to recompute the differences. Theignored file will be displayed as grayed out.</p><!-- ======================================================================= --><a name="compdirs2"></a><h2>Comparing two directories</h2><p>When invoking xxdiff with two directories, we normally think of an old and a newdirectory, where</p><blockquote><tt>xxdiff olddir newdir</tt></blockquote><p>The default colors used here are symmetrical, so invoking the files in adifferent order will result in regions being assigned the same colors.</p><h3>Types of hunks</h3><p>The following hunk types can appear when comparing two directories:</p><ul><li> <b>Same</b>: files are present in both directories and have nodifferences;</li><li> <b>Insert</b>: file has been added to directory;</li><li> <b>Delete</b>: file has been removed from directory;</li><li> <b>Diff</b>: files are present in both directories and havedifferences;</li><li> <b>Directories</b>: directories are present in both directories but wedon't know if they differ;</li></ul><h3>Options</h3><p>The directories can be compared recursively, in which case no directories willbe shown. You can activate this from the command-line or from the ui.</p><p>You can also instruct xxdiff not to display the files that haved changed, justthe insertions and deletions.</p><h3>File operations</h3><p>In directory diffs mode, you can invoke an xxdiff on the pair of files ordirectories under the line cursor. This allows you to start xxdiff on a pair ofdirectories, and then to examine the pairs of files that have changed, all fromthat directory diff. That functionality is available from the popup menu in thetext area (right-click).</p><p>You can also copy and remove files from that menu, see<a href="#merging">merging</a> section for details.</p><!-- ======================================================================= --><a name="merging"></a><h2>Merging files and resolving conflicts</h2><p>Merging files is the process of manually resolving conflicts when two filescannot be merged automatically. This is a common problem when doing parallelsoftware development where multiple developers could be working on the samefiles.</p><p>Most of the merging can be handled automatically, because if the changes wereapplied to fairly independent parts of the files, most of the changes will beinsertions or deletions. However, when overlapping changes occur, no automaticdecision can be taken.</p><p>xxdiff can be used to resolve conflicts by letting the user "select" which sideof a diff hunk should be killed and what side should be kept. The user can takethis decision on a line-by-line basis, and can decide to keep both sides aswell, in any order. xxdiff then allows the user to save the resulting file.</p><!-- ======================================================================= --><h3>Selecting regions</h3><p>Selecting a diff hunk can be carried out by clicking on it. The colors updateto display which side is selected for output. You can select individual lineswith the second button. There are three types of selection that you can carryout:</p><ul><li>select clicked file;</li><li>select no file (take the decision that nothing will be output);</li><li>leave the line/hunk unselected.</li></ul><p>If you want to select more than one side, you have to invoke the split-swap-joincommand (default is on 'S' key), which will split the current diff hunk if it'sa Diff hunk so you can select the pieces you want from both sides. Furtherinvocations of this command will cause swapping the regions, looping through allthe different ordering possibilities, and finally joining the regions again(preserving selections where it is possible).</p><!-- ======================================================================= --><h3>Saving the resulting file</h3><p>The resulting file can be saved under one of the input filenames, under acomputed "merged" filename, or under a new filename (from the File menu). Theintended "merged" filename can be built from the input filenames and it's formatcan be specified through the resources file or the command line.</p><p>If some regions are left unselected, the savedialog will have some widgets that allows you to decide how you want to save theunselected hunks:</p><ul><li><b>Save as merge conflicts:</b> save all sides, separating them with mergeconflict markers similar to those inserted by CVS;</li><li><b>Save with conditionals:</b> save all sides, separating them with Cpre-processor directives, so that you could then use a #define directive to haveone set of changes or another be active if compiling.</li></ul><p>The markers and pre-processor directives can be customized through the resourcesfile.</p><p>There is a customization flag that lets you specify that xxdiff should warn youwhen trying to save with some regions unselected. It will bring the cursor tothe first remaining unselected region and ask for confirmation. This can be usedto insure that the user has made all the required decisions before saving andthat no text will be forgotten.</p><p>You could also decide to save only the selected regions, from the File menu.This can be useful for making comments when reviewing merges.</p><h4>Forcing merged file output</h4><p>xxdiff is often used for merging conflicts, replacing some of the tools that areprovided with popular configuration management systems. Sometime it is"required" that the conflict resolution tool output the merged file. To thatextent, xxdiff has a special command-line switch to address that need:output-on-exit. If specified, the merged-filename will be automatically savedwhen xxdiff exits. If there are remaining conflicts when exiting, a popup willask how to deal with them.</p><!-- ======================================================================= --><h3>Rapid, sequential merge conflict resolution</h3><p>Some people like to merge files within a guided process, where the visual diffprogram asks for a merge decision for each conflictual hunk one-by-one and thenasks for a filename to use for saving the merged output. For example, that ishow ClearCase's xcleardiff works when querying the user to resolve conflicts.</p><p>There are a set of commands under the Region menu that allows one to rapidlytake decisions on merge conflicts. These commands perform a selection and thenautomatically move the cursor to the next unselected region. If there are nomore unselected regions, the save dialog is brought up automatically.</p><!-- ======================================================================= --><h3>Automatic merge</h3><p>By default, xxdiff doesn't perform any selections. You can instruct xxdiff toperform the initial selection of the non-conflictual regions automatically.This can be specified from the command-line or from the Global menu.</p><p>Just like xxdiff can be instructed not to show up if there aren't anydifferences between the files, xxdiff can also be instructed not to show up ifafter the automatic merge there remains no conflictual regions. You can use thereturn value to find out.</p><p>(Note that we do not want to add a feature to xxdiff to allow it to output tothe merged file if there are no conflics, because that would amount to makexxdiff a non-graphical tool, while its mandate is to use such tools underneathand display their output. Besides, that would be the single case where xxdiffwrites to a file without a file dialog. You can very easily implement this fromwithin a script using the return value of either diff or xxdiff.)</p><h4>Requiring an output file</h4><p>Sometimes we want to force the user into producing a merged output file (whencalling xxdiff from an update script, for example). Thus there is a feature toput xxdiff in this mode (see resources or invocation section). In this mode, theuser must save before exiting xxdiff (exiting will prompt for save filename).</p><!-- ======================================================================= --><h3>Merging directories</h3><p>Selecting is disable in directory diffs mode, where the concept of "saving" adirectory does not really make sense. However, you can apply changes to adirectory from xxdiff, such as copying and removing files under the line cursor.This can be invoked from the popup menu in the text area.</p><!-- ======================================================================= --><a name="mergedview"></a><h3>Merged view</h3><p>During selection or before saving the selected regions into the result file, youmight want to visualize what it would look like with the current selections.You can display the "merged view" for this purpose, an dedicated windowshowing the merge output, that updates interactively as you make selections.</p><p>This view will scroll to match the main display. Unselected regions are shownin this view with oblique lines ("in construction" style), and merge decisionsare slightly highlighted as well. This output allows you to review the mergedecisions before commiting the file to output.</p><!-- ======================================================================= --><a name="review"></a><h2>Merge review features</h2><p>One of the most important uses of xxdiff is to assist the merge review process,where one developer visualizes the file changes of another and approves orrejects those changes, making comments along the way.</p><p>For this purpose, xxdiff puts selected text (i.e. when you click on a diff hunk)in the clipboard text buffer when you select it. Thus, the merge cop can selecta region, and paste the results in a neighboring editor window.</p><p>These snippets of code will typically be interspersed with comments. xxdiff canbe format the line contents before they are copied to the clipboard, to makethem distinct from the merge comments. This can be enabled using the "formatclipboard text" option. The clipboard line format is a string that containsformat specifiers similar to printf for each line to be formatted prior to beingput on the clipboard. The following specifiers are allowed:</p><ul><li><b>%N</b>: file line (0 is leftmost file);</li><li><b>%L</b>: line number;</li><li><b>%F</b>: filename;</li><li><b>%s</b>: line contents.</li></ul><p>There is also a "clipboard header format" resource for adding the filename atthe top of the copied text. This is useful for quickly pasting into a mergecomments file.</p><p>Also note that clicking on the filename labels will put the filenames in theclipboard for similar cut-n-paste action. This can be useful when reviewingClearCase revision files, which often have very long p-names.</p><h4>Variable text selection</h4><p>You can press ALT and Button1 to select an arbitrary number of lines. Theselected lines will be marked with a special border to show what gets put in theclipboard. This is very useful when you don't want to quote an entire diff hunk,or a section of text that straddles hunks.</p><h4>Per-hunk ignore whitespace</h4><p>Many source code changes often just reindent or reorganize blocks of code, andresult in many isolated hunks with no relevant changes to look at (for languagesthat don't use whitespace semantics anyway). For merge police duties, this canlead to more work to review changes, and typically, programmers (and groups,sometimes) will explicitly choose not to allow code beautification because ofthat very reason (...and the directed anger of merge cops themselves). xxdiffnow has a new feature that alleviates this problem greatly: it will scan eachdiff hunk for non-whitespace changes, and if the only changes are of whitespace,it will mark the hunk with a special flag. The "ignore per-hunk whitespace"feature will draw these hunks with a different color, by default, a color verysimilar to the "same" hunks. The hunks are not ignored, however, as skippingfrom hunk to hunk will still stop at these hunks, but they can be very quicklyignored by the merge police. So go on ahead now, and reindent that code withoutfear.</p><!-- ======================================================================= --><a name="unmerge"></a><h2>Unmerging merge conflicts</h2><p>Unmerging merge conflicts is a special input mode of xxdiff where a single filecontaining the result of an automatic merge of two files is split into two filesand displayed as such.</p><p>This may sound like a "trava lengua", but unmerging merge conflicts can be avery useful feature, if you like to let your source code management systemautomatically perform merges and save the output without user intervention, suchas the way CVS is normally used. Typical use of the CVS update command willmerge the main branch changes into your local copy files. When there areconflicts, your files are modified to contain both your changes and the mainbranch changes in the regions that conflict. CVS inserts text markers such asthe following to indicate the conflictual regions:</p><pre> Some merged text. >>>>>>>> MYFILE I added this. ======== This line added in main branch. <<<<<<<< 1.1 Some finetext.</pre><p>Then, the user is notified of the conflictual files, and has to go inspect theconflicts and resolve them by editing the file accordingly. The problem is thatit is often quite difficult (and unpleasant) to figure out exactly what happenedduring the automated merge process, without the original files (note that CVSdoes make a backup copy of your file before writing it over with the mergedoutput, see CVS manual for details).</p><p>To help in figuring out what happened during merge and in performing theuser-directed selections, xxdiff can be invoked in "unmerge mode" with the filecontaining the merge conflicts. It parses the file and generates two files fromit, displaying them with differences. You can then perform selections as usualto produce the final merged file.</p><p>Note that we think that this is not the best way of resolving conflicts, ratherjust a useful feature for people who like to work this way. A better way tomerge would be to use your source code management system to fetch the commonancestor revision, the latest/head of the main branch and to invoke xxdiff withyour file, the ancestor and the latest/head. You can also tell xxdiff toinitially perform all non-conflictual selections automatically.</p><h3>Unmerging merge conflicts with three files</h3><p>diff3 can be used to produce a merged file in which all the three files' regionsare shown if there is a conflict. xxdiff can also parse these files and displaythem as a three-way diff. You then have to invoke xxdiff with the 'unmerge3'command-line argument to let it know you want the file split in three.</p><!-- ======================================================================= --><a name="editing"></a><h2>Editing files</h2><p>There has been a conscious decision NOT to develop xxdiff into a fully-featuredediting program. Sometimes it could be handy to be able to edit a few lines ofa difficult conflict. However, that is a task best left to your own favoriteediting program. Saving with merge conflicts will allow you to resolve thosefew remaining conflicts by hand.</p> <p>However, a few commands have been provided under the File menu to spawn aneditor on the input files. You can then redo the diff after your input file haschanged.</p><!-- ======================================================================= --><a name="customization"></a><h2>Customization using resource file</h2><p>Much of the state of xxdiff can be customized through a resource file (actually,some of the features can only be changed through resource customization).By default, xxdiff looks for the file <tt>.xxdiffrc</tt> located in the user'shome directory (this file location can be overriden by setting the environmentvariable XXDIFFRC), and reads that file for resource definition.</p><p>The format of the resource file is a fairly simple list of colon-separatedresource name/value pairs, one per line:</p><blockquote><tt>resourceName: "value"</tt></blockquote><p>Any text after "#" on a line is considered a comment and ignored.</p><p>Some resources may require string delimiters (double-quotes) around their valuespecification, but not all (see below).</p><p>You can also specify additional resources on the command-line, which takeprecendence over the resources specified in the resource file. To get acomplete list of the available resources, use the <tt>--list-resources</tt>command-line option (see <a href="#options">options section</a>).</p><p>Trick: you can use different resources files by invoking xxdiff like this inmost shells:</p><blockquote><tt>XXDIFFRC=myrcfile xxdiff file1 file2</tt></blockquote><!-- ======================================================================= --><h3>Automatic generation of the resource file</h3><p>You can generate a resource file containing only the differences from thedefaults from the "Help -> Generate init file" menu command. This can beused to "save" the current customizable options.</p><!-- ======================================================================= --><a name="resources"></a><h2>Resource reference</h2><p>This section contains a reference of the all the currently supportedcustomizable resources in this version of xxdiff.</p><PRE>
Geometry: 1200x600
</PRE>
<BLOCKQUOTE>
Preferred geometry upon initialization. Format is the same a X geometry specification, plus you can also use `Maximize' to maximize on startup
</BLOCKQUOTE>
<PRE>
Style: "SGI"
</PRE>
<BLOCKQUOTE>
Preferred Qt style, see Qt documentation for more details. The style can otherwise be specified through command-line arguments.
</BLOCKQUOTE>
<PRE>
Accel.[NAME].: "[ACCELERATOR]"
</PRE>
<BLOCKQUOTE>
Accelerators for most functionality. The name of the accelerator should be explicit enough that you can find which function it is bound to.
<PRE>
Accel.Exit: "<key>"
Accel.OpenLeft: "<key>"
Accel.OpenMiddle: "<key>"
Accel.OpenRight: "<key>"
Accel.SaveAsLeft: "<key>"
Accel.SaveAsMiddle: "<key>"
Accel.SaveAsRight: "<key>"
Accel.SaveAs: "<key>"
Accel.SaveSelectedOnly: "<key>"
Accel.EditLeft: "<key>"
Accel.EditMiddle: "<key>"
Accel.EditRight: "<key>"
Accel.Search: "<key>"
Accel.SearchForward: "<key>"
Accel.SearchBackward: "<key>"
Accel.ScrollDown: "<key>"
Accel.ScrollUp: "<key>"
Accel.CursorDown: "<key>"
Accel.CursorUp: "<key>"
Accel.CursorTop: "<key>"
Accel.CursorBottom: "<key>"
Accel.RedoDiff: "<key>"
Accel.EditDiffOptions: "<key>"
Accel.EditDisplayOptions: "<key>"
Accel.DiffFilesAtCursor: "<key>"
Accel.CopyFileRightToLeft: "<key>"
Accel.CopyFileLeftToRight: "<key>"
Accel.RemoveFileLeft: "<key>"
Accel.RemoveFileRight: "<key>"
Accel.NextDifference: "<key>"
Accel.PreviousDifference: "<key>"
Accel.NextUnselected: "<key>"
Accel.PreviousUnselected: "<key>"
Accel.SelectGlobalLeft: "<key>"
Accel.SelectGlobalMiddle: "<key>"
Accel.SelectGlobalRight: "<key>"
Accel.SelectGlobalNeither: "<key>"
Accel.SelectGlobalUnselect: "<key>"
Accel.SelectGlobalUnselectedLeft: "<key>"
Accel.SelectGlobalUnselectedMiddle: "<key>"
Accel.SelectGlobalUnselectedRight: "<key>"
Accel.SelectGlobalUnselectedNeither: "<key>"
Accel.SelectGlobalMerge: "<key>"
Accel.SelectRegionLeft: "<key>"
Accel.SelectRegionMiddle: "<key>"
Accel.SelectRegionRight: "<key>"
Accel.SelectRegionNeither: "<key>"
Accel.SelectRegionUnselect: "<key>"
Accel.SelectRegionLeftAndNext: "<key>"
Accel.SelectRegionMiddleAndNext: "<key>"
Accel.SelectRegionRightAndNext: "<key>"
Accel.SelectRegionNeitherAndNext: "<key>"
Accel.SelectRegionSplitSwapMerge: "<key>"
Accel.SelectLineLeft: "<key>"
Accel.SelectLineMiddle: "<key>"
Accel.SelectLineRight: "<key>"
Accel.SelectLineNeither: "<key>"
Accel.SelectLineUnselect: "<key>"
Accel.TabsAt3: "<key>"
Accel.TabsAt4: "<key>"
Accel.TabsAt8: "<key>"
Accel.IgnoreTrailing: "<key>"
Accel.IgnoreWhitespace: "<key>"
Accel.IgnoreCase: "<key>"
Accel.IgnoreBlankLines: "<key>"
Accel.HideCarriageReturns: "<key>"
Accel.DirDiffIgnoreFileChanges: "<key>"
Accel.DirDiffRecursive: "<key>"
Accel.UseInternalDiff: "<key>"
Accel.QualityNormal: "<key>"
Accel.QualityFastest: "<key>"
Accel.QualityHighest: "<key>"
Accel.TogglePaneMergedView: "<key>"
Accel.TogglePopupMergedView: "<key>"
Accel.ToggleToolbar: "<key>"
Accel.ToggleLineNumbers: "<key>"
Accel.ToggleMarkers: "<key>"
Accel.ToggleVerticalLine: "<key>"
Accel.ToggleOverview: "<key>"
Accel.ToggleShowFilenames: "<key>"
Accel.HorizontalDiffNone: "<key>"
Accel.HorizontalDiffSingle: "<key>"
Accel.HorizontalDiffMultiple: "<key>"
Accel.ToggleIgnoreHorizontalWhitespace: "<key>"
Accel.ToggleIgnorePerHunkWhitespace: "<key>"
Accel.ToggleFormatClipboardText: "<key>"
Accel.IgnoreFileNone: "<key>"
Accel.IgnoreFileLeft: "<key>"
Accel.IgnoreFileMiddle: "<key>"
Accel.IgnoreFileRight: "<key>"
Accel.HelpManPage: "<key>"
Accel.HelpOnContext: "<key>"
Accel.HelpGenInitFile: "<key>"
Accel.HelpAbout: "<key>"
Accel.MergedClose: "<key>"
</PRE>
</BLOCKQUOTE>
<PRE>
FontApp: "<xfld-font-spec>"
</PRE>
<BLOCKQUOTE>
General application font, used for widgets and menus.
</BLOCKQUOTE>
<PRE>
FontText: "<xfld-font-spec>"
</PRE>
<BLOCKQUOTE>
Font to use for diff text view.
</BLOCKQUOTE>
<PRE>
Color.[NAME].[Fore|Back]: "[COLOR]"
</PRE>
<BLOCKQUOTE>
Color choice for diff hunks, and for certain other items in the text view.
<PRE>
Color.Same.Fore: "<color>"
Color.Same.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Identical text
</BLOCKQUOTE>
<PRE>
Color.SameBlank.Fore: "<color>"
Color.SameBlank.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Identical text (blank side, for filler lines when ignore-blank-lines is enabled)
</BLOCKQUOTE>
<PRE>
Color.Insert.Fore: "<color>"
Color.Insert.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Insert text (side with text)
</BLOCKQUOTE>
<PRE>
Color.InsertBlank.Fore: "<color>"
Color.InsertBlank.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Insert text (blank side)
</BLOCKQUOTE>
<PRE>
Color.DiffAll.Fore: "<color>"
Color.DiffAll.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Different in all files
</BLOCKQUOTE>
<PRE>
Color.DiffAllSup.Fore: "<color>"
Color.DiffAllSup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Different in all files (shadowed)
</BLOCKQUOTE>
<PRE>
Color.DiffAllOnly.Fore: "<color>"
Color.DiffAllOnly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Different in all files (only text on lines)
</BLOCKQUOTE>
<PRE>
Color.DiffAllNonly.Fore: "<color>"
Color.DiffAllNonly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Different in all files (blank side)
</BLOCKQUOTE>
<PRE>
Color.DiffOne.Fore: "<color>"
Color.DiffOne.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Different in one file
</BLOCKQUOTE>
<PRE>
Color.DiffOneSup.Fore: "<color>"
Color.DiffOneSup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Different in one file (shadowed)
</BLOCKQUOTE>
<PRE>
Color.DiffOneOnly.Fore: "<color>"
Color.DiffOneOnly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Different in one file (only text on lines)
</BLOCKQUOTE>
<PRE>
Color.DiffOneNonly.Fore: "<color>"
Color.DiffOneNonly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Different in one file (blank side)
</BLOCKQUOTE>
<PRE>
Color.DiffTwo.Fore: "<color>"
Color.DiffTwo.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Common text in two files only
</BLOCKQUOTE>
<PRE>
Color.DiffTwoSup.Fore: "<color>"
Color.DiffTwoSup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Common text in two files only (shadowed)
</BLOCKQUOTE>
<PRE>
Color.DiffTwoOnly.Fore: "<color>"
Color.DiffTwoOnly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Common text in two files only (only text on lines)
</BLOCKQUOTE>
<PRE>
Color.DiffTwoNonly.Fore: "<color>"
Color.DiffTwoNonly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Common text in two files only (blank side)
</BLOCKQUOTE>
<PRE>
Color.Delete.Fore: "<color>"
Color.Delete.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Delete text (side with text)
</BLOCKQUOTE>
<PRE>
Color.DeleteBlank.Fore: "<color>"
Color.DeleteBlank.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Delete text (blank side)
</BLOCKQUOTE>
<PRE>
Color.DiffDel.Fore: "<color>"
Color.DiffDel.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Different and delete text
</BLOCKQUOTE>
<PRE>
Color.DiffDelSup.Fore: "<color>"
Color.DiffDelSup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Different and delete text (shadowed)
</BLOCKQUOTE>
<PRE>
Color.DiffDelOnly.Fore: "<color>"
Color.DiffDelOnly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Different and delete text (only text on lines)
</BLOCKQUOTE>
<PRE>
Color.DiffDelNonly.Fore: "<color>"
Color.DiffDelNonly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Different and delete text (blank side)
</BLOCKQUOTE>
<PRE>
Color.DiffDelBlank.Fore: "<color>"
Color.DiffDelBlank.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(diff3 only) Different and delete text (empty side)
</BLOCKQUOTE>
<PRE>
Color.Selected.Fore: "<color>"
Color.Selected.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Selected text
</BLOCKQUOTE>
<PRE>
Color.SelectedSup.Fore: "<color>"
Color.SelectedSup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Selected text (shadowed)
</BLOCKQUOTE>
<PRE>
Color.IgnoreDisplay.Fore: "<color>"
Color.IgnoreDisplay.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Ignored for display purposes
</BLOCKQUOTE>
<PRE>
Color.IgnoreDisplaySup.Fore: "<color>"
Color.IgnoreDisplaySup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Ignored for display purposes (shadowed)
</BLOCKQUOTE>
<PRE>
Color.IgnoreDisplayOnly.Fore: "<color>"
Color.IgnoreDisplayOnly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Ignored for display purposes (only text on lines)
</BLOCKQUOTE>
<PRE>
Color.IgnoreDisplayNonly.Fore: "<color>"
Color.IgnoreDisplayNonly.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Ignored for display purposes (blank side)
</BLOCKQUOTE>
<PRE>
Color.Deleted.Fore: "<color>"
Color.Deleted.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Deleted text
</BLOCKQUOTE>
<PRE>
Color.DeletedSup.Fore: "<color>"
Color.DeletedSup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Deleted text (shadowed)
</BLOCKQUOTE>
<PRE>
Color.Ignored.Fore: "<color>"
Color.Ignored.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Ignore text
</BLOCKQUOTE>
<PRE>
Color.Directories.Fore: "<color>"
Color.Directories.Back: "<color>"
</PRE>
<BLOCKQUOTE>
(dir.diffs only) Directories in directory diffs
</BLOCKQUOTE>
<PRE>
Color.MergedUndecided.Fore: "<color>"
Color.MergedUndecided.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Merged view undecided text
</BLOCKQUOTE>
<PRE>
Color.MergedDecided1.Fore: "<color>"
Color.MergedDecided1.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Merged view decided text, file 1
</BLOCKQUOTE>
<PRE>
Color.MergedDecided1Sup.Fore: "<color>"
Color.MergedDecided1Sup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Merged view decided text, file 1 (shadowed)
</BLOCKQUOTE>
<PRE>
Color.MergedDecided2.Fore: "<color>"
Color.MergedDecided2.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Merged view decided text, file 2
</BLOCKQUOTE>
<PRE>
Color.MergedDecided2Sup.Fore: "<color>"
Color.MergedDecided2Sup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Merged view decided text, file 2 (shadowed)
</BLOCKQUOTE>
<PRE>
Color.MergedDecided3.Fore: "<color>"
Color.MergedDecided3.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Merged view decided text, file 3
</BLOCKQUOTE>
<PRE>
Color.MergedDecided3Sup.Fore: "<color>"
Color.MergedDecided3Sup.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Merged view decided text, file 3 (shadowed)
</BLOCKQUOTE>
<PRE>
Color.MergedDecidedNeither.Fore: "<color>"
Color.MergedDecidedNeither.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Merged view decided text, neither files
</BLOCKQUOTE>
<PRE>
Color.Background.Fore: "<color>"
Color.Background.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Global background color
</BLOCKQUOTE>
<PRE>
Color.Cursor.Fore: "<color>"
Color.Cursor.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Line cursor color
</BLOCKQUOTE>
<PRE>
Color.VerticalLine.Fore: "<color>"
Color.VerticalLine.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Vertical line color
</BLOCKQUOTE>
<PRE>
Color.TextSelection.Fore: "<color>"
Color.TextSelection.Back: "<color>"
</PRE>
<BLOCKQUOTE>
Color of text region selection
</BLOCKQUOTE>
</BLOCKQUOTE>
<PRE>
ExitOnSame: False
</PRE>
<BLOCKQUOTE>
If true, exit if both files have no differences.
</BLOCKQUOTE>
<PRE>
ExitIfNoConflicts: False
</PRE>
<BLOCKQUOTE>
If true, exit if after an automatic merge there are no conflicts.
</BLOCKQUOTE>
<PRE>
AutoSelectMerge: False
</PRE>
<BLOCKQUOTE>
Pre-selected non-conflictual regions as an automatic merge would.
</BLOCKQUOTE>
<PRE>
IgnoreHorizontalWhitespace: False
</PRE>
<BLOCKQUOTE>
Ignore horizontal whitespace in horizontal diffs.
</BLOCKQUOTE>
<PRE>
IgnorePerHunkWhitespace: False
</PRE>
<BLOCKQUOTE>
For each hunk, ignore hunk if there are only whitespace and line break changes within that hunk. This can be useful for ignoring code reformatting for certain source code languages that allow it (e.g. C++).
</BLOCKQUOTE>
<PRE>
FormatClipboardText: True
</PRE>
<BLOCKQUOTE>
Enables clipboard (copy-paste) formatting. If disabled, text that goes in the clipboard is simply left unformatted.
</BLOCKQUOTE>
<PRE>
IgnoreErrors: False
</PRE>
<BLOCKQUOTE>
Disables diff errors reporting.
</BLOCKQUOTE>
<PRE>
WarnAboutUnsaved: False
</PRE>
<BLOCKQUOTE>
Enables warning upon exiting with unsaved selections.
</BLOCKQUOTE>
<PRE>
DisableCursorDisplay: False
</PRE>
<BLOCKQUOTE>
Disables displaying the line cursor.
</BLOCKQUOTE>
<PRE>
DrawPatternInFillerLines: True
</PRE>
<BLOCKQUOTE>
Some people like to have a pattern drawn for filler lines to make it really dead obvious that they are not real lines, but just inserted for display purpose. This setting enables it.
</BLOCKQUOTE>
<PRE>
HideCarriageReturns: False
</PRE>
<BLOCKQUOTE>
Hides CR characters found in files created under DOS/Windows.
</BLOCKQUOTE>
<PRE>
DirDiffIgnoreFileChanges: False
</PRE>
<BLOCKQUOTE>
In directory diffs, ignores file changes, show just additions and deletions.
</BLOCKQUOTE>
<PRE>
DirDiffBuildSolelyFromOutput: True
</PRE>
<BLOCKQUOTE>
In directory diffs, building diffs only from output, not checking against actual directory contents. This is a self-verification feature only, and unless you're doing development you should leave this to default (true).
</BLOCKQUOTE>
<PRE>
DirDiffRecursive: False
</PRE>
<BLOCKQUOTE>
In directory diffs, enable recursive diff'ing of subdirectories.
</BLOCKQUOTE>
<PRE>
UseInternalDiff: True
</PRE>
<BLOCKQUOTE>
(Not implemented) Use internal diff computation, does not spawn external diff program.
</BLOCKQUOTE>
<PRE>
Show.[NAME]: [True|False]
</PRE>
<BLOCKQUOTE>
Set of options to determine if some UI display element is visible or not upon startup.
<PRE>
Show.Toolbar: False
</PRE>
<BLOCKQUOTE>
Show toolbar on startup.
</BLOCKQUOTE>
<PRE>
Show.LineNumbers: False
</PRE>
<BLOCKQUOTE>
Show line numbers on startup.
</BLOCKQUOTE>
<PRE>
Show.VerticalLine: False
</PRE>
<BLOCKQUOTE>
Show vertical line on startup.
</BLOCKQUOTE>
<PRE>
Show.Overview: True
</PRE>
<BLOCKQUOTE>
Show toolbar on startup.
</BLOCKQUOTE>
<PRE>
Show.Filenames: True
</PRE>
<BLOCKQUOTE>
Show toolbar on startup.
</BLOCKQUOTE>
<PRE>
Show.PaneMergedView: False
</PRE>
<BLOCKQUOTE>
Show pane merged view on startup.
</BLOCKQUOTE>
<PRE>
Show.PopupMergedView: False
</PRE>
<BLOCKQUOTE>
Show popup merged view on startup.
</BLOCKQUOTE>
</BLOCKQUOTE>
<PRE>
TabWidth: 8
</PRE>
<BLOCKQUOTE>
Tab character alignment width.
</BLOCKQUOTE>
<PRE>
Command.[NAME]: "[COMMAND]"
</PRE>
<BLOCKQUOTE>
Commands to use to generate diffs. xxdiff is only an interface to display diff results, it doesn't actually compute diffs itself, unless you use the internal commands options, where it uses the same arguments as specified here. Most likely these are the GNU diff commands and options. Note that you can specify command switches here and the user interface will be automatically updated accordingly (e.g. if you set a command with the -w switch, and UI understands that the ignore whitespace feature has been turned on).
<PRE>
Command.DiffFiles2: "diff"
</PRE>
<BLOCKQUOTE>
Command to use for comparing two files.
</BLOCKQUOTE>
<PRE>
Command.DiffFiles3: "diff3"
</PRE>
<BLOCKQUOTE>
Command to use for comparing three files.
</BLOCKQUOTE>
<PRE>
Command.DiffDirectories: "diff -q -s"
</PRE>
<BLOCKQUOTE>
Command to use for comparing two directories, non-recursively.
</BLOCKQUOTE>
<PRE>
Command.DiffDirectoriesRec: "diff -q -s -r"
</PRE>
<BLOCKQUOTE>
Command to use for comparing two directories, recursively.
</BLOCKQUOTE>
<PRE>
Command.Edit: "xterm -e vi"
</PRE>
<BLOCKQUOTE>
Command to use to spawn an editor on a file.
</BLOCKQUOTE>
</BLOCKQUOTE>
<PRE>
CommandSwitch.IgnoreTrailingBlanks: "-b"
CommandSwitch.IgnoreWhitespace: "-w"
CommandSwitch.IgnoreCase: "-i"
CommandSwitch.IgnoreBlankLines: "-B"
CommandSwitch.QualityNormal: ""
CommandSwitch.QualityFastest: "-d"
CommandSwitch.QualityHighest: "-H"
</PRE>
<BLOCKQUOTE>
Definitions of cmdline switches that should be used to toggle diff options. These resources allow you to specify what switch corresponds to what feature. The defaults are the GNU diff switches (see diff(1)). These are only valid for two-file diff for now. See also the InitSwitch resources.
</BLOCKQUOTE>
<PRE>
InitSwitch.IgnoreTrailingBlanks: Nop
InitSwitch.IgnoreWhitespace: Nop
InitSwitch.IgnoreCase: Nop
InitSwitch.IgnoreBlankLines: Nop
InitSwitch.QualityNormal: Nop
InitSwitch.QualityFastest: Nop
InitSwitch.QualityHighest: Nop
</PRE>
<BLOCKQUOTE>
Initialization of a particular switch after the resources have been read in. This is used to modify the command using the switch definitions. In other words, you could either set the switch within the command specification, or use a plain command and enable/disable the switch using this resource. This resource is only provided for completeness and convenience, as setting the appropriate switch in the command itself amounts to the same. See also the CommandSwitch resources. For the quality options, you should just set a single one to 'true'.
</BLOCKQUOTE>
<PRE>
OverviewFileWidth: 20
</PRE>
<BLOCKQUOTE>
In overview area, width (in pixels) of each file.
</BLOCKQUOTE>
<PRE>
OverviewSepWidth: 14
</PRE>
<BLOCKQUOTE>
In overview area, width (in pixels) between each file.
</BLOCKQUOTE>
<PRE>
VerticalLinePosition: 80
</PRE>
<BLOCKQUOTE>
Initial column to draw vertical alignment line.
</BLOCKQUOTE>
<PRE>
Tag.[NAME]: [True|False]
</PRE>
<BLOCKQUOTE>
Tags used for conditionals used for unselected regions, when that option is used to save files.
<PRE>
Tag.Conflict.Separator: ">>>>>>>>>>>>>>>>>>>> File %d"
</PRE>
<BLOCKQUOTE>
String used to separate chunks when saving with conflicts.
</BLOCKQUOTE>
<PRE>
Tag.Conflict.End: "<<<<<<<<<<<<<<<<<<<<"
</PRE>
<BLOCKQUOTE>
String used to end chunks when saving with conflicts.
</BLOCKQUOTE>
<PRE>
Tag.Conditional.Ifdef: "#if defined( %s )"
</PRE>
<BLOCKQUOTE>
Ifdef string used when saving with conditionals.
</BLOCKQUOTE>
<PRE>
Tag.Conditional.Elseif: "#elif defined( %s )"
</PRE>
<BLOCKQUOTE>
Elseif string used when saving with conditionals.
</BLOCKQUOTE>
<PRE>
Tag.Conditional.Else: "#else"
</PRE>
<BLOCKQUOTE>
Else string used when saving with conditionals.
</BLOCKQUOTE>
<PRE>
Tag.Conditional.Endif: "#endif"
</PRE>
<BLOCKQUOTE>
Endif string used when saving with conditionals.
</BLOCKQUOTE>
<PRE>
Tag.Unmerge.Start: "<<<<<<<"
</PRE>
<BLOCKQUOTE>
Tag that appears at the beginning of a line in a merged file to indicate the start of a merged merge conflict. Default is the CVS start tag.
</BLOCKQUOTE>
<PRE>
Tag.Unmerge.Sep: "======="
</PRE>
<BLOCKQUOTE>
Tag that appears at the beginning of a line in a merged file to separate sides of a merged merge conflict. Default is the CVS start tag.
</BLOCKQUOTE>
<PRE>
Tag.Unmerge.SepExtra: "|||||||"
</PRE>
<BLOCKQUOTE>
Tag that appears at the beginning of a line in a merged file to separate sides of a merged 3-way merge conflict. Default is the tag generated by GNU diff3.
</BLOCKQUOTE>
<PRE>
Tag.Unmerge.End: ">>>>>>>"
</PRE>
<BLOCKQUOTE>
Tag that appears at the beginning of a line in a merged file to indicate the end of a merged merge conflict. Default is the CVS start tag.
</BLOCKQUOTE>
</BLOCKQUOTE>
<PRE>
ClipboardHeaderFormat: "
In file "%F":
------------------------------
"
</PRE>
<BLOCKQUOTE>
Format of header for selection of text for formatted clipboard text.
</BLOCKQUOTE>
<PRE>
ClipboardLineFormat: "%L: %s"
</PRE>
<BLOCKQUOTE>
Format of each selection line for formatted clipboard text.
</BLOCKQUOTE>
<PRE>
HorizontalDiffType: Multiple
</PRE>
<BLOCKQUOTE>
Type of horizontal diffs display. Can be one of None, Single, Multiple. None: doesn't compute nor display horizontal diff; Single: just bracket the changes from line beginnings and ends; Multiple: compute multiple horizontal diff (if the sizes fit in the maximum size (see HorizontalDiffMax resource).
</BLOCKQUOTE>
<PRE>
HorizontalDiffMax: 10000
</PRE>
<BLOCKQUOTE>
Maximum table size for dynamic-programming table used for computing the horizontal diff for change lines. If the size of one horizontal hunk times the size of the other horizontal hunk is over that size, there are no multiple horizontal diffs computed for that line, and the algorithm behaves like the Single algorithm. You most likely don't want to touch that value.
</BLOCKQUOTE>
<PRE>
HorizontalDiffContext: 5
</PRE>
<BLOCKQUOTE>
Minimum amount of characters or token that need to be common to both lines between multiple horizontal diff hunks. If there are not that amount of common characters, skip the horizontal hunk and display it as a changed region. This resource is very useful to remove the cases where few characters align, resulting in many small horizontal hunks, which can be quite confusing. Usually a value of 5 gives enough horizontal context for the eye to figure out what happenened.
</BLOCKQUOTE>
<PRE>
ShowPaneMergedViewPercent: 40
</PRE>
<BLOCKQUOTE>
Initial vertical percentage size, between 0 and 100, of the pane merged view on startup.
</BLOCKQUOTE>
<PRE>
MergedFilename: "%L.merge"
</PRE>
<BLOCKQUOTE>
Default merged filename. %L, %M, %R can be used as placeholders for left, middle and right filenames repectively. Note that ClearCase suffixes are stripped automatically.
</BLOCKQUOTE>
<!-- ======================================================================= --><a name="faq"></a><h2>Frequently Asked Questions (FAQ)</h2><!-- ======================================================================= --><h3>Can I diff files with CRLF DOS characters in them?</h3><p>If you want to diff files with CRLF characters in them, you can use the 'ignorewhitespace option to GNU diff, which will work, even if only one of the fileshas the DOS characters in it.</p><!-- ======================================================================= --><h3>How do I make xxdiff display the revision number of a file?</h3><p>By default, the filenames window display the filename. From the command-line,however, you can set it to display an arbitrary string, which could include yourcurrent revision number.</p><!-- ======================================================================= --><h3>xxdiff fails with an undefined symbol, what do I do?</h3>More precisely, xxdiff fails with the following error:<pre>xxdiff: error while loading shared libraries: xxdiff: undefined symbol:__11QSizePolicyQ211QSizePolicy8SizeTypeT1b</pre><p>You are most likely running nuder Linux RedHat-6.2 and you need to upgrade yourQt library.</p><!-- ======================================================================= --><a name="author"></a><h2>Author</h2><p>This program has been written from scratch and is being actively maintained by<b>Martin Blais</b>(<a href="mailto:blais@iro.umontreal.ca">blais@iro.umontreal.ca</a>).</p><!-- ======================================================================= --><a name="bugs"></a><h2>Reporting bugs</h2> <p>All bug reports and feature requests should be submitted throught theSourceForge bug tracking system at the following URL<a href="http://sourceforge.net/bugs/?group_id=2198">http://sourceforge.net/bugs/?group_id=2198</a>. Please avoid sending the authoremail about xxdiff bugs. Please use this bug tracking system, it is extremelyfast and simple to use.</p><!-- ======================================================================= --><a name="history"></a><h2>Project history</h2><p>This program has been written and inspired after gdiff, mgdiff, and RudyWortel's xdiff under SGI. xxdiff aims to provide a lasting open-sourcereplacement to these programs. Writing this tool from scratch was originallymotivated by the need to have horizontal diffs, which turned out to be anessential feature of this program.</p><p>This program is being extensively tested by several software developmentengineers at discreet, that use it daily in their merge reviewing activities.It has reached a stable state.</p><h3>Licensing</h3><p>This program is distributed under the GNU General Public License. See the<a href="http://www.gnu.org">GNU project website</a> for full details.</p><h3>Dependencies</h3>This program depends on the availability of a textual diff program (such as GNUdiff) and the Qt UI toolkit (available at http://trolltech.com).<h3>Acknowledgements</h3><p>Thanks go to discreet, for letting me deploy my program there, and for notbothering me with the occasional bug fix that I did on the job. Many morethanks to all the many engineers who tested it there and reported problems withit, as well as providing invaluable suggestions.</p><p>SourceForge is hosting my web site and I'm using many of its features. TomasPospisek (tpo@sourcepole.ch) has provided a Debian package. Dan Weeks haspackaged it for one of the BSD variants (danimal@danimal.org).</p>
</body>
</html>
