rugged 1.3.1 → 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.
  *
@@ -141,13 +153,17 @@ typedef enum {
 	 * `git_repository_open_ext` with this flag will error out if either
 	 * $GIT_WORK_TREE or $GIT_COMMON_DIR is set.
 	 */
-	GIT_REPOSITORY_OPEN_FROM_ENV  = (1 << 4),
+	GIT_REPOSITORY_OPEN_FROM_ENV  = (1 << 4)
 } git_repository_open_flag_t;
 
 /**
  * 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
@@ -267,7 +291,7 @@ typedef enum {
 	 * If an alternate workdir is specified, use relative paths for the gitdir
 	 * and core.worktree.
 	 */
-	GIT_REPOSITORY_INIT_RELATIVE_GITLINK  = (1u << 6),
+	GIT_REPOSITORY_INIT_RELATIVE_GITLINK  = (1u << 6)
 } git_repository_init_flag_t;
 
 /**
@@ -292,7 +316,7 @@ typedef enum {
 	/**
 	 * Use "--shared=all" behavior, adding world readability.
 	 */
-	GIT_REPOSITORY_INIT_SHARED_ALL   = 0002777,
+	GIT_REPOSITORY_INIT_SHARED_ALL   = 0002777
 } git_repository_init_mode_t;
 
 /**
@@ -351,9 +375,21 @@ typedef struct {
 	 * pointing to this URL.
 	 */
 	const char *origin_url;
+
+#ifdef GIT_EXPERIMENTAL_SHA256
+	/**
+	 *
+	 * Type of object IDs to use for this repository, or 0 for
+	 * default (currently SHA1).
+	 */
+	git_oid_t oid_type;
+#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}
 
 /**
@@ -378,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.
@@ -395,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
@@ -456,7 +496,9 @@ GIT_EXTERN(int) git_repository_head_unborn(git_repository *repo);
  * Check if a repository is empty
  *
  * An empty repository has just been initialized and contains no references
- * apart from HEAD, which must be pointing to the unborn master branch.
+ * apart from HEAD, which must be pointing to the unborn master branch,
+ * or the branch specified for the repository in the `init.defaultBranch`
+ * configuration variable.
  *
  * @param repo Repo to test
  * @return 1 if the repository is empty, 0 if it isn't, error code
@@ -482,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;
 
@@ -525,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.
@@ -613,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
  */
@@ -629,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
  */
@@ -645,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
  */
@@ -673,6 +716,9 @@ GIT_EXTERN(int) git_repository_message(git_buf *out, git_repository *repo);
  * Remove git's prepared message.
  *
  * Remove the message that `git_repository_message` retrieves.
+ *
+ * @param repo Repository to remove prepared message from.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_repository_message_remove(git_repository *repo);
 
@@ -808,19 +854,19 @@ GIT_EXTERN(int) git_repository_set_head(
  * If the provided committish cannot be found in the repository, the HEAD
  * is unaltered and GIT_ENOTFOUND is returned.
  *
- * If the provided commitish cannot be peeled into a commit, the HEAD
+ * If the provided committish cannot be peeled into a commit, the HEAD
  * is unaltered and -1 is returned.
  *
  * Otherwise, the HEAD will eventually be detached and will directly point to
  * the peeled Commit.
  *
  * @param repo Repository pointer
- * @param commitish Object id of the Commit the HEAD should point to
+ * @param committish Object id of the Commit the HEAD should point to
  * @return 0 on success, or an error code
  */
 GIT_EXTERN(int) git_repository_set_head_detached(
 	git_repository *repo,
-	const git_oid *commitish);
+	const git_oid *committish);
 
 /**
  * Make the repository HEAD directly point to the Commit.
@@ -832,11 +878,13 @@ 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,
-	const git_annotated_commit *commitish);
+	const git_annotated_commit *committish);
 
 /**
  * Detach the HEAD.
@@ -846,7 +894,7 @@ GIT_EXTERN(int) git_repository_set_head_detached_from_annotated(
  * If the HEAD is already detached and points to a Tag, the HEAD is
  * updated into making it point to the peeled Commit, and 0 is returned.
  *
- * If the HEAD is already detached and points to a non commitish, the HEAD is
+ * If the HEAD is already detached and points to a non committish, the HEAD is
  * unaltered, and -1 is returned.
  *
  * Otherwise, the HEAD will be detached and point to the peeled Commit.
@@ -876,7 +924,7 @@ typedef enum {
 	GIT_REPOSITORY_STATE_REBASE_INTERACTIVE,
 	GIT_REPOSITORY_STATE_REBASE_MERGE,
 	GIT_REPOSITORY_STATE_APPLY_MAILBOX,
-	GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE,
+	GIT_REPOSITORY_STATE_APPLY_MAILBOX_OR_REBASE
 } git_repository_state_t;
 
 /**
@@ -925,9 +973,10 @@ 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
  */
 GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, const git_repository *repo);
 
