rugged 1.3.1 → 1.9.0

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

@@ -14,9 +14,15 @@
 
 /**
  * @file git2/filter.h
- * @brief Git filter APIs
- *
+ * @brief Filters modify files during checkout or commit
  * @ingroup Git
+ *
+ * During checkout, filters update a file from a "canonical" state to
+ * a format appropriate for the local filesystem; during commit, filters
+ * produce the canonical state. For example, on Windows, the line ending
+ * filters _may_ take a canonical state (with Unix-style newlines) in
+ * the repository, and place the contents on-disk with Windows-style
+ * `\r\n` line endings.
  * @{
  */
 GIT_BEGIN_DECL
@@ -32,7 +38,7 @@ typedef enum {
 	GIT_FILTER_TO_WORKTREE = 0,
 	GIT_FILTER_SMUDGE = GIT_FILTER_TO_WORKTREE,
 	GIT_FILTER_TO_ODB = 1,
-	GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB,
+	GIT_FILTER_CLEAN = GIT_FILTER_TO_ODB
 } git_filter_mode_t;
 
 /**
@@ -54,7 +60,7 @@ typedef enum {
 	 * Load attributes from `.gitattributes` in a given commit.
 	 * This can only be specified in a `git_filter_options`.
 	 */
-	GIT_FILTER_ATTRIBUTES_FROM_COMMIT = (1u << 3),
+	GIT_FILTER_ATTRIBUTES_FROM_COMMIT = (1u << 3)
 } git_filter_flag_t;
 
 /**
@@ -79,8 +85,11 @@ typedef struct {
 	git_oid attr_commit_id;
 } git_filter_options;
 
- #define GIT_FILTER_OPTIONS_VERSION 1
- #define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION}
+/** Current version for the `git_filter_options` structure */
+#define GIT_FILTER_OPTIONS_VERSION 1
+
+/** Static constructor for `git_filter_options` */
+#define GIT_FILTER_OPTIONS_INIT {GIT_FILTER_OPTIONS_VERSION}
 
 /**
  * A filter that can transform file data
@@ -196,6 +205,7 @@ GIT_EXTERN(int) git_filter_list_apply_to_buffer(
  * @param repo the repository in which to perform the filtering
  * @param path the path of the file to filter, a relative path will be
  * taken as relative to the workdir
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_apply_to_file(
 	git_buf *out,
@@ -209,6 +219,7 @@ GIT_EXTERN(int) git_filter_list_apply_to_file(
  * @param out buffer into which to store the filtered file
  * @param filters the list of filters to apply
  * @param blob the blob to filter
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_apply_to_blob(
 	git_buf *out,
@@ -222,6 +233,7 @@ GIT_EXTERN(int) git_filter_list_apply_to_blob(
  * @param buffer the buffer to filter
  * @param len the size of the buffer
  * @param target the stream into which the data will be written
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_stream_buffer(
 	git_filter_list *filters,
@@ -237,6 +249,7 @@ GIT_EXTERN(int) git_filter_list_stream_buffer(
  * @param path the path of the file to filter, a relative path will be
  * taken as relative to the workdir
  * @param target the stream into which the data will be written
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_stream_file(
 	git_filter_list *filters,
@@ -250,6 +263,7 @@ GIT_EXTERN(int) git_filter_list_stream_file(
  * @param filters the list of filters to apply
  * @param blob the blob to filter
  * @param target the stream into which the data will be written
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_filter_list_stream_blob(
 	git_filter_list *filters,
@@ -263,9 +277,7 @@ GIT_EXTERN(int) git_filter_list_stream_blob(
  */
 GIT_EXTERN(void) git_filter_list_free(git_filter_list *filters);
 
-
-GIT_END_DECL
-
 /** @} */
+GIT_END_DECL
 
 #endif

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

@@ -9,6 +9,12 @@
 
 #include "common.h"
 
+/**
+ * @file git2/global.h
+ * @brief libgit2 library initializer and shutdown functionality
+ * @ingroup Git
+ * @{
+ */
 GIT_BEGIN_DECL
 
 /**
@@ -32,7 +38,7 @@ GIT_EXTERN(int) git_libgit2_init(void);
  * many times as `git_libgit2_init()` was called - it will return the
  * number of remainining initializations that have not been shutdown
  * (after this one).
- * 
+ *
  * @return the number of remaining initializations of the library, or an
  * error code.
  */
@@ -40,5 +46,6 @@ GIT_EXTERN(int) git_libgit2_shutdown(void);
 
 /** @} */
 GIT_END_DECL
+
 #endif
 

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

