"Fossies" - the Fresh Open Source Software Archive
As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard
) with prefixed line numbers.
Alternatively you can here view
the uninterpreted source code file.
See also the last Fossies "Diffs"
side-by-side code changes report for "api-diff.txt": 2.19.2_vs_2.20.0
1 diff API
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.
11 * finding total rewrites (`-B`), renames (`-M`) and copies (`-C`), and
12 changes that touch a string (`-S`), as specified by the caller.
14 * outputting the differences in various formats, as specified by the
17 Calling sequence
20 * Prepare `struct diff_options` to record the set of diff options, and
21 then call `repo_diff_setup()` to initialize this structure. This
22 sets up the vanilla default.
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.
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 the callback set_default in diff_options can be used to tweak this more.
34 * As you find different pairs of files, call `diff_change()` to feed
35 modified files, `diff_addremove()` to feed created or deleted files,
36 or `diff_unmerge()` to feed a file whose state is 'unmerged' to the
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.
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.
43 * Calling `diff_flush()` will produce the output.
46 Data structures
49 * `struct diff_filespec`
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
54 `diff_addremove()`, `diff_change()` and `diff_unmerge()` synthesize and
55 feed `diff_queue()` function with.
57 * `struct diff_filepair`
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`.
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'.
70 * `struct diff_queue`
72 This is a collection of filepairs. Notable members are:
76 An array of pointers to `struct diff_filepair`. This
77 dynamically grows as you add filepairs;
81 The allocated size of the `queue` array;
85 The number of elements in the `queue` array.
88 * `struct diff_options`
90 This describes the set of options the calling program wants to affect
91 the operation of diffcore library with.
93 Notable members are:
96 The output format used when `diff_flush()` is run.
99 Number of context lines to generate in patch output.
101 `break_opt`, `detect_rename`, `rename-score`, `rename_limit`::
102 Affects the way detection logic for complete rewrites, renames
103 and copies.
106 Number of hexdigits to abbreviate raw format output to.
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
112 in its preimage and postimage of the diff_queue.
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
120 Records whether a flag has been changed due to user request
121 (rather than just set/unset by default).
124 Callback which allows tweaking the options in diff_setup_done().
126 BINARY, TEXT;;
127 Affects the way how a file that is seemingly binary is treated.
130 Tells the patch output format not to use abbreviated object
131 names on the "index" lines.
134 Tells the diffcore library that the caller is feeding unchanged
135 filepairs to allow copies from unmodified files be detected.
138 Output should be colored.
141 Output is a colored word-diff.
144 Tells diff-files that the input is not tracked files but files
145 in random locations on the filesystem.
148 Tells output routine that it is Ok to call user specified patch
149 output routine. Plumbing disables this to ensure stable output.
152 Do not show any output.
155 Tells the library that the calling program is feeding the
156 filepairs reversed; `one` is two, and `two` is one.
159 For communication between the calling program and the options
160 parser; tell the calling program to signal the presence of
161 difference using program exit code.
164 Internal; used for optimization to see if there is any change.
167 Affects if diff-files shows removed files.
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.