rugged 1.7.2 → 1.9.0

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

@@ -19,8 +19,8 @@
 
 /**
  * @file git2/remote.h
- * @brief Git remote management functions
- * @defgroup git_remote remote management functions
+ * @brief Remotes are where local repositories fetch from and push to
+ * @defgroup git_remote Remotes are where local repositories fetch from and push to
  * @ingroup Git
  * @{
  */
@@ -76,6 +76,17 @@ typedef enum {
 	GIT_REMOTE_CREATE_SKIP_DEFAULT_FETCHSPEC = (1 << 1)
 } git_remote_create_flags;
 
+/**
+ * How to handle reference updates.
+ */
+typedef enum {
+	/* Write the fetch results to FETCH_HEAD. */
+	GIT_REMOTE_UPDATE_FETCHHEAD = (1 << 0),
+
+	/* Report unchanged tips in the update_refs callback. */
+	GIT_REMOTE_UPDATE_REPORT_UNCHANGED = (1 << 1)
+} git_remote_update_flags;
+
 /**
  * Remote creation options structure
  *
@@ -105,7 +116,10 @@ typedef struct git_remote_create_options {
 	unsigned int flags;
 } git_remote_create_options;
 
+/** Current version for the `git_remote_create_options` structure */
 #define GIT_REMOTE_CREATE_OPTIONS_VERSION 1
+
+/** Static constructor for `git_remote_create_options` */
 #define GIT_REMOTE_CREATE_OPTIONS_INIT {GIT_REMOTE_CREATE_OPTIONS_VERSION}
 
 /**
@@ -455,7 +469,15 @@ typedef enum git_remote_completion_t {
 	GIT_REMOTE_COMPLETION_ERROR
 } git_remote_completion_t;
 
-/** Push network progress notification function */
+/**
+ * Push network progress notification callback.
+ *
+ * @param current The number of objects pushed so far
+ * @param total The total number of objects to push
+ * @param bytes The number of bytes pushed
+ * @param payload The user-specified payload callback
+ * @return 0 or an error code to stop the transfer
+ */
 typedef int GIT_CALLBACK(git_push_transfer_progress_cb)(
 	unsigned int current,
 	unsigned int total,
@@ -491,8 +513,12 @@ typedef struct {
  * as commands to the destination.
  * @param len number of elements in `updates`
  * @param payload Payload provided by the caller
+ * @return 0 or an error code to stop the push
  */
-typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload);
+typedef int GIT_CALLBACK(git_push_negotiation)(
+	const git_push_update **updates,
+	size_t len,
+	void *payload);
 
 /**
  * Callback used to inform of the update status from the remote.
@@ -557,7 +583,8 @@ struct git_remote_callbacks {
 	 * Completion is called when different parts of the download
 	 * process are done (currently unused).
 	 */
-	int GIT_CALLBACK(completion)(git_remote_completion_t type, void *data);
+	int GIT_CALLBACK(completion)(git_remote_completion_t type,
+		void *data);
 
 	/**
 	 * This will be called if the remote host requires
@@ -583,11 +610,22 @@ struct git_remote_callbacks {
 	 */
 	git_indexer_progress_cb transfer_progress;
 
+#ifdef GIT_DEPRECATE_HARD
+	void *reserved_update_tips;
+#else
 	/**
-	 * Each time a reference is updated locally, this function
-	 * will be called with information about it.
+	 * Deprecated callback for reference updates, callers should
+	 * set `update_refs` instead. This is retained for backward
+	 * compatibility; if you specify both `update_refs` and
+	 * `update_tips`, then only the `update_refs` function will
+	 * be called.
+	 *
+	 * @deprecated the `update_refs` callback in this structure
+	 * should be preferred
 	 */
-	int GIT_CALLBACK(update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data);
+	int GIT_CALLBACK(update_tips)(const char *refname,
+		const git_oid *a, const git_oid *b, void *data);
+#endif
 
 	/**
 	 * Function to call with progress information during pack
@@ -644,9 +682,25 @@ struct git_remote_callbacks {
 	 */
 	git_url_resolve_cb resolve_url;
 #endif
+
+	/**
+	 * Each time a reference is updated locally, this function
+	 * will be called with information about it. This should be
+	 * preferred over the `update_tips` callback in this
+	 * structure.
+	 */
+	int GIT_CALLBACK(update_refs)(
+		const char *refname,
+		const git_oid *a,
+		const git_oid *b,
+		git_refspec *spec,
+		void *data);
 };
 
