Skip to content

G
git2
Unverified Commit 7edc1c87 by Patrick Steinhardt Committed by GitHub
Options

Merge pull request #4788 from tiennou/doc-fixes 

Documentation fixes
parents 2054fe50 a4a028be
Showing with 153 additions and 112 deletions
include/git2/diff.h
......@@ -16,50 +16,6 @@
/**
* @file git2/diff.h
* @brief Git tree and file differencing routines.
*
* Overview
* --------
*
* Calculating diffs is generally done in two phases: building a list of
* diffs then traversing it. 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 post-processing phases,
* such as rename detection, in between the steps. When you are done with
* a diff object, it must be freed.
*
* Terminology
* -----------
*
* To understand the diff APIs, you should know the following terms:
*
* - A `diff` 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` 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 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.
*
* @ingroup Git
* @{
*/
......@@ -217,10 +173,22 @@ typedef enum {
/**
* The diff object that contains all individual file deltas.
*
* A `diff` represents the cumulative list of differences between two
* snapshots of a repository (possibly filtered by a set of file name
* patterns).
*
* Calculating diffs is generally done in two phases: building a list of
* diffs then traversing it. 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 post-processing phases,
* such as rename detection, in between the steps. When you are done with
* a diff object, it must be freed.
*
* This is an opaque structure which will be allocated by one of the diff
* generator functions below (such as `git_diff_tree_to_tree`). You are
* responsible for releasing the object memory when done, using the
* `git_diff_free()` function.
*
*/
typedef struct git_diff git_diff;
......@@ -301,6 +269,10 @@ typedef struct {
/**
* 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.
*
......@@ -346,7 +318,7 @@ typedef struct {
/**
* Diff notification callback function.
*
* The callback will be called for each file, just before the `git_delta_t`
* The callback will be called for each file, just before the `git_diff_delta`
* gets inserted into the diff.
*
* When the callback:
......@@ -385,46 +357,79 @@ typedef int (*git_diff_progress_cb)(
* values. Similarly, passing NULL for the options structure will
* give the defaults. The default values are marked below.
*
* - `flags` is a combination of the `git_diff_option_t` values above
* - `context_lines` is the number of unchanged lines that define the
* boundary of a hunk (and to display before and after)
* - `interhunk_lines` is the maximum number of unchanged lines between
* hunk boundaries before the hunks will be merged into a one.
* - `old_prefix` is the virtual "directory" to prefix to old file names
* in hunk headers (default "a")
* - `new_prefix` is the virtual "directory" to prefix to new file names
* in hunk headers (default "b")
* - `pathspec` is an array of paths / fnmatch patterns to constrain diff
* - `max_size` is a file size (in bytes) above which a blob will be marked
* as binary automatically; pass a negative value to disable.
* - `notify_cb` is an optional callback function, notifying the consumer of
* changes to the diff as new deltas are added.
* - `progress_cb` is an optional callback function, notifying the consumer of
* which files are being examined as the diff is generated.
* - `payload` is the payload to pass to the callback functions.
* - `ignore_submodules` overrides the submodule ignore setting for all
* submodules in the diff.
*/
typedef struct {
unsigned int version; /**< version for the struct */
uint32_t flags; /**< defaults to GIT_DIFF_NORMAL */
/**
* A combination of `git_diff_option_t` values above.
* Defaults to GIT_DIFF_NORMAL
*/
uint32_t flags;
/* options controlling which files are in the diff */
git_submodule_ignore_t ignore_submodules; /**< submodule ignore rule */
git_strarray pathspec; /**< defaults to include all paths */
/** Overrides the submodule ignore setting for all submodules in the diff. */
git_submodule_ignore_t ignore_submodules;
/**
* An array of paths / fnmatch patterns to constrain diff.
* All paths are included by default.
*/
git_strarray pathspec;
/**
* An optional callback function, notifying the consumer of changes to
* the diff as new deltas are added.
*/
git_diff_notify_cb notify_cb;
/**
* An optional callback function, notifying the consumer of which files
* are being examined as the diff is generated.
*/
git_diff_progress_cb progress_cb;
/** The payload to pass to the callback functions. */
void *payload;
/* options controlling how to diff text is generated */
uint32_t context_lines; /**< defaults to 3 */
uint32_t interhunk_lines; /**< defaults to 0 */
uint16_t id_abbrev; /**< default 'core.abbrev' or 7 if unset */
git_off_t max_size; /**< defaults to 512MB */
const char *old_prefix; /**< defaults to "a" */
const char *new_prefix; /**< defaults to "b" */
/**
* The number of unchanged lines that define the boundary of a hunk
* (and to display before and after). Defaults to 3.
*/
uint32_t context_lines;
/**
* The maximum number of unchanged lines between hunk boundaries before
* the hunks will be merged into one. Defaults to 0.
*/
uint32_t interhunk_lines;
/**
* The abbreviation length to use when formatting object ids.
* Defaults to the value of 'core.abbrev' from the config, or 7 if unset.
*/
uint16_t id_abbrev;
/**
* A size (in bytes) above which a blob will be marked as binary
* automatically; pass a negative value to disable.
* Defaults to 512MB.
*/
git_off_t max_size;
/**
* The virtual "directory" prefix for old file names in hunk headers.
* Default is "a".
*/
const char *old_prefix;
/**
* The virtual "directory" prefix for new file names in hunk headers.
* Defaults to "b".
*/
const char *new_prefix;
} git_diff_options;
/* The current version of the diff options structure */
......@@ -496,12 +501,21 @@ typedef struct {
size_t inflatedlen;
} git_diff_binary_file;
/** Structure describing the binary contents of a diff. */
/**
* Structure describing the binary contents of a diff.
*
* A `binary` file / delta is a file (or pair) for which no text diffs
* should be generated. A diff 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.
*/
typedef struct {
/**
* Whether there is data in this binary structure or not. If this
* is `1`, then this was produced and included binary content. If
* this is `0` then this was generated knowing only that a binary
* Whether there is data in this binary structure or not.
*
* If this is `1`, then this was produced and included binary content.
* If this is `0` then this was generated knowing only that a binary
* file changed but without providing the data, probably from a patch
* that said `Binary files a/file.txt and b/file.txt differ`.
*/
......@@ -511,9 +525,9 @@ typedef struct {
} git_diff_binary;
/**
* When iterating over a diff, callback that will be made for
* binary content within the diff.
*/
* When iterating over a diff, callback that will be made for
* binary content within the diff.
*/
typedef int(*git_diff_binary_cb)(
const git_diff_delta *delta,
const git_diff_binary *binary,
......@@ -521,6 +535,12 @@ typedef int(*git_diff_binary_cb)(
/**
* Structure describing a hunk of a diff.
*
* 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.
*/
typedef struct {
int old_start; /**< Starting line number in old_file */
......@@ -568,6 +588,14 @@ typedef enum {
/**
* Structure describing a line (or data span) of a diff.
*
* 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.
*/
typedef struct {
char origin; /**< A git_diff_line_t value */
......@@ -686,21 +714,6 @@ typedef struct {
* Control behavior of rename and copy detection
*
* These options mostly mimic parameters that can be passed to git-diff.
*
* - `rename_threshold` is the same as the -M option with a value
* - `copy_threshold` is the same as the -C option with a value
* - `rename_from_rewrite_threshold` matches the top of the -B option
* - `break_rewrite_threshold` matches the bottom of the -B option
* - `rename_limit` is the maximum number of matches to consider for
* a particular file. This is a little different from the `-l` option
* to regular Git because we will still process up to this many matches
* before abandoning the search.
*
* The `metric` option allows you to plug in a custom similarity metric.
* Set it to NULL for the default internal metric which is based on sampling
* hashes of ranges of data in the file. The default metric is a pretty
* good similarity approximation that should work fairly well for both text
* and binary data, and is pretty fast with fixed memory overhead.
*/
typedef struct {
unsigned int version;
......@@ -712,21 +725,49 @@ typedef struct {
*/
uint32_t flags;
/** Similarity to consider a file renamed (default 50) */
/**
* Threshold above which similar files will be considered renames.
* This is equivalent to the -M option. Defaults to 50.
*/
uint16_t rename_threshold;
/** Similarity of modified to be eligible rename source (default 50) */
/**
* Threshold below which similar files will be eligible to be a rename source.
* This is equivalent to the first part of the -B option. Defaults to 50.
*/
uint16_t rename_from_rewrite_threshold;
/** Similarity to consider a file a copy (default 50) */
/**
* Threshold above which similar files will be considered copies.
* This is equivalent to the -C option. Defaults to 50.
*/
uint16_t copy_threshold;
/** Similarity to split modify into delete/add pair (default 60) */
/**
* Treshold below which similar files will be split into a delete/add pair.
* This is equivalent to the last part of the -B option. Defaults to 60.
*/
uint16_t break_rewrite_threshold;
/** Maximum similarity sources to examine for a file (somewhat like
* git-diff's `-l` option or `diff.renameLimit` config) (default 200)
/**
* Maximum number of matches to consider for a particular file.
*
* This is a little different from the `-l` option from Git because we
* will still process up to this many matches before abandoning the search.
* Defaults to 200.
*/
size_t rename_limit;
/** Pluggable similarity metric; pass NULL to use internal metric */
/**
* The `metric` option allows you to plug in a custom similarity metric.
*
* Set it to NULL to use the default internal metric.
*
* The default metric is based on sampling hashes of ranges of data in
* the file, which is a pretty good similarity approximation that should
* work fairly well for both text and binary data while still being
* pretty fast with a fixed memory overhead.
*/
git_diff_similarity_metric *metric;
} git_diff_find_options;
......@@ -782,7 +823,7 @@ GIT_EXTERN(int) git_diff_tree_to_tree(
git_repository *repo,
git_tree *old_tree,
git_tree *new_tree,
const git_diff_options *opts); /**< can be NULL for defaults */
const git_diff_options *opts);
/**
* Create a diff between a tree and repository index.
......@@ -808,7 +849,7 @@ GIT_EXTERN(int) git_diff_tree_to_index(
git_repository *repo,
git_tree *old_tree,
git_index *index,
const git_diff_options *opts); /**< can be NULL for defaults */
const git_diff_options *opts);
/**
* Create a diff between the repository index and the workdir directory.
......@@ -834,7 +875,7 @@ GIT_EXTERN(int) git_diff_index_to_workdir(
git_diff **diff,
git_repository *repo,
git_index *index,
const git_diff_options *opts); /**< can be NULL for defaults */
const git_diff_options *opts);
/**
* Create a diff between a tree and the working directory.
......@@ -863,7 +904,7 @@ GIT_EXTERN(int) git_diff_tree_to_workdir(
git_diff **diff,
git_repository *repo,
git_tree *old_tree,
const git_diff_options *opts); /**< can be NULL for defaults */
const git_diff_options *opts);
/**
* Create a diff between a tree and the working directory using index data
......@@ -882,7 +923,7 @@ GIT_EXTERN(int) git_diff_tree_to_workdir_with_index(
git_diff **diff,
git_repository *repo,
git_tree *old_tree,
const git_diff_options *opts); /**< can be NULL for defaults */
const git_diff_options *opts);
/**
* Create a diff with the difference between two index objects.
......@@ -901,7 +942,7 @@ GIT_EXTERN(int) git_diff_index_to_index(
git_repository *repo,
git_index *old_index,
git_index *new_index,
const git_diff_options *opts); /**< can be NULL for defaults */
const git_diff_options *opts);
/**
* Merge one diff into another.
......@@ -1451,8 +1492,7 @@ GIT_EXTERN(int) git_diff_patchid_init_options(
* defined in git-patch-id(1), and should in fact generate the
* same IDs as the upstream git project does.
*
* @param out Pointer where the calculated patch ID shoul be
* stored
* @param out Pointer where the calculated patch ID should be stored
* @param diff The diff to calculate the ID for
* @param opts Options for how to calculate the patch ID. This is
* intended for future changes, as currently no options are
......
include/git2/errors.h
......@@ -27,7 +27,8 @@ typedef enum {
GIT_EAMBIGUOUS = -5, /**< More than one object matches */
GIT_EBUFS = -6, /**< Output buffer too short to hold data */
/* GIT_EUSER is a special error that is never generated by libgit2
/**
* GIT_EUSER is a special error that is never generated by libgit2
* code. You can return it from a callback (e.g to stop an iteration)
* to know that it was generated by the callback and not by libgit2.
*/
......
include/git2/remote.h
......@@ -643,7 +643,7 @@ typedef struct {
} git_push_options;
#define GIT_PUSH_OPTIONS_VERSION 1
#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 0, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
/**
* Initialize git_push_options structure
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment