rugged 1.3.1 → 1.9.0

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

@@ -11,9 +11,12 @@
 
 /**
  * @file git2/buffer.h
- * @brief Buffer export structure
- *
+ * @brief A data structure to return data to callers
  * @ingroup Git
+ *
+ * The `git_buf` buffer is used to return arbitrary data - typically
+ * strings - to callers. Callers are responsible for freeing the memory
+ * in a buffer with the `git_buf_dispose` function.
  * @{
  */
 GIT_BEGIN_DECL
@@ -23,112 +26,51 @@ GIT_BEGIN_DECL
  *
  * Sometimes libgit2 wants to return an allocated data buffer to the
  * caller and have the caller take responsibility for freeing that memory.
- * This can be awkward if the caller does not have easy access to the same
- * allocation functions that libgit2 is using.  In those cases, libgit2
- * will fill in a `git_buf` and the caller can use `git_buf_dispose()` to
- * release it when they are done.
- *
- * A `git_buf` may also be used for the caller to pass in a reference to
- * a block of memory they hold.  In this case, libgit2 will not resize or
- * free the memory, but will read from it as needed.
+ * To make ownership clear in these cases, libgit2 uses  `git_buf` to
+ * return this data.  Callers should use `git_buf_dispose()` to release
+ * the memory when they are done.
  *
- * Some APIs may occasionally do something slightly unusual with a buffer,
- * such as setting `ptr` to a value that was passed in by the user.  In
- * those cases, the behavior will be clearly documented by the API.
+ * A `git_buf` contains a pointer to a NUL-terminated C string, and
+ * the length of the string (not including the NUL terminator).
  */
 typedef struct {
 	/**
-	 * The buffer contents.
-	 *
-	 * `ptr` points to the start of the allocated memory.  If it is NULL,
-	 * then the `git_buf` is considered empty and libgit2 will feel free
-	 * to overwrite it with new data.
+	 * The buffer contents.  `ptr` points to the start of the buffer
+	 * being returned.  The buffer's length (in bytes) is specified
+	 * by the `size` member of the structure, and contains a NUL
+	 * terminator at position `(size + 1)`.
 	 */
-	char   *ptr;
+	char *ptr;
 
 	/**
-	 * `asize` holds the known total amount of allocated memory if the `ptr`
-	 *  was allocated by libgit2.  It may be larger than `size`.  If `ptr`
-	 *  was not allocated by libgit2 and should not be resized and/or freed,
-	 *  then `asize` will be set to zero.
+	 * This field is reserved and unused.
 	 */
-	size_t asize;
+	size_t reserved;
 
 	/**
-	 * `size` holds the size (in bytes) of the data that is actually used.
+	 * The length (in bytes) of the buffer pointed to by `ptr`,
+	 * not including a NUL terminator.
 	 */
 	size_t size;
 } git_buf;
 
 /**
- * Static initializer for git_buf from static buffer
+ * Use to initialize a `git_buf` before passing it to a function that
+ * will populate it.
  */
-#define GIT_BUF_INIT_CONST(STR,LEN) { (char *)(STR), 0, (size_t)(LEN) }
+#define GIT_BUF_INIT { NULL, 0, 0 }
 
 /**
  * Free the memory referred to by the git_buf.
  *
  * Note that this does not free the `git_buf` itself, just the memory
- * pointed to by `buffer->ptr`.  This will not free the memory if it looks
- * like it was not allocated internally, but it will clear the buffer back
- * to the empty state.
+ * pointed to by `buffer->ptr`.
  *
  * @param buffer The buffer to deallocate
  */
 GIT_EXTERN(void) git_buf_dispose(git_buf *buffer);
 
