<!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.4.5" /> <title>revision walking 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.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 { 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 { padding-left: 2.0em; margin-right: 10%; } div.quoteblock > div.attribution { padding-top: 0.5em; text-align: right; } div.verseblock { padding-left: 2.0em; margin-right: 10%; } 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: 2px solid silver; } div.exampleblock > div.content { border-left: 2px solid silver; padding: 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 { 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; } @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 { 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: 2px solid silver; padding-left: 0.5em; } /* IE6 sets dynamically generated links as visited. */ div#toc a:visited { color: blue; } </style> </head> <body> <div id="header"> <h1>revision walking API</h1> </div> <div id="preamble"> <div class="sectionbody"> <div class="paragraph"><p>The revision walking API offers functions to build a list of revisions and then iterate over that list.</p></div> </div> </div> <h2 id="_calling_sequence">Calling sequence</h2> <div class="sectionbody"> <div class="paragraph"><p>The walking API has a given calling sequence: first you need to initialize a rev_info structure, then add revisions to control what kind of revision list do you want to get, finally you can iterate over the revision list.</p></div> </div> <h2 id="_functions">Functions</h2> <div class="sectionbody"> <div class="dlist"><dl> <dt class="hdlist1"> <tt>init_revisions</tt> </dt> <dd> <p> Initialize a rev_info structure with default values. The second parameter may be NULL or can be prefix path, and then the <tt>.prefix</tt> variable will be set to it. This is typically the first function you want to call when you want to deal with a revision list. After calling this function, you are free to customize options, like set <tt>.ignore_merges</tt> to 0 if you don’t want to ignore merges, and so on. See <tt>revision.h</tt> for a complete list of available options. </p> </dd> <dt class="hdlist1"> <tt>add_pending_object</tt> </dt> <dd> <p> This function can be used if you want to add commit objects as revision information. You can use the <tt>UNINTERESTING</tt> object flag to indicate if you want to include or exclude the given commit (and commits reachable from the given commit) from the revision list. </p> <div class="admonitionblock"> <table><tr> <td class="icon"> <div class="title">Note</div> </td> <td class="content">If you have the commits as a string list then you probably want to use setup_revisions(), instead of parsing each string and using this function.</td> </tr></table> </div> </dd> <dt class="hdlist1"> <tt>setup_revisions</tt> </dt> <dd> <p> Parse revision information, filling in the <tt>rev_info</tt> structure, and removing the used arguments from the argument list. Returns the number of arguments left that weren’t recognized, which are also moved to the head of the argument list. The last parameter is used in case no parameter given by the first two arguments. </p> </dd> <dt class="hdlist1"> <tt>prepare_revision_walk</tt> </dt> <dd> <p> Prepares the rev_info structure for a walk. You should check if it returns any error (non-zero return code) and if it does not, you can start using get_revision() to do the iteration. </p> </dd> <dt class="hdlist1"> <tt>get_revision</tt> </dt> <dd> <p> Takes a pointer to a <tt>rev_info</tt> structure and iterates over it, returning a <tt>struct commit *</tt> each time you call it. The end of the revision list is indicated by returning a NULL pointer. </p> </dd> </dl></div> </div> <h2 id="_data_structures">Data structures</h2> <div class="sectionbody"> <div class="paragraph"><p>Talk about <revision.h>, things like:</p></div> <div class="ulist"><ul> <li> <p> two diff_options, one for path limiting, another for output; </p> </li> <li> <p> remaining functions; </p> </li> </ul></div> <div class="paragraph"><p>(Linus, JC, Dscho)</p></div> </div> <div id="footer"> <div id="footer-text"> Last updated 2010-12-16 02:52:11 UTC </div> </div> </body> </html>