rugged 0.27.10 → 0.27.10.1

data/vendor/libgit2/include/git2/config.h

@@ -64,9 +64,8 @@ typedef enum {
 typedef struct git_config_entry {
 	const char *name; /**< Name of the entry (normalised) */
 	const char *value; /**< String value of the entry */
-	unsigned int include_depth; /**< Depth of includes where this variable was found */
 	git_config_level_t level; /**< Which config file this was found in */
-	void GIT_CALLBACK(free)(struct git_config_entry *entry); /**< Free function for this entry */
+	void (*free)(struct git_config_entry *entry); /**< Free function for this entry */
 	void *payload; /**< Opaque value for the free function. Do not read or write */
 } git_config_entry;
 
@@ -75,37 +74,27 @@ typedef struct git_config_entry {
  */
 GIT_EXTERN(void) git_config_entry_free(git_config_entry *);
 
-/**
- * A config enumeration callback
- *
- * @param entry the entry currently being enumerated
- * @param payload a user-specified pointer
- */
-typedef int GIT_CALLBACK(git_config_foreach_cb)(const git_config_entry *entry, void *payload);
-
-/**
- * An opaque structure for a configuration iterator
- */
+typedef int  (*git_config_foreach_cb)(const git_config_entry *, void *);
 typedef struct git_config_iterator git_config_iterator;
 
 /**
  * Config var type
  */
 typedef enum {
-	GIT_CONFIGMAP_FALSE = 0,
-	GIT_CONFIGMAP_TRUE = 1,
-	GIT_CONFIGMAP_INT32,
-	GIT_CONFIGMAP_STRING
-} git_configmap_t;
+	GIT_CVAR_FALSE = 0,
+	GIT_CVAR_TRUE = 1,
+	GIT_CVAR_INT32,
+	GIT_CVAR_STRING
+} git_cvar_t;
 
 /**
  * Mapping from config variables to values.
  */
 typedef struct {
-	git_configmap_t type;
+	git_cvar_t cvar_type;
 	const char *str_match;
 	int map_value;
-} git_configmap;
+} git_cvar_map;
 
 /**
  * Locate the path to the global configuration file
@@ -262,7 +251,7 @@ GIT_EXTERN(int) git_config_open_level(
  * Open the global/XDG configuration file according to git's rules
  *
  * Git allows you to store your global configuration at
- * `$HOME/.gitconfig` or `$XDG_CONFIG_HOME/git/config`. For backwards
+ * `$HOME/.config` or `$XDG_CONFIG_HOME/git/config`. For backwards
  * compatability, the XDG file shouldn't be used unless the use has
  * created it explicitly. With this function you'll open the correct
  * one to write to.
@@ -591,7 +580,7 @@ GIT_EXTERN(int) git_config_iterator_glob_new(git_config_iterator **out, const gi
 /**
  * Perform an operation on each config variable matching a regular expression.
  *
- * This behaves like `git_config_foreach` with an additional filter of a
+ * This behaviors like `git_config_foreach` with an additional filter of a
  * regular expression that filters which config keys are passed to the
  * callback.
  *
@@ -623,7 +612,7 @@ GIT_EXTERN(int) git_config_foreach_match(
  *
  * A mapping array looks as follows:
  *
- *	git_configmap autocrlf_mapping[] = {
+ *	git_cvar_map autocrlf_mapping[] = {
  *		{GIT_CVAR_FALSE, NULL, GIT_AUTO_CRLF_FALSE},
  *		{GIT_CVAR_TRUE, NULL, GIT_AUTO_CRLF_TRUE},
  *		{GIT_CVAR_STRING, "input", GIT_AUTO_CRLF_INPUT},
@@ -644,7 +633,7 @@ GIT_EXTERN(int) git_config_foreach_match(
  * @param out place to store the result of the mapping
  * @param cfg config file to get the variables from
  * @param name name of the config variable to lookup
- * @param maps array of `git_configmap` objects specifying the possible mappings
+ * @param maps array of `git_cvar_map` objects specifying the possible mappings
  * @param map_n number of mapping objects in `maps`
  * @return 0 on success, error code otherwise
  */