-/**
- * Resize the buffer allocation to make more space.
- *
- * This will attempt to grow the buffer to accommodate the target size.
- *
- * If the buffer refers to memory that was not allocated by libgit2 (i.e.
- * the `asize` field is zero), then `ptr` will be replaced with a newly
- * allocated block of data.  Be careful so that memory allocated by the
- * caller is not lost.  As a special variant, if you pass `target_size` as
- * 0 and the memory is not allocated by libgit2, this will allocate a new
- * buffer of size `size` and copy the external data into it.
- *
- * Currently, this will never shrink a buffer, only expand it.
- *
- * If the allocation fails, this will return an error and the buffer will be
- * marked as invalid for future operations, invaliding the contents.
- *
- * @param buffer The buffer to be resized; may or may not be allocated yet
- * @param target_size The desired available size
- * @return 0 on success, -1 on allocation failure
- */
-GIT_EXTERN(int) git_buf_grow(git_buf *buffer, size_t target_size);
-
-/**
- * Set buffer to a copy of some raw data.
- *
- * @param buffer The buffer to set
- * @param data The data to copy into the buffer
- * @param datalen The length of the data to copy into the buffer
- * @return 0 on success, -1 on allocation failure
- */
-GIT_EXTERN(int) git_buf_set(
-	git_buf *buffer, const void *data, size_t datalen);
-
-/**
-* Check quickly if buffer looks like it contains binary data
-*
-* @param buf Buffer to check
-* @return 1 if buffer looks like non-text data
-*/
-GIT_EXTERN(int) git_buf_is_binary(const git_buf *buf);
-
-/**
-* Check quickly if buffer contains a NUL byte
-*
-* @param buf Buffer to check
-* @return 1 if buffer contains a NUL byte
-*/
-GIT_EXTERN(int) git_buf_contains_nul(const git_buf *buf);
-
-GIT_END_DECL
-
 /** @} */
+GIT_END_DECL
 
 #endif

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

@@ -12,7 +12,7 @@
 
 /**
  * @file git2/cert.h
- * @brief Git certificate objects
+ * @brief TLS and SSH certificate handling
  * @defgroup git_cert Certificate objects
  * @ingroup Git
  * @{
@@ -44,7 +44,7 @@ typedef enum git_cert_t {
 	 * information about the certificate. This is used when using
 	 * curl.
 	 */
-	GIT_CERT_STRARRAY,
+	GIT_CERT_STRARRAY
 } git_cert_t;
 
 /**
@@ -82,7 +82,7 @@ typedef enum {
 	/** SHA-256 is available */
 	GIT_CERT_SSH_SHA256 = (1 << 2),
 	/** Raw hostkey is available */
