rugged 1.3.1 → 1.9.0

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}
 
 /**
@@ -92,6 +98,14 @@ typedef enum {
 	 * merge base to `git-merge-resolve`.
 	 */
 	GIT_MERGE_NO_RECURSIVE = (1 << 3),
+
+	/**
+	 * Treat this merge as if it is to produce the virtual base
+	 * of a recursive merge.  This will ensure that there are
+	 * no conflicts, any conflicting regions will keep conflict
+	 * markers in the merge result.
+	 */
+	GIT_MERGE_VIRTUAL_BASE = (1 << 4)
 } git_merge_flag_t;
 
 /**
@@ -127,7 +141,7 @@ typedef enum {
 	 * which has the result of combining both files.  The index will not
 	 * record a conflict.
 	 */
-	GIT_MERGE_FILE_FAVOR_UNION = 3,
+	GIT_MERGE_FILE_FAVOR_UNION = 3
 } git_merge_file_favor_t;
 
 /**
@@ -160,8 +174,19 @@ typedef enum {
 
 	/** Take extra time to find minimal diff */
 	GIT_MERGE_FILE_DIFF_MINIMAL = (1 << 7),
+
+	/** Create zdiff3 ("zealous diff3")-style files */
+	GIT_MERGE_FILE_STYLE_ZDIFF3 = (1 << 8),
+
+	/**
+	 * Do not produce file conflicts when common regions have
+	 * changed; keep the conflict markers in the file and accept
+	 * that as the merge result.
+	 */
+	GIT_MERGE_FILE_ACCEPT_CONFLICTS = (1 << 9)
 } git_merge_file_flag_t;
 
+/** Default size for conflict markers */
 #define GIT_MERGE_CONFLICT_MARKER_SIZE	7
 
 /**
@@ -199,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}
 
 /**
@@ -294,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 }
 
@@ -341,7 +372,7 @@ typedef enum {
 	 * a valid commit.  No merge can be performed, but the caller may wish
 	 * to simply set HEAD to the target commit(s).
 	 */
-	GIT_MERGE_ANALYSIS_UNBORN = (1 << 3),
+	GIT_MERGE_ANALYSIS_UNBORN = (1 << 3)
 } git_merge_analysis_t;
 
 /**
@@ -364,7 +395,7 @@ typedef enum {
 	 * There is a `merge.ff=only` configuration setting, suggesting that
 	 * the user only wants fast-forward merges.
 	 */
-	GIT_MERGE_PREFERENCE_FASTFORWARD_ONLY = (1 << 1),
+	GIT_MERGE_PREFERENCE_FASTFORWARD_ONLY = (1 << 1)
 } git_merge_preference_t;
 
 /**
@@ -372,6 +403,7 @@ typedef enum {
  * merging them into the HEAD of the repository.
  *
  * @param analysis_out analysis enumeration that the result is written into
+ * @param preference_out One of the `git_merge_preference_t` flag.
  * @param repo the repository to merge
  * @param their_heads the heads to merge into
  * @param their_heads_len the number of heads to merge
@@ -389,6 +421,7 @@ GIT_EXTERN(int) git_merge_analysis(
  * merging them into a reference.
  *
  * @param analysis_out analysis enumeration that the result is written into
+ * @param preference_out One of the `git_merge_preference_t` flag.
  * @param repo the repository to merge
  * @param our_ref the reference to perform the analysis from
  * @param their_heads the heads to merge into
@@ -451,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`
@@ -583,7 +647,7 @@ GIT_EXTERN(int) git_merge_commits(
  * completes, resolve any conflicts and prepare a commit.
  *
  * For compatibility with git, the repository is put into a merging
- * state. Once the commit is done (or if the uses wishes to abort),
+ * state. Once the commit is done (or if the user wishes to abort),
  * you should clear this state by calling
  * `git_repository_state_cleanup()`.
  *
@@ -603,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
  * @{
  */
@@ -75,10 +75,12 @@ GIT_EXTERN(int) git_message_trailers(git_message_trailer_array *arr, const char
 /**
  * Clean's up any allocated memory in the git_message_trailer_array filled by
  * a call to git_message_trailers.
+ *
+ * @param arr The trailer to free.
  */
 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
@@ -221,9 +222,58 @@ GIT_EXTERN(int) git_object_peel(
  *
  * @param dest Pointer to store the copy of the object
  * @param source Original object to copy
+ * @return 0 or an error code
  */
 GIT_EXTERN(int) git_object_dup(git_object **dest, git_object *source);
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+/**
+ * Analyzes a buffer of raw object content and determines its validity.
+ * Tree, commit, and tag objects will be parsed and ensured that they
+ * are valid, parseable content.  (Blobs are always valid by definition.)
+ * An error message will be set with an informative message if the object
+ * is not 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 buf The contents to validate
+ * @param len The length of the buffer
+ * @param object_type The type of the object in the buffer
+ * @param oid_type The object ID type for the OIDs in the given buffer
+ * @return 0 on success or an error code
+ */
+GIT_EXTERN(int) git_object_rawcontent_is_valid(
+	int *valid,
+	const char *buf,
+	size_t len,
+	git_object_t object_type,
+	git_oid_t oid_type);
+#else
+/**
+ * Analyzes a buffer of raw object content and determines its validity.
+ * Tree, commit, and tag objects will be parsed and ensured that they
+ * are valid, parseable content.  (Blobs are always valid by definition.)
+ * An error message will be set with an informative message if the object
+ * is not valid.
+ *
+ * @warning This function is experimental and its signature may change in
+ * the future.
+ *
+ * @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
+ * @return 0 on success or an error code
+ */
+GIT_EXTERN(int) git_object_rawcontent_is_valid(
+	int *valid,
+	const char *buf,
+	size_t len,
+	git_object_t object_type);
+#endif
+
 /** @} */
 GIT_END_DECL