Google Git
Sign in
chromium / external / gitster / git-htmldocs / bed00e716afd5ca14f313c92c54ae41bf20167dd / . / technical / api-revision-walking.html
blob: f1cbc6e27dfd9b75ae1d3b5f0b92ec0560be54db [file] [log] [blame]
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]6<meta name="generator" content="AsciiDoc 8.2.5" />
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]7<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]19a {
20 color: blue;
21 text-decoration: underline;
22}
23a:visited {
24 color: fuchsia;
25}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]26
27em {
28 font-style: italic;
29}
30
31strong {
32 font-weight: bold;
33}
34
35tt {
36 color: navy;
37}
38
39h1, h2, h3, h4, h5, h6 {
40 color: #527bbd;
41 font-family: sans-serif;
42 margin-top: 1.2em;
43 margin-bottom: 0.5em;
44 line-height: 1.3;
45}
46
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]47h1, h2, h3 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]48 border-bottom: 2px solid silver;
49}
50h2 {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]51 padding-top: 0.5em;
52}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]53h3 {
54 float: left;
55}
56h3 + * {
57 clear: left;
58}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]59
60div.sectionbody {
61 font-family: serif;
62 margin-left: 0;
63}
64
65hr {
66 border: 1px solid silver;
67}
68
69p {
70 margin-top: 0.5em;
71 margin-bottom: 0.5em;
72}
73
74pre {
75 padding: 0;
76 margin: 0;
77}
78
79span#author {
80 color: #527bbd;
81 font-family: sans-serif;
82 font-weight: bold;
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]83 font-size: 1.1em;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]84}
85span#email {
86}
87span#revision {
88 font-family: sans-serif;
89}
90
91div#footer {
92 font-family: sans-serif;
93 font-size: small;
94 border-top: 2px solid silver;
95 padding-top: 0.5em;
96 margin-top: 4.0em;
97}
98div#footer-text {
99 float: left;
100 padding-bottom: 0.5em;
101}
102div#footer-badges {
103 float: right;
104 padding-bottom: 0.5em;
105}
106
107div#preamble,
108div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
109div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
110div.admonitionblock {
111 margin-right: 10%;
112 margin-top: 1.5em;
113 margin-bottom: 1.5em;
114}
115div.admonitionblock {
116 margin-top: 2.5em;
117 margin-bottom: 2.5em;
118}
119
120div.content { /* Block element content. */
121 padding: 0;
122}
123
124/* Block element titles. */
125div.title, caption.title {
126 font-family: sans-serif;
127 font-weight: bold;
128 text-align: left;
129 margin-top: 1.0em;
130 margin-bottom: 0.5em;
131}
132div.title + * {
133 margin-top: 0;
134}
135
136td div.title:first-child {
137 margin-top: 0.0em;
138}
139div.content div.title:first-child {
140 margin-top: 0.0em;
141}
142div.content + div.title {
143 margin-top: 0.0em;
144}
145
146div.sidebarblock > div.content {
147 background: #ffffee;
148 border: 1px solid silver;
149 padding: 0.5em;
150}
151
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]152div.listingblock {
153 margin-right: 0%;
154}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]155div.listingblock > div.content {
156 border: 1px solid silver;
157 background: #f4f4f4;
158 padding: 0.5em;
159}
160
161div.quoteblock > div.content {
162 padding-left: 2.0em;
163}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]164
165div.attribution {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]166 text-align: right;
167}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]168div.verseblock + div.attribution {
169 text-align: left;
170}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]171
172div.admonitionblock .icon {
173 vertical-align: top;
174 font-size: 1.1em;
175 font-weight: bold;
176 text-decoration: underline;
177 color: #527bbd;
178 padding-right: 0.5em;
179}
180div.admonitionblock td.content {
181 padding-left: 0.5em;
182 border-left: 2px solid silver;
183}
184
185div.exampleblock > div.content {
186 border-left: 2px solid silver;
187 padding: 0.5em;
188}
189
190div.verseblock div.content {
191 white-space: pre;
192}
193
194div.imageblock div.content { padding-left: 0; }
195div.imageblock img { border: 1px solid silver; }
196span.image img { border-style: none; }
197
198dl {
199 margin-top: 0.8em;
200 margin-bottom: 0.8em;
201}
202dt {
203 margin-top: 0.5em;
204 margin-bottom: 0;
205 font-style: italic;
206}
207dd > *:first-child {
208 margin-top: 0;
209}
210
211ul, ol {
212 list-style-position: outside;
213}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]214div.olist2 ol {
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]215 list-style-type: lower-alpha;
216}
217
218div.tableblock > table {
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]219 border: 3px solid #527bbd;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]220}
221thead {
222 font-family: sans-serif;
223 font-weight: bold;
224}
225tfoot {
226 font-weight: bold;
227}
228
229div.hlist {
230 margin-top: 0.8em;
231 margin-bottom: 0.8em;
232}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]233div.hlist td {
234 padding-bottom: 5px;
235}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]236td.hlist1 {
237 vertical-align: top;
238 font-style: italic;
239 padding-right: 0.8em;
240}
241td.hlist2 {
242 vertical-align: top;
243}
244
245@media print {
246 div#footer-badges { display: none; }
247}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]248
249div#toctitle {
250 color: #527bbd;
251 font-family: sans-serif;
252 font-size: 1.1em;
253 font-weight: bold;
254 margin-top: 1.0em;
255 margin-bottom: 0.1em;
256}
257
258div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
259 margin-top: 0;
260 margin-bottom: 0;
261}
262div.toclevel2 {
263 margin-left: 2em;
264 font-size: 0.9em;
265}
266div.toclevel3 {
267 margin-left: 4em;
268 font-size: 0.9em;
269}
270div.toclevel4 {
271 margin-left: 6em;
272 font-size: 0.9em;
273}
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]274/* Workarounds for IE6's broken and incomplete CSS2. */
275
276div.sidebar-content {
277 background: #ffffee;
278 border: 1px solid silver;
279 padding: 0.5em;
280}
281div.sidebar-title, div.image-title {
282 font-family: sans-serif;
283 font-weight: bold;
284 margin-top: 0.0em;
285 margin-bottom: 0.5em;
286}
287
288div.listingblock div.content {
289 border: 1px solid silver;
290 background: #f4f4f4;
291 padding: 0.5em;
292}
293
294div.quoteblock-content {
295 padding-left: 2.0em;
296}
297
298div.exampleblock-content {
299 border-left: 2px solid silver;
300 padding-left: 0.5em;
301}
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]302
303/* IE6 sets dynamically generated links as visited. */
304div#toc a:visited { color: blue; }
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]305</style>
306<title>revision walking API</title>
307</head>
308<body>
309<div id="header">
310<h1>revision walking API</h1>
311</div>
312<div id="preamble">
313<div class="sectionbody">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]314<div class="para"><p>The revision walking API offers functions to build a list of revisions
315and then iterate over that list.</p></div>
Junio C Hamano054ea082008-06-01 08:26:34[diff] [blame]316</div>
317</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]318<h2 id="_calling_sequence">Calling sequence</h2>
Junio C Hamano054ea082008-06-01 08:26:34[diff] [blame]319<div class="sectionbody">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]320<div class="para"><p>The walking API has a given calling sequence: first you need to
Junio C Hamano054ea082008-06-01 08:26:34[diff] [blame]321initialize a rev_info structure, then add revisions to control what kind
322of revision list do you want to get, finally you can iterate over the
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]323revision list.</p></div>
Junio C Hamano054ea082008-06-01 08:26:34[diff] [blame]324</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]325<h2 id="_functions">Functions</h2>
Junio C Hamano054ea082008-06-01 08:26:34[diff] [blame]326<div class="sectionbody">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]327<div class="vlist"><dl>
Junio C Hamano054ea082008-06-01 08:26:34[diff] [blame]328<dt>
329<tt>init_revisions</tt>
330</dt>
331<dd>
332<p>
333 Initialize a rev_info structure with default values. The second
334 parameter may be NULL or can be prefix path, and then the <tt>.prefix</tt>
335 variable will be set to it. This is typically the first function you
336 want to call when you want to deal with a revision list. After calling
337 this function, you are free to customize options, like set
338 <tt>.ignore_merges</tt> to 0 if you don't want to ignore merges, and so on. See
339 <tt>revision.h</tt> for a complete list of available options.
340</p>
341</dd>
342<dt>
343<tt>add_pending_object</tt>
344</dt>
345<dd>
346<p>
347 This function can be used if you want to add commit objects as revision
348 information. You can use the <tt>UNINTERESTING</tt> object flag to indicate if
349 you want to include or exclude the given commit (and commits reachable
350 from the given commit) from the revision list.
351</p>
352<div class="admonitionblock">
353<table><tr>
354<td class="icon">
355<div class="title">Note</div>
356</td>
357<td class="content">If you have the commits as a string list then you probably want to
358use setup_revisions(), instead of parsing each string and using this
359function.</td>
360</tr></table>
361</div>
362</dd>
363<dt>
364<tt>setup_revisions</tt>
365</dt>
366<dd>
367<p>
368 Parse revision information, filling in the <tt>rev_info</tt> structure, and
369 removing the used arguments from the argument list. Returns the number
370 of arguments left that weren't recognized, which are also moved to the
371 head of the argument list. The last parameter is used in case no
372 parameter given by the first two arguments.
373</p>
374</dd>
375<dt>
376<tt>prepare_revision_walk</tt>
377</dt>
378<dd>
379<p>
380 Prepares the rev_info structure for a walk. You should check if it
381 returns any error (non-zero return code) and if it does not, you can
382 start using get_revision() to do the iteration.
383</p>
384</dd>
385<dt>
386<tt>get_revision</tt>
387</dt>
388<dd>
389<p>
390 Takes a pointer to a <tt>rev_info</tt> structure and iterates over it,
391 returning a <tt>struct commit *</tt> each time you call it. The end of the
392 revision list is indicated by returning a NULL pointer.
393</p>
394</dd>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]395</dl></div>
Junio C Hamano054ea082008-06-01 08:26:34[diff] [blame]396</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]397<h2 id="_data_structures">Data structures</h2>
Junio C Hamano054ea082008-06-01 08:26:34[diff] [blame]398<div class="sectionbody">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]399<div class="para"><p>Talk about &lt;revision.h&gt;, things like:</p></div>
400<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]401<li>
402<p>
403two diff_options, one for path limiting, another for output;
404</p>
405</li>
406<li>
407<p>
Junio C Hamano054ea082008-06-01 08:26:34[diff] [blame]408remaining functions;
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]409</p>
410</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]411</ul></div>
412<div class="para"><p>(Linus, JC, Dscho)</p></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]413</div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]414<div id="footer">
415<div id="footer-text">
Junio C Hamano73d812c2009-07-01 02:33:06[diff] [blame]416Last updated 2009-07-01 02:31:15 UTC
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]417</div>
418</div>
419</body>
420</html>