rugged 1.7.2 → 1.9.0

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

@@ -4,13 +4,23 @@
  * This file is part of libgit2, distributed under the GNU GPL v2 with
  * a Linking Exception. For full terms see the included COPYING file.
  */
-#ifndef _INCLUDE_git_indexer_h__
-#define _INCLUDE_git_indexer_h__
+#ifndef INCLUDE_git_indexer_h__
+#define INCLUDE_git_indexer_h__
 
 #include "common.h"
 #include "types.h"
 #include "oid.h"
 
+/**
+ * @file git2/indexer.h
+ * @brief Packfile indexing
+ * @ingroup Git
+ * @{
+ *
+ * Indexing is the operation of taking a packfile - which is simply a
+ * collection of unordered commits - and producing an "index" so that
+ * one can lookup a commit in the packfile by object ID.
+ */
 GIT_BEGIN_DECL
 
 /** A git indexer object */
@@ -53,6 +63,7 @@ typedef struct git_indexer_progress {
  *
  * @param stats Structure containing information about the state of the transfer
  * @param payload Payload provided by caller
+ * @return 0 on success or an error code
  */
 typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *stats, void *payload);
 
@@ -66,6 +77,9 @@ typedef struct git_indexer_options {
 	/** permissions to use creating packfile or 0 for defaults */
 	unsigned int mode;
 
+	/** the type of object ids in the packfile or 0 for SHA1 */
+	git_oid_t oid_type;
+
 	/**
 	 * object database from which to read base objects when
 	 * fixing thin packs. This can be NULL if there are no thin
@@ -85,7 +99,10 @@ typedef struct git_indexer_options {
 	unsigned char verify;
 } git_indexer_options;
 
+/** Current version for the `git_indexer_options` structure */
 #define GIT_INDEXER_OPTIONS_VERSION 1
+
+/** Static constructor for `git_indexer_options` */
 #define GIT_INDEXER_OPTIONS_INIT { GIT_INDEXER_OPTIONS_VERSION }
 
 /**
@@ -106,13 +123,12 @@ GIT_EXTERN(int) git_indexer_options_init(
  *
  * @param out where to store the indexer instance
  * @param path to the directory where the packfile should be stored
- * @param oid_type the oid type to use for objects
+ * @param opts the options to create the indexer with
  * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_indexer_new(
 		git_indexer **out,
 		const char *path,
-		git_oid_t oid_type,
 		git_indexer_options *opts);
 #else
 /**
@@ -190,6 +206,7 @@ GIT_EXTERN(const char *) git_indexer_name(const git_indexer *idx);
  */
 GIT_EXTERN(void) git_indexer_free(git_indexer *idx);
 
+/** @} */
 GIT_END_DECL
 
 #endif

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

@@ -13,10 +13,15 @@
 
 /**
  * @file git2/mailmap.h
- * @brief Mailmap parsing routines
+ * @brief Mailmaps provide alternate email addresses for users
  * @defgroup git_mailmap Git mailmap routines
  * @ingroup Git
  * @{
+ *
+ * A mailmap can be used to specify alternate email addresses for
+ * repository committers or authors. This allows systems to map
+ * commits made using different email addresses to the same logical
+ * person.
  */
 GIT_BEGIN_DECL
 
@@ -112,4 +117,5 @@ GIT_EXTERN(int) git_mailmap_resolve_signature(
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -17,9 +17,12 @@
 
 /**
  * @file git2/merge.h
- * @brief Git merge routines
+ * @brief Merge re-joins diverging branches of history
  * @defgroup git_merge Git merge routines
  * @ingroup Git
+ *
+ * Merge will take two commits and attempt to produce a commit that
+ * includes the changes that were made in both branches.
  * @{
  */
 GIT_BEGIN_DECL
@@ -45,7 +48,10 @@ typedef struct {
 	unsigned int mode;
 } git_merge_file_input;
 
+/** Current version for the `git_merge_file_input_options` structure */
 #define GIT_MERGE_FILE_INPUT_VERSION 1
+
+/** Static constructor for `git_merge_file_input_options` */
 #define GIT_MERGE_FILE_INPUT_INIT {GIT_MERGE_FILE_INPUT_VERSION}
 
 /**
@@ -180,6 +186,7 @@ typedef enum {
 	GIT_MERGE_FILE_ACCEPT_CONFLICTS = (1 << 9)
 } git_merge_file_flag_t;
 
+/** Default size for conflict markers */
 #define GIT_MERGE_CONFLICT_MARKER_SIZE	7
 
 /**
@@ -217,7 +224,10 @@ typedef struct {
 	unsigned short marker_size;
 } git_merge_file_options;
 
+/** Current version for the `git_merge_file_options` structure */
 #define GIT_MERGE_FILE_OPTIONS_VERSION 1
+
+/** Static constructor for `git_merge_file_options` */
 #define GIT_MERGE_FILE_OPTIONS_INIT {GIT_MERGE_FILE_OPTIONS_VERSION}
 
 /**
@@ -312,7 +322,10 @@ typedef struct {
 	uint32_t file_flags;
 } git_merge_options;
 
+/** Current version for the `git_merge_options` structure */
 #define GIT_MERGE_OPTIONS_VERSION 1
+
+/** Static constructor for `git_merge_options` */
 #define GIT_MERGE_OPTIONS_INIT { \
 	GIT_MERGE_OPTIONS_VERSION, GIT_MERGE_FIND_RENAMES }
 
@@ -471,6 +484,37 @@ GIT_EXTERN(int) git_merge_base_many(
 /**
  * Find all merge bases given a list of commits
  *
+ * This behaves similar to [`git merge-base`](https://git-scm.com/docs/git-merge-base#_discussion).
+ *
+ * Given three commits `a`, `b`, and `c`, `merge_base_many`
+ * will compute a hypothetical commit `m`, which is a merge between `b`
+ * and `c`.
+
+ * For example, with the following topology:
+ * ```text
+ *        o---o---o---o---C
+ *       /
+ *      /   o---o---o---B
+ *     /   /
+ * ---2---1---o---o---o---A
+ * ```
+ *
+ * the result of `merge_base_many` given `a`, `b`, and `c` is 1. This is
+ * because the equivalent topology with the imaginary merge commit `m`
+ * between `b` and `c` is:
+ * ```text
+ *        o---o---o---o---o
+ *       /                 \
+ *      /   o---o---o---o---M
+ *     /   /
+ * ---2---1---o---o---o---A
+ * ```
+ *
+ * and the result of `merge_base_many` given `a` and `m` is 1.
+ *
+ * If you're looking to recieve the common ancestor between all the
+ * given commits, use `merge_base_octopus`.
+ *
  * @param out array in which to store the resulting ids
  * @param repo the repository where the commits exist
  * @param length The number of commits in the provided `input_array`
@@ -623,4 +667,5 @@ GIT_EXTERN(int) git_merge(
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -12,7 +12,7 @@
 
 /**
  * @file git2/message.h
- * @brief Git message management routines
+ * @brief Commit messages
  * @ingroup Git
  * @{
  */
@@ -83,4 +83,4 @@ GIT_EXTERN(void) git_message_trailer_array_free(git_message_trailer_array *arr);
 /** @} */
 GIT_END_DECL
 
-#endif /* INCLUDE_git_message_h__ */
+#endif

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

@@ -13,12 +13,13 @@
 
 /**
  * @file git2/net.h
- * @brief Git networking declarations
+ * @brief Low-level networking functionality
  * @ingroup Git
  * @{
  */
 GIT_BEGIN_DECL
 
+/** Default git protocol port number */
 #define GIT_DEFAULT_PORT "9418"
 
 /**
@@ -51,4 +52,5 @@ struct git_remote_head {
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -11,7 +11,7 @@
 
 /**
  * @file git2/notes.h
- * @brief Git notes management routines
+ * @brief Notes are metadata attached to an object
  * @defgroup git_note Git notes management routines
  * @ingroup Git
  * @{
@@ -21,13 +21,15 @@ GIT_BEGIN_DECL
 /**
  * Callback for git_note_foreach.
  *
- * Receives:
- * - blob_id: Oid of the blob containing the message
- * - annotated_object_id: Oid of the git object being annotated
- * - payload: Payload data passed to `git_note_foreach`
+ * @param blob_id object id of the blob containing the message
+ * @param annotated_object_id the id of the object being annotated
+ * @param payload user-specified data to the foreach function
+ * @return 0 on success, or a negative number on failure
  */
 typedef int GIT_CALLBACK(git_note_foreach_cb)(
-	const git_oid *blob_id, const git_oid *annotated_object_id, void *payload);
+	const git_oid *blob_id,
+	const git_oid *annotated_object_id,
+	void *payload);
 
 /**
  * note iterator
@@ -303,4 +305,5 @@ GIT_EXTERN(int) git_note_foreach(
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -14,13 +14,14 @@
 
 /**
  * @file git2/object.h
- * @brief Git revision object management routines
+ * @brief Objects are blobs (files), trees (directories), commits, and annotated tags
  * @defgroup git_object Git revision object management routines
  * @ingroup Git
  * @{
  */
 GIT_BEGIN_DECL
 
+/** Maximum size of a git object */
 #define GIT_OBJECT_SIZE_MAX UINT64_MAX
 
 /**
@@ -53,18 +54,18 @@ GIT_EXTERN(int) git_object_lookup(
  *
  * The object obtained will be so that its identifier
  * matches the first 'len' hexadecimal characters
- * (packets of 4 bits) of the given 'id'.
- * 'len' must be at least GIT_OID_MINPREFIXLEN, and
- * long enough to identify a unique object matching
- * the prefix; otherwise the method will fail.
+ * (packets of 4 bits) of the given `id`. `len` must be
+ * at least `GIT_OID_MINPREFIXLEN`, and long enough to
+ * identify a unique object matching the prefix; otherwise
+ * the method will fail.
  *
  * The generated reference is owned by the repository and
  * should be closed with the `git_object_free` method
  * instead of free'd manually.
  *
- * The 'type' parameter must match the type of the object
+ * The `type` parameter must match the type of the object
  * in the odb; the method will fail otherwise.
- * The special value 'GIT_OBJECT_ANY' may be passed to let
+ * The special value `GIT_OBJECT_ANY` may be passed to let
  * the method guess the object's type.
  *
  * @param object_out pointer where to store the looked-up object
@@ -260,7 +261,7 @@ GIT_EXTERN(int) git_object_rawcontent_is_valid(
  * @warning This function is experimental and its signature may change in
  * the future.
  *
- * @param valid Output pointer to set with validity of the object content
+ * @param[out] valid Output pointer to set with validity of the object content
  * @param buf The contents to validate
  * @param len The length of the buffer
  * @param object_type The type of the object in the buffer

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

@@ -15,7 +15,7 @@
 
 /**
  * @file git2/odb.h
- * @brief Git object database routines
+ * @brief An object database manages the storage of git objects
  * @defgroup git_odb Git object database routines
  * @ingroup Git
  * @{
@@ -35,6 +35,10 @@ typedef enum {
 
 /**
  * Function type for callbacks from git_odb_foreach.
+ *
+ * @param id an id of an object in the object database
+ * @param payload the payload from the initial call to git_odb_foreach
+ * @return 0 on success, or an error code
  */
 typedef int GIT_CALLBACK(git_odb_foreach_cb)(const git_oid *id, void *payload);
 
@@ -49,30 +53,53 @@ typedef struct {
 	git_oid_t oid_type;
 } git_odb_options;
 
-/* The current version of the diff options structure */
+/** The current version of the diff options structure */
 #define GIT_ODB_OPTIONS_VERSION 1
 
-/* Stack initializer for odb options.  Alternatively use
+/**
+ * Stack initializer for odb options.  Alternatively use
  * `git_odb_options_init` programmatic initialization.
  */
 #define GIT_ODB_OPTIONS_INIT { GIT_ODB_OPTIONS_VERSION }
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+
 /**
  * Create a new object database with no backends.
  *
- * Before the ODB can be used for read/writing, a custom database
- * backend must be manually added using `git_odb_add_backend()`
+ * @param[out] odb location to store the database pointer, if opened.
+ * @param opts the options for this object database or NULL for defaults
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_new(git_odb **odb, const git_odb_options *opts);
+
+/**
+ * Create a new object database and automatically add loose and packed
+ * backends.
  *
- * @param out location to store the database pointer, if opened.
+ * @param[out] odb_out location to store the database pointer, if opened.
  *			Set to NULL if the open failed.
+ * @param objects_dir path of the backends' "objects" directory.
  * @param opts the options for this object database or NULL for defaults
  * @return 0 or an error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_odb_new(git_odb **out, const git_odb_options *opts);
+GIT_EXTERN(int) git_odb_open(
+	git_odb **odb_out,
+	const char *objects_dir,
+	const git_odb_options *opts);
+
 #else
-GIT_EXTERN(int) git_odb_new(git_odb **out);
-#endif
+
+/**
+ * Create a new object database with no backends.
+ *
+ * Before the ODB can be used for read/writing, a custom database
+ * backend must be manually added using `git_odb_add_backend()`
+ *
+ * @param[out] odb location to store the database pointer, if opened.
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_new(git_odb **odb);
 
 /**
  * Create a new object database and automatically add
@@ -85,19 +112,12 @@ GIT_EXTERN(int) git_odb_new(git_odb **out);
  *		assuming `objects_dir` as the Objects folder which
  *		contains a 'pack/' folder with the corresponding data
  *
- * @param out location to store the database pointer, if opened.
+ * @param[out] odb_out location to store the database pointer, if opened.
  *			Set to NULL if the open failed.
  * @param objects_dir path of the backends' "objects" directory.
- * @param opts the options for this object database or NULL for defaults
  * @return 0 or an error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_odb_open(
-	git_odb **out,
-	const char *objects_dir,
-	const git_odb_options *opts);
-#else
-GIT_EXTERN(int) git_odb_open(git_odb **out, const char *objects_dir);
+GIT_EXTERN(int) git_odb_open(git_odb **odb_out, const char *objects_dir);
 #endif
 
 /**
@@ -134,13 +154,13 @@ GIT_EXTERN(void) git_odb_free(git_odb *db);
  * internally cached, so it should be closed
  * by the user once it's no longer in use.
  *
- * @param out pointer where to store the read object
+ * @param[out] obj pointer where to store the read object
  * @param db database to search for the object in.
  * @param id identity of the object to read.
  * @return 0 if the object was read, GIT_ENOTFOUND if the object is
  *         not in the database.
  */
-GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *id);
+GIT_EXTERN(int) git_odb_read(git_odb_object **obj, git_odb *db, const git_oid *id);
 
 /**
  * Read an object from the database, given a prefix
@@ -160,7 +180,7 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i
  * internally cached, so it should be closed
  * by the user once it's no longer in use.
  *
- * @param out pointer where to store the read object
+ * @param[out] obj pointer where to store the read object
  * @param db database to search for the object in.
  * @param short_id a prefix of the id of the object to read.
  * @param len the length of the prefix
@@ -168,7 +188,7 @@ GIT_EXTERN(int) git_odb_read(git_odb_object **out, git_odb *db, const git_oid *i
  *         database. GIT_EAMBIGUOUS if the prefix is ambiguous
  *         (several objects match the prefix)
  */
-GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git_oid *short_id, size_t len);
+GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **obj, git_odb *db, const git_oid *short_id, size_t len);
 
 /**
  * Read the header of an object from the database, without
@@ -180,8 +200,8 @@ GIT_EXTERN(int) git_odb_read_prefix(git_odb_object **out, git_odb *db, const git
  * of an object, so the whole object will be read and then the
  * header will be returned.
  *
- * @param len_out pointer where to store the length
- * @param type_out pointer where to store the type
+ * @param[out] len_out pointer where to store the length
+ * @param[out] type_out pointer where to store the type
  * @param db database to search for the object in.
  * @param id identity of the object to read.
  * @return 0 if the object was read, GIT_ENOTFOUND if the object is not
@@ -286,7 +306,7 @@ GIT_EXTERN(int) git_odb_expand_ids(
  * @param db database to refresh
  * @return 0 on success, error code otherwise
  */
-GIT_EXTERN(int) git_odb_refresh(struct git_odb *db);
+GIT_EXTERN(int) git_odb_refresh(git_odb *db);
 
 /**
  * List all objects available in the database
@@ -301,7 +321,10 @@ GIT_EXTERN(int) git_odb_refresh(struct git_odb *db);
  * @param payload data to pass to the callback
  * @return 0 on success, non-zero callback return value, or error code
  */
-GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payload);
+GIT_EXTERN(int) git_odb_foreach(
+	git_odb *db,
+	git_odb_foreach_cb cb,
+	void *payload);
 
 /**
  * Write an object directly into the ODB
@@ -316,7 +339,7 @@ GIT_EXTERN(int) git_odb_foreach(git_odb *db, git_odb_foreach_cb cb, void *payloa
  *
  * @param out pointer to store the OID result of the write
  * @param odb object database where to store the object
- * @param data buffer with the data to store
+ * @param data @type `const unsigned char *` buffer with the data to store
  * @param len size of the buffer
  * @param type type of the data to store
  * @return 0 or an error code
@@ -382,7 +405,7 @@ GIT_EXTERN(int) git_odb_stream_finalize_write(git_oid *out, git_odb_stream *stre
  * @param stream the stream
  * @param buffer a user-allocated buffer to store the data in.
  * @param len the buffer's length
- * @return 0 if the read succeeded, error code otherwise
+ * @return the number of bytes read if succeeded, error code otherwise
  */
 GIT_EXTERN(int) git_odb_stream_read(git_odb_stream *stream, char *buffer, size_t len);
 
@@ -466,29 +489,54 @@ GIT_EXTERN(int) git_odb_write_pack(
 GIT_EXTERN(int) git_odb_write_multi_pack_index(
 	git_odb *db);
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+
 /**
- * Determine the object-ID (sha1 or sha256 hash) of a data buffer
+ * Generate the object ID (in SHA1 or SHA256 format) for a given data buffer.
  *
- * The resulting OID will be the identifier for the data buffer as if
- * the data buffer it were to written to the ODB.
- *
- * @param out the resulting object-ID.
+ * @param[out] oid the resulting object ID.
  * @param data data to hash
  * @param len size of the data
  * @param object_type of the data to hash
  * @param oid_type the oid type to hash to
  * @return 0 or an error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
 GIT_EXTERN(int) git_odb_hash(
-	git_oid *out,
+	git_oid *oid,
 	const void *data,
 	size_t len,
 	git_object_t object_type,
 	git_oid_t oid_type);
+
+/**
+ * Determine the object ID of a file on disk.
+ *
+ * @param[out] oid oid structure the result is written into.
+ * @param path file to read and determine object id for
+ * @param object_type of the data to hash
+ * @param oid_type the oid type to hash to
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_hashfile(
+	git_oid *oid,
+	const char *path,
+	git_object_t object_type,
+	git_oid_t oid_type);
 #else
-GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_object_t type);
-#endif
+
+/**
+ * Determine the object-ID (sha1 or sha256 hash) of a data buffer
+ *
+ * The resulting OID will be the identifier for the data buffer as if
+ * the data buffer it were to written to the ODB.
+ *
+ * @param[out] oid the resulting object-ID.
+ * @param data data to hash
+ * @param len size of the data
+ * @param object_type of the data to hash
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_odb_hash(git_oid *oid, const void *data, size_t len, git_object_t object_type);
 
 /**
  * Read a file from disk and fill a git_oid with the object id
@@ -498,20 +546,13 @@ GIT_EXTERN(int) git_odb_hash(git_oid *out, const void *data, size_t len, git_obj
  * the `-w` flag, however, with the --no-filters flag.
  * If you need filters, see git_repository_hashfile.
  *
- * @param out oid structure the result is written into.
+ * @param[out] oid oid structure the result is written into.
  * @param path file to read and determine object id for
  * @param object_type of the data to hash
- * @param oid_type the oid type to hash to
  * @return 0 or an error code
  */
-#ifdef GIT_EXPERIMENTAL_SHA256
-GIT_EXTERN(int) git_odb_hashfile(
-	git_oid *out,
-	const char *path,
-	git_object_t object_type,
-	git_oid_t oid_type);
-#else
-GIT_EXTERN(int) git_odb_hashfile(git_oid *out, const char *path, git_object_t type);
+GIT_EXTERN(int) git_odb_hashfile(git_oid *oid, const char *path, git_object_t object_type);
+
 #endif
 
 /**
@@ -557,7 +598,7 @@ GIT_EXTERN(const git_oid *) git_odb_object_id(git_odb_object *object);
  * This pointer is owned by the object and shall not be free'd.
  *
  * @param object the object
- * @return a pointer to the data
+ * @return @type `const unsigned char *` a pointer to the data
  */
 GIT_EXTERN(const void *) git_odb_object_data(git_odb_object *object);
 
@@ -651,4 +692,5 @@ GIT_EXTERN(int) git_odb_set_commit_graph(git_odb *odb, git_commit_graph *cgraph)
 
 /** @} */
 GIT_END_DECL
+
 #endif