@@ -941,9 +990,30 @@ GIT_EXTERN(int) git_repository_ident(const char **name, const char **email, cons
  * @param repo the repository to configure
  * @param name the name to use for the reflog entries
  * @param email the email to use for the reflog entries
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_repository_set_ident(git_repository *repo, const char *name, const char *email);
 
+/**
+ * Gets the object type used by this repository.
+ *
+ * @param repo the repository
+ * @return the object id type
+ */
+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
  * @{
  */
@@ -26,7 +26,7 @@ GIT_BEGIN_DECL
 typedef enum {
 	GIT_RESET_SOFT  = 1, /**< Move the head to the given commit */
 	GIT_RESET_MIXED = 2, /**< SOFT plus reset index to the commit */
-	GIT_RESET_HARD  = 3, /**< MIXED plus changes in working tree discarded */
+	GIT_RESET_HARD  = 3  /**< MIXED plus changes in working tree discarded */
 } git_reset_t;
 
 /**
@@ -48,7 +48,7 @@ typedef enum {
  *
  * @param target Committish to which the Head should be moved to. This object
  * must belong to the given `repo` and can either be a git_commit or a
- * git_tag. When a git_tag is being passed, it should be dereferencable
+ * git_tag. When a git_tag is being passed, it should be dereferenceable
  * to a git_commit which oid will be used as the target of the branch.
  *
  * @param reset_type Kind of reset operation to perform.
@@ -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
  * @{
  */
@@ -74,7 +74,7 @@ typedef enum {
 	/** The spec targeted a range of commits. */
 	GIT_REVSPEC_RANGE          = 1 << 1,
 	/** The spec used the '...' operator, which invokes special semantics. */
-	GIT_REVSPEC_MERGE_BASE     = 1 << 2,
+	GIT_REVSPEC_MERGE_BASE     = 1 << 2
 } git_revspec_t;
 
 /**
@@ -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
  * @{
  */
@@ -49,7 +49,7 @@ typedef enum {
 	 * order; this sorting mode can be combined with
 	 * any of the above.
 	 */
-	GIT_SORT_REVERSE = 1 << 2,
+	GIT_SORT_REVERSE = 1 << 2
 } git_sort_t;
 
 /**
@@ -249,6 +249,7 @@ GIT_EXTERN(int) git_revwalk_push_range(git_revwalk *walk, const char *range);
  *
  * No parents other than the first for each commit will be enqueued.
  *
+ * @param walk The revision walker.
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_revwalk_simplify_first_parent(git_revwalk *walk);
@@ -277,6 +278,7 @@ GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk);
  *
  * @param commit_id oid of Commit
  * @param payload User-specified pointer to data to be passed as data payload
+ * @return non-zero to hide the commmit and it parent.
  */
 typedef int GIT_CALLBACK(git_revwalk_hide_cb)(
 	const git_oid *commit_id,
@@ -288,6 +290,7 @@ typedef int GIT_CALLBACK(git_revwalk_hide_cb)(
  * @param walk the revision walker
  * @param hide_cb  callback function to hide a commit and its parents
  * @param payload  data payload to be passed to callback function
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_revwalk_add_hide_cb(
 	git_revwalk *walk,
@@ -296,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
@@ -71,7 +115,7 @@ GIT_EXTERN(int) git_signature_default(git_signature **out, git_repository *repo)
  *
  * @param out new signature
  * @param buf signature string
- * @return 0 on success, or an error code
+ * @return 0 on success, GIT_EINVALID if the signature is not parseable, or an error code
  */
 GIT_EXTERN(int) git_signature_from_buffer(git_signature **out, const char *buf);
 
@@ -100,4 +144,5 @@ GIT_EXTERN(void) git_signature_free(git_signature *sig);
 
 /** @} */
 GIT_END_DECL
+
 #endif