-	GIT_CERT_SSH_RAW = (1 << 3),
+	GIT_CERT_SSH_RAW = (1 << 3)
 } git_cert_ssh_t;
 
 typedef enum {
@@ -169,4 +169,5 @@ typedef struct {
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -13,9 +13,13 @@
 
 /**
  * @file git2/checkout.h
- * @brief Git checkout routines
+ * @brief Update the contents of the working directory
  * @defgroup git_checkout Git checkout routines
  * @ingroup Git
+ *
+ * Update the contents of the working directory, or a subset of the
+ * files in the working directory, to point to the data in the index
+ * or a specific commit.
  * @{
  */
 GIT_BEGIN_DECL
@@ -31,17 +35,11 @@ GIT_BEGIN_DECL
  * check out, the "baseline" tree of what was checked out previously, the
  * working directory for actual files, and the index for staged changes.
  *
- * You give checkout one of three strategies for update:
- *
- * - `GIT_CHECKOUT_NONE` is a dry-run strategy that checks for conflicts,
- *   etc., but doesn't make any actual changes.
+ * You give checkout one of two strategies for update:
  *
- * - `GIT_CHECKOUT_FORCE` is at the opposite extreme, taking any action to
- *   make the working directory match the target (including potentially
- *   discarding modified files).
- *
- * - `GIT_CHECKOUT_SAFE` is between these two options, it will only make
- *   modifications that will not lose changes.
+ * - `GIT_CHECKOUT_SAFE` is the default, and similar to git's default,
+ *   which will make modifications that will not lose changes in the
+ *   working directory.
  *
  *                         |  target == baseline   |  target != baseline  |
  *    ---------------------|-----------------------|----------------------|
@@ -55,6 +53,10 @@ GIT_BEGIN_DECL
  *      baseline present   |                       |                      |
  *    ---------------------|-----------------------|----------------------|
  *
+ * - `GIT_CHECKOUT_FORCE` will take any action to make the working
+ *   directory match the target (including potentially discarding
+ *   modified files).
+ *
  * To emulate `git checkout`, use `GIT_CHECKOUT_SAFE` with a checkout
  * notification callback (see below) that displays information about dirty
  * files.  The default behavior will cancel checkout on conflicts.
@@ -69,6 +71,9 @@ GIT_BEGIN_DECL
  *
  * There are some additional flags to modify the behavior of checkout:
  *
+ * - `GIT_CHECKOUT_DRY_RUN` is a dry-run strategy that checks for conflicts,
+ *   etc., but doesn't make any actual changes.
+ *
  * - GIT_CHECKOUT_ALLOW_CONFLICTS makes SAFE mode apply safe file updates
  *   even if there are conflicts (instead of cancelling the checkout).
  *
@@ -102,29 +107,24 @@ GIT_BEGIN_DECL
  *   files or folders that fold to the same name on case insensitive
  *   filesystems.  This can cause files to retain their existing names
  *   and write through existing symbolic links.
+ *
+ * @flags
  */
 typedef enum {
-	GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */
-
 	/**
 	 * Allow safe updates that cannot overwrite uncommitted data.
-	 * If the uncommitted changes don't conflict with the checked out files,
-	 * the checkout will still proceed, leaving the changes intact.
-	 *
-	 * Mutually exclusive with GIT_CHECKOUT_FORCE.
-	 * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE.
+	 * If the uncommitted changes don't conflict with the checked
+	 * out files, the checkout will still proceed, leaving the
+	 * changes intact.
 	 */
-	GIT_CHECKOUT_SAFE = (1u << 0),
+	GIT_CHECKOUT_SAFE = 0,
 
 	/**
-	 * Allow all updates to force working directory to look like index.
-	 *
-	 * Mutually exclusive with GIT_CHECKOUT_SAFE.
-	 * GIT_CHECKOUT_FORCE takes precedence over GIT_CHECKOUT_SAFE.
+	 * Allow all updates to force working directory to look like
+	 * the index, potentially losing data in the process.
 	 */
 	GIT_CHECKOUT_FORCE = (1u << 1),
 
-
 	/** Allow checkout to recreate missing files */
 	GIT_CHECKOUT_RECREATE_MISSING = (1u << 2),
 
@@ -178,20 +178,31 @@ typedef enum {
 	GIT_CHECKOUT_DONT_WRITE_INDEX = (1u << 23),
 
 	/**
-	 * Show what would be done by a checkout.  Stop after sending
-	 * notifications; don't update the working directory or index.
+	 * Perform a "dry run", reporting what _would_ be done but
+	 * without actually making changes in the working directory
+	 * or the index.
 	 */
 	GIT_CHECKOUT_DRY_RUN = (1u << 24),
-	
+
+	/** Include common ancestor data in zdiff3 format for conflicts */
+	GIT_CHECKOUT_CONFLICT_STYLE_ZDIFF3 = (1u << 25),
+
 	/**
+	 * Do not do a checkout and do not fire callbacks; this is primarily
+	 * useful only for internal functions that will perform the
+	 * checkout themselves but need to pass checkout options into
+	 * another function, for example, `git_clone`.
+	*/
+	GIT_CHECKOUT_NONE = (1u << 30),
+
+	/*
 	 * THE FOLLOWING OPTIONS ARE NOT YET IMPLEMENTED
 	 */
 
 	/** Recursively checkout submodules with same options (NOT IMPLEMENTED) */
 	GIT_CHECKOUT_UPDATE_SUBMODULES = (1u << 16),
 	/** Recursively checkout submodules if HEAD moved in super repo (NOT IMPLEMENTED) */
-	GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED = (1u << 17),
-
+	GIT_CHECKOUT_UPDATE_SUBMODULES_IF_CHANGED = (1u << 17)
 } git_checkout_strategy_t;
 
 /**
@@ -207,6 +218,8 @@ typedef enum {
  * Notification callbacks are made prior to modifying any files on disk,
  * so canceling on any notification will still happen prior to any files
  * being modified.
+ *
+ * @flags
  */
 typedef enum {
 	GIT_CHECKOUT_NOTIFY_NONE      = 0,
@@ -248,7 +261,17 @@ typedef struct {
 	size_t chmod_calls;
 } git_checkout_perfdata;
 
-/** Checkout notification callback function */
+/**
+ * Checkout notification callback function.
+ *
+ * @param why the notification reason
+ * @param path the path to the file being checked out
+ * @param baseline the baseline's diff file information
+ * @param target the checkout target diff file information
+ * @param workdir the working directory diff file information
+ * @param payload the user-supplied callback payload
+ * @return 0 on success, or an error code
+ */
 typedef int GIT_CALLBACK(git_checkout_notify_cb)(
 	git_checkout_notify_t why,
 	const char *path,
@@ -257,14 +280,26 @@ typedef int GIT_CALLBACK(git_checkout_notify_cb)(
 	const git_diff_file *workdir,
 	void *payload);
 
-/** Checkout progress notification function */
+/**
+ * Checkout progress notification function.
+ *
+ * @param path the path to the file being checked out
+ * @param completed_steps number of checkout steps completed
+ * @param total_steps number of total steps in the checkout process
+ * @param payload the user-supplied callback payload
+ */
 typedef void GIT_CALLBACK(git_checkout_progress_cb)(
 	const char *path,
 	size_t completed_steps,
 	size_t total_steps,
 	void *payload);
 
-/** Checkout perfdata notification function */
+/**
+ * Checkout performance data reporting function.
+ *
+ * @param perfdata the performance data for the checkout
+ * @param payload the user-supplied callback payload
+ */
 typedef void GIT_CALLBACK(git_checkout_perfdata_cb)(
 	const git_checkout_perfdata *perfdata,
 	void *payload);
@@ -275,10 +310,18 @@ typedef void GIT_CALLBACK(git_checkout_perfdata_cb)(
  * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can
  * use `git_checkout_options_init`.
  *
+ * @options[version] GIT_CHECKOUT_OPTIONS_VERSION
+ * @options[init_macro] GIT_CHECKOUT_OPTIONS_INIT
+ * @options[init_function] git_checkout_options_init
  */
 typedef struct git_checkout_options {
 	unsigned int version; /**< The version */
 
+	/**
+	 * Checkout strategy. Default is a safe checkout.
+	 *
+	 * @type[flags] git_checkout_strategy_t
+	 */
 	unsigned int checkout_strategy; /**< default will be a safe checkout */
 
 	int disable_filters;    /**< don't apply filters like CRLF conversion */
@@ -286,7 +329,13 @@ typedef struct git_checkout_options {
 	unsigned int file_mode; /**< default is 0644 or 0755 as dictated by blob */
 	int file_open_flags;    /**< default is O_CREAT | O_TRUNC | O_WRONLY */
 
-	unsigned int notify_flags; /**< see `git_checkout_notify_t` above */
+	/**
+	 * Checkout notification flags specify what operations the notify
+	 * callback is invoked for.
+	 *
+	 * @type[flags] git_checkout_notify_t
+	 */
+	unsigned int notify_flags;
 
 	/**
 	 * Optional callback to get notifications on specific file states.
@@ -341,8 +390,12 @@ typedef struct git_checkout_options {
 	void *perfdata_payload;
 } git_checkout_options;
 
+
+/** Current version for the `git_checkout_options` structure */
 #define GIT_CHECKOUT_OPTIONS_VERSION 1
-#define GIT_CHECKOUT_OPTIONS_INIT {GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE}
+
+/** Static constructor for `git_checkout_options` */
+#define GIT_CHECKOUT_OPTIONS_INIT { GIT_CHECKOUT_OPTIONS_VERSION }
 
 /**
  * Initialize git_checkout_options structure
@@ -411,4 +464,5 @@ GIT_EXTERN(int) git_checkout_tree(
 
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -13,9 +13,12 @@
 
 /**
  * @file git2/cherrypick.h
- * @brief Git cherry-pick routines
+ * @brief Cherry-pick the contents of an individual commit
  * @defgroup git_cherrypick Git cherry-pick routines
  * @ingroup Git
+ *
+ * "Cherry-pick" will attempts to re-apply the changes in an
+ * individual commit to the current index and working directory.
  * @{
  */
 GIT_BEGIN_DECL
@@ -33,8 +36,13 @@ typedef struct {
 	git_checkout_options checkout_opts; /**< Options for the checkout */
 } git_cherrypick_options;
 
+/** Current version for the `git_cherrypick_options` structure */
 #define GIT_CHERRYPICK_OPTIONS_VERSION 1
-#define GIT_CHERRYPICK_OPTIONS_INIT {GIT_CHERRYPICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT}
+
+/** Static constructor for `git_cherrypick_options` */
+#define GIT_CHERRYPICK_OPTIONS_INIT { \
+	GIT_CHERRYPICK_OPTIONS_VERSION, 0, \
+	GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT }
 
 /**
  * Initialize git_cherrypick_options structure
@@ -89,4 +97,3 @@ GIT_EXTERN(int) git_cherrypick(
 GIT_END_DECL
 
 #endif
-

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

@@ -17,9 +17,13 @@
 
 /**
  * @file git2/clone.h
- * @brief Git cloning routines
+ * @brief Clone a remote repository to the local disk
  * @defgroup git_clone Git cloning routines
  * @ingroup Git
+ *
+ * Clone will take a remote repository - located on a remote server
+ * accessible by HTTPS or SSH, or a repository located elsewhere on
+ * the local disk - and place a copy in the given local path.
  * @{
  */
 GIT_BEGIN_DECL
@@ -49,7 +53,7 @@ typedef enum {
 	 * Bypass the git-aware transport, but do not try to use
 	 * hardlinks.
 	 */
-	GIT_CLONE_LOCAL_NO_LINKS,
+	GIT_CLONE_LOCAL_NO_LINKS
 } git_clone_local_t;
 
 /**
@@ -59,7 +63,7 @@ typedef enum {
  * Callers of git_clone may provide a function matching this signature to override
  * the remote creation and customization process during a clone operation.
  *
- * @param out the resulting remote
+ * @param[out] out the resulting remote
  * @param repo the repository in which to create the remote
  * @param name the remote's name
  * @param url the remote's url
@@ -74,14 +78,14 @@ typedef int GIT_CALLBACK(git_remote_create_cb)(
 	void *payload);
 
 /**
- * The signature of a function matchin git_repository_init, with an
- * aditional void * as callback payload.
+ * The signature of a function matching git_repository_init, with an
+ * additional void * as callback payload.
  *
  * Callers of git_clone my provide a function matching this signature
  * to override the repository creation and customization process
  * during a clone operation.
  *
- * @param out the resulting repository
+ * @param[out] out the resulting repository
  * @param path path in which to create the repository
  * @param bare whether the repository is bare. This is the value from the clone options
  * @param payload payload specified by the options
@@ -99,14 +103,17 @@ typedef int GIT_CALLBACK(git_repository_create_cb)(
  * Initialize with `GIT_CLONE_OPTIONS_INIT`. Alternatively, you can
  * use `git_clone_options_init`.
  *
+ * @options[version] GIT_CLONE_OPTIONS_VERSION
+ * @options[init_macro] GIT_CLONE_OPTIONS_INIT
+ * @options[init_function] git_clone_options_init
  */
 typedef struct git_clone_options {
 	unsigned int version;
 
 	/**
 	 * These options are passed to the checkout step. To disable
-	 * checkout, set the `checkout_strategy` to
-	 * `GIT_CHECKOUT_NONE`.
+	 * checkout, set the `checkout_strategy` to `GIT_CHECKOUT_NONE`
+	 * or `GIT_CHECKOUT_DRY_RUN`.
 	 */
 	git_checkout_options checkout_opts;
 
@@ -163,10 +170,14 @@ typedef struct git_clone_options {
 	void *remote_cb_payload;
 } git_clone_options;
 
+/** Current version for the `git_clone_options` structure */
 #define GIT_CLONE_OPTIONS_VERSION 1
-#define GIT_CLONE_OPTIONS_INIT { GIT_CLONE_OPTIONS_VERSION, \
-	{ GIT_CHECKOUT_OPTIONS_VERSION, GIT_CHECKOUT_SAFE }, \
-	GIT_FETCH_OPTIONS_INIT }
+
+/** Static constructor for `git_clone_options` */
+#define GIT_CLONE_OPTIONS_INIT \
+	{ GIT_CLONE_OPTIONS_VERSION, \
+	  GIT_CHECKOUT_OPTIONS_INIT, \
+	  GIT_FETCH_OPTIONS_INIT }
 
 /**
  * Initialize git_clone_options structure
@@ -189,7 +200,11 @@ GIT_EXTERN(int) git_clone_options_init(
  * git's defaults. You can use the options in the callback to
  * customize how these are created.
  *
- * @param out pointer that will receive the resulting repository object
+ * Note that the libgit2 library _must_ be initialized using
+ * `git_libgit2_init` before any APIs can be called, including
+ * this one.
+ *
+ * @param[out] out pointer that will receive the resulting repository object
  * @param url the remote repository to clone
  * @param local_path local directory to clone to
  * @param options configuration options for the clone.  If NULL, the
@@ -206,4 +221,5 @@ GIT_EXTERN(int) git_clone(
 
 /** @} */
 GIT_END_DECL
+
 #endif