<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"

"http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">

<head>

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />

<meta name="generator" content="AsciiDoc 8.2.5" />

<style type="text/css">

/* Debug borders */

p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {

/*

border: 1px solid red;

*/

}

body {

margin: 1em 5% 1em 5%;

}

a {

color: blue;

text-decoration: underline;

}

a:visited {

color: fuchsia;

}

em {

font-style: italic;

}

strong {

font-weight: bold;

}

tt {

color: navy;

}

h1, h2, h3, h4, h5, h6 {

color: #527bbd;

font-family: sans-serif;

margin-top: 1.2em;

margin-bottom: 0.5em;

line-height: 1.3;

}

h1, h2, h3 {

border-bottom: 2px solid silver;

}

h2 {

padding-top: 0.5em;

}

h3 {

float: left;

}

h3 + * {

clear: left;

}

div.sectionbody {

font-family: serif;

margin-left: 0;

}

hr {

border: 1px solid silver;

}

p {

margin-top: 0.5em;

margin-bottom: 0.5em;

}

pre {

padding: 0;

margin: 0;

}

span#author {

color: #527bbd;

font-family: sans-serif;

font-weight: bold;

font-size: 1.1em;

}

span#email {

}

span#revision {

font-family: sans-serif;

}

div#footer {

font-family: sans-serif;

font-size: small;

border-top: 2px solid silver;

padding-top: 0.5em;

margin-top: 4.0em;

}

div#footer-text {

float: left;

padding-bottom: 0.5em;

}

div#footer-badges {

float: right;

padding-bottom: 0.5em;

}

div#preamble,

div.tableblock, div.imageblock, div.exampleblock, div.verseblock,

div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,

div.admonitionblock {

margin-right: 10%;

margin-top: 1.5em;

margin-bottom: 1.5em;

}

div.admonitionblock {

margin-top: 2.5em;

margin-bottom: 2.5em;

}

div.content { /* Block element content. */

padding: 0;

}

/* Block element titles. */

div.title, caption.title {

font-family: sans-serif;

font-weight: bold;

text-align: left;

margin-top: 1.0em;

margin-bottom: 0.5em;

}

div.title + * {

margin-top: 0;

}

td div.title:first-child {

margin-top: 0.0em;

}

div.content div.title:first-child {

margin-top: 0.0em;

}

div.content + div.title {

margin-top: 0.0em;

}

div.sidebarblock > div.content {

background: #ffffee;

border: 1px solid silver;

padding: 0.5em;

}

div.listingblock {

margin-right: 0%;

}

div.listingblock > div.content {

border: 1px solid silver;

background: #f4f4f4;

padding: 0.5em;

}

div.quoteblock > div.content {

padding-left: 2.0em;

}

div.attribution {

text-align: right;

}

div.verseblock + div.attribution {

text-align: left;

}

div.admonitionblock .icon {

vertical-align: top;

font-size: 1.1em;

font-weight: bold;

text-decoration: underline;

color: #527bbd;

padding-right: 0.5em;

}

div.admonitionblock td.content {

padding-left: 0.5em;

border-left: 2px solid silver;

}

div.exampleblock > div.content {

border-left: 2px solid silver;

padding: 0.5em;

}

div.verseblock div.content {

white-space: pre;

}

div.imageblock div.content { padding-left: 0; }

div.imageblock img { border: 1px solid silver; }

span.image img { border-style: none; }

dl {

margin-top: 0.8em;

margin-bottom: 0.8em;

}

dt {

margin-top: 0.5em;

margin-bottom: 0;

font-style: italic;

}

dd > *:first-child {

margin-top: 0;

}

ul, ol {

list-style-position: outside;

}

div.olist2 ol {

list-style-type: lower-alpha;

}

div.tableblock > table {

border: 3px solid #527bbd;

}

thead {

font-family: sans-serif;

font-weight: bold;

}

tfoot {

font-weight: bold;

}

div.hlist {

margin-top: 0.8em;

margin-bottom: 0.8em;

}

div.hlist td {

padding-bottom: 5px;

}

td.hlist1 {

vertical-align: top;

font-style: italic;

padding-right: 0.8em;

}

td.hlist2 {

vertical-align: top;

}

@media print {

div#footer-badges { display: none; }

}

div#toctitle {

color: #527bbd;

font-family: sans-serif;

font-size: 1.1em;

font-weight: bold;

margin-top: 1.0em;

margin-bottom: 0.1em;

}

div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {

margin-top: 0;

margin-bottom: 0;

}

div.toclevel2 {

margin-left: 2em;

font-size: 0.9em;

}

div.toclevel3 {

margin-left: 4em;

font-size: 0.9em;

}

