Merge remote-tracking branch 'origin/main' into cgraph-write

11 files changed, 441 insertions, 137 deletions

diff --git a/include/git2/attr.h b/include/git2/attr.h
index a3ab5a7a2..62c2ed6e7 100644
--- a/include/git2/attr.h
+++ b/include/git2/attr.h
@@ -130,9 +130,32 @@ GIT_EXTERN(git_attr_value_t) git_attr_value(const char *attr);
  *
  * Passing the `GIT_ATTR_CHECK_INCLUDE_HEAD` flag will use attributes
  * from a `.gitattributes` file in the repository at the HEAD revision.
+ *
+ * Passing the `GIT_ATTR_CHECK_INCLUDE_COMMIT` flag will use attributes
+ * from a `.gitattributes` file in a specific commit.
  */
 #define GIT_ATTR_CHECK_NO_SYSTEM        (1 << 2)
 #define GIT_ATTR_CHECK_INCLUDE_HEAD     (1 << 3)
+#define GIT_ATTR_CHECK_INCLUDE_COMMIT   (1 << 4)
+
+/**
+* An options structure for querying attributes.
+*/
+typedef struct {
+	unsigned int version;
+
+	/** A combination of GIT_ATTR_CHECK flags */
+	unsigned int flags;
+
+	/**
+	 * The commit to load attributes from, when
+	 * `GIT_ATTR_CHECK_INCLUDE_COMMIT` is specified.
+	 */
+	git_oid *commit_id;
+} git_attr_options;
+
+#define GIT_ATTR_OPTIONS_VERSION 1
+#define GIT_ATTR_OPTIONS_INIT {GIT_ATTR_OPTIONS_VERSION}
 
 /**
  * Look up the value of one git attribute for path.
@@ -157,6 +180,28 @@ GIT_EXTERN(int) git_attr_get(
 	const char *name);
 
 /**
+ * Look up the value of one git attribute for path with extended options.
+ *
+ * @param value_out Output of the value of the attribute.  Use the GIT_ATTR_...
+ *             macros to test for TRUE, FALSE, UNSPECIFIED, etc. or just
+ *             use the string value for attributes set to a value.  You
+ *             should NOT modify or free this value.
+ * @param repo The repository containing the path.
+ * @param opts The `git_attr_options` to use when querying these attributes.
+ * @param path The path to check for attributes.  Relative paths are
+ *             interpreted relative to the repo root.  The file does
+ *             not have to exist, but if it does not, then it will be
+ *             treated as a plain file (not a directory).
+ * @param name The name of the attribute to look up.
+ */
+GIT_EXTERN(int) git_attr_get_ext(
+	const char **value_out,
+	git_repository *repo,
+	git_attr_options *opts,
+	const char *path,
+	const char *name);
+
+/**
  * Look up a list of git attributes for path.
  *
  * Use this if you have a known list of attributes that you want to
@@ -194,6 +239,30 @@ GIT_EXTERN(int) git_attr_get_many(
 	const char **names);
 
 /**
+ * Look up a list of git attributes for path with extended options.
+ *
+ * @param values_out An array of num_attr entries that will have string
+ *             pointers written into it for the values of the attributes.
+ *             You should not modify or free the values that are written
+ *             into this array (although of course, you should free the
+ *             array itself if you allocated it).
+ * @param repo The repository containing the path.
+ * @param opts The `git_attr_options` to use when querying these attributes.
+ * @param path The path inside the repo to check attributes.  This
+ *             does not have to exist, but if it does not, then
+ *             it will be treated as a plain file (i.e. not a directory).
+ * @param num_attr The number of attributes being looked up
+ * @param names An array of num_attr strings containing attribute names.
+ */
+GIT_EXTERN(int) git_attr_get_many_ext(
+	const char **values_out,
+	git_repository *repo,
+	git_attr_options *opts,
+	const char *path,
+	size_t num_attr,
+	const char **names);
+
+/**
  * The callback used with git_attr_foreach.
  *
  * This callback will be invoked only once per attribute name, even if there
@@ -232,6 +301,26 @@ GIT_EXTERN(int) git_attr_foreach(
 	void *payload);
 
 /**
+ * Loop over all the git attributes for a path with extended options.
+ *
+ * @param repo The repository containing the path.
+ * @param opts The `git_attr_options` to use when querying these attributes.
+ * @param path Path inside the repo to check attributes.  This does not have
+ *             to exist, but if it does not, then it will be treated as a
+ *             plain file (i.e. not a directory).
+ * @param callback Function to invoke on each attribute name and value.
+ *                 See git_attr_foreach_cb.
+ * @param payload Passed on as extra parameter to callback function.
+ * @return 0 on success, non-zero callback return value, or error code
+ */
+GIT_EXTERN(int) git_attr_foreach_ext(
+	git_repository *repo,
+	git_attr_options *opts,
+	const char *path,
+	git_attr_foreach_cb callback,
+	void *payload);
+
+/**
  * Flush the gitattributes cache.
  *
  * Call this if you have reason to believe that the attributes files on
diff --git a/include/git2/blame.h b/include/git2/blame.h
index f42c81552..d193ce14e 100644
--- a/include/git2/blame.h
+++ b/include/git2/blame.h
@@ -26,27 +26,52 @@ GIT_BEGIN_DECL
 typedef enum {
 	/** Normal blame, the default */
 	GIT_BLAME_NORMAL = 0,
