technical/api-diff.html - external/gitster/git-htmldocs - Git at Google

 <!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.5.2" />
 <title>diff API</title>
 <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;
  color: navy;
 }

 strong {
  font-weight: bold;
  color: #083194;
 }

 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;
 }

 ul, ol, li > p {
  margin-top: 0;
 }

 pre {
  padding: 0;
  margin: 0;
 }

 span#author {
  color: #527bbd;
  font-family: sans-serif;
  font-weight: bold;
  font-size: 1.1em;
 }
 span#email {
 }
 span#revnumber, span#revdate, span#revremark {
  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 {
  margin-top: 1.5em;
  margin-bottom: 1.5em;
 }
 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 div.admonitionblock {
  margin-top: 1.0em;
  margin-bottom: 1.5em;
 }
 div.admonitionblock {
  margin-top: 2.0em;
  margin-bottom: 2.0em;
  margin-right: 10%;
  color: #606060;
 }

 div.content { /* Block element content. */
  padding: 0;
 }

 /* Block element titles. */
 div.title, caption.title {
  color: #527bbd;
  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 > div.content {
  border: 1px solid silver;
  background: #f4f4f4;
  padding: 0.5em;
 }

 div.quoteblock, div.verseblock {
  padding-left: 1.0em;
  margin-left: 1.0em;
  margin-right: 10%;
  border-left: 5px solid #dddddd;
  color: #777777;
 }

 div.quoteblock > div.attribution {
  padding-top: 0.5em;
  text-align: right;
 }

 div.verseblock > div.content {
  white-space: pre;
 }
 div.verseblock > div.attribution {
  padding-top: 0.75em;
  text-align: left;
 }
 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 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: 3px solid #dddddd;
 }

 div.exampleblock > div.content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
 }

 div.imageblock div.content { padding-left: 0; }
 span.image img { border-style: none; }
 a.image:visited { color: white; }

 dl {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 dt {
  margin-top: 0.5em;
  margin-bottom: 0;
  font-style: normal;
  color: navy;
 }
 dd > *:first-child {
  margin-top: 0.1em;
 }

 ul, ol {
  list-style-position: outside;
 }
 ol.arabic {
  list-style-type: decimal;
 }
 ol.loweralpha {
  list-style-type: lower-alpha;
 }
 ol.upperalpha {
  list-style-type: upper-alpha;
 }
 ol.lowerroman {
  list-style-type: lower-roman;
 }
 ol.upperroman {
  list-style-type: upper-roman;
 }

 div.compact ul, div.compact ol,
 div.compact p, div.compact p,
 div.compact div, div.compact div {
  margin-top: 0.1em;
  margin-bottom: 0.1em;
 }

 div.tableblock > table {
  border: 3px solid #527bbd;
 }
 thead, p.table.header {
  font-family: sans-serif;
  font-weight: bold;
 }
 tfoot {
  font-weight: bold;
 }
 td > div.verse {
  white-space: pre;
 }
 p.table {
  margin-top: 0;
 }
 /* Because the table frame attribute is overriden by CSS in most browsers. */
 div.tableblock > table[frame="void"] {
  border-style: none;
 }
 div.tableblock > table[frame="hsides"] {
  border-left-style: none;
  border-right-style: none;
 }
 div.tableblock > table[frame="vsides"] {
  border-top-style: none;
  border-bottom-style: none;
 }


 div.hdlist {
  margin-top: 0.8em;
  margin-bottom: 0.8em;
 }
 div.hdlist tr {
  padding-bottom: 15px;
 }
 dt.hdlist1.strong, td.hdlist1.strong {
  font-weight: bold;
 }
 td.hdlist1 {
  vertical-align: top;
  font-style: normal;
  padding-right: 0.8em;
  color: navy;
 }
 td.hdlist2 {
  vertical-align: top;
 }
 div.hdlist.compact tr {
  margin: 0;
  padding-bottom: 0;
 }

 .comment {
  background: yellow;
 }

 .footnote, .footnoteref {
  font-size: 0.8em;
 }

 span.footnote, span.footnoteref {
  vertical-align: super;
 }

 #footnotes {
  margin: 20px 0 20px 0;
  padding: 7px 0 0 0;
 }

 #footnotes div.footnote {
  margin: 0 0 5px 0;
 }

 #footnotes hr {
  border: none;
  border-top: 1px solid silver;
  height: 1px;
  text-align: left;
  margin-left: 0;
  width: 20%;
  min-width: 100px;
 }


 @media print {
  div#footer-badges { display: none; }
 }

 div#toc {
  margin-bottom: 2.5em;
 }

 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 {
  color: #527bbd;
  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-attribution {
  padding-top: 0.5em;
  text-align: right;
 }

 div.verseblock-content {
  white-space: pre;
 }
 div.verseblock-attribution {
  padding-top: 0.75em;
  text-align: left;
 }

 div.exampleblock-content {
  border-left: 3px solid #dddddd;
  padding-left: 0.5em;
 }

 /* IE6 sets dynamically generated links as visited. */
 div#toc a:visited { color: blue; }
 </style>
 <script type="text/javascript">
 /*<![CDATA[*/
 window.onload = function(){asciidoc.footnotes();}
 var asciidoc = { // Namespace.

 /////////////////////////////////////////////////////////////////////
 // Table Of Contents generator
 /////////////////////////////////////////////////////////////////////

 /* Author: Mihai Bazon, September 2002
  * http://students.infoiasi.ro/~mishoo
  *
  * Table Of Content generator
  * Version: 0.4
  *
  * Feel free to use this script under the terms of the GNU General Public
  * License, as long as you do not remove or alter this notice.
  */

  /* modified by Troy D. Hanson, September 2006. License: GPL */
  /* modified by Stuart Rackham, 2006, 2009. License: GPL */

 // toclevels = 1..4.
 toc: function (toclevels) {

  function getText(el) {
  var text = "";
  for (var i = el.firstChild; i != null; i = i.nextSibling) {
  if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
  text += i.data;
  else if (i.firstChild != null)
  text += getText(i);
  }
  return text;
  }

  function TocEntry(el, text, toclevel) {
  this.element = el;
  this.text = text;
  this.toclevel = toclevel;
  }

  function tocEntries(el, toclevels) {
  var result = new Array;
  var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
  // Function that scans the DOM tree for header elements (the DOM2
  // nodeIterator API would be a better technique but not supported by all
  // browsers).
  var iterate = function (el) {
  for (var i = el.firstChild; i != null; i = i.nextSibling) {
  if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
  var mo = re.exec(i.tagName);
  if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
  result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
  }
  iterate(i);
  }
  }
  }
  iterate(el);
  return result;
  }

  var toc = document.getElementById("toc");
  var entries = tocEntries(document.getElementById("content"), toclevels);
  for (var i = 0; i < entries.length; ++i) {
  var entry = entries[i];
  if (entry.element.id == "")
  entry.element.id = "_toc_" + i;
  var a = document.createElement("a");
  a.href = "#" + entry.element.id;
  a.appendChild(document.createTextNode(entry.text));
  var div = document.createElement("div");
  div.appendChild(a);
  div.className = "toclevel" + entry.toclevel;
  toc.appendChild(div);
  }
  if (entries.length == 0)
  toc.parentNode.removeChild(toc);
 },


 /////////////////////////////////////////////////////////////////////
 // Footnotes generator
 /////////////////////////////////////////////////////////////////////

 /* Based on footnote generation code from:
  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
  */

 footnotes: function () {
  var cont = document.getElementById("content");
  var noteholder = document.getElementById("footnotes");
  var spans = cont.getElementsByTagName("span");
  var refs = {};
  var n = 0;
  for (i=0; i<spans.length; i++) {
  if (spans[i].className == "footnote") {
  n++;
  // Use [\s\S] in place of . so multi-line matches work.
  // Because JavaScript has no s (dotall) regex flag.
  note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
  noteholder.innerHTML +=
  "<div class='footnote' id='_footnote_" + n + "'>" +
  "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
  n + "</a>. " + note + "</div>";
  spans[i].innerHTML =
  "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
  "' title='View footnote' class='footnote'>" + n + "</a>]";
  var id =spans[i].getAttribute("id");
  if (id != null) refs["#"+id] = n;
  }
  }
  if (n == 0)
  noteholder.parentNode.removeChild(noteholder);
  else {
  // Process footnoterefs.
  for (i=0; i<spans.length; i++) {
  if (spans[i].className == "footnoteref") {
  var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
  href = href.match(/#.*/)[0]; // Because IE return full URL.
  n = refs[href];
  spans[i].innerHTML =
  "[<a href='#_footnote_" + n +
  "' title='View footnote' class='footnote'>" + n + "</a>]";
  }
  }
  }
 }

 }
 /*]]>*/
 </script>
 </head>
 <body>
 <div id="header">
 <h1>diff API</h1>
 </div>
 <div id="content">
 <div id="preamble">
 <div class="sectionbody">
 <div class="paragraph"><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="ulist"><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="ulist"><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_unmerge()</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="ulist"><ul>
 <li>
 <p>
 <tt>struct diff_filespec</tt>
 </p>
 </li>
 </ul></div>
 <div class="paragraph"><p>This is the internal representation for a single file (blob). It
 records the blob object name (if known&#8201;&#8212;&#8201;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_unmerge()</tt> synthesize and
 feed <tt>diff_queue()</tt> function with.</p></div>
 <div class="ulist"><ul>
 <li>
 <p>
 <tt>struct diff_filepair</tt>
 </p>
 </li>
 </ul></div>
 <div class="paragraph"><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="paragraph"><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="ulist"><ul>
 <li>
 <p>
 <tt>struct diff_queue</tt>
 </p>
 </li>
 </ul></div>
 <div class="paragraph"><p>This is a collection of filepairs. Notable members are:</p></div>
 <div class="dlist"><dl>
 <dt class="hdlist1">
 <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 class="hdlist1">
 <tt>alloc</tt>
 </dt>
 <dd>
 <p>
  The allocated size of the <tt>queue</tt> array;
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>nr</tt>
 </dt>
 <dd>
 <p>
  The number of elements in the <tt>queue</tt> array.
 </p>
 <div class="ulist"><ul>
 <li>
 <p>
 <tt>struct diff_options</tt>
 </p>
 </li>
 </ul></div>
 </dd>
 </dl></div>
 <div class="paragraph"><p>This describes the set of options the calling program wants to affect
 the operation of diffcore library with.</p></div>
 <div class="paragraph"><p>Notable members are:</p></div>
 <div class="dlist"><dl>
 <dt class="hdlist1">
 <tt>output_format</tt>
 </dt>
 <dd>
 <p>
  The output format used when <tt>diff_flush()</tt> is run.
 </p>
 </dd>
 <dt class="hdlist1">
 <tt>context</tt>
 </dt>
 <dd>
 <p>
  Number of context lines to generate in patch output.
 </p>
 </dd>
 <dt class="hdlist1">
 <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 class="hdlist1">
 <tt>abbrev</tt>
 </dt>
 <dd>
 <p>
  Number of hexdigits to abbreviate raw format output to.
 </p>
 </dd>
 <dt class="hdlist1">
 <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 class="hdlist1">
 <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="dlist"><dl>
 <dt class="hdlist1">
 BINARY, TEXT
 </dt>
 <dd>
 <p>
  Affects the way how a file that is seemingly binary is treated.
 </p>
 </dd>
 <dt class="hdlist1">
 FULL_INDEX
 </dt>
 <dd>
 <p>
  Tells the patch output format not to use abbreviated object
  names on the "index" lines.
 </p>
 </dd>
 <dt class="hdlist1">
 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 class="hdlist1">
 COLOR_DIFF
 </dt>
 <dd>
 <p>
  Output should be colored.
 </p>
 </dd>
 <dt class="hdlist1">
 COLOR_DIFF_WORDS
 </dt>
 <dd>
 <p>
  Output is a colored word-diff.
 </p>
 </dd>
 <dt class="hdlist1">
 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 class="hdlist1">
 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 class="hdlist1">
 QUIET
 </dt>
 <dd>
 <p>
  Do not show any output.
 </p>
 </dd>
 <dt class="hdlist1">
 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 class="hdlist1">
 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 class="hdlist1">
 HAS_CHANGES
 </dt>
 <dd>
 <p>
  Internal; used for optimization to see if there is any change.
 </p>
 </dd>
 <dt class="hdlist1">
 SILENT_ON_REMOVE
 </dt>
 <dd>
 <p>
  Affects if diff-files shows removed files.
 </p>
 </dd>
 <dt class="hdlist1">
 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="paragraph"><p>(JC)</p></div>
 </div>
 </div>
 <div id="footnotes"><hr /></div>
 <div id="footer">
 <div id="footer-text">
 Last updated 2011-09-21 23:01:14 PDT
 </div>
 </div>
 </body>
 </html>
	<!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.5.2" />
	<title>diff API</title>
	<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;
	color: navy;
	}

	strong {
	font-weight: bold;
	color: #083194;
	}

	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;
	}

	ul, ol, li > p {
	margin-top: 0;
	}

	pre {
	padding: 0;
	margin: 0;
	}

	span#author {
	color: #527bbd;
	font-family: sans-serif;
	font-weight: bold;
	font-size: 1.1em;
	}
	span#email {
	}
	span#revnumber, span#revdate, span#revremark {
	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 {
	margin-top: 1.5em;
	margin-bottom: 1.5em;
	}
	div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
	div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
	div.admonitionblock {
	margin-top: 1.0em;
	margin-bottom: 1.5em;
	}
	div.admonitionblock {
	margin-top: 2.0em;
	margin-bottom: 2.0em;
	margin-right: 10%;
	color: #606060;
	}

	div.content { /* Block element content. */
	padding: 0;
	}

	/* Block element titles. */
	div.title, caption.title {
	color: #527bbd;
	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 > div.content {
	border: 1px solid silver;
	background: #f4f4f4;
	padding: 0.5em;
	}

	div.quoteblock, div.verseblock {
	padding-left: 1.0em;
	margin-left: 1.0em;
	margin-right: 10%;
	border-left: 5px solid #dddddd;
	color: #777777;
	}

	div.quoteblock > div.attribution {
	padding-top: 0.5em;
	text-align: right;
	}

	div.verseblock > div.content {
	white-space: pre;
	}
	div.verseblock > div.attribution {
	padding-top: 0.75em;
	text-align: left;
	}
	/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
	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: 3px solid #dddddd;
	}

	div.exampleblock > div.content {
	border-left: 3px solid #dddddd;
	padding-left: 0.5em;
	}

	div.imageblock div.content { padding-left: 0; }
	span.image img { border-style: none; }
	a.image:visited { color: white; }

	dl {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	dt {
	margin-top: 0.5em;
	margin-bottom: 0;
	font-style: normal;
	color: navy;
	}
	dd > *:first-child {
	margin-top: 0.1em;
	}

	ul, ol {
	list-style-position: outside;
	}
	ol.arabic {
	list-style-type: decimal;
	}
	ol.loweralpha {
	list-style-type: lower-alpha;
	}
	ol.upperalpha {
	list-style-type: upper-alpha;
	}
	ol.lowerroman {
	list-style-type: lower-roman;
	}
	ol.upperroman {
	list-style-type: upper-roman;
	}

	div.compact ul, div.compact ol,
	div.compact p, div.compact p,
	div.compact div, div.compact div {
	margin-top: 0.1em;
	margin-bottom: 0.1em;
	}

	div.tableblock > table {
	border: 3px solid #527bbd;
	}
	thead, p.table.header {
	font-family: sans-serif;
	font-weight: bold;
	}
	tfoot {
	font-weight: bold;
	}
	td > div.verse {
	white-space: pre;
	}
	p.table {
	margin-top: 0;
	}
	/* Because the table frame attribute is overriden by CSS in most browsers. */
	div.tableblock > table[frame="void"] {
	border-style: none;
	}
	div.tableblock > table[frame="hsides"] {
	border-left-style: none;
	border-right-style: none;
	}
	div.tableblock > table[frame="vsides"] {
	border-top-style: none;
	border-bottom-style: none;
	}


	div.hdlist {
	margin-top: 0.8em;
	margin-bottom: 0.8em;
	}
	div.hdlist tr {
	padding-bottom: 15px;
	}
	dt.hdlist1.strong, td.hdlist1.strong {
	font-weight: bold;
	}
	td.hdlist1 {
	vertical-align: top;
	font-style: normal;
	padding-right: 0.8em;
	color: navy;
	}
	td.hdlist2 {
	vertical-align: top;
	}
	div.hdlist.compact tr {
	margin: 0;
	padding-bottom: 0;
	}

	.comment {
	background: yellow;
	}

	.footnote, .footnoteref {
	font-size: 0.8em;
	}

	span.footnote, span.footnoteref {
	vertical-align: super;
	}

	#footnotes {
	margin: 20px 0 20px 0;
	padding: 7px 0 0 0;
	}

	#footnotes div.footnote {
	margin: 0 0 5px 0;
	}

	#footnotes hr {
	border: none;
	border-top: 1px solid silver;
	height: 1px;
	text-align: left;
	margin-left: 0;
	width: 20%;
	min-width: 100px;
	}


	@media print {
	div#footer-badges { display: none; }
	}

	div#toc {
	margin-bottom: 2.5em;
	}

	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 {
	color: #527bbd;
	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-attribution {
	padding-top: 0.5em;
	text-align: right;
	}

	div.verseblock-content {
	white-space: pre;
	}
	div.verseblock-attribution {
	padding-top: 0.75em;
	text-align: left;
	}

	div.exampleblock-content {
	border-left: 3px solid #dddddd;
	padding-left: 0.5em;
	}

	/* IE6 sets dynamically generated links as visited. */
	div#toc a:visited { color: blue; }
	</style>
	<script type="text/javascript">
	/<![CDATA[/
	window.onload = function(){asciidoc.footnotes();}
	var asciidoc = { // Namespace.

	/////////////////////////////////////////////////////////////////////
	// Table Of Contents generator
	/////////////////////////////////////////////////////////////////////

	/* Author: Mihai Bazon, September 2002
	* http://students.infoiasi.ro/~mishoo
	*
	* Table Of Content generator
	* Version: 0.4
	*
	* Feel free to use this script under the terms of the GNU General Public
	* License, as long as you do not remove or alter this notice.
	*/

	/* modified by Troy D. Hanson, September 2006. License: GPL */
	/* modified by Stuart Rackham, 2006, 2009. License: GPL */

	// toclevels = 1..4.
	toc: function (toclevels) {

	function getText(el) {
	var text = "";
	for (var i = el.firstChild; i != null; i = i.nextSibling) {
	if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
	text += i.data;
	else if (i.firstChild != null)
	text += getText(i);
	}
	return text;
	}

	function TocEntry(el, text, toclevel) {
	this.element = el;
	this.text = text;
	this.toclevel = toclevel;
	}

	function tocEntries(el, toclevels) {
	var result = new Array;
	var re = new RegExp('[hH]([2-'+(toclevels+1)+'])');
	// Function that scans the DOM tree for header elements (the DOM2
	// nodeIterator API would be a better technique but not supported by all
	// browsers).
	var iterate = function (el) {
	for (var i = el.firstChild; i != null; i = i.nextSibling) {
	if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
	var mo = re.exec(i.tagName);
	if (mo && (i.getAttribute("class") \|\| i.getAttribute("className")) != "float") {
	result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
	}
	iterate(i);
	}
	}
	}
	iterate(el);
	return result;
	}

	var toc = document.getElementById("toc");
	var entries = tocEntries(document.getElementById("content"), toclevels);
	for (var i = 0; i < entries.length; ++i) {
	var entry = entries[i];
	if (entry.element.id == "")
	entry.element.id = "_toc_" + i;
	var a = document.createElement("a");
	a.href = "#" + entry.element.id;
	a.appendChild(document.createTextNode(entry.text));
	var div = document.createElement("div");
	div.appendChild(a);
	div.className = "toclevel" + entry.toclevel;
	toc.appendChild(div);
	}
	if (entries.length == 0)
	toc.parentNode.removeChild(toc);
	},


	/////////////////////////////////////////////////////////////////////
	// Footnotes generator
	/////////////////////////////////////////////////////////////////////

	/* Based on footnote generation code from:
	* http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
	*/

	footnotes: function () {
	var cont = document.getElementById("content");
	var noteholder = document.getElementById("footnotes");
	var spans = cont.getElementsByTagName("span");
	var refs = {};
	var n = 0;
	for (i=0; i<spans.length; i++) {
	if (spans[i].className == "footnote") {
	n++;
	// Use [\s\S] in place of . so multi-line matches work.
	// Because JavaScript has no s (dotall) regex flag.
	note = spans[i].innerHTML.match(/\s\[([\s\S])]\s*/)[1];
	noteholder.innerHTML +=
	"<div class='footnote' id='_footnote_" + n + "'>" +
	"<a href='#_footnoteref_" + n + "' title='Return to text'>" +
	n + "</a>. " + note + "</div>";
	spans[i].innerHTML =
	"[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
	"' title='View footnote' class='footnote'>" + n + "</a>]";
	var id =spans[i].getAttribute("id");
	if (id != null) refs["#"+id] = n;
	}
	}
	if (n == 0)
	noteholder.parentNode.removeChild(noteholder);
	else {
	// Process footnoterefs.
	for (i=0; i<spans.length; i++) {
	if (spans[i].className == "footnoteref") {
	var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
	href = href.match(/#.*/)[0]; // Because IE return full URL.
	n = refs[href];
	spans[i].innerHTML =
	"[<a href='#_footnote_" + n +
	"' title='View footnote' class='footnote'>" + n + "</a>]";
	}
	}
	}
	}

	}
	/]]>/
	</script>
	</head>
	<body>
	<div id="header">
	<h1>diff API</h1>
	</div>
	<div id="content">
	<div id="preamble">
	<div class="sectionbody">
	<div class="paragraph"><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="ulist"><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="ulist"><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_unmerge()</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="ulist"><ul>
	<li>
	<p>
	<tt>struct diff_filespec</tt>
	</p>
	</li>
	</ul></div>
	<div class="paragraph"><p>This is the internal representation for a single file (blob). It
	records the blob object name (if known — 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_unmerge()</tt> synthesize and
	feed <tt>diff_queue()</tt> function with.</p></div>
	<div class="ulist"><ul>
	<li>
	<p>
	<tt>struct diff_filepair</tt>
	</p>
	</li>
	</ul></div>
	<div class="paragraph"><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="paragraph"><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="ulist"><ul>
	<li>
	<p>
	<tt>struct diff_queue</tt>
	</p>
	</li>
	</ul></div>
	<div class="paragraph"><p>This is a collection of filepairs. Notable members are:</p></div>
	<div class="dlist"><dl>
	<dt class="hdlist1">
	<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 class="hdlist1">
	<tt>alloc</tt>
	</dt>
	<dd>
	<p>
	The allocated size of the <tt>queue</tt> array;
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>nr</tt>
	</dt>
	<dd>
	<p>
	The number of elements in the <tt>queue</tt> array.
	</p>
	<div class="ulist"><ul>
	<li>
	<p>
	<tt>struct diff_options</tt>
	</p>
	</li>
	</ul></div>
	</dd>
	</dl></div>
	<div class="paragraph"><p>This describes the set of options the calling program wants to affect
	the operation of diffcore library with.</p></div>
	<div class="paragraph"><p>Notable members are:</p></div>
	<div class="dlist"><dl>
	<dt class="hdlist1">
	<tt>output_format</tt>
	</dt>
	<dd>
	<p>
	The output format used when <tt>diff_flush()</tt> is run.
	</p>
	</dd>
	<dt class="hdlist1">
	<tt>context</tt>
	</dt>
	<dd>
	<p>
	Number of context lines to generate in patch output.
	</p>
	</dd>
	<dt class="hdlist1">
	<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 class="hdlist1">
	<tt>abbrev</tt>
	</dt>
	<dd>
	<p>
	Number of hexdigits to abbreviate raw format output to.
	</p>
	</dd>
	<dt class="hdlist1">
	<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 class="hdlist1">
	<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="dlist"><dl>
	<dt class="hdlist1">
	BINARY, TEXT
	</dt>
	<dd>
	<p>
	Affects the way how a file that is seemingly binary is treated.
	</p>
	</dd>
	<dt class="hdlist1">
	FULL_INDEX
	</dt>
	<dd>
	<p>
	Tells the patch output format not to use abbreviated object
	names on the "index" lines.
	</p>
	</dd>
	<dt class="hdlist1">
	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 class="hdlist1">
	COLOR_DIFF
	</dt>
	<dd>
	<p>
	Output should be colored.
	</p>
	</dd>
	<dt class="hdlist1">
	COLOR_DIFF_WORDS
	</dt>
	<dd>
	<p>
	Output is a colored word-diff.
	</p>
	</dd>
	<dt class="hdlist1">
	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 class="hdlist1">
	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 class="hdlist1">
	QUIET
	</dt>
	<dd>
	<p>
	Do not show any output.
	</p>
	</dd>
	<dt class="hdlist1">
	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 class="hdlist1">
	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 class="hdlist1">
	HAS_CHANGES
	</dt>
	<dd>
	<p>
	Internal; used for optimization to see if there is any change.
	</p>
	</dd>
	<dt class="hdlist1">
	SILENT_ON_REMOVE
	</dt>
	<dd>
	<p>
	Affects if diff-files shows removed files.
	</p>
	</dd>
	<dt class="hdlist1">
	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="paragraph"><p>(JC)</p></div>
	</div>
	</div>
	<div id="footnotes"><hr /></div>
	<div id="footer">
	<div id="footer-text">
	Last updated 2011-09-21 23:01:14 PDT
	</div>
	</div>
	</body>
	</html>