Autogenerated HTML docs for v1.5.5.1-357-g1af8b

diff --git a/git-add.html b/git-add.html
index a1fc8d07d5be92fb99463bbb4787757ce3c0f576..2de91ce2ff2f2ee3c83a507428d09e66097b466e 100644 (file)
--- a/git-add.html
+++ b/git-add.html
@@ -274,7 +274,7 @@ git-add(1) Manual Page
 <div class="sectionbody">\r
 <div class="verseblock">\r
 <div class="content"><em>git-add</em> [-n] [-v] [-f] [--interactive | -i] [--patch | -p] [-u] [--refresh]\r
-          [--] &lt;filepattern&gt;&#8230;</div></div>\r
+          [--ignore-errors] [--] &lt;filepattern&gt;&#8230;</div></div>\r
 </div>\r
 <h2>DESCRIPTION</h2>\r
 <div class="sectionbody">\r
@@ -384,6 +384,16 @@ commit.</p>
 </p>\r
 </dd>\r
 <dt>\r
+--ignore-errors\r
+</dt>\r
+<dd>\r
+<p>\r
+        If some files could not be added because of errors indexing\r
+        them, do not abort the operation, but continue adding the\r
+        others. The command shall still exit with non-zero status.\r
+</p>\r
+</dd>\r
+<dt>\r
 --\r
 </dt>\r
 <dd>\r
@@ -594,7 +604,7 @@ double-quote and control characters will still have problems.</p>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 09-May-2008 05:45:35 UTC\r
+Last updated 22-May-2008 00:52:45 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-add.txt b/git-add.txt
index e0e730b6c44d473ad6cc9a23f7b727ab818d63a5..bb4abe26bb5d12916e8f396e3b94573f42e37a29 100644 (file)
--- a/git-add.txt
+++ b/git-add.txt
@@ -9,7 +9,7 @@ SYNOPSIS
 --------
 [verse]
 'git-add' [-n] [-v] [-f] [--interactive | -i] [--patch | -p] [-u] [--refresh]
-          [--] <filepattern>...
+         [--ignore-errors] [--] <filepattern>...
 
 DESCRIPTION
 -----------
@@ -83,6 +83,11 @@ OPTIONS
        Don't add the file(s), but only refresh their stat()
        information in the index.
 
