rugged 0.28.5 → 0.99.0

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

@@ -75,9 +75,9 @@ GIT_EXTERN(int) git_branch_create_from_annotated(
 /**
  * Delete an existing branch reference.
  *
- * If the branch is successfully deleted, the passed reference
- * object will be invalidated. The reference must be freed manually
- * by the user.
+ * Note that if the deletion succeeds, the reference object will not
+ * be valid anymore, and should be freed immediately by the user using
+ * `git_reference_free()`.
  *
  * @param branch A valid reference representing a branch
  * @return 0 on success, or an error code.
@@ -126,6 +126,12 @@ GIT_EXTERN(void) git_branch_iterator_free(git_branch_iterator *iter);
  * The new branch name will be checked for validity.
  * See `git_tag_create()` for rules about valid names.
  *
+ * Note that if the move succeeds, the old reference object will not
+ + be valid anymore, and should be freed immediately by the user using
+ + `git_reference_free()`.
+ *
+ * @param out New reference object for the updated name.
+ *
  * @param branch Current underlying reference of the branch.
  *
  * @param new_branch_name Target name of the branch once the move
@@ -145,17 +151,14 @@ GIT_EXTERN(int) git_branch_move(
  * Lookup a branch by its name in a repository.
  *
  * The generated reference must be freed by the user.
- *
  * The branch name will be checked for validity.
- * See `git_tag_create()` for rules about valid names.
  *
- * @param out pointer to the looked-up branch reference
+ * @see git_tag_create for rules about valid names.
  *
+ * @param out pointer to the looked-up branch reference
  * @param repo the repository to look up the branch
- *
  * @param branch_name Name of the branch to be looked-up;
  * this name is validated for consistency.
- *
  * @param branch_type Type of the considered branch. This should
  * be valued with either GIT_BRANCH_LOCAL or GIT_BRANCH_REMOTE.
  *
@@ -169,65 +172,74 @@ GIT_EXTERN(int) git_branch_lookup(
 	git_branch_t branch_type);
 
 /**
- * Return the name of the given local or remote branch.
+ * Get the branch name
+ *
+ * Given a reference object, this will check that it really is a branch (ie.
+ * it lives under "refs/heads/" or "refs/remotes/"), and return the branch part
+ * of it.
  *
- * The name of the branch matches the definition of the name
- * for git_branch_lookup. That is, if the returned name is given
- * to git_branch_lookup() then the reference is returned that
- * was given to this function.
+ * @param out Pointer to the abbreviated reference name.
+ *        Owned by ref, do not free.
  *
- * @param out where the pointer of branch name is stored;
- * this is valid as long as the ref is not freed.
- * @param ref the reference ideally pointing to a branch
+ * @param ref A reference object, ideally pointing to a branch
  *
- * @return 0 on success; otherwise an error code (e.g., if the
- *  ref is no local or remote branch).
+ * @return 0 on success; GIT_EINVALID if the reference isn't either a local or
+ *         remote branch, otherwise an error code.
  */
 GIT_EXTERN(int) git_branch_name(
 		const char **out,
 		const git_reference *ref);
 
 /**
- * Return the reference supporting the remote tracking branch,
- * given a local branch reference.
+ * Get the upstream of a branch
  *
- * @param out Pointer where to store the retrieved
- * reference.
+ * Given a reference, this will return a new reference object corresponding
+ * to its remote tracking branch. The reference must be a local branch.
  *
+ * @see git_branch_upstream_name for details on the resolution.
+ *
+ * @param out Pointer where to store the retrieved reference.
  * @param branch Current underlying reference of the branch.
  *
  * @return 0 on success; GIT_ENOTFOUND when no remote tracking
- * reference exists, otherwise an error code.
+ *         reference exists, otherwise an error code.
  */
 GIT_EXTERN(int) git_branch_upstream(
 	git_reference **out,
 	const git_reference *branch);
 
 /**
- * Set the upstream configuration for a given local branch
+ * Set a branch's upstream branch
  *
- * @param branch the branch to configure
+ * This will update the configuration to set the branch named `branch_name` as the upstream of `branch`.
+ * Pass a NULL name to unset the upstream information.
  *
- * @param upstream_name remote-tracking or local branch to set as
- * upstream. Pass NULL to unset.
+ * @note the actual tracking reference must have been already created for the
+ * operation to succeed.
  *
- * @return 0 or an error code
+ * @param branch the branch to configure
+ * @param branch_name remote-tracking or local branch to set as upstream.
+ *
+ * @return 0 on success; GIT_ENOTFOUND if there's no branch named `branch_name`
+ *         or an error code
  */
-GIT_EXTERN(int) git_branch_set_upstream(git_reference *branch, const char *upstream_name);
+GIT_EXTERN(int) git_branch_set_upstream(
+	git_reference *branch,
+	const char *branch_name);
 
 /**
- * Return the name of the reference supporting the remote tracking branch,
- * given the name of a local branch reference.
- *
- * @param out Pointer to the user-allocated git_buf which will be
- * filled with the name of the reference.
+ * Get the upstream name of a branch
  *
- * @param repo the repository where the branches live
+ * Given a local branch, this will return its remote-tracking branch information,
+ * as a full reference name, ie. "feature/nice" would become
+ * "refs/remote/origin/feature/nice", depending on that branch's configuration.
  *
+ * @param out the buffer into which the name will be written.
+ * @param repo the repository where the branches live.
  * @param refname reference name of the local branch.
  *
- * @return 0, GIT_ENOTFOUND when no remote tracking reference exists,
- *     otherwise an error code.
+ * @return 0 on success, GIT_ENOTFOUND when no remote tracking reference exists,
+ *         or an error code.
  */
 GIT_EXTERN(int) git_branch_upstream_name(
 	git_buf *out,
@@ -235,50 +247,55 @@ GIT_EXTERN(int) git_branch_upstream_name(
 	const char *refname);
 
 /**
- * Determine if the current local branch is pointed at by HEAD.
+ * Determine if HEAD points to the given branch
  *
- * @param branch Current underlying reference of the branch.
+ * @param branch A reference to a local branch.
  *
- * @return 1 if HEAD points at the branch, 0 if it isn't,
- * error code otherwise.
+ * @return 1 if HEAD points at the branch, 0 if it isn't, or a negative value
+ * 		   as an error code.
  */
 GIT_EXTERN(int) git_branch_is_head(
 	const git_reference *branch);
 
 /**
- * Determine if the current branch is checked out in any linked
- * repository.
+ * Determine if any HEAD points to the current branch
  *
- * @param branch Reference to the branch.
+ * This will iterate over all known linked repositories (usually in the form of
+ * worktrees) and report whether any HEAD is pointing at the current branch.
  *
- * @return 1 if branch is checked out, 0 if it isn't,
- * error code otherwise.
+ * @param branch A reference to a local branch.
+ *
+ * @return 1 if branch is checked out, 0 if it isn't, an error code otherwise.
  */
 GIT_EXTERN(int) git_branch_is_checked_out(
 	const git_reference *branch);
 
 /**
- * Return the name of remote that the remote tracking branch belongs to.
+ * Find the remote name of a remote-tracking branch
  *
- * @param out Pointer to the user-allocated git_buf which will be filled with the name of the remote.
+ * This will return the name of the remote whose fetch refspec is matching
+ * the given branch. E.g. given a branch "refs/remotes/test/master", it will
+ * extract the "test" part. If refspecs from multiple remotes match,
+ * the function will return GIT_EAMBIGUOUS.
  *
+ * @param out The buffer into which the name will be written.
  * @param repo The repository where the branch lives.
+ * @param refname complete name of the remote tracking branch.
  *
- * @param canonical_branch_name name of the remote tracking branch.
- *
- * @return 0, GIT_ENOTFOUND
- *     when no remote matching remote was found,
- *     GIT_EAMBIGUOUS when the branch maps to several remotes,
- *     otherwise an error code.
+ * @return 0 on success, GIT_ENOTFOUND when no matching remote was found,
+ *         GIT_EAMBIGUOUS when the branch maps to several remotes,
+ *         otherwise an error code.
  */
 GIT_EXTERN(int) git_branch_remote_name(
 	git_buf *out,
 	git_repository *repo,
-	const char *canonical_branch_name);
-
+	const char *refname);
 
 /**
- * Retrieve the name of the upstream remote of a local branch
+ * Retrieve the upstream remote of a local branch
+ *
+ * This will return the currently configured "branch.*.remote" for a given
+ * branch. This branch must be local.
  *
  * @param buf the buffer into which to write the name
  * @param repo the repository in which to look

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

@@ -32,26 +32,32 @@ GIT_BEGIN_DECL
  * a block of memory they hold.  In this case, libgit2 will not resize or
  * free the memory, but will read from it as needed.
  *
- * A `git_buf` is a public structure with three fields:
- *
- * - `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.
- *
- * - `size` holds the size (in bytes) of the data that is actually used.
- *
- * - `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.
- *
  * 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.
  */
 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.
+	 */
 	char   *ptr;
-	size_t asize, size;
+
+	/**
+	 * `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.
+	 */
+	size_t asize;
+
+	/**
+	 * `size` holds the size (in bytes) of the data that is actually used.
+	 */
+	size_t size;
 } git_buf;
 
 /**

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

@@ -0,0 +1,135 @@
+/*
+ * Copyright (C) the libgit2 contributors. All rights reserved.
+ *
+ * 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_cert_h__
+#define INCLUDE_git_cert_h__
+
+#include "common.h"
+
+/**
+ * @file git2/cert.h
+ * @brief Git certificate objects
+ * @defgroup git_cert Certificate objects
+ * @ingroup Git
+ * @{
+ */
+GIT_BEGIN_DECL
+
+/**
+ * Type of host certificate structure that is passed to the check callback
+ */
+typedef enum git_cert_t {
+	/**
+	 * No information about the certificate is available. This may
+	 * happen when using curl.
+	 */
+	GIT_CERT_NONE,
+	/**
+	 * The `data` argument to the callback will be a pointer to
+	 * the DER-encoded data.
+	 */
+	GIT_CERT_X509,
+	/**
+	 * The `data` argument to the callback will be a pointer to a
+	 * `git_cert_hostkey` structure.
+	 */
+	GIT_CERT_HOSTKEY_LIBSSH2,
+	/**
+	 * The `data` argument to the callback will be a pointer to a
+	 * `git_strarray` with `name:content` strings containing
+	 * information about the certificate. This is used when using
+	 * curl.
+	 */
+	GIT_CERT_STRARRAY,
+} git_cert_t;
+
+/**
+ * Parent type for `git_cert_hostkey` and `git_cert_x509`.
+ */
+struct git_cert {
+	/**
+	 * Type of certificate. A `GIT_CERT_` value.
+	 */
+	git_cert_t cert_type;
+};
+
+/**
+ * Callback for the user's custom certificate checks.
+ *
+ * @param cert The host certificate
+ * @param valid Whether the libgit2 checks (OpenSSL or WinHTTP) think
+ * this certificate is valid
+ * @param host Hostname of the host libgit2 connected to
+ * @param payload Payload provided by the caller
+ * @return 0 to proceed with the connection, < 0 to fail the connection
+ *         or > 0 to indicate that the callback refused to act and that
+ *         the existing validity determination should be honored
+ */
+typedef int GIT_CALLBACK(git_transport_certificate_check_cb)(git_cert *cert, int valid, const char *host, void *payload);
+
+/**
+ * Type of SSH host fingerprint
+ */
+typedef enum {
+	/** MD5 is available */
+	GIT_CERT_SSH_MD5 = (1 << 0),
+	/** SHA-1 is available */
+	GIT_CERT_SSH_SHA1 = (1 << 1),
+	/** SHA-256 is available */
+	GIT_CERT_SSH_SHA256 = (1 << 2),
+} git_cert_ssh_t;
+
+/**
+ * Hostkey information taken from libssh2
+ */
+typedef struct {
+	git_cert parent; /**< The parent cert */
+
+	/**
+	 * A hostkey type from libssh2, either
+	 * `GIT_CERT_SSH_MD5` or `GIT_CERT_SSH_SHA1`
+	 */
+	git_cert_ssh_t type;
+
+	/**
+	 * Hostkey hash. If type has `GIT_CERT_SSH_MD5` set, this will
+	 * have the MD5 hash of the hostkey.
+	 */
+	unsigned char hash_md5[16];
+
+	/**
+	 * Hostkey hash. If type has `GIT_CERT_SSH_SHA1` set, this will
+	 * have the SHA-1 hash of the hostkey.
+	 */
+	unsigned char hash_sha1[20];
+
+	/**
+	 * Hostkey hash. If type has `GIT_CERT_SSH_SHA256` set, this will
+	 * have the SHA-256 hash of the hostkey.
+	 */
+	unsigned char hash_sha256[32];
+} git_cert_hostkey;
+
+/**
+ * X.509 certificate information
+ */
+typedef struct {
+	git_cert parent; /**< The parent cert */
+
+	/**
+	 * Pointer to the X.509 certificate data
+	 */
+	void *data;
+
+	/**
+	 * Length of the memory block pointed to by `data`.
+	 */
+	size_t len;
+} git_cert_x509;
+
+/** @} */
+GIT_END_DECL
+#endif

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