@@ -652,20 +641,20 @@ GIT_EXTERN(int) git_config_get_mapped(
 	int *out,
 	const git_config *cfg,
 	const char *name,
-	const git_configmap *maps,
+	const git_cvar_map *maps,
 	size_t map_n);
 
 /**
  * Maps a string value to an integer constant
  *
  * @param out place to store the result of the parsing
- * @param maps array of `git_configmap` objects specifying the possible mappings
+ * @param maps array of `git_cvar_map` objects specifying the possible mappings
  * @param map_n number of mapping objects in `maps`
  * @param value value to parse
  */
 GIT_EXTERN(int) git_config_lookup_map_value(
 	int *out,
-	const git_configmap *maps,
+	const git_cvar_map *maps,
 	size_t map_n,
 	const char *value);
 
@@ -721,11 +710,11 @@ GIT_EXTERN(int) git_config_parse_int64(int64_t *out, const char *value);
 GIT_EXTERN(int) git_config_parse_path(git_buf *out, const char *value);
 
 /**
- * Perform an operation on each config variable in a given config backend,
+ * Perform an operation on each config variable in given config backend
  * matching a regular expression.
  *
- * This behaves like `git_config_foreach_match` except that only config
- * entries from the given backend entry are enumerated.
+ * This behaviors like `git_config_foreach_match` except instead of all config
+ * entries it just enumerates through the given backend entry.
  *
  * The regular expression is applied case-sensitively on the normalized form of
  * the variable name: the section and variable parts are lower-cased. The

data/vendor/libgit2/include/git2/describe.h

@@ -36,9 +36,10 @@ typedef enum {
 /**
  * Describe options structure
  *
- * Initialize with `GIT_DESCRIBE_OPTIONS_INIT`. Alternatively, you can
- * use `git_describe_options_init`.
+ * Initialize with `GIT_DESCRIBE_OPTIONS_INIT` macro to correctly set
+ * the `version` field.  E.g.
  *
+ *		git_describe_options opts = GIT_DESCRIBE_OPTIONS_INIT;
  */
 typedef struct git_describe_options {
 	unsigned int version;
@@ -69,24 +70,10 @@ typedef struct git_describe_options {
 	GIT_DESCRIBE_DEFAULT_MAX_CANDIDATES_TAGS, \
 }
 
-/**
- * Initialize git_describe_options structure
- *
- * Initializes a `git_describe_options` with default values. Equivalent to creating
- * an instance with GIT_DESCRIBE_OPTIONS_INIT.
- *
- * @param opts The `git_describe_options` struct to initialize.
- * @param version The struct version; pass `GIT_DESCRIBE_OPTIONS_VERSION`.
- * @return Zero on success; -1 on failure.
- */
-GIT_EXTERN(int) git_describe_options_init(git_describe_options *opts, unsigned int version);
+GIT_EXTERN(int) git_describe_init_options(git_describe_options *opts, unsigned int version);
 
 /**
- * Describe format options structure
- *
- * Initialize with `GIT_DESCRIBE_FORMAT_OPTIONS_INIT`. Alternatively, you can
- * use `git_describe_format_options_init`.
- *
+ * Options for formatting the describe string
  */
 typedef struct {
 	unsigned int version;
@@ -116,17 +103,7 @@ typedef struct {
 		GIT_DESCRIBE_DEFAULT_ABBREVIATED_SIZE, \
  }
 
-/**
- * Initialize git_describe_format_options structure
- *
- * Initializes a `git_describe_format_options` with default values. Equivalent to creating
- * an instance with GIT_DESCRIBE_FORMAT_OPTIONS_INIT.
- *
- * @param opts The `git_describe_format_options` struct to initialize.
- * @param version The struct version; pass `GIT_DESCRIBE_FORMAT_OPTIONS_VERSION`.
- * @return Zero on success; -1 on failure.
- */
-GIT_EXTERN(int) git_describe_format_options_init(git_describe_format_options *opts, unsigned int version);
+GIT_EXTERN(int) git_describe_init_format_options(git_describe_format_options *opts, unsigned int version);
 
 /**
  * A struct that stores the result of a describe operation.
@@ -141,7 +118,7 @@ typedef struct git_describe_result git_describe_result;
  * @param result pointer to store the result. You must free this once
  * you're done with it.
  * @param committish a committish to describe
- * @param opts the lookup options (or NULL for defaults)
+ * @param opts the lookup options
  */
 GIT_EXTERN(int) git_describe_commit(
 	git_describe_result **result,
@@ -158,7 +135,7 @@ GIT_EXTERN(int) git_describe_commit(
  * @param out pointer to store the result. You must free this once
  * you're done with it.
  * @param repo the repository in which to perform the describe
- * @param opts the lookup options (or NULL for defaults)
+ * @param opts the lookup options
  */
 GIT_EXTERN(int) git_describe_workdir(
 	git_describe_result **out,
@@ -171,7 +148,7 @@ GIT_EXTERN(int) git_describe_workdir(
  * @param out The buffer to store the result
  * @param result the result from `git_describe_commit()` or
  * `git_describe_workdir()`.
- * @param opts the formatting options (or NULL for defaults)
+ * @param opts the formatting options
  */
 GIT_EXTERN(int) git_describe_format(
 	git_buf *out,

data/vendor/libgit2/include/git2/diff.h

@@ -16,6 +16,50 @@
 /**
  * @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
  * @{
  */
@@ -119,7 +163,7 @@ typedef enum {
 
 	/** Include unreadable files in the diff */
 	GIT_DIFF_INCLUDE_UNREADABLE = (1u << 16),
-
+	
 	/** Include unreadable files in the diff */
 	GIT_DIFF_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 17),
 
@@ -127,12 +171,6 @@ typedef enum {
 	 * Options controlling how output will be generated
 	 */
 
-	/** Use a heuristic that takes indentation and whitespace into account
-	 * which generally can produce better diffs when dealing with ambiguous
-	 * diff hunks.
-	 */
-	GIT_DIFF_INDENT_HEURISTIC = (1u << 18),
-
 	/** Treat all files as text, disabling binary attributes & detection */
 	GIT_DIFF_FORCE_TEXT = (1u << 20),
 	/** Treat all files as binary, disabling text diffs */
@@ -168,27 +206,21 @@ typedef enum {
 	 *  can apply given diff information to binary files.
 	 */
 	GIT_DIFF_SHOW_BINARY = (1u << 30),
+
+	/** Use a heuristic that takes indentation and whitespace into account
+	 * which generally can produce better diffs when dealing with ambiguous
+	 * diff hunks.
+	 */
+	GIT_DIFF_INDENT_HEURISTIC = (1u << 31),
 } git_diff_option_t;
 
 /**
  * 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;
 
@@ -258,21 +290,17 @@ typedef enum {
  * abbreviated to something reasonable, like 7 characters.
  */
 typedef struct {
-	git_oid            id;
-	const char        *path;
-	git_object_size_t  size;
-	uint32_t           flags;
-	uint16_t           mode;
-	uint16_t           id_abbrev;
+	git_oid     id;
+	const char *path;
+	git_off_t   size;
+	uint32_t    flags;
+	uint16_t    mode;
+	uint16_t    id_abbrev;
 } git_diff_file;
 
 /**
  * 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.
  *
@@ -318,7 +346,7 @@ typedef struct {
 /**
  * Diff notification callback function.
  *
- * The callback will be called for each file, just before the `git_diff_delta`
+ * The callback will be called for each file, just before the `git_delta_t`
  * gets inserted into the diff.
  *
  * When the callback:
@@ -328,7 +356,7 @@ typedef struct {
  * - returns 0, the delta is inserted into the diff, and the diff process
  *		continues.
  */
-typedef int GIT_CALLBACK(git_diff_notify_cb)(
+typedef int (*git_diff_notify_cb)(
 	const git_diff *diff_so_far,
 	const git_diff_delta *delta_to_add,
 	const char *matched_pathspec,
@@ -344,7 +372,7 @@ typedef int GIT_CALLBACK(git_diff_notify_cb)(
  * @param new_path The path to the new file or NULL.
  * @return Non-zero to abort the diff.
  */
-typedef int GIT_CALLBACK(git_diff_progress_cb)(
+typedef int (*git_diff_progress_cb)(
 	const git_diff *diff_so_far,
 	const char *old_path,
 	const char *new_path,
@@ -357,79 +385,46 @@ typedef int GIT_CALLBACK(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 */
-
-	/**
-	 * A combination of `git_diff_option_t` values above.
-	 * Defaults to GIT_DIFF_NORMAL
-	 */
-	uint32_t flags;
+	uint32_t flags;            /**< defaults to GIT_DIFF_NORMAL */
 
 	/* options controlling which files are in the diff */
 
-	/** 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_submodule_ignore_t ignore_submodules; /**< submodule ignore rule */
+	git_strarray       pathspec;     /**< defaults to include all paths */
 	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 */
 
-	/**
-	 * 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;
+	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" */
 } git_diff_options;
 
 /* The current version of the diff options structure */
@@ -442,16 +437,14 @@ typedef struct {
 	{GIT_DIFF_OPTIONS_VERSION, 0, GIT_SUBMODULE_IGNORE_UNSPECIFIED, {NULL,0}, NULL, NULL, NULL, 3}
 
 /**
- * Initialize git_diff_options structure
- *
- * Initializes a `git_diff_options` with default values. Equivalent to creating
- * an instance with GIT_DIFF_OPTIONS_INIT.
+ * Initializes a `git_diff_options` with default values. Equivalent to
+ * creating an instance with GIT_DIFF_OPTIONS_INIT.
  *
- * @param opts The `git_diff_options` struct to initialize.
- * @param version The struct version; pass `GIT_DIFF_OPTIONS_VERSION`.
+ * @param opts The `git_diff_options` struct to initialize
+ * @param version Version of struct; pass `GIT_DIFF_OPTIONS_VERSION`
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_diff_options_init(
+GIT_EXTERN(int) git_diff_init_options(
 	git_diff_options *opts,
 	unsigned int version);
 
@@ -462,7 +455,7 @@ GIT_EXTERN(int) git_diff_options_init(
  * @param progress Goes from 0 to 1 over the diff
  * @param payload User-specified pointer from foreach function
  */
-typedef int GIT_CALLBACK(git_diff_file_cb)(
+typedef int (*git_diff_file_cb)(
 	const git_diff_delta *delta,
 	float progress,
 	void *payload);
@@ -501,21 +494,12 @@ typedef struct {
 	size_t inflatedlen;
 } git_diff_binary_file;
 
-/**
- * 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.
- */
+/** Structure describing the binary contents of a diff. */
 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`.
 	 */
@@ -525,22 +509,16 @@ typedef struct {
 } git_diff_binary;
 
 /**
- * When iterating over a diff, callback that will be made for
- * binary content within the diff.
- */
-typedef int GIT_CALLBACK(git_diff_binary_cb)(
+* 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,
 	void *payload);
 
 /**
  * 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 */
@@ -554,7 +532,7 @@ typedef struct {
 /**
  * When iterating over a diff, callback that will be made per hunk.
  */
-typedef int GIT_CALLBACK(git_diff_hunk_cb)(
+typedef int (*git_diff_hunk_cb)(
 	const git_diff_delta *delta,
 	const git_diff_hunk *hunk,
 	void *payload);
@@ -588,14 +566,6 @@ 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 */
@@ -615,7 +585,7 @@ typedef struct {
  * of text.  This uses some extra GIT_DIFF_LINE_... constants for output
  * of lines of file and hunk headers.
  */
-typedef int GIT_CALLBACK(git_diff_line_cb)(
+typedef int (*git_diff_line_cb)(
 	const git_diff_delta *delta, /**< delta that contains this data */
 	const git_diff_hunk *hunk,   /**< hunk containing this data */
 	const git_diff_line *line,   /**< line data */
@@ -699,14 +669,14 @@ typedef enum {
  * Pluggable similarity metric
  */
 typedef struct {
-	int GIT_CALLBACK(file_signature)(
+	int (*file_signature)(
 		void **out, const git_diff_file *file,
 		const char *fullpath, void *payload);
-	int GIT_CALLBACK(buffer_signature)(
+	int (*buffer_signature)(
 		void **out, const git_diff_file *file,
 		const char *buf, size_t buflen, void *payload);
-	void GIT_CALLBACK(free_signature)(void *sig, void *payload);
-	int GIT_CALLBACK(similarity)(int *score, void *siga, void *sigb, void *payload);
+	void (*free_signature)(void *sig, void *payload);
+	int (*similarity)(int *score, void *siga, void *sigb, void *payload);
 	void *payload;
 } git_diff_similarity_metric;
 
@@ -714,6 +684,21 @@ 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;
@@ -725,49 +710,21 @@ typedef struct {
 	 */
 	uint32_t flags;
 
-	/**
-	 * Threshold above which similar files will be considered renames.
-	 * This is equivalent to the -M option. Defaults to 50.
-	 */
+	/** Similarity to consider a file renamed (default 50) */
 	uint16_t rename_threshold;
-
-	/**
-	 * 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.
-	 */
+	/** Similarity of modified to be eligible rename source (default 50) */
 	uint16_t rename_from_rewrite_threshold;
-
-	/**
-	 * Threshold above which similar files will be considered copies.
-	 * This is equivalent to the -C option. Defaults to 50.
-	 */
+	/** Similarity to consider a file a copy (default 50) */
 	uint16_t copy_threshold;
-
-	/**
-	 * 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.
-	 */
+	/** Similarity to split modify into delete/add pair (default 60) */
 	uint16_t break_rewrite_threshold;
 
-	/**
-	 * 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.
+	/** Maximum similarity sources to examine for a file (somewhat like
+	 *  git-diff's `-l` option or `diff.renameLimit` config) (default 200)
 	 */
 	size_t rename_limit;
 
-	/**
-	 * 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.
-	 */
+	/** Pluggable similarity metric; pass NULL to use internal metric */
 	git_diff_similarity_metric *metric;
 } git_diff_find_options;
 
@@ -775,16 +732,14 @@ typedef struct {
 #define GIT_DIFF_FIND_OPTIONS_INIT {GIT_DIFF_FIND_OPTIONS_VERSION}
 
 /**
- * Initialize git_diff_find_options structure
- *
- * Initializes a `git_diff_find_options` with default values. Equivalent to creating
- * an instance with GIT_DIFF_FIND_OPTIONS_INIT.
+ * Initializes a `git_diff_find_options` with default values. Equivalent to
+ * creating an instance with GIT_DIFF_FIND_OPTIONS_INIT.
  *
- * @param opts The `git_diff_find_options` struct to initialize.
- * @param version The struct version; pass `GIT_DIFF_FIND_OPTIONS_VERSION`.
+ * @param opts The `git_diff_find_options` struct to initialize
+ * @param version Version of struct; pass `GIT_DIFF_FIND_OPTIONS_VERSION`
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_diff_find_options_init(
+GIT_EXTERN(int) git_diff_find_init_options(
 	git_diff_find_options *opts,
 	unsigned int version);
 
@@ -823,7 +778,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);
+	const git_diff_options *opts); /**< can be NULL for defaults */
 
 /**
  * Create a diff between a tree and repository index.
@@ -849,7 +804,7 @@ GIT_EXTERN(int) git_diff_tree_to_index(
 	git_repository *repo,
 	git_tree *old_tree,
 	git_index *index,
-	const git_diff_options *opts);
+	const git_diff_options *opts); /**< can be NULL for defaults */
 
 /**
  * Create a diff between the repository index and the workdir directory.
@@ -875,7 +830,7 @@ GIT_EXTERN(int) git_diff_index_to_workdir(
 	git_diff **diff,
 	git_repository *repo,
 	git_index *index,
-	const git_diff_options *opts);
+	const git_diff_options *opts); /**< can be NULL for defaults */
 
 /**
  * Create a diff between a tree and the working directory.
@@ -904,7 +859,7 @@ GIT_EXTERN(int) git_diff_tree_to_workdir(
 	git_diff **diff,
 	git_repository *repo,
 	git_tree *old_tree,
-	const git_diff_options *opts);
+	const git_diff_options *opts); /**< can be NULL for defaults */
 
 /**
  * Create a diff between a tree and the working directory using index data
@@ -923,7 +878,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);
+	const git_diff_options *opts); /**< can be NULL for defaults */
 
 /**
  * Create a diff with the difference between two index objects.
@@ -942,7 +897,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);
+	const git_diff_options *opts); /**< can be NULL for defaults */
 
 /**
  * Merge one diff into another.
@@ -1093,7 +1048,6 @@ typedef enum {
 	GIT_DIFF_FORMAT_RAW          = 3u, /**< like git diff --raw */
 	GIT_DIFF_FORMAT_NAME_ONLY    = 4u, /**< like git diff --name-only */
 	GIT_DIFF_FORMAT_NAME_STATUS  = 5u, /**< like git diff --name-status */
-	GIT_DIFF_FORMAT_PATCH_ID     = 6u, /**< git diff as used by git patch-id */
 } git_diff_format_t;
 
 /**
@@ -1379,8 +1333,7 @@ typedef enum {
 typedef struct {
 	unsigned int version;
 
-	/** see `git_diff_format_email_flags_t` above */
-	uint32_t flags;
+	git_diff_format_email_flags_t flags;
 
 	/** This patch number */
 	size_t patch_no;
@@ -1437,29 +1390,27 @@ GIT_EXTERN(int) git_diff_commit_as_email(
 	git_commit *commit,
 	size_t patch_no,
 	size_t total_patches,
-	uint32_t flags,
+	git_diff_format_email_flags_t flags,
 	const git_diff_options *diff_opts);
 
 /**
- * Initialize git_diff_format_email_options structure
+ * Initializes a `git_diff_format_email_options` with default values.
  *
- * Initializes a `git_diff_format_email_options` with default values. Equivalent
- * to creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT.
+ * Equivalent to creating an instance with GIT_DIFF_FORMAT_EMAIL_OPTIONS_INIT.
  *
- * @param opts The `git_blame_options` struct to initialize.
- * @param version The struct version; pass `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION`.
+ * @param opts The `git_diff_format_email_options` struct to initialize
+ * @param version Version of struct; pass `GIT_DIFF_FORMAT_EMAIL_OPTIONS_VERSION`
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_diff_format_email_options_init(
+GIT_EXTERN(int) git_diff_format_email_init_options(
 	git_diff_format_email_options *opts,
 	unsigned int version);
 
 /**
  * Patch ID options structure
  *
- * Initialize with `GIT_PATCHID_OPTIONS_INIT`. Alternatively, you can
- * use `git_diff_patchid_options_init`.
- *
+ * Initialize with `GIT_DIFF_PATCHID_OPTIONS_INIT` macro to
+ * correctly set the default values and version.
  */
 typedef struct git_diff_patchid_options {
 	unsigned int version;
@@ -1469,16 +1420,12 @@ typedef struct git_diff_patchid_options {
 #define GIT_DIFF_PATCHID_OPTIONS_INIT { GIT_DIFF_PATCHID_OPTIONS_VERSION }
 
 /**
- * Initialize git_diff_patchid_options structure
+ * Initialize `git_diff_patchid_options` structure.
  *
- * Initializes a `git_diff_patchid_options` with default values. Equivalent to
+ * Initializes the structure with default values. Equivalent to
  * creating an instance with `GIT_DIFF_PATCHID_OPTIONS_INIT`.
- *
- * @param opts The `git_diff_patchid_options` struct to initialize.
- * @param version The struct version; pass `GIT_DIFF_PATCHID_OPTIONS_VERSION`.
- * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_diff_patchid_options_init(
+GIT_EXTERN(int) git_diff_patchid_init_options(
 	git_diff_patchid_options *opts,
 	unsigned int version);
 
@@ -1494,7 +1441,8 @@ GIT_EXTERN(int) git_diff_patchid_options_init(
  * 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 should be stored
+ * @param out Pointer where the calculated patch ID shoul 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