diff options
author | Patrick Steinhardt <ps@pks.im> | 2018-08-30 12:51:05 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2018-08-30 12:51:05 +0200 |
commit | 7edc1c870e34647a5fad0f243331d0385b2cab5d (patch) | |
tree | 6e6499438c9efa9ba4bdef86dd23809df1c50573 | |
parent | 2054fe50ee8d3a8798e63acb7c603b273c5f79fc (diff) | |
parent | a4a028be7bc2523225c55a7a07f5d167e8d9b6e6 (diff) | |
download | libgit2-7edc1c870e34647a5fad0f243331d0385b2cab5d.tar.gz |
Merge pull request #4788 from tiennou/doc-fixes
Documentation fixes
-rw-r--r-- | include/git2/diff.h | 262 | ||||
-rw-r--r-- | include/git2/errors.h | 3 | ||||
-rw-r--r-- | include/git2/remote.h | 2 |
3 files changed, 154 insertions, 113 deletions
diff --git a/include/git2/diff.h b/include/git2/diff.h index 3d810f589..b64bf2013 100644 --- a/include/git2/diff.h +++ b/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 + * 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 diff --git a/include/git2/errors.h b/include/git2/errors.h index 676434f4a..c2a01de76 100644 --- a/include/git2/errors.h +++ b/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. */ diff --git a/include/git2/remote.h b/include/git2/remote.h index 757515d8a..f521fab78 100644 --- a/include/git2/remote.h +++ b/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 |