Google Git
Sign in
chromium / external / gitster / git-htmldocs / bc4852e8d68ccfc18b8d3c0cf4c3d602917d454a / . / technical / api-diff.html
blob: 4414408b81110cd9ec4b761f7b730bae5a93e944 [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>diff API</title>
307</head>
308<body>
309<div id="header">
310<h1>diff 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 diff API is for programs that compare two sets of files (e.g. two
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]315trees, one tree and the index) and present the found difference in
316various ways. The calling program is responsible for feeding the API
317pairs of files, one from the "old" set and the corresponding one from
318"new" set, that are different. The library called through this API is
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]319called diffcore, and is responsible for two things.</p></div>
320<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]321<li>
322<p>
323finding total rewrites (<tt>-B</tt>), renames (<tt>-M</tt>) and copies (<tt>-C</tt>), and
324 changes that touch a string (<tt>-S</tt>), as specified by the caller.
325</p>
326</li>
327<li>
328<p>
329outputting the differences in various formats, as specified by the
330 caller.
331</p>
332</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]333</ul></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]334</div>
335</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]336<h2 id="_calling_sequence">Calling sequence</h2>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]337<div class="sectionbody">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]338<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]339<li>
340<p>
341Prepare <tt>struct diff_options</tt> to record the set of diff options, and
342 then call <tt>diff_setup()</tt> to initialize this structure. This sets up
343 the vanilla default.
344</p>
345</li>
346<li>
347<p>
348Fill in the options structure to specify desired output format, rename
349 detection, etc. <tt>diff_opt_parse()</tt> can be used to parse options given
350 from the command line in a way consistent with existing git-diff
351 family of programs.
352</p>
353</li>
354<li>
355<p>
356Call <tt>diff_setup_done()</tt>; this inspects the options set up so far for
357 internal consistency and make necessary tweaking to it (e.g. if
358 textual patch output was asked, recursive behaviour is turned on).
359</p>
360</li>
361<li>
362<p>
363As you find different pairs of files, call <tt>diff_change()</tt> to feed
364 modified files, <tt>diff_addremove()</tt> to feed created or deleted files,
365 or <tt>diff_unmerged()</tt> to feed a file whose state is <em>unmerged</em> to the
366 API. These are thin wrappers to a lower-level <tt>diff_queue()</tt> function
367 that is flexible enough to record any of these kinds of changes.
368</p>
369</li>
370<li>
371<p>
372Once you finish feeding the pairs of files, call <tt>diffcore_std()</tt>.
373 This will tell the diffcore library to go ahead and do its work.
374</p>
375</li>
376<li>
377<p>
Junio C Hamano40f54d32008-02-29 09:21:50[diff] [blame]378Calling <tt>diff_flush()</tt> will produce the output.
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]379</p>
380</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]381</ul></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]382</div>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]383<h2 id="_data_structures">Data structures</h2>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]384<div class="sectionbody">
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]385<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]386<li>
387<p>
388<tt>struct diff_filespec</tt>
389</p>
390</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]391</ul></div>
392<div class="para"><p>This is the internal representation for a single file (blob). It
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]393records the blob object name (if known &#8212; for a work tree file it
394typically is a NUL SHA-1), filemode and pathname. This is what the
395<tt>diff_addremove()</tt>, <tt>diff_change()</tt> and <tt>diff_unmerged()</tt> synthesize and
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]396feed <tt>diff_queue()</tt> function with.</p></div>
397<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]398<li>
399<p>
400<tt>struct diff_filepair</tt>
401</p>
402</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]403</ul></div>
404<div class="para"><p>This records a pair of <tt>struct diff_filespec</tt>; the filespec for a file
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]405in the "old" set (i.e. preimage) is called <tt>one</tt>, and the filespec for a
406file in the "new" set (i.e. postimage) is called <tt>two</tt>. A change that
407represents file creation has NULL in <tt>one</tt>, and file deletion has NULL
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]408in <tt>two</tt>.</p></div>
409<div class="para"><p>A <tt>filepair</tt> starts pointing at <tt>one</tt> and <tt>two</tt> that are from the same
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]410filename, but <tt>diffcore_std()</tt> can break pairs and match component
411filespecs with other filespecs from a different filepair to form new
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]412filepair. This is called <em>rename detection</em>.</p></div>
413<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]414<li>
415<p>
416<tt>struct diff_queue</tt>
417</p>
418</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]419</ul></div>
420<div class="para"><p>This is a collection of filepairs. Notable members are:</p></div>
421<div class="vlist"><dl>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]422<dt>
423<tt>queue</tt>
424</dt>
425<dd>
426<p>
427 An array of pointers to <tt>struct diff_filepair</tt>. This
428 dynamically grows as you add filepairs;
429</p>
430</dd>
431<dt>
432<tt>alloc</tt>
433</dt>
434<dd>
435<p>
436 The allocated size of the <tt>queue</tt> array;
437</p>
438</dd>
439<dt>
440<tt>nr</tt>
441</dt>
442<dd>
443<p>
444 The number of elements in the <tt>queue</tt> array.
445</p>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]446<div class="ilist"><ul>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]447<li>
448<p>
449<tt>struct diff_options</tt>
450</p>
451</li>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]452</ul></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]453</dd>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]454</dl></div>
455<div class="para"><p>This describes the set of options the calling program wants to affect
456the operation of diffcore library with.</p></div>
457<div class="para"><p>Notable members are:</p></div>
458<div class="vlist"><dl>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]459<dt>
460<tt>output_format</tt>
461</dt>
462<dd>
463<p>
464 The output format used when <tt>diff_flush()</tt> is run.
465</p>
466</dd>
467<dt>
468<tt>context</tt>
469</dt>
470<dd>
471<p>
472 Number of context lines to generate in patch output.
473</p>
474</dd>
475<dt>
476<tt>break_opt</tt>, <tt>detect_rename</tt>, <tt>rename-score</tt>, <tt>rename_limit</tt>
477</dt>
478<dd>
479<p>
480 Affects the way detection logic for complete rewrites, renames
481 and copies.
482</p>
483</dd>
484<dt>
485<tt>abbrev</tt>
486</dt>
487<dd>
488<p>
Junio C Hamano4e272312008-01-08 09:13:21[diff] [blame]489 Number of hexdigits to abbreviate raw format output to.
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]490</p>
491</dd>
492<dt>
493<tt>pickaxe</tt>
494</dt>
495<dd>
496<p>
497 A constant string (can and typically does contain newlines to
498 look for a block of text, not just a single line) to filter out
499 the filepairs that do not change the number of strings contained
Junio C Hamano4e272312008-01-08 09:13:21[diff] [blame]500 in its preimage and postimage of the diff_queue.
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]501</p>
502</dd>
503<dt>
504<tt>flags</tt>
505</dt>
506<dd>
507<p>
508 This is mostly a collection of boolean options that affects the
509 operation, but some do not have anything to do with the diffcore
510 library.
511</p>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]512<div class="vlist"><dl>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]513<dt>
514BINARY, TEXT
515</dt>
516<dd>
517<p>
518 Affects the way how a file that is seemingly binary is treated.
519</p>
520</dd>
521<dt>
522FULL_INDEX
523</dt>
524<dd>
525<p>
526 Tells the patch output format not to use abbreviated object
527 names on the "index" lines.
528</p>
529</dd>
530<dt>
531FIND_COPIES_HARDER
532</dt>
533<dd>
534<p>
535 Tells the diffcore library that the caller is feeding unchanged
536 filepairs to allow copies from unmodified files be detected.
537</p>
538</dd>
539<dt>
540COLOR_DIFF
541</dt>
542<dd>
543<p>
544 Output should be colored.
545</p>
546</dd>
547<dt>
548COLOR_DIFF_WORDS
549</dt>
550<dd>
551<p>
552 Output is a colored word-diff.
553</p>
554</dd>
555<dt>
556NO_INDEX
557</dt>
558<dd>
559<p>
560 Tells diff-files that the input is not tracked files but files
561 in random locations on the filesystem.
562</p>
563</dd>
564<dt>
565ALLOW_EXTERNAL
566</dt>
567<dd>
568<p>
569 Tells output routine that it is Ok to call user specified patch
570 output routine. Plumbing disables this to ensure stable output.
571</p>
572</dd>
573<dt>
574QUIET
575</dt>
576<dd>
577<p>
578 Do not show any output.
579</p>
580</dd>
581<dt>
582REVERSE_DIFF
583</dt>
584<dd>
585<p>
586 Tells the library that the calling program is feeding the
587 filepairs reversed; <tt>one</tt> is two, and <tt>two</tt> is one.
588</p>
589</dd>
590<dt>
591EXIT_WITH_STATUS
592</dt>
593<dd>
594<p>
595 For communication between the calling program and the options
Junio C Hamano4e272312008-01-08 09:13:21[diff] [blame]596 parser; tell the calling program to signal the presence of
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]597 difference using program exit code.
598</p>
599</dd>
600<dt>
601HAS_CHANGES
602</dt>
603<dd>
604<p>
605 Internal; used for optimization to see if there is any change.
606</p>
607</dd>
608<dt>
609SILENT_ON_REMOVE
610</dt>
611<dd>
612<p>
613 Affects if diff-files shows removed files.
614</p>
615</dd>
616<dt>
617RECURSIVE, TREE_IN_RECURSIVE
618</dt>
619<dd>
620<p>
621 Tells if tree traversal done by tree-diff should recursively
622 descend into a tree object pair that are different in preimage
623 and postimage set.
624</p>
625</dd>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]626</dl></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]627</dd>
Junio C Hamano4604fe52008-09-19 06:37:10[diff] [blame]628</dl></div>
629<div class="para"><p>(JC)</p></div>
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]630</div>
631<div id="footer">
632<div id="footer-text">
Junio C Hamanoec87f522008-12-10 08:35:25[diff] [blame]633Last updated 2008-12-10 08:33:37 UTC
Junio C Hamano3dac5042007-12-15 08:40:54[diff] [blame]634</div>
635</div>
636</body>
637</html>