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.
When iterating over a diff, this will be passed to most callbacks and
you can use the contents to understand exactly what has changed.
The old_file represents the "from" side of the diff and the new_file
represents to "to" side of the diff. What those means depend on the
function that was used to generate the diff and will be documented below.
You can also use the git_diff_option_t.GIT_DIFF_REVERSE flag to flip it around.
Although the two sides of the delta are named "old_file" and "new_file",
they actually may correspond to entries that represent a file, a symbolic
link, a submodule commit id, or even a tree (if you are tracking type
changes or ignored/untracked directories).
Under some circumstances, in the name of efficiency, not all fields will
be filled in, but we generally try to fill in as much as possible. One
example is that the "flags" field may not have either the BINARY or the
NOT_BINARY flag set to avoid examining file contents if you do not pass
in hunk and/or line callbacks to the diff foreach iteration function. It
will just use the git attributes for those files.
The similarity score is zero unless you call git_diff_find_similar()
which does a similarity analysis of files in the diff. Use that
function to do rename and copy detection, and to split heavily modified
files in add/delete pairs. After that call, deltas with a status of
GIT_DELTA_RENAMED or GIT_DELTA_COPIED will have a similarity score
between 0 and 100 indicating how similar the old and new sides are.
If you ask git_diff_find_similar to find heavily modified files to
break, but to not *actually* break the records, then GIT_DELTA_MODIFIED
records may have a non-zero similarity score if the self-similarity is
below the split threshold. To display this value like core Git, invert
the score (a la printf("M%03d", 100 - delta->similarity)).
Description of changes to one entry.
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.
When iterating over a diff, this will be passed to most callbacks and you can use the contents to understand exactly what has changed.
The old_file represents the "from" side of the diff and the new_file represents to "to" side of the diff. What those means depend on the function that was used to generate the diff and will be documented below. You can also use the git_diff_option_t.GIT_DIFF_REVERSE flag to flip it around.
Although the two sides of the delta are named "old_file" and "new_file", they actually may correspond to entries that represent a file, a symbolic link, a submodule commit id, or even a tree (if you are tracking type changes or ignored/untracked directories).
Under some circumstances, in the name of efficiency, not all fields will be filled in, but we generally try to fill in as much as possible. One example is that the "flags" field may not have either the BINARY or the NOT_BINARY flag set to avoid examining file contents if you do not pass in hunk and/or line callbacks to the diff foreach iteration function. It will just use the git attributes for those files.
The similarity score is zero unless you call git_diff_find_similar() which does a similarity analysis of files in the diff. Use that function to do rename and copy detection, and to split heavily modified files in add/delete pairs. After that call, deltas with a status of GIT_DELTA_RENAMED or GIT_DELTA_COPIED will have a similarity score between 0 and 100 indicating how similar the old and new sides are.
If you ask git_diff_find_similar to find heavily modified files to break, but to not *actually* break the records, then GIT_DELTA_MODIFIED records may have a non-zero similarity score if the self-similarity is below the split threshold. To display this value like core Git, invert the score (a la printf("M%03d", 100 - delta->similarity)).