@@ -13,7 +13,7 @@
 
 /**
  * @file git2/graph.h
- * @brief Git graph traversal routines
+ * @brief Graph traversal routines
  * @defgroup git_revwalk Git graph traversal routines
  * @ingroup Git
  * @{
@@ -33,6 +33,7 @@ GIT_BEGIN_DECL
  * @param repo the repository where the commits exist
  * @param local the commit for local
  * @param upstream the commit for upstream
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_graph_ahead_behind(size_t *ahead, size_t *behind, git_repository *repo, const git_oid *local, const git_oid *upstream);
 
@@ -60,8 +61,8 @@ GIT_EXTERN(int) git_graph_descendant_of(
  *
  * @param repo the repository where the commits exist
  * @param commit a previously loaded commit
- * @param length the number of commits in the provided `descendant_array`
  * @param descendant_array oids of the commits
+ * @param length the number of commits in the provided `descendant_array`
  * @return 1 if the given commit is an ancestor of any of the given potential
  * descendants, 0 if not, error code otherwise.
  */
@@ -73,4 +74,5 @@ GIT_EXTERN(int) git_graph_reachable_from_any(
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -10,6 +10,15 @@
 #include "common.h"
 #include "types.h"
 
+/**
+ * @file git2/ignore.h
+ * @brief Ignore particular untracked files
+ * @ingroup Git
+ * @{
+ *
+ * When examining the repository status, git can optionally ignore
+ * specified untracked files.
+ */
 GIT_BEGIN_DECL
 
 /**
@@ -29,7 +38,7 @@ GIT_BEGIN_DECL
  * This would add three rules to the ignores.
  *
  * @param repo The repository to add ignore rules to.
- * @param rules Text of rules, a la the contents of a .gitignore file.
+ * @param rules Text of rules, the contents to add on a .gitignore file.
  *              It is okay to have multiple rules in the text; if so,
  *              each rule should be terminated with a newline.
  * @return 0 on success
@@ -73,6 +82,7 @@ GIT_EXTERN(int) git_ignore_path_is_ignored(
 	git_repository *repo,
 	const char *path);
 
+/** @} */
 GIT_END_DECL
 
 #endif

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
 
 /**
@@ -86,12 +94,20 @@ typedef struct git_index_entry {
  */
 typedef enum {
 	GIT_INDEX_ENTRY_EXTENDED  = (0x4000),
-	GIT_INDEX_ENTRY_VALID     = (0x8000),
+	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)
@@ -119,7 +135,7 @@ typedef enum {
 
 	GIT_INDEX_ENTRY_EXTENDED_FLAGS =  (GIT_INDEX_ENTRY_INTENT_TO_ADD | GIT_INDEX_ENTRY_SKIP_WORKTREE),
 
-	GIT_INDEX_ENTRY_UPTODATE       =  (1 << 2),
+	GIT_INDEX_ENTRY_UPTODATE       =  (1 << 2)
 } git_index_entry_extended_flag_t;
 
 /** Capabilities of system that affect index actions. */
@@ -127,11 +143,18 @@ typedef enum {
 	GIT_INDEX_CAPABILITY_IGNORE_CASE = 1,
 	GIT_INDEX_CAPABILITY_NO_FILEMODE = 2,
 	GIT_INDEX_CAPABILITY_NO_SYMLINKS = 4,
-	GIT_INDEX_CAPABILITY_FROM_OWNER  = -1,
+	GIT_INDEX_CAPABILITY_FROM_OWNER  = -1
 } 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);
 
@@ -140,7 +163,7 @@ typedef enum {
 	GIT_INDEX_ADD_DEFAULT = 0,
 	GIT_INDEX_ADD_FORCE = (1u << 0),
 	GIT_INDEX_ADD_DISABLE_PATHSPEC_MATCH = (1u << 1),
-	GIT_INDEX_ADD_CHECK_PATHSPEC = (1u << 2),
+	GIT_INDEX_ADD_CHECK_PATHSPEC = (1u << 2)
 } git_index_add_option_t;
 
 /** Git index stage states */