-	/** Track lines that have moved within a file (like `git blame -M`).
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have moved within a file (like `git blame -M`).
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_SAME_FILE = (1<<0),
-	/** Track lines that have moved across files in the same commit (like `git blame -C`).
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have moved across files in the same commit
+	 * (like `git blame -C`).
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_SAME_COMMIT_MOVES = (1<<1),
-	/** Track lines that have been copied from another file that exists in the
-	 * same commit (like `git blame -CC`). Implies SAME_FILE.
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have been copied from another file that exists
+	 * in the same commit (like `git blame -CC`).  Implies SAME_FILE.
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_SAME_COMMIT_COPIES = (1<<2),
-	/** Track lines that have been copied from another file that exists in *any*
-	 * commit (like `git blame -CCC`). Implies SAME_COMMIT_COPIES.
-	 * NOT IMPLEMENTED. */
+
+	/**
+	 * Track lines that have been copied from another file that exists in
+	 * *any* commit (like `git blame -CCC`).  Implies SAME_COMMIT_COPIES.
+	 *
+	 * This is not yet implemented and reserved for future use.
+	 */
 	GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES = (1<<3),
-	/** Restrict the search of commits to those reachable following only the
-	 * first parents. */
+
+	/**
+	 * Restrict the search of commits to those reachable following only
+	 * the first parents.
+	 */
 	GIT_BLAME_FIRST_PARENT = (1<<4),
-	/** Use mailmap file to map author and committer names and email addresses
-	 * to canonical real names and email addresses. The mailmap will be read
-	 * from the working directory, or HEAD in a bare repository. */
+
+	/**
+	 * Use mailmap file to map author and committer names and email
+	 * addresses to canonical real names and email addresses. The
+	 * mailmap will be read from the working directory, or HEAD in a
+	 * bare repository.
+	 */
 	GIT_BLAME_USE_MAILMAP = (1<<5),
+
 	/** Ignore whitespace differences */
 	GIT_BLAME_IGNORE_WHITESPACE = (1<<6),
 } git_blame_flag_t;
