The diff API is for programs that compare two sets of files (e.g. two trees, one tree and the index) and present the found difference in various ways. The calling program is responsible for feeding the API pairs of files, one from the "old" set and the corresponding one from "new" set, that are different. The library called through this API is called diffcore, and is responsible for two things.

  • finding total rewrites (-B), renames (-M) and copies (-C), and changes that touch a string (-S), as specified by the caller.

  • outputting the differences in various formats, as specified by the caller.

Calling sequence

Data structures

This is the internal representation for a single file (blob). It records the blob object name (if known — for a work tree file it typically is a NUL SHA-1), filemode and pathname. This is what the diff_addremove(), diff_change() and diff_unmerge() synthesize and feed diff_queue() function with.

This records a pair of struct diff_filespec; the filespec for a file in the "old" set (i.e. preimage) is called one, and the filespec for a file in the "new" set (i.e. postimage) is called two. A change that represents file creation has NULL in one, and file deletion has NULL in two.

A filepair starts pointing at one and two that are from the same filename, but diffcore_std() can break pairs and match component filespecs with other filespecs from a different filepair to form new filepair. This is called rename detection.

This is a collection of filepairs. Notable members are:

queue

An array of pointers to struct diff_filepair. This dynamically grows as you add filepairs;

alloc

The allocated size of the queue array;

nr

The number of elements in the queue array.

  • struct diff_options

This describes the set of options the calling program wants to affect the operation of diffcore library with.

Notable members are:

output_format

The output format used when diff_flush() is run.

context

Number of context lines to generate in patch output.

break_opt, detect_rename, rename-score, rename_limit

Affects the way detection logic for complete rewrites, renames and copies.

abbrev

Number of hexdigits to abbreviate raw format output to.

pickaxe

A constant string (can and typically does contain newlines to look for a block of text, not just a single line) to filter out the filepairs that do not change the number of strings contained in its preimage and postimage of the diff_queue.

flags

This is mostly a collection of boolean options that affects the operation, but some do not have anything to do with the diffcore library.

BINARY, TEXT

Affects the way how a file that is seemingly binary is treated.

FULL_INDEX

Tells the patch output format not to use abbreviated object names on the "index" lines.

FIND_COPIES_HARDER

Tells the diffcore library that the caller is feeding unchanged filepairs to allow copies from unmodified files be detected.

COLOR_DIFF

Output should be colored.

COLOR_DIFF_WORDS

Output is a colored word-diff.

NO_INDEX

Tells diff-files that the input is not tracked files but files in random locations on the filesystem.

ALLOW_EXTERNAL

Tells output routine that it is Ok to call user specified patch output routine. Plumbing disables this to ensure stable output.

QUIET

Do not show any output.

REVERSE_DIFF

Tells the library that the calling program is feeding the filepairs reversed; one is two, and two is one.

EXIT_WITH_STATUS

For communication between the calling program and the options parser; tell the calling program to signal the presence of difference using program exit code.

HAS_CHANGES

Internal; used for optimization to see if there is any change.

SILENT_ON_REMOVE

Affects if diff-files shows removed files.

RECURSIVE, TREE_IN_RECURSIVE

Tells if tree traversal done by tree-diff should recursively descend into a tree object pair that are different in preimage and postimage set.

(JC)