@@ -106,10 +106,22 @@ GIT_BEGIN_DECL
 typedef enum {
 	GIT_CHECKOUT_NONE = 0, /**< default is a dry run, no actual updates */
 
-	/** Allow safe updates that cannot overwrite uncommitted data */
+	/**
+	 * 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.
+	 */
 	GIT_CHECKOUT_SAFE = (1u << 0),
 
-	/** Allow all updates to force working directory to look like index */
+	/**
+	 * 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.
+	 */
 	GIT_CHECKOUT_FORCE = (1u << 1),
 
 
@@ -213,6 +225,7 @@ typedef enum {
 	GIT_CHECKOUT_NOTIFY_ALL       = 0x0FFFFu
 } git_checkout_notify_t;
 
+/** Checkout performance-reporting structure */
 typedef struct {
 	size_t mkdir_calls;
 	size_t stat_calls;
@@ -244,11 +257,11 @@ typedef void GIT_CALLBACK(git_checkout_perfdata_cb)(
  * Checkout options structure
  *
  * Initialize with `GIT_CHECKOUT_OPTIONS_INIT`. Alternatively, you can
- * use `git_checkout_init_options`.
+ * use `git_checkout_options_init`.
  *
  */
 typedef struct git_checkout_options {
-	unsigned int version;
+	unsigned int version; /**< The version */
 
 	unsigned int checkout_strategy; /**< default will be a safe checkout */
 
@@ -258,29 +271,46 @@ typedef struct git_checkout_options {
 	int file_open_flags;    /**< default is O_CREAT | O_TRUNC | O_WRONLY */
 
 	unsigned int notify_flags; /**< see `git_checkout_notify_t` above */
+
+	/**
+	 * Optional callback to get notifications on specific file states.
+	 * @see git_checkout_notify_t
+	 */
 	git_checkout_notify_cb notify_cb;
+
+	/** Payload passed to notify_cb */
 	void *notify_payload;
 
 	/** Optional callback to notify the consumer of checkout progress. */
 	git_checkout_progress_cb progress_cb;
+
+	/** Payload passed to progress_cb */
 	void *progress_payload;
 
-	/** When not zeroed out, array of fnmatch patterns specifying which
-	 *  paths should be taken into account, otherwise all files.  Use
-	 *  GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as simple list.
+	/**
+	 * A list of wildmatch patterns or paths.
+	 *
+	 * By default, all paths are processed. If you pass an array of wildmatch
+	 * patterns, those will be used to filter which paths should be taken into
+	 * account.
+	 *
+	 * Use GIT_CHECKOUT_DISABLE_PATHSPEC_MATCH to treat as a simple list.
 	 */
 	git_strarray paths;
 
-	/** The expected content of the working directory; defaults to HEAD.
-	 *  If the working directory does not match this baseline information,
-	 *  that will produce a checkout conflict.
+	/**
+	 * The expected content of the working directory; defaults to HEAD.
+	 *
+	 * If the working directory does not match this baseline information,
+	 * that will produce a checkout conflict.
 	 */
 	git_tree *baseline;
 
-	/** Like `baseline` above, though expressed as an index.  This
-	 *  option overrides `baseline`.
+	/**
+	 * Like `baseline` above, though expressed as an index.  This
+	 * option overrides `baseline`.
 	 */
-	git_index *baseline_index; /**< expected content of workdir, expressed as an index. */
+	git_index *baseline_index;
 
 	const char *target_directory; /**< alternative checkout path to workdir */
 
@@ -290,6 +320,8 @@ typedef struct git_checkout_options {
 
 	/** Optional callback to notify the consumer of performance data. */
 	git_checkout_perfdata_cb perfdata_cb;
+
+	/** Payload passed to perfdata_cb */
 	void *perfdata_payload;
 } git_checkout_options;
 
@@ -306,7 +338,7 @@ typedef struct git_checkout_options {
  * @param version The struct version; pass `GIT_CHECKOUT_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_checkout_init_options(
+GIT_EXTERN(int) git_checkout_options_init(
 	git_checkout_options *opts,
 	unsigned int version);