+/** Current version for the `git_remote_callbacks_options` structure */
 #define GIT_REMOTE_CALLBACKS_VERSION 1
+
+/** Static constructor for `git_remote_callbacks_options` */
 #define GIT_REMOTE_CALLBACKS_INIT {GIT_REMOTE_CALLBACKS_VERSION}
 
 /**
@@ -733,10 +787,9 @@ typedef struct {
 	git_fetch_prune_t prune;
 
 	/**
-	 * Whether to write the results to FETCH_HEAD. Defaults to
-	 * on. Leave this default in order to behave like git.
+	 * How to handle reference updates; see `git_remote_update_flags`.
 	 */
-	int update_fetchhead;
+	unsigned int update_fetchhead;
 
 	/**
 	 * Determines how to behave regarding tags on the remote, such
@@ -774,9 +827,17 @@ typedef struct {
 	git_strarray custom_headers;
 } git_fetch_options;
 
+/** Current version for the `git_fetch_options` structure */
 #define GIT_FETCH_OPTIONS_VERSION 1
-#define GIT_FETCH_OPTIONS_INIT { GIT_FETCH_OPTIONS_VERSION, GIT_REMOTE_CALLBACKS_INIT, GIT_FETCH_PRUNE_UNSPECIFIED, 1, \
-				 GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED, GIT_PROXY_OPTIONS_INIT }
+
+/** Static constructor for `git_fetch_options` */
+#define GIT_FETCH_OPTIONS_INIT { \
+	GIT_FETCH_OPTIONS_VERSION, \
+	GIT_REMOTE_CALLBACKS_INIT, \
+	GIT_FETCH_PRUNE_UNSPECIFIED, \
+	GIT_REMOTE_UPDATE_FETCHHEAD, \
+	GIT_REMOTE_DOWNLOAD_TAGS_UNSPECIFIED, \
+	GIT_PROXY_OPTIONS_INIT }
 
 /**
  * Initialize git_fetch_options structure
@@ -830,9 +891,17 @@ typedef struct {
 	 * Extra headers for this push operation
 	 */
 	git_strarray custom_headers;
+
+	/**
+	 * "Push options" to deliver to the remote.
+	 */
+	git_strarray remote_push_options;
 } git_push_options;
 
+/** Current version for the `git_push_options` structure */
 #define GIT_PUSH_OPTIONS_VERSION 1
+
+/** Static constructor for `git_push_options` */
 #define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
 
 /**
@@ -876,7 +945,10 @@ typedef struct {
 	git_strarray custom_headers;
 } git_remote_connect_options;
 
+/** Current version for the `git_remote_connect_options` structure */
 #define GIT_REMOTE_CONNECT_OPTIONS_VERSION 1
+
+/** Static constructor for `git_remote_connect_options` */
 #define GIT_REMOTE_CONNECT_OPTIONS_INIT { \
 	GIT_REMOTE_CONNECT_OPTIONS_VERSION, \
 	GIT_REMOTE_CALLBACKS_INIT, \