div.toclevel4 {

margin-left: 6em;

font-size: 0.9em;

}

/* Workarounds for IE6's broken and incomplete CSS2. */

div.sidebar-content {

background: #ffffee;

border: 1px solid silver;

padding: 0.5em;

}

div.sidebar-title, div.image-title {

font-family: sans-serif;

font-weight: bold;

margin-top: 0.0em;

margin-bottom: 0.5em;

}

div.listingblock div.content {

border: 1px solid silver;

background: #f4f4f4;

padding: 0.5em;

}

div.quoteblock-content {

padding-left: 2.0em;

}

div.exampleblock-content {

border-left: 2px solid silver;

padding-left: 0.5em;

}

/* IE6 sets dynamically generated links as visited. */

div#toc a:visited { color: blue; }

</style>

<title>diff API</title>

</head>

<body>

<div id="header">

<h1>diff API</h1>

</div>

<div id="preamble">

<div class="sectionbody">

<div class="para"><p>The diff API is for programs that compare two sets of files (e.g. two

trees, one tree and the index) and present the found difference in

various ways. The calling program is responsible for feeding the API

pairs of files, one from the "old" set and the corresponding one from

"new" set, that are different. The library called through this API is

called diffcore, and is responsible for two things.</p></div>

<div class="ilist"><ul>

<li>

<p>

finding total rewrites (<tt>-B</tt>), renames (<tt>-M</tt>) and copies (<tt>-C</tt>), and

changes that touch a string (<tt>-S</tt>), as specified by the caller.

</p>

</li>

<li>

<p>

outputting the differences in various formats, as specified by the

caller.

</p>

</li>

</ul></div>

</div>

</div>

<h2 id="_calling_sequence">Calling sequence</h2>

<div class="sectionbody">

<div class="ilist"><ul>

<li>

<p>

Prepare <tt>struct diff_options</tt> to record the set of diff options, and

then call <tt>diff_setup()</tt> to initialize this structure. This sets up

the vanilla default.

</p>

</li>

<li>

<p>

Fill in the options structure to specify desired output format, rename

detection, etc. <tt>diff_opt_parse()</tt> can be used to parse options given

from the command line in a way consistent with existing git-diff

family of programs.

</p>

</li>

<li>

<p>

Call <tt>diff_setup_done()</tt>; this inspects the options set up so far for

internal consistency and make necessary tweaking to it (e.g. if

textual patch output was asked, recursive behaviour is turned on).

</p>

</li>

<li>

<p>

As you find different pairs of files, call <tt>diff_change()</tt> to feed

modified files, <tt>diff_addremove()</tt> to feed created or deleted files,

or <tt>diff_unmerged()</tt> to feed a file whose state is <em>unmerged</em> to the

API. These are thin wrappers to a lower-level <tt>diff_queue()</tt> function

that is flexible enough to record any of these kinds of changes.

</p>

</li>

<li>

<p>

Once you finish feeding the pairs of files, call <tt>diffcore_std()</tt>.

This will tell the diffcore library to go ahead and do its work.

</p>

</li>

<li>

<p>

Calling <tt>diff_flush()</tt> will produce the output.

</p>

</li>

</ul></div>

</div>

<h2 id="_data_structures">Data structures</h2>

<div class="sectionbody">

<div class="ilist"><ul>

<li>

<p>

<tt>struct diff_filespec</tt>

</p>

</li>

</ul></div>

<div class="para"><p>This is the internal representation for a single file (blob). It

records the blob object name (if known &#8212; for a work tree file it

typically is a NUL SHA-1), filemode and pathname. This is what the

<tt>diff_addremove()</tt>, <tt>diff_change()</tt> and <tt>diff_unmerged()</tt> synthesize and

feed <tt>diff_queue()</tt> function with.</p></div>

<div class="ilist"><ul>

<li>

<p>

<tt>struct diff_filepair</tt>

</p>

</li>

</ul></div>

<div class="para"><p>This records a pair of <tt>struct diff_filespec</tt>; the filespec for a file

in the "old" set (i.e. preimage) is called <tt>one</tt>, and the filespec for a

file in the "new" set (i.e. postimage) is called <tt>two</tt>. A change that

represents file creation has NULL in <tt>one</tt>, and file deletion has NULL

in <tt>two</tt>.</p></div>

<div class="para"><p>A <tt>filepair</tt> starts pointing at <tt>one</tt> and <tt>two</tt> that are from the same

filename, but <tt>diffcore_std()</tt> can break pairs and match component

filespecs with other filespecs from a different filepair to form new

filepair. This is called <em>rename detection</em>.</p></div>

<div class="ilist"><ul>

<li>

<p>

<tt>struct diff_queue</tt>