+\--ignore-errors::
+       If some files could not be added because of errors indexing
+       them, do not abort the operation, but continue adding the
+       others. The command shall still exit with non-zero status.
+
 \--::
        This option can be used to separate command-line options from
        the list of files, (useful when filenames might be mistaken

diff --git a/git-cvsexportcommit.html b/git-cvsexportcommit.html
index bdef20e79f01a22f52bee5bc73a3109e2944dc3b..d1d10b92a14fc504a7eddc29a169e5086c1dab54 100644 (file)
--- a/git-cvsexportcommit.html
+++ b/git-cvsexportcommit.html
@@ -368,7 +368,8 @@ should the changeset be done against.</p>
 <p>\r
         Specify the location of the CVS checkout to use for the export. This\r
         option does not require GIT_DIR to be set before execution if the\r
-        current directory is within a git repository.\r
+        current directory is within a git repository.  The default is the\r
+        value of <em>cvsexportcommit.cvsdir</em>.\r
 </p>\r
 </dd>\r
 <dt>\r
@@ -381,6 +382,19 @@ should the changeset be done against.</p>
 </dd>\r
 </dl>\r
 </div>\r
+<h2>CONFIGURATION</h2>\r
+<div class="sectionbody">\r
+<dl>\r
+<dt>\r
+cvsexportcommit.cvsdir\r
+</dt>\r
+<dd>\r
+<p>\r
+        The default location of the CVS checkout to use for the export.\r
+</p>\r
+</dd>\r
+</dl>\r
+</div>\r
 <h2>EXAMPLES</h2>\r
 <div class="sectionbody">\r
 <dl>\r
@@ -432,7 +446,7 @@ $ git-cherry cvshead myhead | sed -n 's/^+ //p' | xargs -l1 git-cvsexportcommit
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 07-Jan-2008 07:50:09 UTC\r
+Last updated 22-May-2008 00:52:45 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-cvsexportcommit.txt b/git-cvsexportcommit.txt
index 9a47b4c397cec8e6782962bfe6766eee48b78ce1..363c36d694231c5876527ff0d062fbd385d66630 100644 (file)
--- a/git-cvsexportcommit.txt
+++ b/git-cvsexportcommit.txt
@@ -65,11 +65,17 @@ OPTIONS
 -w::
        Specify the location of the CVS checkout to use for the export. This
        option does not require GIT_DIR to be set before execution if the
-       current directory is within a git repository.
+       current directory is within a git repository.  The default is the
+       value of 'cvsexportcommit.cvsdir'.
 
 -v::
        Verbose.
 
+CONFIGURATION
+-------------
+cvsexportcommit.cvsdir::
+       The default location of the CVS checkout to use for the export.
+
 EXAMPLES
 --------
 

diff --git a/git-daemon.html b/git-daemon.html
index 0e983efbc79ad1f8c99fa337bf99d2eac62fe04b..ad3e4bc8a7263c1592243db3c017c1f665fa7dee 100644 (file)
--- a/git-daemon.html
+++ b/git-daemon.html
@@ -545,7 +545,7 @@ upload-archive
 <p>\r
         This serves <tt>git-archive --remote</tt>.  It is disabled by\r
         default, but a repository can enable it by setting\r
-        <tt>daemon.uploadarchive</tt> configuration item to <tt>true</tt>.\r
+        <tt>daemon.uploadarch</tt> configuration item to <tt>true</tt>.\r
 </p>\r
 </dd>\r
 <dt>\r
@@ -656,7 +656,7 @@ selectively enable/disable services per repository
 <div class="content">\r
 <pre><tt>        [daemon]\r
                 uploadpack = false\r
-                uploadarchive = true</tt></pre>\r
+                uploadarch = true</tt></pre>\r
 </div></div>\r
 </dd>\r
 </dl>\r
@@ -676,7 +676,7 @@ selectively enable/disable services per repository
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 07-Jan-2008 07:50:11 UTC\r
+Last updated 22-May-2008 00:52:46 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-daemon.txt b/git-daemon.txt
index fd83bc7833312b20a7ef045a9dfd128fc2539838..cf261dd40d98a95d8eda4ee1008451ca67029bd3 100644 (file)
--- a/git-daemon.txt
+++ b/git-daemon.txt
@@ -174,7 +174,7 @@ upload-pack::
 upload-archive::
        This serves `git-archive --remote`.  It is disabled by
        default, but a repository can enable it by setting
-       `daemon.uploadarchive` configuration item to `true`.
+       `daemon.uploadarch` configuration item to `true`.
 
 receive-pack::
        This serves `git-send-pack` clients, allowing anonymous
@@ -257,7 +257,7 @@ selectively enable/disable services per repository::
 ----------------------------------------------------------------
        [daemon]
                uploadpack = false
-               uploadarchive = true
+               uploadarch = true
 ----------------------------------------------------------------
 
 

diff --git a/git-log.html b/git-log.html
index 1b7735aa47545bc1b2233559f72d4552e6f8a70b..45ab542d2e4ff2a47198006bbdc72535dcef6d64 100644 (file)
--- a/git-log.html
+++ b/git-log.html
@@ -945,6 +945,19 @@ format, often found in E-mail messages.</p>
         -xxxxxxx... 1st on a</tt></pre>\r
 </div></div>\r
 </dd>\r
+<dt>\r
+--graph\r
+</dt>\r
+<dd>\r
+<p>\r
+        Draw a text-based graphical representation of the commit history\r
+        on the left hand side of the output.  This may cause extra lines\r
+        to be printed in between commits, in order for the graph history\r
+        to be drawn properly.\r
+</p>\r
+<p>This implies the <em>--topo-order</em> option by default, but the\r
+<em>--date-order</em> option may also be specified.</p>\r
+</dd>\r
 </dl>\r
 <h3>Diff Formatting</h3>\r
 <p>Below are listed options that control the formatting of diff output.\r
@@ -1929,7 +1942,7 @@ reversible operation.</p>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 23-Apr-2008 16:08:37 UTC\r
+Last updated 22-May-2008 00:52:46 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-rev-list.html b/git-rev-list.html
index d05c4c405fd5b15a532d1d71a2ada45ff633bcfe..7a19b6dda1e294cda12cb9180313efce696f9ccf 100644 (file)
--- a/git-rev-list.html
+++ b/git-rev-list.html
@@ -475,6 +475,19 @@ format, often found in E-mail messages.</p>
         -xxxxxxx... 1st on a</tt></pre>\r
 </div></div>\r
 </dd>\r
+<dt>\r
+--graph\r
+</dt>\r
+<dd>\r
+<p>\r
+        Draw a text-based graphical representation of the commit history\r
+        on the left hand side of the output.  This may cause extra lines\r
+        to be printed in between commits, in order for the graph history\r
+        to be drawn properly.\r
+</p>\r
+<p>This implies the <em>--topo-order</em> option by default, but the\r
+<em>--date-order</em> option may also be specified.</p>\r
+</dd>\r
 </dl>\r
 <h3>Diff Formatting</h3>\r
 <p>Below are listed options that control the formatting of diff output.\r
@@ -1211,7 +1224,7 @@ and the git-list &lt;git@vger.kernel.org&gt;.</p>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 09-Apr-2008 09:38:27 UTC\r
+Last updated 22-May-2008 00:52:46 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-rev-parse.html b/git-rev-parse.html
index b3f7a956b4bf9c1607a19493a6b69a187aa84879..527597bdb0ffe40aaa32c715e26a6af5b1e69a4e 100644 (file)
--- a/git-rev-parse.html
+++ b/git-rev-parse.html
@@ -851,6 +851,40 @@ C?        option C with an optional argument"
 eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?`</tt></pre>\r
 </div></div>\r
 </div>\r
+<h2>EXAMPLES</h2>\r
+<div class="sectionbody">\r
+<ul>\r
+<li>\r
+<p>\r
+Print the object name of the current commit:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git rev-parse --verify HEAD</tt></pre>\r
+</div></div>\r
+</li>\r
+<li>\r
+<p>\r
+Print the commit object name from the revision in the $REV shell variable:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git rev-parse --verify $REV</tt></pre>\r
+</div></div>\r
+<p>This will error out if $REV is empty or not a valid revision.</p>\r
+</li>\r
+<li>\r
+<p>\r
+Same as above:\r
+</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>$ git rev-parse --default master --verify $REV</tt></pre>\r
+</div></div>\r
+<p>but if $REV is empty, the commit object name from master will be printed.</p>\r
+</li>\r
+</ul>\r
+</div>\r
 <h2>Author</h2>\r
 <div class="sectionbody">\r
 <p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt; .\r
@@ -866,7 +900,7 @@ Junio C Hamano &lt;junkio@cox.net&gt; and Pierre Habouzit &lt;madcoder@debian.or
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 14-May-2008 22:24:42 UTC\r
+Last updated 22-May-2008 00:52:47 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-rev-parse.txt b/git-rev-parse.txt
index b6b2fe92a15bcb3ea314e5411e957e41e67904d8..69599ffb679b17ebbe6ba85c772cd10a3511d89e 100644 (file)
--- a/git-rev-parse.txt
+++ b/git-rev-parse.txt
@@ -378,6 +378,31 @@ C?        option C with an optional argument"
 eval `echo "$OPTS_SPEC" | git-rev-parse --parseopt -- "$@" || echo exit $?`
 ------------
 
+EXAMPLES
+--------
+
+* Print the object name of the current commit:
++
+------------
+$ git rev-parse --verify HEAD
+------------
+
+* Print the commit object name from the revision in the $REV shell variable:
++
+------------
+$ git rev-parse --verify $REV
+------------
++
+This will error out if $REV is empty or not a valid revision.
+
+* Same as above:
++
+------------
+$ git rev-parse --default master --verify $REV
+------------
++
+but if $REV is empty, the commit object name from master will be printed.
+
 
 Author
 ------

diff --git a/git-svn.html b/git-svn.html
index 2db4ab83d29fdca410df684a3fbceba923964ad3..6cebaf7eeecae9af19ec0ef26abb3b93eed42b6b 100644 (file)
--- a/git-svn.html
+++ b/git-svn.html
@@ -625,7 +625,8 @@ environment). This command has the same behaviour.</td>
 <p>\r
         Recursively finds the svn:ignore property on directories and\r
         creates matching .gitignore files. The resulting files are staged to\r
-        be committed, but are not committed.\r
+        be committed, but are not committed. Use -r/--revision to refer to a\r
+        specfic revision.\r
 </p>\r
 </dd>\r
 <dt>\r
@@ -665,6 +666,34 @@ environment). This command has the same behaviour.</td>
         <em>URL:</em> field.\r
 </p>\r
 </dd>\r
+<dt>\r
+<em>proplist</em>\r
+</dt>\r
+<dd>\r
+<p>\r
+        Lists the properties stored in the Subversion repository about a\r
+        given file or directory.  Use -r/--revision to refer to a specific\r
+        Subversion revision.\r
+</p>\r
+</dd>\r
+<dt>\r
+<em>propget</em>\r
+</dt>\r
+<dd>\r
+<p>\r
+        Gets the Subversion property given as the first argument, for a\r
+        file.  A specific revision can be specified with -r/--revision.\r
+</p>\r
+</dd>\r
+<dt>\r
+<em>show-externals</em>\r
+</dt>\r
+<dd>\r
+<p>\r
+        Shows the Subversion externals.  Use -r/--revision to specify a\r
+        specific revision.\r
+</p>\r
+</dd>\r
 </dl>\r
 </div>\r
 <h2>OPTIONS</h2>\r
@@ -1120,7 +1149,7 @@ should be manually entered with a text-editor or using
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 12-May-2008 00:29:22 UTC\r
+Last updated 22-May-2008 00:52:47 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/git-svn.txt b/git-svn.txt
index c6b56b4ef35879124f9e1bb8468a59761d09cb3b..3eae1ebb7dc104fd51c5e25d163ec33ab7b61ef1 100644 (file)
--- a/git-svn.txt
+++ b/git-svn.txt
@@ -196,10 +196,10 @@ Any other arguments are passed directly to `git log'
        independently of git-svn functions.
 
 'create-ignore'::
-
        Recursively finds the svn:ignore property on directories and
        creates matching .gitignore files. The resulting files are staged to
-       be committed, but are not committed.
+       be committed, but are not committed. Use -r/--revision to refer to a
+       specfic revision.
 
 'show-ignore'::
        Recursively finds and lists the svn:ignore property on
@@ -223,6 +223,19 @@ Any other arguments are passed directly to `git log'
        argument.  Use the --url option to output only the value of the
        'URL:' field.
 
+'proplist'::
+       Lists the properties stored in the Subversion repository about a
+       given file or directory.  Use -r/--revision to refer to a specific
+       Subversion revision.
+
+'propget'::
+       Gets the Subversion property given as the first argument, for a
+       file.  A specific revision can be specified with -r/--revision.
+
+'show-externals'::
+       Shows the Subversion externals.  Use -r/--revision to specify a
+       specific revision.
+
 --
 
 OPTIONS

diff --git a/rev-list-options.txt b/rev-list-options.txt
index 2648a550850bf07128e4a0a14c82860d6bad17b8..ce6a1017a34aed25efc192e889a9f04adb5aa2f3 100644 (file)
--- a/rev-list-options.txt
+++ b/rev-list-options.txt
@@ -75,6 +75,16 @@ you would get an output line this:
        -xxxxxxx... 1st on a
 -----------------------------------------------------------------------
 
+--graph::
+
+       Draw a text-based graphical representation of the commit history
+       on the left hand side of the output.  This may cause extra lines
+       to be printed in between commits, in order for the graph history
+       to be drawn properly.
++
+This implies the '--topo-order' option by default, but the
+'--date-order' option may also be specified.
+
 Diff Formatting
 ~~~~~~~~~~~~~~~
 

diff --git a/technical/api-history-graph.html b/technical/api-history-graph.html
new file mode 100644 (file)
index 0000000..a0e0231
--- /dev/null
+++ b/technical/api-history-graph.html
@@ -0,0 +1,508 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"\r
+    "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">\r
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">\r
+<head>\r
+<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />\r
+<meta name="generator" content="AsciiDoc 7.0.2" />\r
+<style type="text/css">\r
+/* Debug borders */\r
+p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {\r
+/*\r
+  border: 1px solid red;\r
+*/\r
+}\r
+\r
+body {\r
+  margin: 1em 5% 1em 5%;\r
+}\r
+\r
+a { color: blue; }\r
+a:visited { color: fuchsia; }\r
+\r
+em {\r
+  font-style: italic;\r
+}\r
+\r
+strong {\r
+  font-weight: bold;\r
+}\r
+\r
+tt {\r
+  color: navy;\r
+}\r
+\r
+h1, h2, h3, h4, h5, h6 {\r
+  color: #527bbd;\r
+  font-family: sans-serif;\r
+  margin-top: 1.2em;\r
+  margin-bottom: 0.5em;\r
+  line-height: 1.3;\r
+}\r
+\r
+h1 {\r
+  border-bottom: 2px solid silver;\r
+}\r
+h2 {\r
+  border-bottom: 2px solid silver;\r
+  padding-top: 0.5em;\r
+}\r
+\r
+div.sectionbody {\r
+  font-family: serif;\r
+  margin-left: 0;\r
+}\r
+\r
+hr {\r
+  border: 1px solid silver;\r
+}\r
+\r
+p {\r
+  margin-top: 0.5em;\r
+  margin-bottom: 0.5em;\r
+}\r
+\r
+pre {\r
+  padding: 0;\r
+  margin: 0;\r
+}\r
+\r
+span#author {\r
+  color: #527bbd;\r
+  font-family: sans-serif;\r
+  font-weight: bold;\r
+  font-size: 1.2em;\r
+}\r
+span#email {\r
+}\r
+span#revision {\r
+  font-family: sans-serif;\r
+}\r
+\r
+div#footer {\r
+  font-family: sans-serif;\r
+  font-size: small;\r
+  border-top: 2px solid silver;\r
+  padding-top: 0.5em;\r
+  margin-top: 4.0em;\r
+}\r
+div#footer-text {\r
+  float: left;\r
+  padding-bottom: 0.5em;\r
+}\r
+div#footer-badges {\r
+  float: right;\r
+  padding-bottom: 0.5em;\r
+}\r
+\r
+div#preamble,\r
+div.tableblock, div.imageblock, div.exampleblock, div.verseblock,\r
+div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,\r
+div.admonitionblock {\r
+  margin-right: 10%;\r
+  margin-top: 1.5em;\r
+  margin-bottom: 1.5em;\r
+}\r
+div.admonitionblock {\r
+  margin-top: 2.5em;\r
+  margin-bottom: 2.5em;\r
+}\r
+\r
+div.content { /* Block element content. */\r
+  padding: 0;\r
+}\r
+\r
+/* Block element titles. */\r
+div.title, caption.title {\r
+  font-family: sans-serif;\r
+  font-weight: bold;\r
+  text-align: left;\r
+  margin-top: 1.0em;\r
+  margin-bottom: 0.5em;\r
+}\r
+div.title + * {\r
+  margin-top: 0;\r
+}\r
+\r
+td div.title:first-child {\r
+  margin-top: 0.0em;\r
+}\r
+div.content div.title:first-child {\r
+  margin-top: 0.0em;\r
+}\r
+div.content + div.title {\r
+  margin-top: 0.0em;\r
+}\r
+\r
+div.sidebarblock > div.content {\r
+  background: #ffffee;\r
+  border: 1px solid silver;\r
+  padding: 0.5em;\r
+}\r
+\r
+div.listingblock > div.content {\r
+  border: 1px solid silver;\r
+  background: #f4f4f4;\r
+  padding: 0.5em;\r
+}\r
+\r
+div.quoteblock > div.content {\r
+  padding-left: 2.0em;\r
+}\r
+div.quoteblock .attribution {\r
+  text-align: right;\r
+}\r
+\r
+div.admonitionblock .icon {\r
+  vertical-align: top;\r
+  font-size: 1.1em;\r
+  font-weight: bold;\r
+  text-decoration: underline;\r
+  color: #527bbd;\r
+  padding-right: 0.5em;\r
+}\r
+div.admonitionblock td.content {\r
+  padding-left: 0.5em;\r
+  border-left: 2px solid silver;\r
+}\r
+\r
+div.exampleblock > div.content {\r
+  border-left: 2px solid silver;\r
+  padding: 0.5em;\r
+}\r
+\r
+div.verseblock div.content {\r
+  white-space: pre;\r
+}\r
+\r
+div.imageblock div.content { padding-left: 0; }\r
+div.imageblock img { border: 1px solid silver; }\r
+span.image img { border-style: none; }\r
+\r
+dl {\r
+  margin-top: 0.8em;\r
+  margin-bottom: 0.8em;\r
+}\r
+dt {\r
+  margin-top: 0.5em;\r
+  margin-bottom: 0;\r
+  font-style: italic;\r
+}\r
+dd > *:first-child {\r
+  margin-top: 0;\r
+}\r
+\r
+ul, ol {\r
+    list-style-position: outside;\r
+}\r
+ol.olist2 {\r
+  list-style-type: lower-alpha;\r
+}\r
+\r
+div.tableblock > table {\r
+  border-color: #527bbd;\r
+  border-width: 3px;\r
+}\r
+thead {\r
+  font-family: sans-serif;\r
+  font-weight: bold;\r
+}\r
+tfoot {\r
+  font-weight: bold;\r
+}\r
+\r
+div.hlist {\r
+  margin-top: 0.8em;\r
+  margin-bottom: 0.8em;\r
+}\r
+td.hlist1 {\r
+  vertical-align: top;\r
+  font-style: italic;\r
+  padding-right: 0.8em;\r
+}\r
+td.hlist2 {\r
+  vertical-align: top;\r
+}\r
+\r
+@media print {\r
+  div#footer-badges { display: none; }\r
+}\r
+/* Workarounds for IE6's broken and incomplete CSS2. */\r
+\r
+div.sidebar-content {\r
+  background: #ffffee;\r
+  border: 1px solid silver;\r
+  padding: 0.5em;\r
+}\r
+div.sidebar-title, div.image-title {\r
+  font-family: sans-serif;\r
+  font-weight: bold;\r
+  margin-top: 0.0em;\r
+  margin-bottom: 0.5em;\r
+}\r
+\r
+div.listingblock div.content {\r
+  border: 1px solid silver;\r
+  background: #f4f4f4;\r
+  padding: 0.5em;\r
+}\r
+\r
+div.quoteblock-content {\r
+  padding-left: 2.0em;\r
+}\r
+\r
+div.exampleblock-content {\r
+  border-left: 2px solid silver;\r
+  padding-left: 0.5em;\r
+}\r
+</style>\r
+<title>history graph API</title>\r
+</head>\r
+<body>\r
+<div id="header">\r
+<h1>history graph API</h1>\r
+</div>\r
+<div id="preamble">\r
+<div class="sectionbody">\r
+<p>The graph API is used to draw a text-based representation of the commit\r
+history.  The API generates the graph in a line-by-line fashion.</p>\r
+</div>\r
+</div>\r
+<h2>Functions</h2>\r
+<div class="sectionbody">\r
+<p>Core functions:</p>\r
+<ul>\r
+<li>\r
+<p>\r
+<tt>graph_init()</tt> creates a new <tt>struct git_graph</tt>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_release()</tt> destroys a <tt>struct git_graph</tt>, and frees the memory\r
+  associated with it.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_update()</tt> moves the graph to a new commit.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_next_line()</tt> outputs the next line of the graph into a strbuf.  It\r
+  does not add a terminating newline.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_padding_line()</tt> outputs a line of vertical padding in the graph.  It\r
+  is similar to <tt>graph_next_line()</tt>, but is guaranteed to never print the line\r
+  containing the current commit.  Where <tt>graph_next_line()</tt> would print the\r
+  commit line next, <tt>graph_padding_line()</tt> prints a line that simply extends\r
+  all branch lines downwards one row, leaving their positions unchanged.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_is_commit_finished()</tt> determines if the graph has output all lines\r
+  necessary for the current commit.  If <tt>graph_update()</tt> is called before all\r
+  lines for the current commit have been printed, the next call to\r
+  <tt>graph_next_line()</tt> will output an ellipsis, to indicate that a portion of\r
+  the graph was omitted.\r
+</p>\r
+</li>\r
+</ul>\r
+<p>The following utility functions are wrappers around <tt>graph_next_line()</tt> and\r
+<tt>graph_is_commit_finished()</tt>.  They always print the output to stdout.\r
+They can all be called with a NULL graph argument, in which case no graph\r
+output will be printed.</p>\r
+<ul>\r
+<li>\r
+<p>\r
+<tt>graph_show_commit()</tt> calls <tt>graph_next_line()</tt> until it returns non-zero.\r
+  This prints all graph lines up to, and including, the line containing this\r
+  commit.  Output is printed to stdout.  The last line printed does not contain\r
+  a terminating newline.  This should not be called if the commit line has\r
+  already been printed, or it will loop forever.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_show_oneline()</tt> calls <tt>graph_next_line()</tt> and prints the result to\r
+  stdout.  The line printed does not contain a terminating newline.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_show_padding()</tt> calls <tt>graph_padding_line()</tt> and prints the result to\r
+  stdout.  The line printed does not contain a terminating newline.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_show_remainder()</tt> calls <tt>graph_next_line()</tt> until\r
+  <tt>graph_is_commit_finished()</tt> returns non-zero.  Output is printed to stdout.\r
+  The last line printed does not contain a terminating newline.  Returns 1 if\r
+  output was printed, and 0 if no output was necessary.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_show_strbuf()</tt> prints the specified strbuf to stdout, prefixing all\r
+  lines but the first with a graph line.  The caller is responsible for\r
+  ensuring graph output for the first line has already been printed to stdout.\r
+  (This can be done with <tt>graph_show_commit()</tt> or <tt>graph_show_oneline()</tt>.)  If\r
+  a NULL graph is supplied, the strbuf is printed as-is.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_show_commit_msg()</tt> is similar to <tt>graph_show_strbuf()</tt>, but it also\r
+  prints the remainder of the graph, if more lines are needed after the strbuf\r
+  ends.  It is better than directly calling <tt>graph_show_strbuf()</tt> followed by\r
+  <tt>graph_show_remainder()</tt> since it properly handles buffers that do not end in\r
+  a terminating newline.  The output printed by <tt>graph_show_commit_msg()</tt> will\r
+  end in a newline if and only if the strbuf ends in a newline.\r
+</p>\r
+</li>\r
+</ul>\r
+</div>\r
+<h2>Data structure</h2>\r
+<div class="sectionbody">\r
+<p><tt>struct git_graph</tt> is an opaque data type used to store the current graph\r
+state.</p>\r
+</div>\r
+<h2>Calling sequence</h2>\r
+<div class="sectionbody">\r
+<ul>\r
+<li>\r
+<p>\r
+Create a <tt>struct git_graph</tt> by calling <tt>graph_init()</tt>.  When using the\r
+  revision walking API, this is done automatically by <tt>setup_revisions()</tt> if\r
+  the <em>&#8212;graph</em> option is supplied.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+Use the revision walking API to walk through a group of contiguous commits.\r
+  The <tt>get_revision()</tt> function automatically calls <tt>graph_update()</tt> each time\r
+  it is invoked.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+For each commit, call <tt>graph_next_line()</tt> repeatedly, until\r
+  <tt>graph_is_commit_finished()</tt> returns non-zero.  Each call go\r
+  <tt>graph_next_line()</tt> will output a single line of the graph.  The resulting\r
+  lines will not contain any newlines.  <tt>graph_next_line()</tt> returns 1 if the\r
+  resulting line contains the current commit, or 0 if this is merely a line\r
+  needed to adjust the graph before or after the current commit.  This return\r
+  value can be used to determine where to print the commit summary information\r
+  alongside the graph output.\r
+</p>\r
+</li>\r
+</ul>\r
+</div>\r
+<h2>Limitations</h2>\r
+<div class="sectionbody">\r
+<ul>\r
+<li>\r
+<p>\r
+<tt>graph_update()</tt> must be called with commits in topological order.  It should\r
+  not be called on a commit if it has already been invoked with an ancestor of\r
+  that commit, or the graph output will be incorrect.\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
+<tt>graph_update()</tt> must be called on a contiguous group of commits.  If\r
+  <tt>graph_update()</tt> is called on a particular commit, it should later be called\r
+  on all parents of that commit.  Parents must not be skipped, or the graph\r
+  output will appear incorrect.\r
+</p>\r
+<p><tt>graph_update()</tt> may be used on a pruned set of commits only if the parent list\r
+has been rewritten so as to include only ancestors from the pruned set.</p>\r
+</li>\r
+<li>\r
+<p>\r
+The graph API does not currently support reverse commit ordering.  In\r
+  order to implement reverse ordering, the graphing API needs an\r
+  (efficient) mechanism to find the children of a commit.\r
+</p>\r
+</li>\r
+</ul>\r
+</div>\r
+<h2>Sample usage</h2>\r
+<div class="sectionbody">\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>struct commit *commit;\r
+struct git_graph *graph = graph_init();\r
+\r
+while ((commit = get_revision(opts)) != NULL) {\r
+        graph_update(graph, commit);\r
+        while (!graph_is_commit_finished(graph))\r
+        {\r
+                struct strbuf sb;\r
+                int is_commit_line;\r
+\r
+                strbuf_init(&amp;sb, 0);\r
+                is_commit_line = graph_next_line(graph, &amp;sb);\r
+                fputs(sb.buf, stdout);\r
+\r
+                if (is_commit_line)\r
+                        log_tree_commit(opts, commit);\r
+                else\r
+                        putchar(opts-&gt;diffopt.line_termination);\r
+        }\r
+}\r
+\r
+graph_release(graph);</tt></pre>\r
+</div></div>\r
+</div>\r
+<h2>Sample output</h2>\r
+<div class="sectionbody">\r
+<p>The following is an example of the output from the graph API.  This output does\r
+not include any commit summary information&#8212;callers are responsible for\r
+outputting that information, if desired.</p>\r
+<div class="listingblock">\r
+<div class="content">\r
+<pre><tt>*\r
+*\r
+M\r
+|\\r
+* |\r
+| | *\r
+| \ \\r
+|  \ \\r
+M-. \ \\r
+|\ \ \ \\r
+| | * | |\r
+| | | | | *\r
+| | | | | *\r
+| | | | | M\r
+| | | | | |\\r
+| | | | | | *\r
+| * | | | | |\r
+| | | | | M  \\r
+| | | | | |\  |\r
+| | | | * | | |\r
+| | | | * | | |\r
+* | | | | | | |\r
+| |/ / / / / /\r
+|/| / / / / /\r
+* | | | | | |\r
+|/ / / / / /\r
+* | | | | |\r
+| | | | | *\r
+| | | | |/\r
+| | | | *</tt></pre>\r
+</div></div>\r
+</div>\r
+<div id="footer">\r
+<div id="footer-text">\r
+Last updated 22-May-2008 00:52:48 UTC\r
+</div>\r
+</div>\r
+</body>\r
+</html>\r

diff --git a/technical/api-history-graph.txt b/technical/api-history-graph.txt
new file mode 100644 (file)
index 0000000..ce1c08e
--- /dev/null
+++ b/technical/api-history-graph.txt
@@ -0,0 +1,179 @@
+history graph API
+=================
+
+The graph API is used to draw a text-based representation of the commit
+history.  The API generates the graph in a line-by-line fashion.
+
+Functions
+---------
+
+Core functions:
+
+* `graph_init()` creates a new `struct git_graph`
+
+* `graph_release()` destroys a `struct git_graph`, and frees the memory
+  associated with it.
+
+* `graph_update()` moves the graph to a new commit.
+
+* `graph_next_line()` outputs the next line of the graph into a strbuf.  It
+  does not add a terminating newline.
+
+* `graph_padding_line()` outputs a line of vertical padding in the graph.  It
+  is similar to `graph_next_line()`, but is guaranteed to never print the line
+  containing the current commit.  Where `graph_next_line()` would print the
+  commit line next, `graph_padding_line()` prints a line that simply extends
+  all branch lines downwards one row, leaving their positions unchanged.
+
+* `graph_is_commit_finished()` determines if the graph has output all lines
+  necessary for the current commit.  If `graph_update()` is called before all
+  lines for the current commit have been printed, the next call to
+  `graph_next_line()` will output an ellipsis, to indicate that a portion of
+  the graph was omitted.
+
+The following utility functions are wrappers around `graph_next_line()` and
+`graph_is_commit_finished()`.  They always print the output to stdout.
+They can all be called with a NULL graph argument, in which case no graph
+output will be printed.
+
+* `graph_show_commit()` calls `graph_next_line()` until it returns non-zero.
+  This prints all graph lines up to, and including, the line containing this
+  commit.  Output is printed to stdout.  The last line printed does not contain
+  a terminating newline.  This should not be called if the commit line has
+  already been printed, or it will loop forever.
+
+* `graph_show_oneline()` calls `graph_next_line()` and prints the result to
+  stdout.  The line printed does not contain a terminating newline.
+
+* `graph_show_padding()` calls `graph_padding_line()` and prints the result to
+  stdout.  The line printed does not contain a terminating newline.
+
+* `graph_show_remainder()` calls `graph_next_line()` until
+  `graph_is_commit_finished()` returns non-zero.  Output is printed to stdout.
+  The last line printed does not contain a terminating newline.  Returns 1 if
+  output was printed, and 0 if no output was necessary.
+
+* `graph_show_strbuf()` prints the specified strbuf to stdout, prefixing all
+  lines but the first with a graph line.  The caller is responsible for
+  ensuring graph output for the first line has already been printed to stdout.
+  (This can be done with `graph_show_commit()` or `graph_show_oneline()`.)  If
+  a NULL graph is supplied, the strbuf is printed as-is.
+
+* `graph_show_commit_msg()` is similar to `graph_show_strbuf()`, but it also
+  prints the remainder of the graph, if more lines are needed after the strbuf
+  ends.  It is better than directly calling `graph_show_strbuf()` followed by
+  `graph_show_remainder()` since it properly handles buffers that do not end in
+  a terminating newline.  The output printed by `graph_show_commit_msg()` will
+  end in a newline if and only if the strbuf ends in a newline.
+
+Data structure
+--------------
+`struct git_graph` is an opaque data type used to store the current graph
+state.
+
+Calling sequence
+----------------
+
+* Create a `struct git_graph` by calling `graph_init()`.  When using the
+  revision walking API, this is done automatically by `setup_revisions()` if
+  the '--graph' option is supplied.
+
+* Use the revision walking API to walk through a group of contiguous commits.
+  The `get_revision()` function automatically calls `graph_update()` each time
+  it is invoked.
+
+* For each commit, call `graph_next_line()` repeatedly, until
+  `graph_is_commit_finished()` returns non-zero.  Each call go
+  `graph_next_line()` will output a single line of the graph.  The resulting
+  lines will not contain any newlines.  `graph_next_line()` returns 1 if the
+  resulting line contains the current commit, or 0 if this is merely a line
+  needed to adjust the graph before or after the current commit.  This return
+  value can be used to determine where to print the commit summary information
+  alongside the graph output.
+
+Limitations
+-----------
+
+* `graph_update()` must be called with commits in topological order.  It should
+  not be called on a commit if it has already been invoked with an ancestor of
+  that commit, or the graph output will be incorrect.
+
+* `graph_update()` must be called on a contiguous group of commits.  If
+  `graph_update()` is called on a particular commit, it should later be called
+  on all parents of that commit.  Parents must not be skipped, or the graph
+  output will appear incorrect.
++
+`graph_update()` may be used on a pruned set of commits only if the parent list
+has been rewritten so as to include only ancestors from the pruned set.
+
+* The graph API does not currently support reverse commit ordering.  In
+  order to implement reverse ordering, the graphing API needs an
+  (efficient) mechanism to find the children of a commit.
+
+Sample usage
+------------
+
+------------
+struct commit *commit;
+struct git_graph *graph = graph_init();
+
+while ((commit = get_revision(opts)) != NULL) {
+       graph_update(graph, commit);
+       while (!graph_is_commit_finished(graph))
+       {
+               struct strbuf sb;
+               int is_commit_line;
+
+               strbuf_init(&sb, 0);
+               is_commit_line = graph_next_line(graph, &sb);
+               fputs(sb.buf, stdout);
+
+               if (is_commit_line)
+                       log_tree_commit(opts, commit);
+               else
+                       putchar(opts->diffopt.line_termination);
+       }
+}
+
+graph_release(graph);
+------------
+
+Sample output
+-------------
+
+The following is an example of the output from the graph API.  This output does
+not include any commit summary information--callers are responsible for
+outputting that information, if desired.
+
+------------
+*
+*
+M
+|\
+* |
+| | *
+| \ \
+|  \ \
+M-. \ \
+|\ \ \ \
+| | * | |
+| | | | | *
+| | | | | *
+| | | | | M
+| | | | | |\
+| | | | | | *
+| * | | | | |
+| | | | | M  \
+| | | | | |\  |
+| | | | * | | |
+| | | | * | | |
+* | | | | | | |
+| |/ / / / / /
+|/| / / / / /
+* | | | | | |
+|/ / / / / /
+* | | | | |
+| | | | | *
+| | | | |/
+| | | | *
+------------

diff --git a/technical/api-index.html b/technical/api-index.html
index 58fc703f9037f1170f68abc74d59b0c1c7fad08c..6ae6947b4f8add5e645853be3c6cc5bc9aa33807 100644 (file)
--- a/technical/api-index.html
+++ b/technical/api-index.html
@@ -308,6 +308,11 @@ documents them.</p>
 </li>\r
 <li>\r
 <p>\r
+<a href="api-history-graph.html">history graph API</a>\r
+</p>\r
+</li>\r
+<li>\r
+<p>\r
 <a href="api-in-core-index.html">in-core index API</a>\r
 </p>\r
 </li>\r
@@ -377,7 +382,7 @@ documents them.</p>
 </div>\r
 <div id="footer">\r
 <div id="footer-text">\r
-Last updated 20-Feb-2008 10:44:10 UTC\r
+Last updated 22-May-2008 00:52:49 UTC\r
 </div>\r
 </div>\r
 </body>\r

diff --git a/technical/api-index.txt b/technical/api-index.txt
index 6c272fc0841ea9bec5c0fcc197a875e50325a0f8..4a1190de60e07e262e4a02cef2bd1d92b3da8e0c 100644 (file)
--- a/technical/api-index.txt
+++ b/technical/api-index.txt
@@ -15,6 +15,7 @@ documents them.
 * link:api-gitattributes.html[gitattributes API]
 * link:api-grep.html[grep API]
 * link:api-hash.html[hash API]
+* link:api-history-graph.html[history graph API]
 * link:api-in-core-index.html[in-core index API]
 * link:api-lockfile.html[lockfile API]
 * link:api-object-access.html[object access API]