"Fossies" - the Fresh Open Source Software Archive

Member "technical/api-diff.txt" (15 Dec 2018, 5626 Bytes) of package /linux/misc/git-htmldocs-2.20.1.tar.xz:


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 or download 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
    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 `repo_diff_setup()` to initialize this structure.  This
   22   sets up 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   the callback set_default in diff_options can be used to tweak this more.
   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,
   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.
   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 
   43 * Calling `diff_flush()` will produce the output.
   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
   54 `diff_addremove()`, `diff_change()` and `diff_unmerge()` synthesize and
   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`::
  106 	Number of hexdigits to abbreviate raw format output to.
  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
  112 	in its preimage and postimage of the diff_queue.
  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 
  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 
  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
  160 	parser; tell the calling program to signal the presence of
  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)