rugged 1.6.3 → 1.9.0

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

@@ -15,9 +15,14 @@
 
 /**
  * @file git2/index.h
- * @brief Git index parsing and manipulation routines
+ * @brief Index (aka "cache" aka "staging area")
  * @defgroup git_index Git index parsing and manipulation routines
  * @ingroup Git
+ *
+ * The index (or "cache", or "staging area") is the contents of the
+ * next commit. In addition, the index stores other data, such as
+ * conflicts that occurred during the last merge operation, and
+ * the "treecache" to speed up various on-disk operations.
  * @{
  */
 GIT_BEGIN_DECL
@@ -77,8 +82,11 @@ typedef struct git_index_entry {
  * data in the `flags`.
  */
 
+/** Mask for name length */
 #define GIT_INDEX_ENTRY_NAMEMASK  (0x0fff)
+/** Mask for index entry stage */
 #define GIT_INDEX_ENTRY_STAGEMASK (0x3000)
+/** Shift bits for index entry */
 #define GIT_INDEX_ENTRY_STAGESHIFT 12
 
 /**
@@ -89,9 +97,17 @@ typedef enum {
 	GIT_INDEX_ENTRY_VALID     = (0x8000)
 } git_index_entry_flag_t;
 
+/**
+ * Macro to get the stage value (0 for the "main index", or a conflict
+ * value) from an index entry.
+ */
 #define GIT_INDEX_ENTRY_STAGE(E) \
 	(((E)->flags & GIT_INDEX_ENTRY_STAGEMASK) >> GIT_INDEX_ENTRY_STAGESHIFT)
 
+/**
+ * Macro to set the stage value (0 for the "main index", or a conflict
+ * value) for an index entry.
+ */
 #define GIT_INDEX_ENTRY_STAGE_SET(E,S) do { \
 	(E)->flags = ((E)->flags & ~GIT_INDEX_ENTRY_STAGEMASK) | \
 		(((S) & 0x03) << GIT_INDEX_ENTRY_STAGESHIFT); } while (0)
@@ -131,7 +147,14 @@ typedef enum {
 } git_index_capability_t;
 
 
-/** Callback for APIs that add/remove/update files matching pathspec */
+/**
+ * Callback for APIs that add/remove/update files matching pathspec
+ *
+ * @param path the path
+ * @param matched_pathspec the given pathspec
+ * @param payload the user-specified payload
+ * @return 0 to continue with the index operation, positive number to         skip this file for the index operation, negative number on failure
+ */
 typedef int GIT_CALLBACK(git_index_matched_path_cb)(
 	const char *path, const char *matched_pathspec, void *payload);
 
@@ -166,6 +189,74 @@ typedef enum {
 	GIT_INDEX_STAGE_THEIRS = 3
 } git_index_stage_t;
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+
+/**
+ * The options for opening or creating an index.
+ *
+ * Initialize with `GIT_INDEX_OPTIONS_INIT`. Alternatively, you can
+ * use `git_index_options_init`.
+ *
+ * @options[version] GIT_INDEX_OPTIONS_VERSION
+ * @options[init_macro] GIT_INDEX_OPTIONS_INIT
+ * @options[init_function] git_index_options_init
+ */
+typedef struct git_index_options {
+	unsigned int version; /**< The version */
+
+	/**
+	 * The object ID type for the object IDs that exist in the index.
+	 *
+	 * If this is not specified, this defaults to `GIT_OID_SHA1`.
+	 */
+	git_oid_t oid_type;
+} git_index_options;
+
+/** Current version for the `git_index_options` structure */
+#define GIT_INDEX_OPTIONS_VERSION 1
+
+/** Static constructor for `git_index_options` */
+#define GIT_INDEX_OPTIONS_INIT { GIT_INDEX_OPTIONS_VERSION }
+
+/**
+ * Initialize git_index_options structure
+ *
+ * Initializes a `git_index_options` with default values. Equivalent to creating
+ * an instance with GIT_INDEX_OPTIONS_INIT.
+ *
+ * @param opts The `git_index_options` struct to initialize.
+ * @param version The struct version; pass `GIT_INDEX_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
+ */
+GIT_EXTERN(int) git_index_options_init(
+	git_index_options *opts,
+	unsigned int version);
+
+/**
+ * Creates a new bare Git index object, without a repository to back
+ * it. This index object is capable of storing SHA256 objects.
+ *
+ * @param index_out the pointer for the new index
+ * @param index_path the path to the index file in disk
+ * @param opts the options for opening the index, or NULL
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_index_open(
+	git_index **index_out,
+	const char *index_path,
+	const git_index_options *opts);
+
+/**
+ * Create an in-memory index object.
+ *
+ * @param index_out the pointer for the new index
+ * @param opts the options for opening the index, or NULL
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_index_new(git_index **index_out, const git_index_options *opts);
+
+#else
+
 /**
  * Create a new bare Git index object as a memory representation
  * of the Git index file in 'index_path', without a repository
@@ -180,11 +271,11 @@ typedef enum {
  *
  * The index must be freed once it's no longer in use.
  *
- * @param out the pointer for the new index
+ * @param index_out the pointer for the new index
  * @param index_path the path to the index file in disk
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path);
+GIT_EXTERN(int) git_index_open(git_index **index_out, const char *index_path);
 
 /**
  * Create an in-memory index object.
@@ -194,10 +285,12 @@ GIT_EXTERN(int) git_index_open(git_index **out, const char *index_path);
  *
  * The index must be freed once it's no longer in use.
  *
- * @param out the pointer for the new index
+ * @param index_out the pointer for the new index
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_index_new(git_index **out);
+GIT_EXTERN(int) git_index_new(git_index **index_out);
+
+#endif
 
 /**
  * Free an existing index object.
@@ -836,4 +929,5 @@ GIT_EXTERN(void) git_index_conflict_iterator_free(
 
 /** @} */
 GIT_END_DECL
+
 #endif

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