Author: Martin Blais <blais@furius.ca>

# The Almost Secret Features of xxdiff

Author: | Martin Blais <blais@furius.ca>
Last update: | 2006-04-12

Abstract

A short exposé of some of the least-known or non-obvious features of xxdiff.

Table of Contents

- Introduction
- Horizontal Diffs
- Checking for Strict Equality
- Number of Remaining Hunks
- Selecting Text
- Per-Hunk Ignore Whitespace
- Decision Mode

# Introduction

xxdiff has grown a number of little cool features that are not necessarily obvious from its user interface. This documents aims at presenting some of them together outside of the general documentation. (All these features are also documented in the user's manual.)

# Horizontal Diffs

When there are small changes between lines, it can be laborious to quickly figure out exactly what has changed between them. An extremely addictive feature of xxdiff is that it can compute the diffs between pairs of matching lines, i.e. horizontal diffs. The differing parts are highlighted with a brighter color.

# Checking for Strict Equality

When comparing a large number of files for merge review, we want to minimize the amount of time we spend on useless changes, and you will most likely enable the "ignore whitespace" features. Sometimes some automated scripts that will launch xxdiff will be lauching it on two files which have no non-whitespace differences. It is then impossible to "see" if the files are exactly the same or not (I mean, byte-for-byte the same or not).

Sometimes it is important to know that, for example, before committing changes to a revision control system. For this purpose, you can check out the label over the overview area which will contain an equal sign `(=)` if there are no differences at all, not even whitespace differences. If you can see no visible differences and this marker is not present, this indicates that the files do differ, probably just in whitespace.

# Number of Remaining Hunks

That little number of the overview area is the number of diff hunks that are unselected. You can save a merged result when all the hunks are selected, so this indicates the number of remaining hunks to resolve before you can save.

# Selecting Text

In the context of merge reviewing, it is often useful to make comments on the code that is visible from xxdiff. You can use the `Control` key and mouse button 1 to select an arbitrary set of lines in either file, and that text is put into the clipboard. You can then cut-n-paste it in a text editor where you make your comments.

A red line appears to display the selection of text stored in the clipboard.

How the line is formatted can be configured with the resources to include the line numbers and some other things.

# Per-Hunk Ignore Whitespace

Often in a context of looking at many changes, code reviewers get really annoyed with having to review formatting changes intermixed with code changes. Fortunately, some of these changes can be ignored by diff by ignoring the whitespace characters (and this is also supported by xxdiff) but this does not help for the cases when reformatting involves breaking lines.

In practice, if you're just re-formatting some code, it is often the case that only whitespace differences are appearing in a diff hunk. For this purpose, xxdiff has a special feature that de-emphasizes diff hunks that only differ in whitespace.

The algorithm we use is really simple: given a diff hunk with text on both sides (i.e. a change hunk), we compare all the non-whitespace characters. If the entire hunks do not differ in that way, we de-emphasize the hunk to make it look like both regions are the same (using a gray color similar to the color for non-differing hunks). Those hunks are otherwise still selectable for merging.

# Decision Mode

Sometimes you want to force the user to produce a merged file. There is a special “decision” mode that does just that. In the toolbar-if you have that enabled-3 buttons will appear:

Decision mode: you must Reject, Accept or Merge.

1. R: reject the changes (keep the left file);
2. M: merge the selected changes (keep the selections) [1];
3. A: accept the changes (keep the right file);

Upon exit, xxdiff will print one of following strings on stdout: `REJECT`, `MERGED` or `ACCEPT`, corresponding to the user's choices. (If you close xxdiff via your window manager, a special `NODECISION` code will be output). This can be used in collaboration with the `--merged-filename` option to write scripts that will invoke xxdiff to get a merged file, and then do something with that merged file (for example, this could be used to resolve conflicts).

In addition, there is a Python xxdiff package that supports calling xxdiff in this way. See the `xxdiff.invoke` module in the Python xxdiff scripts code.

[1] | Note that if you exit with M, xxdiff will make sure that all diff hunks have had a decision made for them, and ask you what to do with the unselected hunks if any have been forgotten.