</p>

</li>

</ul></div>

<div class="para"><p>This is a collection of filepairs. Notable members are:</p></div>

<div class="vlist"><dl>

<dt>

<tt>queue</tt>

</dt>

<dd>

<p>

An array of pointers to <tt>struct diff_filepair</tt>. This

dynamically grows as you add filepairs;

</p>

</dd>

<dt>

<tt>alloc</tt>

</dt>

<dd>

<p>

The allocated size of the <tt>queue</tt> array;

</p>

</dd>

<dt>

<tt>nr</tt>

</dt>

<dd>

<p>

The number of elements in the <tt>queue</tt> array.

</p>

<div class="ilist"><ul>

<li>

<p>

<tt>struct diff_options</tt>

</p>

</li>

</ul></div>

</dd>

</dl></div>

<div class="para"><p>This describes the set of options the calling program wants to affect

the operation of diffcore library with.</p></div>

<div class="para"><p>Notable members are:</p></div>

<div class="vlist"><dl>

<dt>

<tt>output_format</tt>

</dt>

<dd>

<p>

The output format used when <tt>diff_flush()</tt> is run.

</p>

</dd>

<dt>

<tt>context</tt>

</dt>

<dd>

<p>

Number of context lines to generate in patch output.

</p>

</dd>

<dt>

<tt>break_opt</tt>, <tt>detect_rename</tt>, <tt>rename-score</tt>, <tt>rename_limit</tt>

</dt>

<dd>

<p>

Affects the way detection logic for complete rewrites, renames

and copies.

</p>

</dd>

<dt>

<tt>abbrev</tt>

</dt>

<dd>

<p>

Number of hexdigits to abbreviate raw format output to.

</p>

</dd>

<dt>

<tt>pickaxe</tt>

</dt>

<dd>

<p>

A constant string (can and typically does contain newlines to

look for a block of text, not just a single line) to filter out

the filepairs that do not change the number of strings contained

in its preimage and postimage of the diff_queue.

</p>

</dd>

<dt>

<tt>flags</tt>

</dt>

<dd>

<p>

This is mostly a collection of boolean options that affects the

operation, but some do not have anything to do with the diffcore

library.

</p>

<div class="vlist"><dl>

<dt>

BINARY, TEXT

</dt>

<dd>

<p>

Affects the way how a file that is seemingly binary is treated.

</p>

</dd>

<dt>

FULL_INDEX

</dt>

<dd>

<p>

Tells the patch output format not to use abbreviated object

names on the "index" lines.

</p>

</dd>

<dt>

FIND_COPIES_HARDER

</dt>

<dd>

<p>

Tells the diffcore library that the caller is feeding unchanged

filepairs to allow copies from unmodified files be detected.

</p>

</dd>

<dt>

COLOR_DIFF

</dt>

<dd>

<p>

Output should be colored.

</p>

</dd>

<dt>

COLOR_DIFF_WORDS

</dt>

<dd>

<p>

Output is a colored word-diff.

</p>

</dd>

<dt>

NO_INDEX

</dt>

<dd>

<p>

Tells diff-files that the input is not tracked files but files

in random locations on the filesystem.

</p>

</dd>

<dt>

ALLOW_EXTERNAL

</dt>

<dd>

<p>

Tells output routine that it is Ok to call user specified patch

output routine. Plumbing disables this to ensure stable output.

</p>

</dd>

<dt>

QUIET

</dt>

<dd>

<p>

Do not show any output.

</p>

</dd>

<dt>

REVERSE_DIFF

</dt>

<dd>

<p>

Tells the library that the calling program is feeding the

filepairs reversed; <tt>one</tt> is two, and <tt>two</tt> is one.

</p>

</dd>

<dt>

EXIT_WITH_STATUS

</dt>

<dd>

<p>

For communication between the calling program and the options

parser; tell the calling program to signal the presence of

difference using program exit code.

</p>

</dd>

<dt>

HAS_CHANGES

</dt>

<dd>

<p>

Internal; used for optimization to see if there is any change.

</p>

</dd>

<dt>

SILENT_ON_REMOVE

</dt>

<dd>

<p>

Affects if diff-files shows removed files.

</p>

</dd>

<dt>

RECURSIVE, TREE_IN_RECURSIVE

</dt>

<dd>

<p>

Tells if tree traversal done by tree-diff should recursively

descend into a tree object pair that are different in preimage

and postimage set.

</p>

</dd>

</dl></div>

</dd>

</dl></div>

<div class="para"><p>(JC)</p></div>

</div>

<div id="footer">

<div id="footer-text">

Last updated 2010-09-18 23:57:10 UTC

</div>

</div>

</body>

</html>