]>
Commit | Line | Data |
---|---|---|
530e741c JH |
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 | |
e6757652 NTND |
21 | then call `repo_diff_setup()` to initialize this structure. This |
22 | sets up the vanilla default. | |
530e741c JH |
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 | |
6c374008 JH |
31 | textual patch output was asked, recursive behaviour is turned on); |
32 | the callback set_default in diff_options can be used to tweak this more. | |
530e741c JH |
33 | |
34 | * As you find different pairs of files, call `diff_change()` to feed | |
35 | modified files, `diff_addremove()` to feed created or deleted files, | |
7a45c313 | 36 | or `diff_unmerge()` to feed a file whose state is 'unmerged' to the |
530e741c JH |
37 | API. These are thin wrappers to a lower-level `diff_queue()` function |
38 | that is flexible enough to record any of these kinds of changes. | |
39 | ||
40 | * Once you finish feeding the pairs of files, call `diffcore_std()`. | |
41 | This will tell the diffcore library to go ahead and do its work. | |
42 | ||
a6f13ccf | 43 | * Calling `diff_flush()` will produce the output. |
530e741c JH |
44 | |
45 | ||
46 | Data structures | |
47 | --------------- | |
48 | ||
49 | * `struct diff_filespec` | |
50 | ||
51 | This is the internal representation for a single file (blob). It | |
52 | records the blob object name (if known -- for a work tree file it | |
53 | typically is a NUL SHA-1), filemode and pathname. This is what the | |
7a45c313 | 54 | `diff_addremove()`, `diff_change()` and `diff_unmerge()` synthesize and |
530e741c JH |
55 | feed `diff_queue()` function with. |
56 | ||
57 | * `struct diff_filepair` | |
58 | ||
59 | This records a pair of `struct diff_filespec`; the filespec for a file | |
60 | in the "old" set (i.e. preimage) is called `one`, and the filespec for a | |
61 | file in the "new" set (i.e. postimage) is called `two`. A change that | |
62 | represents file creation has NULL in `one`, and file deletion has NULL | |
63 | in `two`. | |
64 | ||
65 | A `filepair` starts pointing at `one` and `two` that are from the same | |
66 | filename, but `diffcore_std()` can break pairs and match component | |
67 | filespecs with other filespecs from a different filepair to form new | |
68 | filepair. This is called 'rename detection'. | |
69 | ||
70 | * `struct diff_queue` | |
71 | ||
72 | This is a collection of filepairs. Notable members are: | |
73 | ||
74 | `queue`:: | |
75 | ||
76 | An array of pointers to `struct diff_filepair`. This | |
77 | dynamically grows as you add filepairs; | |
78 | ||
79 | `alloc`:: | |
80 | ||
81 | The allocated size of the `queue` array; | |
82 | ||
83 | `nr`:: | |
84 | ||
85 | The number of elements in the `queue` array. | |
86 | ||
87 | ||
88 | * `struct diff_options` | |
89 | ||
90 | This describes the set of options the calling program wants to affect | |
91 | the operation of diffcore library with. | |
92 | ||
93 | Notable members are: | |
94 | ||
95 | `output_format`:: | |
96 | The output format used when `diff_flush()` is run. | |
97 | ||
98 | `context`:: | |
99 | Number of context lines to generate in patch output. | |
100 | ||
101 | `break_opt`, `detect_rename`, `rename-score`, `rename_limit`:: | |
102 | Affects the way detection logic for complete rewrites, renames | |
103 | and copies. | |
104 | ||
105 | `abbrev`:: | |
f1cdcc70 | 106 | Number of hexdigits to abbreviate raw format output to. |
530e741c JH |
107 | |
108 | `pickaxe`:: | |
109 | A constant string (can and typically does contain newlines to | |
110 | look for a block of text, not just a single line) to filter out | |
111 | the filepairs that do not change the number of strings contained | |
f1cdcc70 | 112 | in its preimage and postimage of the diff_queue. |
530e741c JH |
113 | |
114 | `flags`:: | |
115 | This is mostly a collection of boolean options that affects the | |
116 | operation, but some do not have anything to do with the diffcore | |
117 | library. | |
118 | ||
6c374008 JH |
119 | `touched_flags`:: |
120 | Records whether a flag has been changed due to user request | |
121 | (rather than just set/unset by default). | |
122 | ||
123 | `set_default`:: | |
124 | Callback which allows tweaking the options in diff_setup_done(). | |
125 | ||
530e741c JH |
126 | BINARY, TEXT;; |
127 | Affects the way how a file that is seemingly binary is treated. | |
128 | ||
129 | FULL_INDEX;; | |
130 | Tells the patch output format not to use abbreviated object | |
131 | names on the "index" lines. | |
132 | ||
133 | FIND_COPIES_HARDER;; | |
134 | Tells the diffcore library that the caller is feeding unchanged | |
135 | filepairs to allow copies from unmodified files be detected. | |
136 | ||
137 | COLOR_DIFF;; | |
138 | Output should be colored. | |
139 | ||
140 | COLOR_DIFF_WORDS;; | |
141 | Output is a colored word-diff. | |
142 | ||
143 | NO_INDEX;; | |
144 | Tells diff-files that the input is not tracked files but files | |
145 | in random locations on the filesystem. | |
146 | ||
147 | ALLOW_EXTERNAL;; | |
148 | Tells output routine that it is Ok to call user specified patch | |
149 | output routine. Plumbing disables this to ensure stable output. | |
150 | ||
151 | QUIET;; | |
152 | Do not show any output. | |
153 | ||
154 | REVERSE_DIFF;; | |
155 | Tells the library that the calling program is feeding the | |
156 | filepairs reversed; `one` is two, and `two` is one. | |
157 | ||
158 | EXIT_WITH_STATUS;; | |
159 | For communication between the calling program and the options | |
f1cdcc70 | 160 | parser; tell the calling program to signal the presence of |
530e741c JH |
161 | difference using program exit code. |
162 | ||
163 | HAS_CHANGES;; | |
164 | Internal; used for optimization to see if there is any change. | |
165 | ||
166 | SILENT_ON_REMOVE;; | |
167 | Affects if diff-files shows removed files. | |
168 | ||
169 | RECURSIVE, TREE_IN_RECURSIVE;; | |
170 | Tells if tree traversal done by tree-diff should recursively | |
171 | descend into a tree object pair that are different in preimage | |
172 | and postimage set. | |
173 | ||
174 | (JC) |