@@ -163,9 +186,77 @@ typedef enum {
 	GIT_INDEX_STAGE_OURS = 2,
 
 	/** The "theirs" side of a conflict. */
-	GIT_INDEX_STAGE_THEIRS = 3,
+	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.
@@ -296,6 +389,7 @@ GIT_EXTERN(int) git_index_write(git_index *index);
  */
 GIT_EXTERN(const char *) git_index_path(const git_index *index);
 
+#ifndef GIT_DEPRECATE_HARD
 /**
  * Get the checksum of the index
  *
@@ -303,10 +397,12 @@ GIT_EXTERN(const char *) git_index_path(const git_index *index);
  * last 20 bytes which are the checksum itself). In cases where the
  * index does not exist on-disk, it will be zeroed out.
  *
+ * @deprecated this function is deprecated with no replacement
  * @param index an existing index object
  * @return a pointer to the checksum of the index
  */
 GIT_EXTERN(const git_oid *) git_index_checksum(git_index *index);
+#endif
 
 /**
  * Read a tree into the index file with stats
@@ -491,6 +587,7 @@ GIT_EXTERN(int) git_index_entry_is_conflict(const git_index_entry *entry);
  *
  * @param iterator_out The newly created iterator
  * @param index The index to iterate
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_index_iterator_new(
 	git_index_iterator **iterator_out,
@@ -787,6 +884,7 @@ GIT_EXTERN(int) git_index_conflict_cleanup(git_index *index);
 /**
  * Determine if the index contains entries representing file conflicts.
  *
+ * @param index An existing index object.
  * @return 1 if at least one conflict is found, 0 otherwise.
  */
 GIT_EXTERN(int) git_index_has_conflicts(const git_index *index);
@@ -811,6 +909,7 @@ GIT_EXTERN(int) git_index_conflict_iterator_new(
  * @param ancestor_out Pointer to store the ancestor side of the conflict
  * @param our_out Pointer to store our side of the conflict
  * @param their_out Pointer to store their side of the conflict
+ * @param iterator The conflict iterator.
  * @return 0 (no error), GIT_ITEROVER (iteration is done) or an error code
  *         (negative value)
  */
@@ -830,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);
 
@@ -62,6 +73,22 @@ typedef int GIT_CALLBACK(git_indexer_progress_cb)(const git_indexer_progress *st
 typedef struct git_indexer_options {
 	unsigned int version;
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+	/** 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
+	 * packs; if a thin pack is encountered, an error will be
+	 * returned if there are bases missing.
+	 */
+	git_odb *odb;
+#endif
+
 	/** progress_cb function to call with progress information */
 	git_indexer_progress_cb progress_cb;
 
@@ -72,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 }
 
 /**
@@ -87,6 +117,20 @@ GIT_EXTERN(int) git_indexer_options_init(
 	git_indexer_options *opts,
 	unsigned int version);
 
+#ifdef GIT_EXPERIMENTAL_SHA256
+/**
+ * Create a new indexer instance
+ *
+ * @param out where to store the indexer instance
+ * @param path to the directory where the packfile should be stored
+ * @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_indexer_options *opts);
+#else
 /**
  * Create a new indexer instance
  *
@@ -98,6 +142,7 @@ GIT_EXTERN(int) git_indexer_options_init(
  * will be returned if there are bases missing)
  * @param opts Optional structure containing additional options. See
  * `git_indexer_options` above.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_indexer_new(
 		git_indexer **out,
@@ -105,6 +150,7 @@ GIT_EXTERN(int) git_indexer_new(
 		unsigned int mode,
 		git_odb *odb,
 		git_indexer_options *opts);
+#endif
 
 /**
  * Add data to the indexer
@@ -113,6 +159,7 @@ GIT_EXTERN(int) git_indexer_new(
  * @param data the data to add
  * @param size the size of the data in bytes
  * @param stats stat storage
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_indexer_append(git_indexer *idx, const void *data, size_t size, git_indexer_progress *stats);
 
@@ -122,18 +169,35 @@ GIT_EXTERN(int) git_indexer_append(git_indexer *idx, const void *data, size_t si
  * Resolve any pending deltas and write out the index file
  *
  * @param idx the indexer
+ * @param stats Stat storage.
+ * @return 0 or an error code.
  */
 GIT_EXTERN(int) git_indexer_commit(git_indexer *idx, git_indexer_progress *stats);
 
+#ifndef GIT_DEPRECATE_HARD
 /**
  * Get the packfile's hash
  *
  * A packfile's name is derived from the sorted hashing of all object
  * names. This is only correct after the index has been finalized.
  *
+ * @deprecated use git_indexer_name
  * @param idx the indexer instance
+ * @return the packfile's hash
  */
 GIT_EXTERN(const git_oid *) git_indexer_hash(const git_indexer *idx);
+#endif
+
+/**
+ * Get the unique name for the resulting packfile.
+ *
+ * The packfile's name is derived from the packfile's content.
+ * This is only correct after the index has been finalized.
+ *
+ * @param idx the indexer instance
+ * @return a NUL terminated string for the packfile name
+ */
+GIT_EXTERN(const char *) git_indexer_name(const git_indexer *idx);
 
 /**
  * Free the indexer and its resources
@@ -142,6 +206,7 @@ GIT_EXTERN(const git_oid *) git_indexer_hash(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