Overview

Calculating diffs is generally done in two phases: building a diff list then traversing the diff list. This makes is easier to share logic across the various types of diffs (tree vs tree, workdir vs index, etc.), and also allows you to insert optional diff list post-processing phases, such as rename detected, in between the steps. When you are done with a diff list object, it must be freed. Terminology

To understand the diff APIs, you should know the following terms:

• A diff or diff list represents the cumulative list of differences between two snapshots of a repository (possibly filtered by a set of file name patterns). This is the git_diff_list object.
• A delta is a file pair with an old and new revision. The old version may be absent if the file was just created and the new version may be absent if the file was deleted. A diff is mostly just a list of deltas.
• A binary file / delta is a file (or pair) for which no text diffs should be generated. A diff list can contain delta entries that are binary, but no diff content will be output for those files. There is a base heuristic for binary detection and you can further tune the behavior with git attributes or diff flags and option settings.
• A hunk is a span of modified lines in a delta along with some stable surrounding context. You can configure the amount of context and other properties of how hunks are generated. Each hunk also comes with a header that described where it starts and ends in both the old and new versions in the delta.
• A line is a range of characters inside a hunk. It could be a context line (i.e. in both old and new versions), an added line (i.e. only in the new version), or a removed line (i.e. only in the old version). Unfortunately, we don't know anything about the encoding of data in the file being diffed, so we cannot tell you much about the line content. Line data will not be NUL-byte terminated, however, because it will be just a span of bytes inside the larger file.