@@ -996,20 +1068,20 @@ GIT_EXTERN(int) git_remote_upload(
  * `git_remote_connect` will be used (if it was called).
  *
  * @param remote the remote to update
+ * @param callbacks  pointer to the callback structure to use or NULL
+ * @param update_flags the git_remote_update_flags for these tips.
+ * @param download_tags what the behaviour for downloading tags is for this fetch. This is
+ * ignored for push. This must be the same value passed to `git_remote_download()`.
  * @param reflog_message The message to insert into the reflogs. If
  * NULL and fetching, the default is "fetch <name>", where <name> is
  * the name of the remote (or its url, for in-memory remotes). This
  * parameter is ignored when pushing.
- * @param callbacks  pointer to the callback structure to use or NULL
- * @param update_fetchhead whether to write to FETCH_HEAD. Pass 1 to behave like git.
- * @param download_tags what the behaviour for downloading tags is for this fetch. This is
- * ignored for push. This must be the same value passed to `git_remote_download()`.
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_remote_update_tips(
 		git_remote *remote,
 		const git_remote_callbacks *callbacks,
-		int update_fetchhead,
+		unsigned int update_flags,
 		git_remote_autotag_option_t download_tags,
 		const char *reflog_message);
 
@@ -1071,6 +1143,9 @@ GIT_EXTERN(int) git_remote_push(
 
 /**
  * Get the statistics structure that is filled in by the fetch operation.
+ *
+ * @param remote the remote to get statistics for
+ * @return the git_indexer_progress for the remote
  */
 GIT_EXTERN(const git_indexer_progress *) git_remote_stats(git_remote *remote);
 
@@ -1170,4 +1245,5 @@ GIT_EXTERN(int) git_remote_default_branch(git_buf *out, git_remote *remote);
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -10,12 +10,14 @@
 #include "common.h"
 #include "types.h"
 #include "oid.h"
+#include "odb.h"
 #include "buffer.h"
+#include "commit.h"
 
 /**
  * @file git2/repository.h
- * @brief Git repository management routines
- * @defgroup git_repository Git repository management routines
+ * @brief The repository stores revisions for a source tree
+ * @defgroup git_repository The repository stores revisions for a source tree
  * @ingroup Git
  * @{
  */
@@ -30,7 +32,11 @@ GIT_BEGIN_DECL
  * The method will automatically detect if 'path' is a normal
  * or bare repository or fail is 'path' is neither.
  *
- * @param out pointer to the repo which will be opened
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
+ * @param[out] out pointer to the repo which will be opened
  * @param path the path to the repository
  * @return 0 or an error code
  */
@@ -56,19 +62,11 @@ GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_work
  *
  * @param out pointer to the repo
  * @param odb the object database to wrap
- * @param oid_type the oid type of the object database
  * @return 0 or an error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_repository_wrap_odb(
-	git_repository **out,
-	git_odb *odb,
-	git_oid_t oid_type);
-#else
 GIT_EXTERN(int) git_repository_wrap_odb(
 	git_repository **out,
 	git_odb *odb);
-#endif
 
 /**
  * Look for a git repository and copy its path in the given buffer.
@@ -80,6 +78,10 @@ GIT_EXTERN(int) git_repository_wrap_odb(
  * The method will automatically detect if the repository is bare
  * (if there is a repository).
  *
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
  * @param out A pointer to a user-allocated git_buf which will contain
  * the found path.
  *
@@ -157,7 +159,11 @@ typedef enum {
 /**
  * Find and open a repository with extended controls.
  *
- * @param out Pointer to the repo which will be opened.  This can
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
+ * @param[out] out Pointer to the repo which will be opened.  This can
  *        actually be NULL if you only want to use the error code to
  *        see if a repo at this path could be opened.
  * @param path Path to open as git repository.  If the flags
@@ -185,7 +191,11 @@ GIT_EXTERN(int) git_repository_open_ext(
  * if you're e.g. hosting git repositories and need to access them
  * efficiently
  *
- * @param out Pointer to the repo which will be opened.
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
+ * @param[out] out Pointer to the repo which will be opened.
  * @param bare_path Direct path to the bare repository
  * @return 0 on success, or an error code
  */
@@ -210,7 +220,11 @@ GIT_EXTERN(void) git_repository_free(git_repository *repo);
  * TODO:
  *	- Reinit the repository
  *
- * @param out pointer to the repo which will be created or reinitialized
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
+ * @param[out] out pointer to the repo which will be created or reinitialized
  * @param path the path to the repository
  * @param is_bare if true, a Git repository without a working directory is
  *		created at the pointed path. If false, provided path will be
@@ -372,7 +386,10 @@ typedef struct {
 #endif
 } git_repository_init_options;
 
+/** Current version for the `git_repository_init_options` structure */
 #define GIT_REPOSITORY_INIT_OPTIONS_VERSION 1
+
+/** Static constructor for `git_repository_init_options` */
 #define GIT_REPOSITORY_INIT_OPTIONS_INIT {GIT_REPOSITORY_INIT_OPTIONS_VERSION}
 
 /**
@@ -397,6 +414,10 @@ GIT_EXTERN(int) git_repository_init_options_init(
  * auto-detect the case sensitivity of the file system and if the
  * file system supports file mode bits correctly.
  *
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
  * @param out Pointer to the repo which will be created or reinitialized.
  * @param repo_path The path to the repository.
  * @param opts Pointer to git_repository_init_options struct.
@@ -414,7 +435,7 @@ GIT_EXTERN(int) git_repository_init_ext(
  * `git_reference_free()` must be called when done with it to release the
  * allocated memory and prevent a leak.
  *
- * @param out pointer to the reference which will be retrieved
+ * @param[out] out pointer to the reference which will be retrieved
  * @param repo a repository object
  *
  * @return 0 on success, GIT_EUNBORNBRANCH when HEAD points to a non existing
@@ -503,6 +524,7 @@ typedef enum {
 	GIT_REPOSITORY_ITEM_LOGS,
 	GIT_REPOSITORY_ITEM_MODULES,
 	GIT_REPOSITORY_ITEM_WORKTREES,
+	GIT_REPOSITORY_ITEM_WORKTREE_CONFIG,
 	GIT_REPOSITORY_ITEM__LAST
 } git_repository_item_t;
 
@@ -634,7 +656,7 @@ GIT_EXTERN(int) git_repository_config_snapshot(git_config **out, git_repository
  * The ODB must be freed once it's no longer being used by
  * the user.
  *
- * @param out Pointer to store the loaded ODB
+ * @param[out] out Pointer to store the loaded ODB
  * @param repo A repository object
  * @return 0, or an error code
  */
@@ -650,7 +672,7 @@ GIT_EXTERN(int) git_repository_odb(git_odb **out, git_repository *repo);
  * The refdb must be freed once it's no longer being used by
  * the user.
  *
- * @param out Pointer to store the loaded refdb
+ * @param[out] out Pointer to store the loaded refdb
  * @param repo A repository object
  * @return 0, or an error code
  */
@@ -666,7 +688,7 @@ GIT_EXTERN(int) git_repository_refdb(git_refdb **out, git_repository *repo);
  * The index must be freed once it's no longer being used by
  * the user.
  *
- * @param out Pointer to store the loaded index
+ * @param[out] out Pointer to store the loaded index
  * @param repo A repository object
  * @return 0, or an error code
  */
@@ -856,7 +878,9 @@ GIT_EXTERN(int) git_repository_set_head_detached(
  *
  * See the documentation for `git_repository_set_head_detached()`.
  *
- * @see git_repository_set_head_detached
+ * @param repo Repository pointer
+ * @param committish annotated commit to point HEAD to
+ * @return 0 on success, or an error code
  */
 GIT_EXTERN(int) git_repository_set_head_detached_from_annotated(
 	git_repository *repo,
@@ -949,8 +973,8 @@ GIT_EXTERN(int) git_repository_is_shallow(git_repository *repo);
  * The memory is owned by the repository and must not be freed by the
  * user.
  *
- * @param name where to store the pointer to the name
- * @param email where to store the pointer to the email
+ * @param[out] name where to store the pointer to the name
+ * @param[out] email where to store the pointer to the email
  * @param repo the repository
  * @return 0 or an error code
  */
@@ -978,6 +1002,18 @@ GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name,
  */
 GIT_EXTERN(git_oid_t) git_repository_oid_type(git_repository *repo);
 
+/**
+ * Gets the parents of the next commit, given the current repository state.
+ * Generally, this is the HEAD commit, except when performing a merge, in
+ * which case it is two or more commits.
+ *
+ * @param commits a `git_commitarray` that will contain the commit parents
+ * @param repo the repository
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_repository_commit_parents(git_commitarray *commits, git_repository *repo);
+
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -14,7 +14,7 @@
 
 /**
  * @file git2/reset.h
- * @brief Git reset management routines
+ * @brief Reset will update the local repository to a prior state
  * @ingroup Git
  * @{
  */
@@ -75,11 +75,23 @@ GIT_EXTERN(int) git_reset(
  *
  * See the documentation for `git_reset()`.
  *
- * @see git_reset
+ * @param repo Repository where to perform the reset operation.
+ *
+ * @param target Annotated commit to which the Head should be moved to.
+ * This object must belong to the given `repo`, it will be dereferenced
+ * to a git_commit which oid will be used as the target of the branch.
+ *
+ * @param reset_type Kind of reset operation to perform.
+ *
+ * @param checkout_opts Optional checkout options to be used for a HARD reset.
+ * The checkout_strategy field will be overridden (based on reset_type).
+ * This parameter can be used to propagate notify and progress callbacks.
+ *
+ * @return 0 on success or an error code
  */
 GIT_EXTERN(int) git_reset_from_annotated(
 	git_repository *repo,
-	const git_annotated_commit *commit,
+	const git_annotated_commit *target,
 	git_reset_t reset_type,
 	const git_checkout_options *checkout_opts);
 
@@ -108,4 +120,5 @@ GIT_EXTERN(int) git_reset_default(
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -13,8 +13,8 @@
 
 /**
  * @file git2/revert.h
- * @brief Git revert routines
- * @defgroup git_revert Git revert routines
+ * @brief Cherry-pick the inverse of a change to "undo" its effects
+ * @defgroup git_revert Cherry-pick the inverse of a change to "undo" its effects
  * @ingroup Git
  * @{
  */
@@ -33,8 +33,13 @@ typedef struct {
 	git_checkout_options checkout_opts; /**< Options for the checkout */
 } git_revert_options;
 
+/** Current version for the `git_revert_options` structure */
 #define GIT_REVERT_OPTIONS_VERSION 1
-#define GIT_REVERT_OPTIONS_INIT {GIT_REVERT_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT}
+
+/** Static constructor for `git_revert_options` */
+#define GIT_REVERT_OPTIONS_INIT { \
+	GIT_REVERT_OPTIONS_VERSION, 0, \
+	GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT }
 
 /**
  * Initialize git_revert_options structure
@@ -87,5 +92,5 @@ GIT_EXTERN(int) git_revert(
 
 /** @} */
 GIT_END_DECL
-#endif
 
+#endif

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

@@ -12,8 +12,8 @@
 
 /**
  * @file git2/revparse.h
- * @brief Git revision parsing routines
- * @defgroup git_revparse Git revision parsing routines
+ * @brief Parse the textual revision information
+ * @defgroup git_revparse Parse the textual revision information
  * @ingroup Git
  * @{
  */
@@ -107,7 +107,7 @@ GIT_EXTERN(int) git_revparse(
 	git_repository *repo,
 	const char *spec);
 
-
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -13,8 +13,8 @@
 
 /**
  * @file git2/revwalk.h
- * @brief Git revision traversal routines
- * @defgroup git_revwalk Git revision traversal routines
+ * @brief Traverse (walk) the commit graph (revision history)
+ * @defgroup git_revwalk Traverse (walk) the commit graph (revision history)
  * @ingroup Git
  * @{
  */
@@ -299,4 +299,5 @@ GIT_EXTERN(int) git_revwalk_add_hide_cb(
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -12,9 +12,13 @@
 
 /**
  * @file git2/signature.h
- * @brief Git signature creation
+ * @brief Signatures are the actor in a repository and when they acted
  * @defgroup git_signature Git signature creation
  * @ingroup Git
+ *
+ * Signatures contain the information about the actor (committer or
+ * author) in a repository, and the time that they performed the
+ * commit, or authoring.
  * @{
  */
 GIT_BEGIN_DECL
@@ -48,6 +52,42 @@ GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const c
  */
 GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const char *email);
 
+/**
+ * Create a new author and/or committer signatures with default
+ * information based on the configuration and environment variables.
+ *
+ * If `author_out` is set, it will be populated with the author
+ * information. The `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL`
+ * environment variables will be honored, and `user.name` and
+ * `user.email` configuration options will be honored if the
+ * environment variables are unset. For timestamps, `GIT_AUTHOR_DATE`
+ * will be used, otherwise the current time will be used.
+ *
+ * If `committer_out` is set, it will be populated with the
+ * committer information. The `GIT_COMMITTER_NAME` and
+ * `GIT_COMMITTER_EMAIL` environment variables will be honored,
+ * and `user.name` and `user.email` configuration options will
+ * be honored if the environment variables are unset. For timestamps,
+ * `GIT_COMMITTER_DATE` will be used, otherwise the current time will
+ * be used.
+ *
+ * If neither `GIT_AUTHOR_DATE` nor `GIT_COMMITTER_DATE` are set,
+ * both timestamps will be set to the same time.
+ *
+ * It will return `GIT_ENOTFOUND` if either the `user.name` or
+ * `user.email` are not set and there is no fallback from an environment
+ * variable. One of `author_out` or `committer_out` must be set.
+ *
+ * @param author_out pointer to set the author signature, or NULL
+ * @param committer_out pointer to set the committer signature, or NULL
+ * @param repo repository pointer
+ * @return 0 on success, GIT_ENOTFOUND if config is missing, or error code
+ */
+GIT_EXTERN(int) git_signature_default_from_env(
+	git_signature **author_out,
+	git_signature **committer_out,
+	git_repository *repo);
+
 /**
  * Create a new action signature with default user and now timestamp.
  *
@@ -56,6 +96,10 @@ GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const c
  * based on that information.  It will return GIT_ENOTFOUND if either the
  * user.name or user.email are not set.
  *
+ * Note that these do not examine environment variables, only the
+ * configuration files. Use `git_signature_default_from_env` to
+ * consider the environment variables.
+ *
  * @param out new signature
  * @param repo repository pointer
  * @return 0 on success, GIT_ENOTFOUND if config is missing, or error code
@@ -100,4 +144,5 @@ GIT_EXTERN(void) git_signature_free(git_signature *sig);
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -13,8 +13,13 @@
 
 /**
  * @file git2/stash.h
- * @brief Git stash management routines
+ * @brief Stashes stores some uncommitted state in the repository
  * @ingroup Git
+ *
+ * Stashes stores some uncommitted state in the repository; generally
+ * this allows a user to stash some changes so that they can restore
+ * the working directory to an unmodified state. This can allow a
+ * developer to work on two different changes in parallel.
  * @{
  */
 GIT_BEGIN_DECL
@@ -94,7 +99,10 @@ typedef struct git_stash_save_options {
 	git_strarray paths;
 } git_stash_save_options;
 
+/** Current version for the `git_stash_save_options` structure */
 #define GIT_STASH_SAVE_OPTIONS_VERSION 1
+
+/** Static constructor for `git_stash_save_options` */
 #define GIT_STASH_SAVE_OPTIONS_INIT { GIT_STASH_SAVE_OPTIONS_VERSION }
 
 /**
@@ -165,6 +173,10 @@ typedef enum {
  * Stash application progress notification function.
  * Return 0 to continue processing, or a negative value to
  * abort the stash application.
+ *
+ * @param progress the progress information
+ * @param payload the user-specified payload to the apply function
+ * @return 0 on success, -1 on error
  */
 typedef int GIT_CALLBACK(git_stash_apply_progress_cb)(
 	git_stash_apply_progress_t progress,
@@ -191,7 +203,10 @@ typedef struct git_stash_apply_options {
 	void *progress_payload;
 } git_stash_apply_options;
 
+/** Current version for the `git_stash_apply_options` structure */
 #define GIT_STASH_APPLY_OPTIONS_VERSION 1
+
+/** Static constructor for `git_stash_apply_options` */
 #define GIT_STASH_APPLY_OPTIONS_INIT { \
 	GIT_STASH_APPLY_OPTIONS_VERSION, \
 	GIT_STASH_APPLY_DEFAULT, \
@@ -225,8 +240,6 @@ GIT_EXTERN(int) git_stash_apply_options_init(
  * GIT_EMERGECONFLICT and both the working directory and index will be left
  * unmodified.
  *
- * Note that a minimum checkout strategy of `GIT_CHECKOUT_SAFE` is implied.
- *
  * @param repo The owning repository.
  * @param index The position within the stash list. 0 points to the
  *              most recent stashed state.
@@ -311,4 +324,5 @@ GIT_EXTERN(int) git_stash_pop(
 
 /** @} */
 GIT_END_DECL
+
 #endif