@@ -63,25 +88,33 @@ typedef struct git_blame_options {
 
 	/** A combination of `git_blame_flag_t` */
 	uint32_t flags;
-	/** The lower bound on the number of alphanumeric
-	 *   characters that must be detected as moving/copying within a file for it to
-	 *   associate those lines with the parent commit. The default value is 20.
-	 *   This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
-	 *   flags are specified.
+
+	/**
+	 * The lower bound on the number of alphanumeric characters that
+	 * must be detected as moving/copying within a file for it to
+	 * associate those lines with the parent commit. The default value
+	 * is 20.
+	 *
+	 * This value only takes effect if any of the `GIT_BLAME_TRACK_COPIES_*`
+	 * flags are specified.
 	 */
 	uint16_t min_match_characters;
+
 	/** The id of the newest commit to consider. The default is HEAD. */
 	git_oid newest_commit;
+
 	/**
 	 * The id of the oldest commit to consider.
 	 * The default is the first commit encountered with a NULL parent.
 	 */
 	git_oid oldest_commit;
+
 	/**
 	 * The first line in the file to blame.
 	 * The default is 1 (line numbers start with 1).
 	 */
 	size_t min_line;
+
 	/**
 	 * The last line in the file to blame.
 	 * The default is the last line of the file.
@@ -108,41 +141,59 @@ GIT_EXTERN(int) git_blame_options_init(
 
 /**
  * Structure that represents a blame hunk.
- *
- * - `lines_in_hunk` is the number of lines in this hunk
- * - `final_commit_id` is the OID of the commit where this line was last
- *   changed.
- * - `final_start_line_number` is the 1-based line number where this hunk
- *   begins, in the final version of the file
- * - `final_signature` is the author of `final_commit_id`. If
- *   `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical
- *    real name and email address.
- * - `orig_commit_id` is the OID of the commit where this hunk was found.  This
- *   will usually be the same as `final_commit_id`, except when
- *   `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified.
- * - `orig_path` is the path to the file where this hunk originated, as of the
- *   commit specified by `orig_commit_id`.
- * - `orig_start_line_number` is the 1-based line number where this hunk begins
- *   in the file named by `orig_path` in the commit specified by
- *   `orig_commit_id`.
- * - `orig_signature` is the author of `orig_commit_id`. If
- *   `GIT_BLAME_USE_MAILMAP` has been specified, it will contain the canonical
- *    real name and email address.
- * - `boundary` is 1 iff the hunk has been tracked to a boundary commit (the
- *   root, or the commit specified in git_blame_options.oldest_commit)
  */
 typedef struct git_blame_hunk {
+	/**
+	 * The number of lines in this hunk.
+	 */
 	size_t lines_in_hunk;
 
+	/**
+	 * The OID of the commit where this line was last changed.
+	 */
 	git_oid final_commit_id;
+
+	/**
+	 * The 1-based line number where this hunk begins, in the final version
+	 * of the file.
+	 */
 	size_t final_start_line_number;
+
+	/**
+	 * The author of `final_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been
+	 * specified, it will contain the canonical real name and email address.
+	 */
 	git_signature *final_signature;
 
+	/**
+	 * The OID of the commit where this hunk was found.
+	 * This will usually be the same as `final_commit_id`, except when
+	 * `GIT_BLAME_TRACK_COPIES_ANY_COMMIT_COPIES` has been specified.
+	 */
 	git_oid orig_commit_id;
+
+	/**
+	 * The path to the file where this hunk originated, as of the commit
+	 * specified by `orig_commit_id`.
+	 */
 	const char *orig_path;
+
+	/**
+	 * The 1-based line number where this hunk begins in the file named by
+	 * `orig_path` in the commit specified by `orig_commit_id`.
+	 */
 	size_t orig_start_line_number;
+
+	/**
+	 * The author of `orig_commit_id`. If `GIT_BLAME_USE_MAILMAP` has been
+	 * specified, it will contain the canonical real name and email address.
+	 */
 	git_signature *orig_signature;
 
+	/**
+	 * The 1 iff the hunk has been tracked to a boundary commit (the root,
+	 * or the commit specified in git_blame_options.oldest_commit)
+	 */
 	char boundary;
 } git_blame_hunk;
 
diff --git a/include/git2/blob.h b/include/git2/blob.h
index 3f6738675..fceb5c771 100644
--- a/include/git2/blob.h
+++ b/include/git2/blob.h
@@ -114,6 +114,12 @@ typedef enum {
 	 * in the HEAD commit.
 	 */
 	GIT_BLOB_FILTER_ATTRIBUTES_FROM_HEAD = (1 << 2),
+
+	/**
+	 * When set, filters will be loaded from a `.gitattributes` file
+	 * in the specified commit.
+	 */
+	GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT = (1 << 3),
 } git_blob_filter_flag_t;
 
 /**
@@ -128,6 +134,12 @@ typedef struct {
 
 	/** Flags to control the filtering process, see `git_blob_filter_flag_t` above */
 	uint32_t flags;
+
+	/**
+	 * The commit to load attributes from, when
+	 * `GIT_BLOB_FILTER_ATTRIBUTES_FROM_COMMIT` is specified.
+	 */
+	git_oid *commit_id;
 } git_blob_filter_options;
 
 #define GIT_BLOB_FILTER_OPTIONS_VERSION 1
