rugged 1.6.3 → 1.9.0

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
  */
@@ -58,7 +64,9 @@ GIT_EXTERN(int) git_repository_open_from_worktree(git_repository **out, git_work
  * @param odb the object database to wrap
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_repository_wrap_odb(git_repository **out, git_odb *odb);
+GIT_EXTERN(int) git_repository_wrap_odb(
+	git_repository **out,
+	git_odb *odb);
 
 /**
  * Look for a git repository and copy its path in the given buffer.
@@ -70,6 +78,10 @@ GIT_EXTERN(int) git_repository_wrap_odb(git_repository **out, git_odb *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.
  *
@@ -147,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
@@ -175,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
  */
@@ -200,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
@@ -362,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}
 
 /**
@@ -387,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.
@@ -404,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
@@ -493,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;
 
@@ -536,7 +568,7 @@ GIT_EXTERN(const char *) git_repository_workdir(const git_repository *repo);
 
 /**
  * Get the path of the shared common directory for this repository.
- * 
+ *
  * If the repository is bare, it is the root directory for the repository.
  * If the repository is a worktree, it is the parent repo's gitdir.
  * Otherwise, it is the gitdir.
@@ -624,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
  */
@@ -640,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
  */
@@ -656,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
  */
@@ -846,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,
@@ -939,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
  */
@@ -968,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

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

@@ -14,7 +14,7 @@
 
 /**
  * @file git2/status.h
- * @brief Git file status routines
+ * @brief Status indicates how a user has changed the working directory and index
  * @defgroup git_status Git file status routines
  * @ingroup Git
  * @{
@@ -54,11 +54,10 @@ typedef enum {
 /**
  * Function pointer to receive status on individual files
  *
- * `path` is the relative path to the file from the root of the repository.
- *
- * `status_flags` is a combination of `git_status_t` values that apply.
- *
- * `payload` is the value you passed to the foreach function as payload.
+ * @param path is the path to the file
+ * @param status_flags the `git_status_t` values for file's status
+ * @param payload the user-specified payload to the foreach function
+ * @return 0 on success, or a negative number on failure
  */
 typedef int GIT_CALLBACK(git_status_cb)(
 	const char *path, unsigned int status_flags, void *payload);
@@ -207,6 +206,7 @@ typedef enum {
 	GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED  = (1u << 15)
 } git_status_opt_t;
 
+/** Default `git_status_opt_t` values */
 #define GIT_STATUS_OPT_DEFAULTS \
 	(GIT_STATUS_OPT_INCLUDE_IGNORED | \
 	GIT_STATUS_OPT_INCLUDE_UNTRACKED | \
@@ -261,7 +261,10 @@ typedef struct {
 	uint16_t          rename_threshold;
 } git_status_options;
 
+/** Current version for the `git_status_options` structure */
 #define GIT_STATUS_OPTIONS_VERSION 1
+
+/** Static constructor for `git_status_options` */
 #define GIT_STATUS_OPTIONS_INIT {GIT_STATUS_OPTIONS_VERSION}
 
 /**
@@ -449,4 +452,5 @@ GIT_EXTERN(int) git_status_should_ignore(
 
 /** @} */
 GIT_END_DECL
+
 #endif