1diff API 2======== 3 4The diff API is for programs that compare two sets of files (e.g. two 5trees, one tree and the index) and present the found difference in 6various ways. The calling program is responsible for feeding the API 7pairs 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 9called 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 17Calling 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_unmerge()` 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 `diff_flush()` will produce the output. 43 44 45Data structures 46--------------- 47 48* `struct diff_filespec` 49 50This is the internal representation for a single file (blob). It 51records the blob object name (if known -- for a work tree file it 52typically is a NUL SHA-1), filemode and pathname. This is what the 53`diff_addremove()`, `diff_change()` and `diff_unmerge()` synthesize and 54feed `diff_queue()` function with. 55 56* `struct diff_filepair` 57 58This records a pair of `struct diff_filespec`; the filespec for a file 59in the "old" set (i.e. preimage) is called `one`, and the filespec for a 60file in the "new" set (i.e. postimage) is called `two`. A change that 61represents file creation has NULL in `one`, and file deletion has NULL 62in `two`. 63 64A `filepair` starts pointing at `one` and `two` that are from the same 65filename, but `diffcore_std()` can break pairs and match component 66filespecs with other filespecs from a different filepair to form new 67filepair. This is called 'rename detection'. 68 69* `struct diff_queue` 70 71This 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 89This describes the set of options the calling program wants to affect 90the operation of diffcore library with. 91 92Notable 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 abbreviate 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 postimage 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 118BINARY, TEXT;; 119 Affects the way how a file that is seemingly binary is treated. 120 121FULL_INDEX;; 122 Tells the patch output format not to use abbreviated object 123 names on the "index" lines. 124 125FIND_COPIES_HARDER;; 126 Tells the diffcore library that the caller is feeding unchanged 127 filepairs to allow copies from unmodified files be detected. 128 129COLOR_DIFF;; 130 Output should be colored. 131 132COLOR_DIFF_WORDS;; 133 Output is a colored word-diff. 134 135NO_INDEX;; 136 Tells diff-files that the input is not tracked files but files 137 in random locations on the filesystem. 138 139ALLOW_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 143QUIET;; 144 Do not show any output. 145 146REVERSE_DIFF;; 147 Tells the library that the calling program is feeding the 148 filepairs reversed; `one` is two, and `two` is one. 149 150EXIT_WITH_STATUS;; 151 For communication between the calling program and the options 152 parser; tell the calling program to signal the presence of 153 difference using program exit code. 154 155HAS_CHANGES;; 156 Internal; used for optimization to see if there is any change. 157 158SILENT_ON_REMOVE;; 159 Affects if diff-files shows removed files. 160 161RECURSIVE, 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)