rugged 1.7.2 → 1.9.0

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

@@ -13,17 +13,13 @@
 
 /**
  * @file git2/backend.h
- * @brief Git custom backend functions
+ * @brief Object database backends manage the storage of git objects
  * @defgroup git_odb Git object database routines
  * @ingroup Git
  * @{
  */
 GIT_BEGIN_DECL
 
-/*
- * Constructors for in-box ODB backends.
- */
-
 /** Options for configuring a packfile object backend. */
 typedef struct {
 	unsigned int version; /**< version for the struct */
@@ -35,56 +31,16 @@ typedef struct {
 	git_oid_t oid_type;
 } git_odb_backend_pack_options;
 
-/* The current version of the diff options structure */
+/** The current version of the diff options structure */
 #define GIT_ODB_BACKEND_PACK_OPTIONS_VERSION 1
 
-/* Stack initializer for odb pack backend options.  Alternatively use
+/**
+ * Stack initializer for odb pack backend options.  Alternatively use
  * `git_odb_backend_pack_options_init` programmatic initialization.
  */
 #define GIT_ODB_BACKEND_PACK_OPTIONS_INIT \
 	{ GIT_ODB_BACKEND_PACK_OPTIONS_VERSION }
 
-/**
- * Create a backend for the packfiles.
- *
- * @param out location to store the odb backend pointer
- * @param objects_dir the Git repository's objects directory
- *
- * @return 0 or an error code
- */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_odb_backend_pack(
-	git_odb_backend **out,
-	const char *objects_dir,
-	const git_odb_backend_pack_options *opts);
-#else
-GIT_EXTERN(int) git_odb_backend_pack(
-	git_odb_backend **out,
-	const char *objects_dir);
-#endif
-
-/**
- * Create a backend out of a single packfile
- *
- * This can be useful for inspecting the contents of a single
- * packfile.
- *
- * @param out location to store the odb backend pointer
- * @param index_file path to the packfile's .idx file
- *
- * @return 0 or an error code
- */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_odb_backend_one_pack(
-	git_odb_backend **out,
-	const char *index_file,
-	const git_odb_backend_pack_options *opts);
-#else
-GIT_EXTERN(int) git_odb_backend_one_pack(
-	git_odb_backend **out,
-	const char *index_file);
-#endif
-
 typedef enum {
 	GIT_ODB_BACKEND_LOOSE_FSYNC = (1 << 0)
 } git_odb_backend_loose_flag_t;
@@ -118,30 +74,100 @@ typedef struct {
 	git_oid_t oid_type;
 } git_odb_backend_loose_options;
 
-/* The current version of the diff options structure */
+/** The current version of the diff options structure */
 #define GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION 1
 
-/* Stack initializer for odb loose backend options.  Alternatively use
+/**
+ * Stack initializer for odb loose backend options.  Alternatively use
  * `git_odb_backend_loose_options_init` programmatic initialization.
  */
 #define GIT_ODB_BACKEND_LOOSE_OPTIONS_INIT \
 	{ GIT_ODB_BACKEND_LOOSE_OPTIONS_VERSION, 0, -1 }
 
+/*
+ * Constructors for in-box ODB backends.
+ */
+
+#ifdef GIT_EXPERIMENTAL_SHA256
+
+/**
+ * Create a backend for a directory containing packfiles.
+ *
+ * @param[out] out location to store the odb backend pointer
+ * @param objects_dir the Git repository's objects directory
+ * @param opts the options to use when creating the pack backend
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_backend_pack(
+	git_odb_backend **out,
+	const char *objects_dir,
+	const git_odb_backend_pack_options *opts);
+
+/**
+ * Create a backend for a single packfile.
+ *
+ * @param[out] out location to store the odb backend pointer
+ * @param index_file path to the packfile's .idx file
+ * @param opts the options to use when creating the pack backend
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_backend_one_pack(
+	git_odb_backend **out,
+	const char *index_file,
+	const git_odb_backend_pack_options *opts);
+
 /**
  * Create a backend for loose objects
  *
- * @param out location to store the odb backend pointer
+ * @param[out] out location to store the odb backend pointer
  * @param objects_dir the Git repository's objects directory
  * @param opts options for the loose object backend or NULL
  *
  * @return 0 or an error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
 GIT_EXTERN(int) git_odb_backend_loose(
 	git_odb_backend **out,
 	const char *objects_dir,
 	git_odb_backend_loose_options *opts);
+
 #else
+
+/**
+ * Create a backend for a directory containing packfiles.
+ *
+ * @param[out] out location to store the odb backend pointer
+ * @param objects_dir the Git repository's objects directory
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_backend_pack(
+	git_odb_backend **out,
+	const char *objects_dir);
+
+/**
+ * Create a backend out of a single packfile
+ *
+ * This can be useful for inspecting the contents of a single
+ * packfile.
+ *
+ * @param[out] out location to store the odb backend pointer
+ * @param index_file path to the packfile's .idx file
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_backend_one_pack(
+	git_odb_backend **out,
+	const char *index_file);
+
+/**
+ * Create a backend for loose objects
+ *
+ * @param[out] out location to store the odb backend pointer
+ * @param objects_dir the Git repository's objects directory
+ * @param compression_level zlib compression level (0-9), or -1 for the default
+ * @param do_fsync if non-zero, perform an fsync on write
+ * @param dir_mode permission to use when creating directories, or 0 for default
+ * @param file_mode permission to use when creating directories, or 0 for default
+ * @return 0 or an error code
+ */
 GIT_EXTERN(int) git_odb_backend_loose(
 	git_odb_backend **out,
 	const char *objects_dir,
@@ -149,6 +175,7 @@ GIT_EXTERN(int) git_odb_backend_loose(
 	int do_fsync,
 	unsigned int dir_mode,
 	unsigned int file_mode);
+
 #endif
 
 /** Streaming mode */
@@ -218,6 +245,7 @@ struct git_odb_writepack {
 	void GIT_CALLBACK(free)(git_odb_writepack *writepack);
 };
 
+/** @} */
 GIT_END_DECL
 
 #endif

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

@@ -13,7 +13,7 @@
 
 /**
  * @file git2/oid.h
- * @brief Git object id routines
+ * @brief Object IDs
  * @defgroup git_oid Git object id routines
  * @ingroup Git
  * @{
@@ -82,13 +82,18 @@ typedef enum {
 
 #endif
 
-/* Maximum possible object ID size in raw / hex string format. */
-#ifndef GIT_EXPERIMENTAL_SHA256
-# define GIT_OID_MAX_SIZE        GIT_OID_SHA1_SIZE
-# define GIT_OID_MAX_HEXSIZE     GIT_OID_SHA1_HEXSIZE
-#else
+/** Maximum possible object ID size in raw format */
+#ifdef GIT_EXPERIMENTAL_SHA256
 # define GIT_OID_MAX_SIZE        GIT_OID_SHA256_SIZE
+#else
+# define GIT_OID_MAX_SIZE        GIT_OID_SHA1_SIZE
+#endif
+
+/** Maximum possible object ID size in hex format */
+#ifdef GIT_EXPERIMENTAL_SHA256
 # define GIT_OID_MAX_HEXSIZE     GIT_OID_SHA256_HEXSIZE
+#else
+# define GIT_OID_MAX_HEXSIZE     GIT_OID_SHA1_HEXSIZE
 #endif
 
 /** Minimum length (in number of hex characters,
@@ -107,6 +112,15 @@ typedef struct git_oid {
 	unsigned char id[GIT_OID_MAX_SIZE];
 } git_oid;
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+
+GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str, git_oid_t type);
+GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str, git_oid_t type);
+GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length, git_oid_t type);
+GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw, git_oid_t type);
+
+#else
+
 /**
  * Parse a hex formatted object id into a git_oid.
  *
@@ -119,28 +133,18 @@ typedef struct git_oid {
  *		the hex sequence and have at least the number of bytes
  *		needed for an oid encoded in hex (40 bytes for sha1,
  *		256 bytes for sha256).
- * @param type the type of object id
  * @return 0 or an error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str, git_oid_t type);
-#else
 GIT_EXTERN(int) git_oid_fromstr(git_oid *out, const char *str);
-#endif
 
 /**
  * Parse a hex formatted NUL-terminated string into a git_oid.
  *
  * @param out oid structure the result is written into.
  * @param str input hex string; must be null-terminated.
- * @param type the type of object id
  * @return 0 or an error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str, git_oid_t type);
-#else
 GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str);
-#endif
 
 /**
  * Parse N characters of a hex formatted object id into a git_oid.
@@ -151,14 +155,9 @@ GIT_EXTERN(int) git_oid_fromstrp(git_oid *out, const char *str);
  * @param out oid structure the result is written into.
  * @param str input hex string of at least size `length`
  * @param length length of the input string
- * @param type the type of object id
  * @return 0 or an error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length, git_oid_t type);
-#else
 GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length);
-#endif
 
 /**
  * Copy an already raw oid into a git_oid structure.
@@ -167,10 +166,8 @@ GIT_EXTERN(int) git_oid_fromstrn(git_oid *out, const char *str, size_t length);
  * @param raw the raw input bytes to be copied.
  * @return 0 on success or error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw, git_oid_t type);
-#else
 GIT_EXTERN(int) git_oid_fromraw(git_oid *out, const unsigned char *raw);
+
 #endif
 
 /**
@@ -310,6 +307,7 @@ GIT_EXTERN(int) git_oid_strcmp(const git_oid *id, const char *str);
 /**
  * Check is an oid is all zeros.
  *
+ * @param id the object ID to check
  * @return 1 if all zeros, 0 otherwise.
  */
 GIT_EXTERN(int) git_oid_is_zero(const git_oid *id);
@@ -370,4 +368,5 @@ GIT_EXTERN(void) git_oid_shorten_free(git_oid_shorten *os);
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -10,6 +10,13 @@
 #include "common.h"
 #include "oid.h"
 
+/**
+ * @file git2/oidarray.h
+ * @brief An array of object IDs
+ * @defgroup git_oidarray Arrays of object IDs
+ * @ingroup Git
+ * @{
+ */
 GIT_BEGIN_DECL
 
 /** Array of object ids */
@@ -34,4 +41,3 @@ GIT_EXTERN(void) git_oidarray_dispose(git_oidarray *array);
 GIT_END_DECL
 
 #endif
-

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

@@ -233,7 +233,15 @@ GIT_EXTERN(size_t) git_packbuilder_object_count(git_packbuilder *pb);
  */
 GIT_EXTERN(size_t) git_packbuilder_written(git_packbuilder *pb);
 
-/** Packbuilder progress notification function */
+/**
+ * Packbuilder progress notification function.
+ *
+ * @param stage the stage of the packbuilder
+ * @param current the current object
+ * @param total the total number of objects
+ * @param payload the callback payload
+ * @return 0 on success or an error code
+ */
 typedef int GIT_CALLBACK(git_packbuilder_progress)(
 	int stage,
 	uint32_t current,
@@ -247,6 +255,9 @@ typedef int GIT_CALLBACK(git_packbuilder_progress)(
  * @param progress_cb Function to call with progress information during
  * pack building. Be aware that this is called inline with pack building
  * operations, so performance may be affected.
+ * When progress_cb returns an error, the pack building process will be
+ * aborted and the error will be returned from the invoked function.
+ * `pb` must then be freed.
  * @param progress_cb_payload Payload for progress callback.
  * @return 0 or an error code
  */
@@ -264,4 +275,5 @@ GIT_EXTERN(void) git_packbuilder_free(git_packbuilder *pb);
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -14,7 +14,7 @@
 
 /**
  * @file git2/patch.h
- * @brief Patch handling routines.
+ * @brief Patches store the textual diffs in a delta
  * @ingroup Git
  * @{
  */
@@ -283,8 +283,7 @@ GIT_EXTERN(int) git_patch_to_buf(
 	git_buf *out,
 	git_patch *patch);
 
-GIT_END_DECL
-
 /**@}*/
+GIT_END_DECL
 
 #endif

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

@@ -12,6 +12,13 @@
 #include "strarray.h"
 #include "diff.h"
 
+/**
+ * @file git2/pathspec.h
+ * @brief Specifiers for path matching
+ * @defgroup git_pathspec Specifiers for path matching
+ * @ingroup Git
+ * @{
+ */
 GIT_BEGIN_DECL
 
 /**
@@ -276,5 +283,7 @@ GIT_EXTERN(size_t) git_pathspec_match_list_failed_entrycount(
 GIT_EXTERN(const char *) git_pathspec_match_list_failed_entry(
 	const git_pathspec_match_list *m, size_t pos);
 
+/** @} */
 GIT_END_DECL
+
 #endif

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

@@ -12,6 +12,12 @@
 #include "cert.h"
 #include "credential.h"
 
+/**
+ * @file git2/proxy.h
+ * @brief TLS proxies
+ * @ingroup Git
+ * @{
+ */
 GIT_BEGIN_DECL
 
 /**
@@ -78,7 +84,10 @@ typedef struct {
 	void *payload;
 } git_proxy_options;
 
+/** Current version for the `git_proxy_options` structure */
 #define GIT_PROXY_OPTIONS_VERSION 1
+
+/** Static constructor for `git_proxy_options` */
 #define GIT_PROXY_OPTIONS_INIT {GIT_PROXY_OPTIONS_VERSION}
 
 /**
@@ -93,6 +102,7 @@ typedef struct {
  */
 GIT_EXTERN(int) git_proxy_options_init(git_proxy_options *opts, unsigned int version);
 
+/** @} */
 GIT_END_DECL
 
 #endif

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

@@ -17,8 +17,8 @@
 
 /**
  * @file git2/rebase.h
- * @brief Git rebase routines
- * @defgroup git_rebase Git merge routines
+ * @brief Rebase manipulates commits, placing them on a new parent
+ * @defgroup git_rebase Rebase manipulates commits, placing them on a new parent
  * @ingroup Git
  * @{
  */
@@ -67,10 +67,9 @@ typedef struct {
 
 	/**
 	 * Options to control how files are written during `git_rebase_init`,
-	 * `git_rebase_next` and `git_rebase_abort`.  Note that a minimum
-	 * strategy of `GIT_CHECKOUT_SAFE` is defaulted in `init` and `next`,
-	 * and a minimum strategy of `GIT_CHECKOUT_FORCE` is defaulted in
-	 * `abort` to match git semantics.
+	 * `git_rebase_next` and `git_rebase_abort`.  Note that during
+	 * `abort`, these options will add an implied `GIT_CHECKOUT_FORCE`
+	 * to match git semantics.
 	 */
 	git_checkout_options checkout_options;
 
@@ -155,7 +154,10 @@ typedef enum {
 	GIT_REBASE_OPERATION_EXEC
 } git_rebase_operation_t;
 
+/** Current version for the `git_rebase_options` structure */
 #define GIT_REBASE_OPTIONS_VERSION 1
+
+/** Static constructor for `git_rebase_options` */
 #define GIT_REBASE_OPTIONS_INIT \
 	{ GIT_REBASE_OPTIONS_VERSION, 0, 0, NULL, GIT_MERGE_OPTIONS_INIT, \
 	  GIT_CHECKOUT_OPTIONS_INIT, NULL, NULL }
@@ -396,4 +398,5 @@ GIT_EXTERN(void) git_rebase_free(git_rebase *rebase);
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -14,8 +14,8 @@
 
 /**
  * @file git2/refdb.h
- * @brief Git custom refs backend functions
- * @defgroup git_refdb Git custom refs backend API
+ * @brief A database for references (branches and tags)
+ * @defgroup git_refdb A database for references (branches and tags)
  * @ingroup Git
  * @{
  */

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

@@ -13,8 +13,8 @@
 
 /**
  * @file git2/reflog.h
- * @brief Git reflog management routines
- * @defgroup git_reflog Git reflog management routines
+ * @brief Reference logs store how references change
+ * @defgroup git_reflog Reference logs store how references change
  * @ingroup Git
  * @{
  */
@@ -167,4 +167,5 @@ GIT_EXTERN(void) git_reflog_free(git_reflog *reflog);
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -14,8 +14,8 @@
 
 /**
  * @file git2/refs.h
- * @brief Git reference management routines
- * @defgroup git_reference Git reference management routines
+ * @brief References point to a commit; generally these are branches and tags
+ * @defgroup git_reference References point to a commit; generally these are branches and tags
  * @ingroup Git
  * @{
  */
@@ -29,7 +29,7 @@ GIT_BEGIN_DECL
  * The name will be checked for validity.
  * See `git_reference_symbolic_create()` for rules about valid names.
  *
- * @param out pointer to the looked-up reference
+ * @param[out] out pointer to the looked-up reference
  * @param repo the repository to look up the reference
  * @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...)
  * @return 0 on success, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code.
@@ -371,6 +371,7 @@ GIT_EXTERN(int) git_reference_set_target(
  * reflog is enabled for the repository. We only rename
  * the reflog if it exists.
  *
+ * @param[out] new_ref The new reference
  * @param ref The reference to rename
  * @param new_name The new name for the reference
  * @param force Overwrite an existing reference
@@ -406,6 +407,7 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref);
  * This method removes the named reference from the repository without
  * looking at its old value.
  *
+ * @param repo The repository to remove the reference from
  * @param name The reference to remove
  * @return 0 or an error code
  */
@@ -518,7 +520,7 @@ GIT_EXTERN(int) git_reference_cmp(
 /**
  * Create an iterator for the repo's references
  *
- * @param out pointer in which to store the iterator
+ * @param[out] out pointer in which to store the iterator
  * @param repo the repository
  * @return 0 or an error code
  */
@@ -543,7 +545,7 @@ GIT_EXTERN(int) git_reference_iterator_glob_new(
 /**
  * Get the next reference
  *
- * @param out pointer in which to store the reference
+ * @param[out] out pointer in which to store the reference
  * @param iter the iterator
  * @return 0, GIT_ITEROVER if there are no more; or an error code
  */
@@ -724,7 +726,7 @@ GIT_EXTERN(int) git_reference_normalize_name(
  * If you pass `GIT_OBJECT_ANY` as the target type, then the object
  * will be peeled until a non-tag object is met.
  *
- * @param out Pointer to the peeled git_object
+ * @param[out] out Pointer to the peeled git_object
  * @param ref The reference to be processed
  * @param type The type of the requested object (GIT_OBJECT_COMMIT,
  * GIT_OBJECT_TAG, GIT_OBJECT_TREE, GIT_OBJECT_BLOB or GIT_OBJECT_ANY).
@@ -768,4 +770,5 @@ GIT_EXTERN(const char *) git_reference_shorthand(const git_reference *ref);
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -14,8 +14,8 @@
 
 /**
  * @file git2/refspec.h
- * @brief Git refspec attributes
- * @defgroup git_refspec Git refspec attributes
+ * @brief Refspecs map local references to remote references
+ * @defgroup git_refspec Refspecs map local references to remote references
  * @ingroup Git
  * @{
  */
@@ -58,7 +58,7 @@ GIT_EXTERN(const char *) git_refspec_dst(const git_refspec *refspec);
  * Get the refspec's string
  *
  * @param refspec the refspec
- * @returns the refspec's original string
+ * @return the refspec's original string
  */
 GIT_EXTERN(const char *) git_refspec_string(const git_refspec *refspec);
 
@@ -79,7 +79,16 @@ GIT_EXTERN(int) git_refspec_force(const git_refspec *refspec);
 GIT_EXTERN(git_direction) git_refspec_direction(const git_refspec *spec);
 
 /**
- * Check if a refspec's source descriptor matches a reference 
+ * Check if a refspec's source descriptor matches a negative reference
+ *
+ * @param refspec the refspec
+ * @param refname the name of the reference to check
+ * @return 1 if the refspec matches, 0 otherwise
+ */
+GIT_EXTERN(int) git_refspec_src_matches_negative(const git_refspec *refspec, const char *refname);
+
+/**
+ * Check if a refspec's source descriptor matches a reference
  *
  * @param refspec the refspec
  * @param refname the name of the reference to check
@@ -116,6 +125,7 @@ GIT_EXTERN(int) git_refspec_transform(git_buf *out, const git_refspec *spec, con
  */
 GIT_EXTERN(int) git_refspec_rtransform(git_buf *out, const git_refspec *spec, const char *name);
 
+/** @} */
 GIT_END_DECL
 
 #endif