rugged 1.7.2 → 1.9.0

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
@@ -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
@@ -81,7 +85,7 @@ typedef int GIT_CALLBACK(git_remote_create_cb)(
  * 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

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

@@ -14,9 +14,13 @@
 
 /**
  * @file git2/commit.h
- * @brief Git commit parsing, formatting routines
+ * @brief A representation of a set of changes in the repository
  * @defgroup git_commit Git commit parsing, formatting routines
  * @ingroup Git
+ *
+ * A commit represents a set of changes made to the files within a
+ * repository, and metadata about who made the changes, and when the
+ * changes were made.
  * @{
  */
 GIT_BEGIN_DECL
@@ -380,7 +384,38 @@ GIT_EXTERN(int) git_commit_create(
  *
  * All other parameters remain the same as `git_commit_create()`.
  *
- * @see git_commit_create
+ * @param id Pointer in which to store the OID of the newly created commit
+ *
+ * @param repo Repository where to store the commit
+ *
+ * @param update_ref If not NULL, name of the reference that
+ *	will be updated to point to this commit. If the reference
+ *	is not direct, it will be resolved to a direct reference.
+ *	Use "HEAD" to update the HEAD of the current branch and
+ *	make it point to this commit. If the reference doesn't
+ *	exist yet, it will be created. If it does exist, the first
+ *	parent must be the tip of this branch.
+ *
+ * @param author Signature with author and author time of commit
+ *
+ * @param committer Signature with committer and * commit time of commit
+ *
+ * @param message_encoding The encoding for the message in the
+ *  commit, represented with a standard encoding name.
+ *  E.g. "UTF-8". If NULL, no encoding header is written and
+ *  UTF-8 is assumed.
+ *
+ * @param message Full message for this commit
+ *
+ * @param tree An instance of a `git_tree` object that will
+ *  be used as the tree for the commit. This tree object must
+ *  also be owned by the given `repo`.
+ *
+ * @param parent_count Number of parents for this commit
+ *
+ * @return 0 or an error code
+ *	The created commit will be written to the Object Database and
+ *	the given reference will be updated to point to it
  */
 GIT_EXTERN(int) git_commit_create_v(
 	git_oid *id,
@@ -394,6 +429,52 @@ GIT_EXTERN(int) git_commit_create_v(
 	size_t parent_count,
 	...);
 
+typedef struct {
+	unsigned int version;
+
+	/**
+	 * Flags for creating the commit.
+	 *
+	 * If `allow_empty_commit` is specified, a commit with no changes
+	 * from the prior commit (and "empty" commit) is allowed. Otherwise,
+	 * commit creation will be stopped.
+	 */
+	unsigned int allow_empty_commit : 1;
+
+	/** The commit author, or NULL for the default. */
+	const git_signature *author;
+
+	/** The committer, or NULL for the default. */
+	const git_signature *committer;
+
+	/** Encoding for the commit message; leave NULL for default. */
+	const char *message_encoding;
+} git_commit_create_options;
+
+/** Current version for the `git_commit_create_options` structure */
+#define GIT_COMMIT_CREATE_OPTIONS_VERSION 1
+
+/** Static constructor for `git_commit_create_options` */
+#define GIT_COMMIT_CREATE_OPTIONS_INIT { GIT_COMMIT_CREATE_OPTIONS_VERSION }
+
+/**
+ * Commits the staged changes in the repository; this is a near analog to
+ * `git commit -m message`.
+ *
+ * By default, empty commits are not allowed.
+ *
+ * @param id pointer to store the new commit's object id
+ * @param repo repository to commit changes in
+ * @param message the commit message
+ * @param opts options for creating the commit
+ * @return 0 on success, GIT_EUNCHANGED if there were no changes to commit, or an error code
+ */
+GIT_EXTERN(int) git_commit_create_from_stage(
+	git_oid *id,
+	git_repository *repo,
+	const char *message,
+	const git_commit_create_options *opts);
+
 /**
  * Amend an existing commit by replacing only non-NULL values.
  *
@@ -413,7 +494,36 @@ GIT_EXTERN(int) git_commit_create_v(
  *
  * All parameters have the same meanings as in `git_commit_create()`.
  *
- * @see git_commit_create
+ * @param id Pointer in which to store the OID of the newly created commit
+ *
+ * @param commit_to_amend The commit to amend
+ *
+ * @param update_ref If not NULL, name of the reference that
+ *	will be updated to point to this commit. If the reference
+ *	is not direct, it will be resolved to a direct reference.
+ *	Use "HEAD" to update the HEAD of the current branch and
+ *	make it point to this commit. If the reference doesn't
+ *	exist yet, it will be created. If it does exist, the first
+ *	parent must be the tip of this branch.
+ *
+ * @param author Signature with author and author time of commit
+ *
+ * @param committer Signature with committer and * commit time of commit
+ *
+ * @param message_encoding The encoding for the message in the
+ *  commit, represented with a standard encoding name.
+ *  E.g. "UTF-8". If NULL, no encoding header is written and
+ *  UTF-8 is assumed.
+ *
+ * @param message Full message for this commit
+ *
+ * @param tree An instance of a `git_tree` object that will
+ *  be used as the tree for the commit. This tree object must
+ *  also be owned by the given `repo`.
+ *
+ * @return 0 or an error code
+ *	The created commit will be written to the Object Database and
+ *	the given reference will be updated to point to it
  */
 GIT_EXTERN(int) git_commit_amend(
 	git_oid *id,
@@ -541,6 +651,25 @@ typedef int (*git_commit_create_cb)(
 	const git_commit *parents[],
 	void *payload);
 
+/** An array of commits returned from the library */
+typedef struct git_commitarray {
+	git_commit *const *commits;
+	size_t count;
+} git_commitarray;
+
+/**
+ * Free the commits contained in a commit array.  This method should
+ * be called on `git_commitarray` objects that were provided by the
+ * library.  Not doing so will result in a memory leak.
+ *
+ * This does not free the `git_commitarray` itself, since the library
+ * will never allocate that object directly itself.
+ *
+ * @param array The git_commitarray that contains commits to free
+ */
+GIT_EXTERN(void) git_commitarray_dispose(git_commitarray *array);
+
 /** @} */
 GIT_END_DECL
+
 #endif

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

@@ -11,7 +11,9 @@
 #include <stdlib.h>
 
 #ifdef __cplusplus
+ /** Start declarations in C mode for C++ compatibility */
 # define GIT_BEGIN_DECL extern "C" {
+ /** End declarations in C mode */
 # define GIT_END_DECL	}
 #else
  /** Start declarations in C mode */
@@ -71,19 +73,19 @@ typedef size_t size_t;
 # define GIT_FORMAT_PRINTF(a,b) /* empty */
 #endif
 
-#if (defined(_WIN32)) && !defined(__CYGWIN__)
-#define GIT_WIN32 1
-#endif
-
 #ifdef __amigaos4__
 #include <netinet/in.h>
 #endif
 
 /**
  * @file git2/common.h
- * @brief Git common platform definitions
+ * @brief Base platform functionality
  * @defgroup git_common Git common platform definitions
  * @ingroup Git
+ *
+ * Common platform functionality including introspecting libgit2
+ * itself - information like how it was built, and the current
+ * running version.
  * @{
  */
 
@@ -94,10 +96,10 @@ GIT_BEGIN_DECL
  * environment variable). A semi-colon ";" is used on Windows and
  * AmigaOS, and a colon ":" for all other systems.
  */
-#if defined(GIT_WIN32) || defined(AMIGA)
-#define GIT_PATH_LIST_SEPARATOR ';'
+#if (defined(_WIN32) && !defined(__CYGWIN__)) || defined(AMIGA)
+# define GIT_PATH_LIST_SEPARATOR ';'
 #else
-#define GIT_PATH_LIST_SEPARATOR ':'
+# define GIT_PATH_LIST_SEPARATOR ':'
 #endif
 
 /**
@@ -128,56 +130,80 @@ GIT_EXTERN(int) git_libgit2_version(int *major, int *minor, int *rev);
 GIT_EXTERN(const char *) git_libgit2_prerelease(void);
 
 /**
- * Combinations of these values describe the features with which libgit2
- * was compiled
+ * Configurable features of libgit2; either optional settings (like
+ * threading), or features that can be enabled by one of a number of
+ * different backend "providers" (like HTTPS, which can be provided by
+ * OpenSSL, mbedTLS, or system libraries).
  */
 typedef enum {
-  /**
-   * If set, libgit2 was built thread-aware and can be safely used from multiple
-   * threads.
-   */
-	GIT_FEATURE_THREADS	= (1 << 0),
-  /**
-   * If set, libgit2 was built with and linked against a TLS implementation.
-   * Custom TLS streams may still be added by the user to support HTTPS
-   * regardless of this.
-   */
-	GIT_FEATURE_HTTPS	= (1 << 1),
-  /**
-   * If set, libgit2 was built with and linked against libssh2. A custom
-   * transport may still be added by the user to support libssh2 regardless of
-   * this.
-   */
-	GIT_FEATURE_SSH		= (1 << 2),
-  /**
-   * If set, libgit2 was built with support for sub-second resolution in file
-   * modification times.
-   */
-	GIT_FEATURE_NSEC	= (1 << 3)
+	/**
+	 * libgit2 is thread-aware and can be used from multiple threads
+	 * (as described in the documentation).
+	 */
+	GIT_FEATURE_THREADS        = (1 << 0),
+
+	/** HTTPS remotes */
+	GIT_FEATURE_HTTPS          = (1 << 1),
+
+	/** SSH remotes */
+	GIT_FEATURE_SSH	           = (1 << 2),
+
+	/** Sub-second resolution in index timestamps */
+	GIT_FEATURE_NSEC           = (1 << 3),
+
+	/** HTTP parsing; always available */
+	GIT_FEATURE_HTTP_PARSER    = (1 << 4),
+
+	/** Regular expression support; always available */
+	GIT_FEATURE_REGEX          = (1 << 5),
+
+	/** Internationalization support for filename translation */
+	GIT_FEATURE_I18N           = (1 << 6),
+
+	/** NTLM support over HTTPS */
+	GIT_FEATURE_AUTH_NTLM      = (1 << 7),
+
+	/** Kerberos (SPNEGO) authentication support over HTTPS */
+	GIT_FEATURE_AUTH_NEGOTIATE = (1 << 8),
+
+	/** zlib support; always available */
+	GIT_FEATURE_COMPRESSION    = (1 << 9),
+
+	/** SHA1 object support; always available */
+	GIT_FEATURE_SHA1           = (1 << 10),
+
+	/** SHA256 object support */
+	GIT_FEATURE_SHA256         = (1 << 11)
 } git_feature_t;
 
 /**
  * Query compile time options for libgit2.
  *
  * @return A combination of GIT_FEATURE_* values.
+ */
+GIT_EXTERN(int) git_libgit2_features(void);
+
+/**
+ * Query the backend details for the compile-time feature in libgit2.
  *
- * - GIT_FEATURE_THREADS
- *   Libgit2 was compiled with thread support. Note that thread support is
- *   still to be seen as a 'work in progress' - basic object lookups are
- *   believed to be threadsafe, but other operations may not be.
+ * This will return the "backend" for the feature, which is useful for
+ * things like HTTPS or SSH support, that can have multiple backends
+ * that could be compiled in.
  *
- * - GIT_FEATURE_HTTPS
- *   Libgit2 supports the https:// protocol. This requires the openssl
- *   library to be found when compiling libgit2.
+ * For example, when libgit2 is compiled with dynamic OpenSSL support,
+ * the feature backend will be `openssl-dynamic`. The feature backend
+ * names reflect the compilation options specified to the build system
+ * (though in all lower case). The backend _may_ be "builtin" for
+ * features that are provided by libgit2 itself.
  *
- * - GIT_FEATURE_SSH
- *   Libgit2 supports the SSH protocol for network operations. This requires
- *   the libssh2 library to be found when compiling libgit2
+ * If the feature is not supported by the library, this API returns
+ * `NULL`.
  *
- * - GIT_FEATURE_NSEC
- *   Libgit2 supports the sub-second resolution in file modification times.
+ * @param feature the feature to query details for
+ * @return the provider details, or NULL if the feature is not supported
  */
-GIT_EXTERN(int) git_libgit2_features(void);
+GIT_EXTERN(const char *) git_libgit2_feature_backend(
+	git_feature_t feature);
 
 /**
  * Global library options
@@ -228,7 +254,10 @@ typedef enum {
 	GIT_OPT_SET_SERVER_CONNECT_TIMEOUT,
 	GIT_OPT_GET_SERVER_CONNECT_TIMEOUT,
 	GIT_OPT_SET_SERVER_TIMEOUT,
-	GIT_OPT_GET_SERVER_TIMEOUT
+	GIT_OPT_GET_SERVER_TIMEOUT,
+	GIT_OPT_SET_USER_AGENT_PRODUCT,
+	GIT_OPT_GET_USER_AGENT_PRODUCT,
+	GIT_OPT_ADD_SSL_X509_CERT
 } git_libgit2_opt_t;
 
 /**
@@ -333,15 +362,52 @@ typedef enum {
  *		> - `path` is the location of a directory holding several
  *		>   certificates, one per file.
  *		>
+ *		> Calling `GIT_OPT_ADD_SSL_X509_CERT` may override the
+ *		> data in `path`.
+ *		>
  * 		> Either parameter may be `NULL`, but not both.
  *
+ *  * opts(GIT_OPT_ADD_SSL_X509_CERT, const X509 *cert)
+ *
+ *		> Add a raw X509 certificate into the SSL certs store.
+ *		> This certificate is only used by libgit2 invocations
+ *		> during the application lifetime and is not persisted
+ *		> to disk. This certificate cannot be removed from the
+ *		> application once is has been added.
+ *		>
+ *		> - `cert` is the raw X509 cert will be added to cert store.
+ *
  *	* opts(GIT_OPT_SET_USER_AGENT, const char *user_agent)
  *
- *		> Set the value of the User-Agent header.  This value will be
- *		> appended to "git/1.0", for compatibility with other git clients.
+ *		> Set the value of the comment section of the User-Agent header.
+ *		> This can be information about your product and its version.
+ *		> By default this is "libgit2" followed by the libgit2 version.
+ *		>
+ *		> This value will be appended to User-Agent _product_, which
+ *		> is typically set to "git/2.0".
+ *		>
+ *		> Set to the empty string ("") to not send any information in the
+ *		> comment section, or set to NULL to restore the default.
+ *
+ *	* opts(GIT_OPT_GET_USER_AGENT, git_buf *out)
+ *
+ *		> Get the value of the User-Agent header.
+ *		> The User-Agent is written to the `out` buffer.
+ *
+ *	* opts(GIT_OPT_SET_USER_AGENT_PRODUCT, const char *user_agent_product)
+ *
+ *		> Set the value of the product portion of the User-Agent header.
+ *		> This defaults to "git/2.0", for compatibility with other git
+ *		> clients. It is recommended to keep this as git/<version> for
+ *		> compatibility with servers that do user-agent detection.
  *		>
- *		> - `user_agent` is the value that will be delivered as the
- *		>   User-Agent header on HTTP requests.
+ *		> Set to the empty string ("") to not send any user-agent string,
+ *		> or set to NULL to restore the default.
+ *
+ *	* opts(GIT_OPT_GET_USER_AGENT_PRODUCT, git_buf *out)
+ *
+ *		> Get the value of the User-Agent product header.
+ *		> The User-Agent product is written to the `out` buffer.
  *
  *	* opts(GIT_OPT_SET_WINDOWS_SHAREMODE, unsigned long value)
  *
@@ -377,11 +443,6 @@ typedef enum {
  *		>
  *		> - `ciphers` is the list of ciphers that are eanbled.
  *
- *	* opts(GIT_OPT_GET_USER_AGENT, git_buf *out)
- *
- *		> Get the value of the User-Agent header.
- *		> The User-Agent is written to the `out` buffer.
- *
  *	* opts(GIT_OPT_ENABLE_OFS_DELTA, int enabled)
  *
  *		> Enable or disable the use of "offset deltas" when creating packfiles,
@@ -490,10 +551,9 @@ typedef enum {
  *
  *   opts(GIT_OPT_SET_SERVER_CONNECT_TIMEOUT, int timeout)
  *      > Sets the timeout (in milliseconds) to attempt connections to
- *      > a remote server. This is supported only for HTTP(S) connections
- *      > and is not supported by SSH. Set to 0 to use the system default.
- *      > Note that this may not be able to be configured longer than the
- *      > system default, typically 75 seconds.
+ *      > a remote server. Set to 0 to use the system default. Note that
+ *      > this may not be able to be configured longer than the system
+ *      > default, typically 75 seconds.
  *
  *   opts(GIT_OPT_GET_SERVER_TIMEOUT, int *timeout)
  *      > Gets the timeout (in milliseconds) for reading from and writing
@@ -501,12 +561,9 @@ typedef enum {
  *
  *   opts(GIT_OPT_SET_SERVER_TIMEOUT, int timeout)
  *      > Sets the timeout (in milliseconds) for reading from and writing
- *      > to a remote server. This is supported only for HTTP(S)
- *      > connections and is not supported by SSH. Set to 0 to use the
- *      > system default.
+ *      > to a remote server. Set to 0 to use the system default.
  *
  * @param option Option key
- * @param ... value to set the option
  * @return 0 on success, <0 on failure
  */
 GIT_EXTERN(int) git_libgit2_opts(int option, ...);