diff --git a/include/git2/branch.h b/include/git2/branch.h
index 0c0cc7ff7..24ea7f7d0 100644
--- a/include/git2/branch.h
+++ b/include/git2/branch.h
@@ -305,6 +305,19 @@ GIT_EXTERN(int) git_branch_remote_name(
  GIT_EXTERN(int) git_branch_upstream_remote(git_buf *buf, git_repository *repo, const char *refname);
 
 /**
+ * Retrieve the upstream merge of a local branch
+ *
+ * This will return the currently configured "branch.*.merge" for a given
+ * branch. This branch must be local.
+ *
+ * @param buf the buffer into which to write the name
+ * @param repo the repository in which to look
+ * @param refname the full name of the branch
+ * @return 0 or an error code
+ */
+ GIT_EXTERN(int) git_branch_upstream_merge(git_buf *buf, git_repository *repo, const char *refname);
+
+/**
  * Determine whether a branch name is valid, meaning that (when prefixed
  * with `refs/heads/`) that it is a valid reference name, and that any
  * additional branch name restrictions are imposed (eg, it cannot start
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index 3c87001bf..ca6f17aa6 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -194,18 +194,6 @@ typedef enum {
  * Checkout will invoke an options notification callback (`notify_cb`) for
  * certain cases - you pick which ones via `notify_flags`:
  *
- * - GIT_CHECKOUT_NOTIFY_CONFLICT invokes checkout on conflicting paths.
- *
- * - GIT_CHECKOUT_NOTIFY_DIRTY notifies about "dirty" files, i.e. those that
- *   do not need an update but no longer match the baseline.  Core git
- *   displays these files when checkout runs, but won't stop the checkout.
- *
- * - GIT_CHECKOUT_NOTIFY_UPDATED sends notification for any file changed.
- *
- * - GIT_CHECKOUT_NOTIFY_UNTRACKED notifies about untracked files.
- *
- * - GIT_CHECKOUT_NOTIFY_IGNORED notifies about ignored files.
- *
  * Returning a non-zero value from this callback will cancel the checkout.
  * The non-zero return value will be propagated back and returned by the
  * git_checkout_... call.
@@ -216,10 +204,32 @@ typedef enum {
  */
 typedef enum {
 	GIT_CHECKOUT_NOTIFY_NONE      = 0,
+
+	/**
+	 * Invokes checkout on conflicting paths.
+	 */
 	GIT_CHECKOUT_NOTIFY_CONFLICT  = (1u << 0),
+
+	/**
+	 * Notifies about "dirty" files, i.e. those that do not need an update
+	 * but no longer match the baseline.  Core git displays these files when
+	 * checkout runs, but won't stop the checkout.
+	 */
 	GIT_CHECKOUT_NOTIFY_DIRTY     = (1u << 1),
+
+	/**
+	 * Sends notification for any file changed.
+	 */
 	GIT_CHECKOUT_NOTIFY_UPDATED   = (1u << 2),
+
+	/**
+	 * Notifies about untracked files.
+	 */
 	GIT_CHECKOUT_NOTIFY_UNTRACKED = (1u << 3),
+
+	/**
+	 * Notifies about ignored files.
+	 */
 	GIT_CHECKOUT_NOTIFY_IGNORED   = (1u << 4),
 
 	GIT_CHECKOUT_NOTIFY_ALL       = 0x0FFFFu
diff --git a/include/git2/common.h b/include/git2/common.h
index dee260e05..d278c01b6 100644
--- a/include/git2/common.h
+++ b/include/git2/common.h
@@ -91,10 +91,10 @@ GIT_BEGIN_DECL
 
 /**
  * The separator used in path list strings (ie like in the PATH
- * environment variable). A semi-colon ";" is used on Windows, and
- * a colon ":" for all other systems.
+ * environment variable). A semi-colon ";" is used on Windows and
+ * AmigaOS, and a colon ":" for all other systems.
  */
-#ifdef GIT_WIN32
+#if defined(GIT_WIN32) || defined(AMIGA)
 #define GIT_PATH_LIST_SEPARATOR ';'
 #else
 #define GIT_PATH_LIST_SEPARATOR ':'
@@ -207,7 +207,9 @@ typedef enum {
 	GIT_OPT_DISABLE_PACK_KEEP_FILE_CHECKS,
 	GIT_OPT_ENABLE_HTTP_EXPECT_CONTINUE,
 	GIT_OPT_GET_MWINDOW_FILE_LIMIT,
-	GIT_OPT_SET_MWINDOW_FILE_LIMIT
+	GIT_OPT_SET_MWINDOW_FILE_LIMIT,
+	GIT_OPT_SET_ODB_PACKED_PRIORITY,
+	GIT_OPT_SET_ODB_LOOSE_PRIORITY
 } git_libgit2_opt_t;
 
 /**
@@ -421,6 +423,14 @@ typedef enum {
  *		> authentication, use expect/continue when POSTing data.
  *		> This option is not available on Windows.
  *
+ *   opts(GIT_OPT_SET_ODB_PACKED_PRIORITY, int priority)
+ *      > Override the default priority of the packed ODB backend which
+ *      > is added when default backends are assigned to a repository
+ *
+ *   opts(GIT_OPT_SET_ODB_LOOSE_PRIORITY, int priority)
+ *      > Override the default priority of the loose ODB backend which
+ *      > is added when default backends are assigned to a repository
+ *
  * @param option Option key
  * @param ... value to set the option
  * @return 0 on success, <0 on failure
diff --git a/include/git2/diff.h b/include/git2/diff.h
index c63d93dc8..9497793c3 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -241,32 +241,43 @@ typedef enum {
  * Although this is called a "file", it could represent a file, a symbolic
  * link, a submodule commit id, or even a tree (although that only if you
  * are tracking type changes or ignored/untracked directories).
- *
- * The `id` is the `git_oid` of the item.  If the entry represents an
- * absent side of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta),
- * then the oid will be zeroes.
- *
- * `path` is the NUL-terminated path to the entry relative to the working
- * directory of the repository.
- *
- * `size` is the size of the entry in bytes.
- *
- * `flags` is a combination of the `git_diff_flag_t` types
- *
- * `mode` is, roughly, the stat() `st_mode` value for the item.  This will
- * be restricted to one of the `git_filemode_t` values.
- *
- * The `id_abbrev` represents the known length of the `id` field, when
- * converted to a hex string.  It is generally `GIT_OID_HEXSZ`, unless this
- * delta was created from reading a patch file, in which case it may be
- * abbreviated to something reasonable, like 7 characters.
  */
 typedef struct {
+	/**
+	 * The `git_oid` of the item.  If the entry represents an
+	 * absent side of a diff (e.g. the `old_file` of a `GIT_DELTA_ADDED` delta),
+	 * then the oid will be zeroes.
+	 */
 	git_oid            id;
+
+	/**
+	 * The NUL-terminated path to the entry relative to the working
+	 * directory of the repository.
+	 */
 	const char        *path;
+
+	/**
+	 * The size of the entry in bytes.
+	 */
 	git_object_size_t  size;
+
+	/**
+	 * A combination of the `git_diff_flag_t` types
+	 */
 	uint32_t           flags;
+
+	/**
+	 * Roughly, the stat() `st_mode` value for the item.  This will
+	 * be restricted to one of the `git_filemode_t` values.
+	 */
 	uint16_t           mode;
+
+	/**
+	 * Represents the known length of the `id` field, when
+	 * converted to a hex string.  It is generally `GIT_OID_HEXSZ`, unless this
+	 * delta was created from reading a patch file, in which case it may be
+	 * abbreviated to something reasonable, like 7 characters.
+	 */
 	uint16_t           id_abbrev;
 } git_diff_file;
 
diff --git a/include/git2/filter.h b/include/git2/filter.h
index a0185ee88..044c3b870 100644
--- a/include/git2/filter.h
+++ b/include/git2/filter.h
@@ -49,9 +49,34 @@ typedef enum {
 
 	/** Load attributes from `.gitattributes` in the root of HEAD */
 	GIT_FILTER_ATTRIBUTES_FROM_HEAD = (1u << 2),
+
+	/**
+	 * Load attributes from `.gitattributes` in a given commit.
+	 * This can only be specified in a `git_filter_options`.
+	 */
+	GIT_FILTER_ATTRIBUTES_FROM_COMMIT = (1u << 3),
 } git_filter_flag_t;
 
 /**
+ * Filtering options
+ */
+typedef struct {
+	unsigned int version;
+
+	/** See `git_filter_flag_t` above */
+	uint32_t flags;
+
+	/**
+	 * The commit to load attributes from, when
+	 * `GIT_FILTER_ATTRIBUTES_FROM_COMMIT` is specified.
+	 */
+	git_oid *commit_id;
+} git_filter_options;
+
+ #define GIT_FILTER_OPTIONS_VERSION 1
+ #define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION}
+
+/**
  * A filter that can transform file data
  *
  * This represents a filter that can be used to transform or even replace
@@ -104,6 +129,29 @@ GIT_EXTERN(int) git_filter_list_load(
 	uint32_t flags);
 
 /**
+ * Load the filter list for a given path.
+ *
+ * This will return 0 (success) but set the output git_filter_list to NULL
+ * if no filters are requested for the given file.
+ *
+ * @param filters Output newly created git_filter_list (or NULL)
+ * @param repo Repository object that contains `path`
+ * @param blob The blob to which the filter will be applied (if known)
+ * @param path Relative path of the file to be filtered
+ * @param mode Filtering direction (WT->ODB or ODB->WT)
+ * @param opts The `git_filter_options` to use when loading filters
+ * @return 0 on success (which could still return NULL if no filters are
+ *         needed for the requested file), <0 on error
+ */
+GIT_EXTERN(int) git_filter_list_load_ext(
+	git_filter_list **filters,
+	git_repository *repo,
+	git_blob *blob,
+	const char *path,
+	git_filter_mode_t mode,
+	git_filter_options *opts);
+
+/**
  * Query the filter list to see if a given filter (by name) will run.
  * The built-in filters "crlf" and "ident" can be queried, otherwise this
  * is the name of the filter specified by the filter attribute.
diff --git a/include/git2/remote.h b/include/git2/remote.h
index b82bd250b..5d7a5367d 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -253,6 +253,7 @@ GIT_EXTERN(int) git_remote_set_url(git_repository *repo, const char *remote, con
  * @param repo the repository in which to perform the change
  * @param remote the remote's name
  * @param url the url to set
+ * @return 0, or an error code
  */
 GIT_EXTERN(int) git_remote_set_pushurl(git_repository *repo, const char *remote, const char* url);
 
@@ -876,8 +877,10 @@ GIT_EXTERN(git_remote_autotag_option_t) git_remote_autotag(const git_remote *rem
  * @param repo the repository in which to make the change
  * @param remote the name of the remote
  * @param value the new value to take.
+ * @return 0, or an error code.
  */
 GIT_EXTERN(int) git_remote_set_autotag(git_repository *repo, const char *remote, git_remote_autotag_option_t value);
+
 /**
  * Retrieve the ref-prune setting
  *
@@ -944,7 +947,7 @@ GIT_EXTERN(int) git_remote_delete(git_repository *repo, const char *name);
  *
  * This function must only be called after connecting.
  *
- * @param out the buffern in which to store the reference name
+ * @param out the buffer in which to store the reference name
  * @param remote the remote
  * @return 0, GIT_ENOTFOUND if the remote does not have any references
  * or none of them point to HEAD's commit, or an error message.
diff --git a/include/git2/status.h b/include/git2/status.h
index 9693cc478..543e3faa8 100644
--- a/include/git2/status.h
+++ b/include/git2/status.h
@@ -69,89 +69,141 @@ typedef int GIT_CALLBACK(git_status_cb)(
  * With `git_status_foreach_ext`, this will control which changes get
  * callbacks.  With `git_status_list_new`, these will control which
  * changes are included in the list.
- *
- * - GIT_STATUS_SHOW_INDEX_AND_WORKDIR is the default.  This roughly
- *   matches `git status --porcelain` regarding which files are
- *   included and in what order.
- * - GIT_STATUS_SHOW_INDEX_ONLY only gives status based on HEAD to index
- *   comparison, not looking at working directory changes.
- * - GIT_STATUS_SHOW_WORKDIR_ONLY only gives status based on index to
- *   working directory comparison, not comparing the index to the HEAD.
  */
 typedef enum {
+	/**
+	 * The default. This roughly matches `git status --porcelain` regarding
+	 * which files are included and in what order.
+	 */
 	GIT_STATUS_SHOW_INDEX_AND_WORKDIR = 0,
+
+	/**
+	 * Only gives status based on HEAD to index comparison, not looking at
+	 * working directory changes.
+	 */
 	GIT_STATUS_SHOW_INDEX_ONLY = 1,
+
+	/**
+	 * Only gives status based on index to working directory comparison,
+	 * not comparing the index to the HEAD.
+	 */
 	GIT_STATUS_SHOW_WORKDIR_ONLY = 2,
 } git_status_show_t;
 
 /**
  * Flags to control status callbacks
  *
- * - GIT_STATUS_OPT_INCLUDE_UNTRACKED says that callbacks should be made
- *   on untracked files.  These will only be made if the workdir files are
- *   included in the status "show" option.
- * - GIT_STATUS_OPT_INCLUDE_IGNORED says that ignored files get callbacks.
- *   Again, these callbacks will only be made if the workdir files are
- *   included in the status "show" option.
- * - GIT_STATUS_OPT_INCLUDE_UNMODIFIED indicates that callback should be
- *   made even on unmodified files.
- * - GIT_STATUS_OPT_EXCLUDE_SUBMODULES indicates that submodules should be
- *   skipped.  This only applies if there are no pending typechanges to
- *   the submodule (either from or to another type).
- * - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS indicates that all files in
- *   untracked directories should be included.  Normally if an entire
- *   directory is new, then just the top-level directory is included (with
- *   a trailing slash on the entry name).  This flag says to include all
- *   of the individual files in the directory instead.
- * - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH indicates that the given path
- *   should be treated as a literal path, and not as a pathspec pattern.
- * - GIT_STATUS_OPT_RECURSE_IGNORED_DIRS indicates that the contents of
- *   ignored directories should be included in the status.  This is like
- *   doing `git ls-files -o -i --exclude-standard` with core git.
- * - GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX indicates that rename detection
- *   should be processed between the head and the index and enables
- *   the GIT_STATUS_INDEX_RENAMED as a possible status flag.
- * - GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR indicates that rename
- *   detection should be run between the index and the working directory
- *   and enabled GIT_STATUS_WT_RENAMED as a possible status flag.
- * - GIT_STATUS_OPT_SORT_CASE_SENSITIVELY overrides the native case
- *   sensitivity for the file system and forces the output to be in
- *   case-sensitive order
- * - GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY overrides the native case
- *   sensitivity for the file system and forces the output to be in
- *   case-insensitive order
- * - GIT_STATUS_OPT_RENAMES_FROM_REWRITES indicates that rename detection
- *   should include rewritten files
- * - GIT_STATUS_OPT_NO_REFRESH bypasses the default status behavior of
- *   doing a "soft" index reload (i.e. reloading the index data if the
- *   file on disk has been modified outside libgit2).
- * - GIT_STATUS_OPT_UPDATE_INDEX tells libgit2 to refresh the stat cache
- *   in the index for files that are unchanged but have out of date stat
- *   information in the index.  It will result in less work being done on
- *   subsequent calls to get status.  This is mutually exclusive with the
- *   NO_REFRESH option.
- *
  * Calling `git_status_foreach()` is like calling the extended version
  * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED,
  * and GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS.  Those options are bundled
  * together as `GIT_STATUS_OPT_DEFAULTS` if you want them as a baseline.
  */
 typedef enum {
+	/**
+	 * Says that callbacks should be made on untracked files.
+	 * These will only be made if the workdir files are included in the status
+	 * "show" option.
+	 */
 	GIT_STATUS_OPT_INCLUDE_UNTRACKED                = (1u << 0),
+
+	/**
+	 * Says that ignored files get callbacks.
+	 * Again, these callbacks will only be made if the workdir files are
+	 * included in the status "show" option.
+	 */
 	GIT_STATUS_OPT_INCLUDE_IGNORED                  = (1u << 1),
+
+	/**
+	 * Indicates that callback should be made even on unmodified files.
+	 */
 	GIT_STATUS_OPT_INCLUDE_UNMODIFIED               = (1u << 2),
+
+	/**
+	 * Indicates that submodules should be skipped.
+	 * This only applies if there are no pending typechanges to the submodule
+	 * (either from or to another type).
+	 */
 	GIT_STATUS_OPT_EXCLUDE_SUBMODULES               = (1u << 3),
+
+	/**
+	 * Indicates that all files in untracked directories should be included.
+	 * Normally if an entire directory is new, then just the top-level
+	 * directory is included (with a trailing slash on the entry name).
+	 * This flag says to include all of the individual files in the directory
+	 * instead.
+	 */
 	GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS           = (1u << 4),
+
+	/**
+	 * Indicates that the given path should be treated as a literal path,
+	 * and not as a pathspec pattern.
+	 */
 	GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH           = (1u << 5),
+
+	/**
+	 * Indicates that the contents of ignored directories should be included
+	 * in the status. This is like doing `git ls-files -o -i --exclude-standard`
+	 * with core git.
+	 */
 	GIT_STATUS_OPT_RECURSE_IGNORED_DIRS             = (1u << 6),
+
+	/**
+	 * Indicates that rename detection should be processed between the head and
+	 * the index and enables the GIT_STATUS_INDEX_RENAMED as a possible status
+	 * flag.
+	 */
 	GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX            = (1u << 7),
+
+	/**
+	 * Indicates that rename detection should be run between the index and the
+	 * working directory and enabled GIT_STATUS_WT_RENAMED as a possible status
+	 * flag.
+	 */
 	GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR         = (1u << 8),
+
+	/**
+	 * Overrides the native case sensitivity for the file system and forces
+	 * the output to be in case-sensitive order.
+	 */
 	GIT_STATUS_OPT_SORT_CASE_SENSITIVELY            = (1u << 9),
+
+	/**
+	 * Overrides the native case sensitivity for the file system and forces
+	 * the output to be in case-insensitive order.
+	 */
 	GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY          = (1u << 10),
+
+	/**
+	 * Iindicates that rename detection should include rewritten files.
+	 */
 	GIT_STATUS_OPT_RENAMES_FROM_REWRITES            = (1u << 11),
+
+	/**
+	 * Bypasses the default status behavior of doing a "soft" index reload
+	 * (i.e. reloading the index data if the file on disk has been modified
+	 * outside libgit2).
+	 */
 	GIT_STATUS_OPT_NO_REFRESH                       = (1u << 12),
+
+	/**
+	 * Tells libgit2 to refresh the stat cache in the index for files that are
+	 * unchanged but have out of date stat einformation in the index.
+	 * It will result in less work being done on subsequent calls to get status.
+	 * This is mutually exclusive with the NO_REFRESH option.
+	 */
 	GIT_STATUS_OPT_UPDATE_INDEX                     = (1u << 13),
+
+	/**
+	 * Normally files that cannot be opened or read are ignored as
+	 * these are often transient files; this option will return
+	 * unreadable files as `GIT_STATUS_WT_UNREADABLE`.
+	 */
 	GIT_STATUS_OPT_INCLUDE_UNREADABLE               = (1u << 14),
+
+	/**
+	 * Unreadable files will be detected and given the status
+	 * untracked instead of unreadable.
+	 */
 	GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED  = (1u << 15),
 } git_status_opt_t;
 
@@ -168,7 +220,10 @@ typedef enum {
  *
  */
 typedef struct {
-	unsigned int      version; /**< The version */
+	/**
+	 * The struct version; pass `GIT_STATUS_OPTIONS_VERSION`.
+	 */
+	unsigned int version;
 
 	/**
 	 * The `show` value is one of the `git_status_show_t` constants that
@@ -177,21 +232,22 @@ typedef struct {
 	git_status_show_t show;
 
 	/**
-	 * The `flags` value is an OR'ed combination of the `git_status_opt_t`
-	 * values above.
+	 * The `flags` value is an OR'ed combination of the
+	 * `git_status_opt_t` values above.
 	 */
 	unsigned int      flags;
 
 	/**
 	 * The `pathspec` is an array of path patterns to match (using
-	 * fnmatch-style matching), or just an array of paths to match exactly if
-	 * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
+	 * fnmatch-style matching), or just an array of paths to match
+	 * exactly if `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified
+	 * in the flags.
 	 */
 	git_strarray      pathspec;
 
 	/**
-	 * The `baseline` is the tree to be used for comparison to the working directory
-	 * and index; defaults to HEAD.
+	 * The `baseline` is the tree to be used for comparison to the
+	 * working directory and index; defaults to HEAD.
 	 */
 	git_tree          *baseline;
 } git_status_options;
diff --git a/include/git2/worktree.h b/include/git2/worktree.h
index 049511da1..23084d8cd 100644
--- a/include/git2/worktree.h
+++ b/include/git2/worktree.h
@@ -198,6 +198,7 @@ typedef enum {
 typedef struct git_worktree_prune_options {
 	unsigned int version;
 
+	/** A combination of `git_worktree_prune_t` */
 	uint32_t flags;
 } git_worktree_prune_options;