Start preparing the API documents.
[git/git.git] / Documentation / technical / api-diff.txt
1 diff API
2 ========
3
4 The diff API is for programs that compare two sets of files (e.g. two
5 trees, one tree and the index) and present the found difference in
6 various ways. The calling program is responsible for feeding the API
7 pairs of files, one from the "old" set and the corresponding one from
8 "new" set, that are different. The library called through this API is
9 called diffcore, and is responsible for two things.
10
11 * finding total rewrites (`-B`), renames (`-M`) and copies (`-C`), and
12 changes that touch a string (`-S`), as specified by the caller.
13
14 * outputting the differences in various formats, as specified by the
15 caller.
16
17 Calling sequence
18 ----------------
19
20 * Prepare `struct diff_options` to record the set of diff options, and
21 then call `diff_setup()` to initialize this structure. This sets up
22 the vanilla default.
23
24 * Fill in the options structure to specify desired output format, rename
25 detection, etc. `diff_opt_parse()` can be used to parse options given
26 from the command line in a way consistent with existing git-diff
27 family of programs.
28
29 * Call `diff_setup_done()`; this inspects the options set up so far for
30 internal consistency and make necessary tweaking to it (e.g. if
31 textual patch output was asked, recursive behaviour is turned on).
32
33 * As you find different pairs of files, call `diff_change()` to feed
34 modified files, `diff_addremove()` to feed created or deleted files,
35 or `diff_unmerged()` to feed a file whose state is 'unmerged' to the
36 API. These are thin wrappers to a lower-level `diff_queue()` function
37 that is flexible enough to record any of these kinds of changes.
38
39 * Once you finish feeding the pairs of files, call `diffcore_std()`.
40 This will tell the diffcore library to go ahead and do its work.
41
42 * Calling `diffcore_flush()` will produce the output.
43
44
45 Data structures
46 ---------------
47
48 * `struct diff_filespec`
49
50 This is the internal representation for a single file (blob). It
51 records the blob object name (if known -- for a work tree file it
52 typically is a NUL SHA-1), filemode and pathname. This is what the
53 `diff_addremove()`, `diff_change()` and `diff_unmerged()` synthesize and
54 feed `diff_queue()` function with.
55
56 * `struct diff_filepair`
57
58 This records a pair of `struct diff_filespec`; the filespec for a file
59 in the "old" set (i.e. preimage) is called `one`, and the filespec for a
60 file in the "new" set (i.e. postimage) is called `two`. A change that
61 represents file creation has NULL in `one`, and file deletion has NULL
62 in `two`.
63
64 A `filepair` starts pointing at `one` and `two` that are from the same
65 filename, but `diffcore_std()` can break pairs and match component
66 filespecs with other filespecs from a different filepair to form new
67 filepair. This is called 'rename detection'.
68
69 * `struct diff_queue`
70
71 This is a collection of filepairs. Notable members are:
72
73 `queue`::
74
75 An array of pointers to `struct diff_filepair`. This
76 dynamically grows as you add filepairs;
77
78 `alloc`::
79
80 The allocated size of the `queue` array;
81
82 `nr`::
83
84 The number of elements in the `queue` array.
85
86
87 * `struct diff_options`
88
89 This describes the set of options the calling program wants to affect
90 the operation of diffcore library with.
91
92 Notable members are:
93
94 `output_format`::
95 The output format used when `diff_flush()` is run.
96
97 `context`::
98 Number of context lines to generate in patch output.
99
100 `break_opt`, `detect_rename`, `rename-score`, `rename_limit`::
101 Affects the way detection logic for complete rewrites, renames
102 and copies.
103
104 `abbrev`::
105 Number of hexdigits to abbrevate raw format output to.
106
107 `pickaxe`::
108 A constant string (can and typically does contain newlines to
109 look for a block of text, not just a single line) to filter out
110 the filepairs that do not change the number of strings contained
111 in its preimage and postmage of the diff_queue.
112
113 `flags`::
114 This is mostly a collection of boolean options that affects the
115 operation, but some do not have anything to do with the diffcore
116 library.
117
118 BINARY, TEXT;;
119 Affects the way how a file that is seemingly binary is treated.
120
121 FULL_INDEX;;
122 Tells the patch output format not to use abbreviated object
123 names on the "index" lines.
124
125 FIND_COPIES_HARDER;;
126 Tells the diffcore library that the caller is feeding unchanged
127 filepairs to allow copies from unmodified files be detected.
128
129 COLOR_DIFF;;
130 Output should be colored.
131
132 COLOR_DIFF_WORDS;;
133 Output is a colored word-diff.
134
135 NO_INDEX;;
136 Tells diff-files that the input is not tracked files but files
137 in random locations on the filesystem.
138
139 ALLOW_EXTERNAL;;
140 Tells output routine that it is Ok to call user specified patch
141 output routine. Plumbing disables this to ensure stable output.
142
143 QUIET;;
144 Do not show any output.
145
146 REVERSE_DIFF;;
147 Tells the library that the calling program is feeding the
148 filepairs reversed; `one` is two, and `two` is one.
149
150 EXIT_WITH_STATUS;;
151 For communication between the calling program and the options
152 parser; tell the calling program to signal the presense of
153 difference using program exit code.
154
155 HAS_CHANGES;;
156 Internal; used for optimization to see if there is any change.
157
158 SILENT_ON_REMOVE;;
159 Affects if diff-files shows removed files.
160
161 RECURSIVE, TREE_IN_RECURSIVE;;
162 Tells if tree traversal done by tree-diff should recursively
163 descend into a tree object pair that are different in preimage
164 and postimage set.
165
166 (JC)