Merge remote-tracking branch 'upstream/master' into cmn/ssh-retry

16 files changed, 560 insertions, 480 deletions

diff --git a/include/git2/attr.h b/include/git2/attr.h
index 3adbb2c24..0238f3dd7 100644
--- a/include/git2/attr.h
+++ b/include/git2/attr.h
@@ -76,25 +76,28 @@ GIT_BEGIN_DECL
  */
 #define GIT_ATTR_HAS_VALUE(attr) (git_attr_value(attr) == GIT_ATTR_VALUE_T)
 
+/**
+ * Possible states for an attribute
+ */
 typedef enum {
-	GIT_ATTR_UNSPECIFIED_T = 0,
-	GIT_ATTR_TRUE_T,
-	GIT_ATTR_FALSE_T,
-	GIT_ATTR_VALUE_T,
+	GIT_ATTR_UNSPECIFIED_T = 0, /**< The attribute has been left unspecified */
+	GIT_ATTR_TRUE_T,  /**< The attribute has been set */
+	GIT_ATTR_FALSE_T, /**< The attribute has been unset */
+	GIT_ATTR_VALUE_T, /**< This attribute has a value */
 } git_attr_t;
 
-/*
- *	Return the value type for a given attribute.
+/**
+ * Return the value type for a given attribute.
  *
- *	This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute
- *	was not set at all), or `VALUE`, if the attribute was set to
- *	an actual string.
+ * This can be either `TRUE`, `FALSE`, `UNSPECIFIED` (if the attribute
+ * was not set at all), or `VALUE`, if the attribute was set to an
+ * actual string.
  *
- *	If the attribute has a `VALUE` string, it can be accessed normally
- *	as a NULL-terminated C string.
+ * If the attribute has a `VALUE` string, it can be accessed normally
+ * as a NULL-terminated C string.
  *
- *	@param attr The attribute
- *	@return the value type for the attribute
+ * @param attr The attribute
+ * @return the value type for the attribute
  */
 GIT_EXTERN(git_attr_t) git_attr_value(const char *attr);
 
diff --git a/include/git2/buffer.h b/include/git2/buffer.h
index 36a61e6c9..1c216bf3a 100644
--- a/include/git2/buffer.h
+++ b/include/git2/buffer.h
@@ -105,6 +105,22 @@ GIT_EXTERN(int) git_buf_grow(git_buf *buffer, size_t target_size);
 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
 
 /** @} */
diff --git a/include/git2/checkout.h b/include/git2/checkout.h
index ad44173e6..fe4966aa2 100644
--- a/include/git2/checkout.h
+++ b/include/git2/checkout.h
@@ -233,18 +233,18 @@ typedef void (*git_checkout_progress_cb)(
 typedef struct git_checkout_options {
 	unsigned int version;
 
-	unsigned int checkout_strategy; /** default will be a dry run */
+	unsigned int checkout_strategy; /**< default will be a dry run */
 
-	int disable_filters;    /** don't apply filters like CRLF conversion */
-	unsigned int dir_mode;  /** default is 0755 */
-	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 */
+	int disable_filters;    /**< don't apply filters like CRLF conversion */
+	unsigned int dir_mode;  /**< default is 0755 */
+	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 */
+	unsigned int notify_flags; /**< see `git_checkout_notify_t` above */
 	git_checkout_notify_cb notify_cb;
 	void *notify_payload;
 
-	/* Optional callback to notify the consumer of checkout progress. */
+	/** Optional callback to notify the consumer of checkout progress. */
 	git_checkout_progress_cb progress_cb;
 	void *progress_payload;
 
@@ -254,13 +254,13 @@ typedef struct git_checkout_options {
 	 */
 	git_strarray paths;
 
-	git_tree *baseline; /** expected content of workdir, defaults to HEAD */
+	git_tree *baseline; /**< expected content of workdir, defaults to HEAD */
 
-	const char *target_directory; /** alternative checkout path to workdir */
+	const char *target_directory; /**< alternative checkout path to workdir */
 
-	const char *ancestor_label; /** the name of the common ancestor side of conflicts */
-	const char *our_label; /** the name of the "our" side of conflicts */
-	const char *their_label; /** the name of the "their" side of conflicts */
+	const char *ancestor_label; /**< the name of the common ancestor side of conflicts */
+	const char *our_label; /**< the name of the "our" side of conflicts */
+	const char *their_label; /**< the name of the "their" side of conflicts */
 } git_checkout_options;
 
 #define GIT_CHECKOUT_OPTIONS_VERSION 1
diff --git a/include/git2/cherrypick.h b/include/git2/cherrypick.h
index 9eccb0af9..dea67c1ff 100644
--- a/include/git2/cherrypick.h
+++ b/include/git2/cherrypick.h
@@ -28,21 +28,21 @@ typedef struct {
 
 	git_merge_options merge_opts;
 	git_checkout_options checkout_opts;
-} git_cherry_pick_options;
+} git_cherrypick_options;
 
-#define GIT_CHERRY_PICK_OPTIONS_VERSION 1
-#define GIT_CHERRY_PICK_OPTIONS_INIT {GIT_CHERRY_PICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT}
+#define GIT_CHERRYPICK_OPTIONS_VERSION 1
+#define GIT_CHERRYPICK_OPTIONS_INIT {GIT_CHERRYPICK_OPTIONS_VERSION, 0, GIT_MERGE_OPTIONS_INIT, GIT_CHECKOUT_OPTIONS_INIT}
 
 /**
- * Initializes a `git_cherry_pick_options` with default values. Equivalent to
- * creating an instance with GIT_CHERRY_PICK_OPTIONS_INIT.
+ * Initializes a `git_cherrypick_options` with default values. Equivalent to
+ * creating an instance with GIT_CHERRYPICK_OPTIONS_INIT.
  *
- * @param opts the `git_cherry_pick_options` struct to initialize
- * @param version Version of struct; pass `GIT_CHERRY_PICK_OPTIONS_VERSION`
+ * @param opts the `git_cherrypick_options` struct to initialize
+ * @param version Version of struct; pass `GIT_CHERRYPICK_OPTIONS_VERSION`
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_cherry_pick_init_options(
-	git_cherry_pick_options *opts,
+GIT_EXTERN(int) git_cherrypick_init_options(
+	git_cherrypick_options *opts,
 	unsigned int version);
 
 /**
@@ -53,16 +53,16 @@ GIT_EXTERN(int) git_cherry_pick_init_options(
  *
  * @param out pointer to store the index result in
  * @param repo the repository that contains the given commits
- * @param cherry_pick_commit the commit to cherry-pick
+ * @param cherrypick_commit the commit to cherry-pick
  * @param our_commit the commit to revert against (eg, HEAD)
  * @param mainline the parent of the revert commit, if it is a merge
  * @param merge_options the merge options (or null for defaults)
  * @return zero on success, -1 on failure.
  */
-GIT_EXTERN(int) git_cherry_pick_commit(
+GIT_EXTERN(int) git_cherrypick_commit(
 	git_index **out,
 	git_repository *repo,
-	git_commit *cherry_pick_commit,
+	git_commit *cherrypick_commit,
 	git_commit *our_commit,
 	unsigned int mainline,
 	const git_merge_options *merge_options);
@@ -72,13 +72,13 @@ GIT_EXTERN(int) git_cherry_pick_commit(
  *
  * @param repo the repository to cherry-pick
  * @param commit the commit to cherry-pick
- * @param cherry_pick_options the cherry-pick options (or null for defaults)
+ * @param cherrypick_options the cherry-pick options (or null for defaults)
  * @return zero on success, -1 on failure.
  */
-GIT_EXTERN(int) git_cherry_pick(
+GIT_EXTERN(int) git_cherrypick(
 	git_repository *repo,
 	git_commit *commit,
-	const git_cherry_pick_options *cherry_pick_options);
+	const git_cherrypick_options *cherrypick_options);
 
 /** @} */
 GIT_END_DECL
diff --git a/include/git2/clone.h b/include/git2/clone.h
index 05b7522ce..fa2e25b60 100644
--- a/include/git2/clone.h
+++ b/include/git2/clone.h
@@ -12,6 +12,7 @@
 #include "indexer.h"
 #include "checkout.h"
 #include "remote.h"
+#include "transport.h"
 
 
 /**
@@ -52,6 +53,47 @@ typedef enum {
 } git_clone_local_t;
 
 /**
+ * The signature of a function matching git_remote_create, with an additional
+ * void* as a callback payload.
+ *
+ * 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 repo the repository in which to create the remote
+ * @param name the remote's name
+ * @param url the remote's url
+ * @param payload an opaque payload
+ * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
+ */
+typedef int (*git_remote_create_cb)(
+	git_remote **out,
+	git_repository *repo,
+	const char *name,
+	const char *url,
+	void *payload);
+
+/**
+ * The signature of a function matchin git_repository_init, with an
+ * aditional 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 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
+ * @return 0, or a negative value to indicate error
+ */
+typedef int (*git_repository_create_cb)(
+	git_repository **out,
+	const char *path,
+	int bare,
+	void *payload);
+
+/**
  * Clone options structure
  *
  * Use the GIT_CLONE_OPTIONS_INIT to get the default settings, like this:
@@ -72,7 +114,11 @@ typedef struct git_clone_options {
 	git_checkout_options checkout_opts;
 
 	/**
-	 * Callbacks to use for reporting fetch progress.
+	 * Callbacks to use for reporting fetch progress, and for acquiring
+	 * credentials in the event they are needed. This parameter is ignored if
+	 * the remote_cb parameter is set; if you provide a remote creation
+	 * callback, then you have the opportunity to configure remote callbacks in
+	 * provided function.
 	 */
 	git_remote_callbacks remote_callbacks;
 
@@ -83,23 +129,11 @@ typedef struct git_clone_options {
 	int bare;
 
 	/**
-	 * Set to 1 if errors validating the remote host's certificate
-	 * should be ignored.
-	 */
-	int ignore_cert_errors;
-
-	/**
 	 * Whether to use a fetch or copy the object database.
 	 */
 	git_clone_local_t local;
 
 	/**
-	 * The name to be given to the remote that will be
-	 * created. The default is "origin".
-	 */
-	const char *remote_name;
-
-	/**
 	 * The name of the branch to checkout. NULL means use the
 	 * remote's default branch.
 	 */
@@ -110,6 +144,33 @@ typedef struct git_clone_options {
 	 * use the default signature using the config.
 	 */
 	git_signature *signature;
+
+	/**
+	 * A callback used to create the new repository into which to
+	 * clone. If NULL, the 'bare' field will be used to determine
+	 * whether to create a bare repository.
+	 */
+	git_repository_create_cb repository_cb;
+
+	/**
+	 * An opaque payload to pass to the git_repository creation callback.
+	 * This parameter is ignored unless repository_cb is non-NULL.
+	 */
+	void *repository_cb_payload;
+
+	/**
+	 * A callback used to create the git_remote, prior to its being
+	 * used to perform the clone operation. See the documentation for
+	 * git_remote_create_cb for details. This parameter may be NULL,
+	 * indicating that git_clone should provide default behavior.
+	 */
+	git_remote_create_cb remote_cb;
+
+	/**
+	 * An opaque payload to pass to the git_remote creation callback.
+	 * This parameter is ignored unless remote_cb is non-NULL.
+	 */
+	void *remote_cb_payload;
 } git_clone_options;
 
 #define GIT_CLONE_OPTIONS_VERSION 1
@@ -130,9 +191,9 @@ GIT_EXTERN(int) git_clone_init_options(
 /**
  * Clone a remote repository.
  *
- * This version handles the simple case. If you'd like to create the
- * repository or remote with non-default settings, you can create and
- * configure them and then use `git_clone_into()`.
+ * By default this creates its repository and initial remote to match
+ * 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
  * @param url the remote repository to clone
@@ -149,59 +210,6 @@ GIT_EXTERN(int) git_clone(
 	const char *local_path,
 	const git_clone_options *options);
 
-/**
- * Clone into a repository
- *
- * After creating the repository and remote and configuring them for
- * paths and callbacks respectively, you can call this function to
- * perform the clone operation and optionally checkout files.
- *
- * @param repo the repository to use
- * @param remote the remote repository to clone from
- * @param co_opts options to use during checkout
- * @param branch the branch to checkout after the clone, pass NULL for the
- *        remote's default branch
- * @param signature The identity used when updating the reflog.
- * @return 0 on success, any non-zero return value from a callback
- *         function, or a negative value to indicate an error (use
- *         `giterr_last` for a detailed error message)
- */
-GIT_EXTERN(int) git_clone_into(
-	git_repository *repo,
-	git_remote *remote,
-	const git_checkout_options *co_opts,
-	const char *branch,
-	const git_signature *signature);
-
-/**
- * Perform a local clone into a repository
- *
- * A "local clone" bypasses any git-aware protocols and simply copies
- * over the object database from the source repository. It is often
- * faster than a git-aware clone, but no verification of the data is
- * performed, and can copy over too much data.
- *
- * @param repo the repository to use
- * @param remote the remote repository to clone from
- * @param co_opts options to use during checkout
- * @param branch the branch to checkout after the clone, pass NULL for the
- *        remote's default branch
- * @param link wether to use hardlinks instead of copying
- * objects. This is only possible if both repositories are on the same
- * filesystem.
- * @param signature the identity used when updating the reflog
- * @return 0 on success, any non-zero return value from a callback
- *         function, or a negative value to indicate an error (use
- *         `giterr_last` for a detailed error message)
- */
-GIT_EXTERN(int) git_clone_local_into(
-	git_repository *repo,
-	git_remote *remote,
-	const git_checkout_options *co_opts,
-	const char *branch,
-	int link,
-	const git_signature *signature);
-
 /** @} */
 GIT_END_DECL
 #endif
diff --git a/include/git2/diff.h b/include/git2/diff.h
index 675c209be..8147fd31c 100644
--- a/include/git2/diff.h
+++ b/include/git2/diff.h
@@ -152,6 +152,12 @@ typedef enum {
 	 */
 	GIT_DIFF_UPDATE_INDEX = (1u << 15),
 
+	/** Include unreadable files in the diff */
+	GIT_DIFF_INCLUDE_UNREADABLE = (1u << 16),
+	
+	/** Include unreadable files in the diff */
+	GIT_DIFF_INCLUDE_UNREADABLE_AS_UNTRACKED = (1u << 17),
+
 	/*
 	 * Options controlling how output will be generated
 	 */
@@ -237,6 +243,7 @@ typedef enum {
 	GIT_DELTA_IGNORED = 6,    /**< entry is ignored item in workdir */
 	GIT_DELTA_UNTRACKED = 7,  /**< entry is untracked item in workdir */
 	GIT_DELTA_TYPECHANGE = 8, /**< type of entry changed between old and new */
+	GIT_DELTA_UNREADABLE = 9, /**< entry is unreadable */
 } git_delta_t;
 
 /**
diff --git a/include/git2/oid.h b/include/git2/oid.h
index 1cfd4e5e2..db2f3af70 100644
--- a/include/git2/oid.h
+++ b/include/git2/oid.h
@@ -116,13 +116,17 @@ GIT_EXTERN(void) git_oid_nfmt(char *out, size_t n, const git_oid *id);
 GIT_EXTERN(void) git_oid_pathfmt(char *out, const git_oid *id);
 
 /**
- * Format a git_oid into a newly allocated c-string.
+ * Format a git_oid into a statically allocated c-string.
+ *
+ * The c-string is owned by the library and should not be freed
+ * by the user. If libgit2 is built with thread support, the string
+ * will be stored in TLS (i.e. one buffer per thread) to allow for
+ * concurrent calls of the function.
  *
  * @param id the oid structure to format
- * @return the c-string; NULL if memory is exhausted. Caller must
- *			deallocate the string with git__free().
+ * @return the c-string
  */
-GIT_EXTERN(char *) git_oid_allocfmt(const git_oid *id);
+GIT_EXTERN(char *) git_oid_tostr_s(const git_oid *oid);
 
 /**
  * Format a git_oid into a buffer as a hex format c-string.
diff --git a/include/git2/remote.h b/include/git2/remote.h
index c72c9c8cc..c0717fa31 100644
--- a/include/git2/remote.h
+++ b/include/git2/remote.h
@@ -419,22 +419,6 @@ GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo);
 GIT_EXTERN(void) git_remote_check_cert(git_remote *remote, int check);
 
 /**
- * Sets a custom transport for the remote. The caller can use this function
- * to bypass the automatic discovery of a transport by URL scheme (i.e.
- * http://, https://, git://) and supply their own transport to be used
- * instead. After providing the transport to a remote using this function,
- * the transport object belongs exclusively to that remote, and the remote will
- * free it when it is freed with git_remote_free.
- *
- * @param remote the remote to configure
- * @param transport the transport object for the remote to use
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_remote_set_transport(
-	git_remote *remote,
-	git_transport *transport);
-
-/**
  * Argument to the completion callback which tells it which operation
  * finished.
  */
diff --git a/include/git2/repository.h b/include/git2/repository.h
index 6a8ff4545..18e515cb0 100644
--- a/include/git2/repository.h
+++ b/include/git2/repository.h
@@ -662,7 +662,7 @@ typedef enum {
 	GIT_REPOSITORY_STATE_NONE,
 	GIT_REPOSITORY_STATE_MERGE,
 	GIT_REPOSITORY_STATE_REVERT,
-	GIT_REPOSITORY_STATE_CHERRY_PICK,
+	GIT_REPOSITORY_STATE_CHERRYPICK,
 	GIT_REPOSITORY_STATE_BISECT,
 	GIT_REPOSITORY_STATE_REBASE,
 	GIT_REPOSITORY_STATE_REBASE_INTERACTIVE,
diff --git a/include/git2/reset.h b/include/git2/reset.h
index b8c580339..ea7217efe 100644
--- a/include/git2/reset.h
+++ b/include/git2/reset.h
@@ -7,6 +7,10 @@
 #ifndef INCLUDE_git_reset_h__
 #define INCLUDE_git_reset_h__
 
+#include "common.h"
+#include "types.h"
+#include "strarray.h"
+
 /**
  * @file git2/reset.h
  * @brief Git reset management routines
diff --git a/include/git2/revert.h b/include/git2/revert.h
index fc1767c93..ab9dd9af9 100644
--- a/include/git2/revert.h
+++ b/include/git2/revert.h
@@ -59,7 +59,7 @@ GIT_EXTERN(int) git_revert_init_options(
  * @param merge_options the merge options (or null for defaults)
  * @return zero on success, -1 on failure.
  */
-int git_revert_commit(
+GIT_EXTERN(int) git_revert_commit(
 	git_index **out,
 	git_repository *repo,
 	git_commit *revert_commit,
diff --git a/include/git2/status.h b/include/git2/status.h
index effe5e1ea..3c86e5d7b 100644
--- a/include/git2/status.h
+++ b/include/git2/status.h
@@ -43,6 +43,7 @@ typedef enum {
 	GIT_STATUS_WT_DELETED       = (1u << 9),
 	GIT_STATUS_WT_TYPECHANGE    = (1u << 10),
 	GIT_STATUS_WT_RENAMED       = (1u << 11),
+	GIT_STATUS_WT_UNREADABLE    = (1u << 12),
 
 	GIT_STATUS_IGNORED          = (1u << 14),
 } git_status_t;
@@ -133,20 +134,22 @@ typedef enum {
  * together as `GIT_STATUS_OPT_DEFAULTS` if you want them as a baseline.
  */
 typedef enum {
-	GIT_STATUS_OPT_INCLUDE_UNTRACKED        = (1u << 0),
-	GIT_STATUS_OPT_INCLUDE_IGNORED          = (1u << 1),
-	GIT_STATUS_OPT_INCLUDE_UNMODIFIED       = (1u << 2),
-	GIT_STATUS_OPT_EXCLUDE_SUBMODULES       = (1u << 3),
-	GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS   = (1u << 4),
-	GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH   = (1u << 5),
-	GIT_STATUS_OPT_RECURSE_IGNORED_DIRS     = (1u << 6),
-	GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX    = (1u << 7),
-	GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR = (1u << 8),
-	GIT_STATUS_OPT_SORT_CASE_SENSITIVELY    = (1u << 9),
-	GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY  = (1u << 10),
-	GIT_STATUS_OPT_RENAMES_FROM_REWRITES    = (1u << 11),
-	GIT_STATUS_OPT_NO_REFRESH               = (1u << 12),
-	GIT_STATUS_OPT_UPDATE_INDEX             = (1u << 13),
+	GIT_STATUS_OPT_INCLUDE_UNTRACKED                = (1u << 0),
+	GIT_STATUS_OPT_INCLUDE_IGNORED                  = (1u << 1),
+	GIT_STATUS_OPT_INCLUDE_UNMODIFIED               = (1u << 2),
+	GIT_STATUS_OPT_EXCLUDE_SUBMODULES               = (1u << 3),
+	GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS           = (1u << 4),
+	GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH           = (1u << 5),
+	GIT_STATUS_OPT_RECURSE_IGNORED_DIRS             = (1u << 6),
+	GIT_STATUS_OPT_RENAMES_HEAD_TO_INDEX            = (1u << 7),
+	GIT_STATUS_OPT_RENAMES_INDEX_TO_WORKDIR         = (1u << 8),
+	GIT_STATUS_OPT_SORT_CASE_SENSITIVELY            = (1u << 9),
+	GIT_STATUS_OPT_SORT_CASE_INSENSITIVELY          = (1u << 10),
+	GIT_STATUS_OPT_RENAMES_FROM_REWRITES            = (1u << 11),
+	GIT_STATUS_OPT_NO_REFRESH                       = (1u << 12),
+	GIT_STATUS_OPT_UPDATE_INDEX                     = (1u << 13),
+	GIT_STATUS_OPT_INCLUDE_UNREADABLE               = (1u << 14),
+	GIT_STATUS_OPT_INCLUDE_UNREADABLE_AS_UNTRACKED  = (1u << 15),
 } git_status_opt_t;
 
 #define GIT_STATUS_OPT_DEFAULTS \
diff --git a/include/git2/sys/transport.h b/include/git2/sys/transport.h
new file mode 100644
index 000000000..62ac455d3
--- /dev/null
+++ b/include/git2/sys/transport.h
@@ -0,0 +1,354 @@
+/*
+ * 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_sys_git_transport_h
+#define INCLUDE_sys_git_transport_h
+
+#include "git2/net.h"
+#include "git2/types.h"
+
+/**
+ * @file git2/sys/transport.h
+ * @brief Git custom transport registration interfaces and functions
+ * @defgroup git_transport Git custom transport registration
+ * @ingroup Git
+ * @{
+ */
+
+GIT_BEGIN_DECL
+
+typedef enum {
+	GIT_TRANSPORTFLAGS_NONE = 0,
+	/* If the connection is secured with SSL/TLS, the authenticity
+	 * of the server certificate should not be verified. */
+	GIT_TRANSPORTFLAGS_NO_CHECK_CERT = 1
+} git_transport_flags_t;
+
+typedef struct git_transport git_transport;
+
+struct git_transport {
+	unsigned int version;
+	/* Set progress and error callbacks */
+	int (*set_callbacks)(
+		git_transport *transport,
+		git_transport_message_cb progress_cb,
+		git_transport_message_cb error_cb,
+		void *payload);
+
+	/* Connect the transport to the remote repository, using the given
+	 * direction. */
+	int (*connect)(
+		git_transport *transport,
+		const char *url,
+		git_cred_acquire_cb cred_acquire_cb,
+		void *cred_acquire_payload,
+		int direction,
+		int flags);
+
+	/* This function may be called after a successful call to
+	 * connect(). The array returned is owned by the transport and
+	 * is guranteed until the next call of a transport function. */
+	int (*ls)(
+		const git_remote_head ***out,
+		size_t *size,
+		git_transport *transport);
+
+	/* Executes the push whose context is in the git_push object. */
+	int (*push)(git_transport *transport, git_push *push);
+
+	/* This function may be called after a successful call to connect(), when
+	 * the direction is FETCH. The function performs a negotiation to calculate
+	 * the wants list for the fetch. */
+	int (*negotiate_fetch)(
+		git_transport *transport,
+		git_repository *repo,
+		const git_remote_head * const *refs,
+		size_t count);
+
+	/* This function may be called after a successful call to negotiate_fetch(),
+	 * when the direction is FETCH. This function retrieves the pack file for
+	 * the fetch from the remote end. */
+	int (*download_pack)(
+		git_transport *transport,
+		git_repository *repo,
+		git_transfer_progress *stats,
+		git_transfer_progress_cb progress_cb,
+		void *progress_payload);
+
+	/* Checks to see if the transport is connected */
+	int (*is_connected)(git_transport *transport);
+
+	/* Reads the flags value previously passed into connect() */
+	int (*read_flags)(git_transport *transport, int *flags);
+
+	/* Cancels any outstanding transport operation */
+	void (*cancel)(git_transport *transport);
+
+	/* This function is the reverse of connect() -- it terminates the
+	 * connection to the remote end. */
+	int (*close)(git_transport *transport);
+
+	/* Frees/destructs the git_transport object. */
+	void (*free)(git_transport *transport);
+};
+
+#define GIT_TRANSPORT_VERSION 1
+#define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION}
+
+/**
+ * Initializes a `git_transport` with default values. Equivalent to
+ * creating an instance with GIT_TRANSPORT_INIT.
+ *
+ * @param opts the `git_transport` struct to initialize
+ * @param version Version of struct; pass `GIT_TRANSPORT_VERSION`
+ * @return Zero on success; -1 on failure.
+ */
+GIT_EXTERN(int) git_transport_init(
+	git_transport *opts,
+	unsigned int version);
+
+/**
+ * Function to use to create a transport from a URL. The transport database
+ * is scanned to find a transport that implements the scheme of the URI (i.e.
+ * git:// or http://) and a transport object is returned to the caller.
+ *
+ * @param out The newly created transport (out)
+ * @param owner The git_remote which will own this transport
+ * @param url The URL to connect to
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const char *url);
+
+/**
+ * Create an ssh transport with custom git command paths
+ *
+ * This is a factory function suitable for setting as the transport
+ * callback in a remote (or for a clone in the options).
+ *
+ * The payload argument must be a strarray pointer with the paths for
+ * the `git-upload-pack` and `git-receive-pack` at index 0 and 1.
+ *
+ * @param out the resulting transport
+ * @param owner the owning remote
+ * @param payload a strarray with the paths
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_transport_ssh_with_paths(git_transport **out, git_remote *owner, void *payload);
+
+/* Signature of a function which creates a transport */
+typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param);
+
+/**
+ * Add a custom transport definition, to be used in addition to the built-in
+ * set of transports that come with libgit2.
+ *
+ * The caller is responsible for synchronizing calls to git_transport_register
+ * and git_transport_unregister with other calls to the library that
+ * instantiate transports.
+ *
+ * @param prefix The scheme (ending in "://") to match, i.e. "git://"
+ * @param cb The callback used to create an instance of the transport
+ * @param param A fixed parameter to pass to cb at creation time
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_transport_register(
+	const char *prefix,
+	git_transport_cb cb,
+	void *param);
+
+/**
+ *
+ * Unregister a custom transport definition which was previously registered
+ * with git_transport_register.
+ *
+ * @param prefix From the previous call to git_transport_register
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_transport_unregister(
+	const char *prefix);
+
+/* Transports which come with libgit2 (match git_transport_cb). The expected
+ * value for "param" is listed in-line below. */
+
+/**
+ * Create an instance of the dummy transport.
+ *
+ * @param out The newly created transport (out)
+ * @param owner The git_remote which will own this transport
+ * @param payload You must pass NULL for this parameter.
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_transport_dummy(
+	git_transport **out,
+	git_remote *owner,
+	/* NULL */ void *payload);
+
+/**
+ * Create an instance of the local transport.
+ *
+ * @param out The newly created transport (out)
+ * @param owner The git_remote which will own this transport
+ * @param payload You must pass NULL for this parameter.
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_transport_local(
+	git_transport **out,
+	git_remote *owner,
+	/* NULL */ void *payload);
+
+/**
+ * Create an instance of the smart transport.
+ *
+ * @param out The newly created transport (out)
+ * @param owner The git_remote which will own this transport
+ * @param payload A pointer to a git_smart_subtransport_definition
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_transport_smart(
+	git_transport **out,
+	git_remote *owner,
+	/* (git_smart_subtransport_definition *) */ void *payload);
+
+/*
+ *** End of base transport interface ***
+ *** Begin interface for subtransports for the smart transport ***
+ */
+
+/* The smart transport knows how to speak the git protocol, but it has no
+ * knowledge of how to establish a connection between it and another endpoint,
+ * or how to move data back and forth. For this, a subtransport interface is
+ * declared, and the smart transport delegates this work to the subtransports.
+ * Three subtransports are implemented: git, http, and winhttp. (The http and
+ * winhttp transports each implement both http and https.) */
+
+/* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1
+ * (request/response). The smart transport handles the differences in its own
+ * logic. The git subtransport is RPC = 0, while http and winhttp are both
+ * RPC = 1. */
+
+/* Actions that the smart transport can ask
+ * a subtransport to perform */
+typedef enum {
+	GIT_SERVICE_UPLOADPACK_LS = 1,
+	GIT_SERVICE_UPLOADPACK = 2,
+	GIT_SERVICE_RECEIVEPACK_LS = 3,
+	GIT_SERVICE_RECEIVEPACK = 4,
+} git_smart_service_t;
+
+typedef struct git_smart_subtransport git_smart_subtransport;
+typedef struct git_smart_subtransport_stream git_smart_subtransport_stream;
+
+/* A stream used by the smart transport to read and write data
+ * from a subtransport */
+struct git_smart_subtransport_stream {
+	/* The owning subtransport */
+	git_smart_subtransport *subtransport;
+
+	int (*read)(
+		git_smart_subtransport_stream *stream,
+		char *buffer,
+		size_t buf_size,
+		size_t *bytes_read);
+
+	int (*write)(
+		git_smart_subtransport_stream *stream,
+		const char *buffer,
+		size_t len);
+
+	void (*free)(
+		git_smart_subtransport_stream *stream);
+};
+
+/* An implementation of a subtransport which carries data for the
+ * smart transport */
+struct git_smart_subtransport {
+	int (* action)(
+			git_smart_subtransport_stream **out,
+			git_smart_subtransport *transport,
+			const char *url,
+			git_smart_service_t action);
+
+	/* Subtransports are guaranteed a call to close() between
+	 * calls to action(), except for the following two "natural" progressions
+	 * of actions against a constant URL.
+	 *
+	 * 1. UPLOADPACK_LS -> UPLOADPACK
+	 * 2. RECEIVEPACK_LS -> RECEIVEPACK */
+	int (*close)(git_smart_subtransport *transport);
+
+	void (*free)(git_smart_subtransport *transport);
+};
+
+/* A function which creates a new subtransport for the smart transport */
+typedef int (*git_smart_subtransport_cb)(
+	git_smart_subtransport **out,
+	git_transport* owner);
+
+typedef struct git_smart_subtransport_definition {
+	/* The function to use to create the git_smart_subtransport */
+	git_smart_subtransport_cb callback;
+
+	/* True if the protocol is stateless; false otherwise. For example,
+	 * http:// is stateless, but git:// is not. */
+	unsigned rpc;
+} git_smart_subtransport_definition;
+
+/* Smart transport subtransports that come with libgit2 */
+
+/**
+ * Create an instance of the http subtransport. This subtransport
+ * also supports https. On Win32, this subtransport may be implemented
+ * using the WinHTTP library.
+ *
+ * @param out The newly created subtransport
+ * @param owner The smart transport to own this subtransport
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_smart_subtransport_http(
+	git_smart_subtransport **out,
+	git_transport* owner);
+
+/**
+ * Create an instance of the git subtransport.
+ *
+ * @param out The newly created subtransport
+ * @param owner The smart transport to own this subtransport
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_smart_subtransport_git(
+	git_smart_subtransport **out,
+	git_transport* owner);
+
+/**
+ * Create an instance of the ssh subtransport.
+ *
+ * @param out The newly created subtransport
+ * @param owner The smart transport to own this subtransport
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_smart_subtransport_ssh(
+	git_smart_subtransport **out,
+	git_transport* owner);
+
+/**
+ * Sets a custom transport factory for the remote. The caller can use this
+ * function to override the transport used for this remote when performing
+ * network operations.
+ *
+ * @param remote the remote to configure
+ * @param transport_cb the function to use to create a transport
+ * @param payload opaque parameter passed to transport_cb
+ * @return 0 or an error code
+ */
+GIT_EXTERN(int) git_remote_set_transport(
+	git_remote *remote,
+	git_transport_cb transport_cb,
+	void *payload);
+
+/** @} */
+GIT_END_DECL
+#endif
diff --git a/include/git2/transport.h b/include/git2/transport.h
index b57d1dd7f..7090698ac 100644
--- a/include/git2/transport.h
+++ b/include/git2/transport.h
@@ -11,10 +11,6 @@
 #include "net.h"
 #include "types.h"
 
-#ifdef GIT_SSH
-#include <libssh2.h>
-#endif
-
 /**
  * @file git2/transport.h
  * @brief Git transport interfaces and functions
@@ -24,10 +20,6 @@
  */
 GIT_BEGIN_DECL
 
-/*
- *** Begin interface for credentials acquisition ***
- */
-
 /** Authentication type requested */
 typedef enum {
 	/* git_cred_userpass_plaintext */
@@ -69,14 +61,20 @@ typedef struct {
 	char *password;
 } git_cred_userpass_plaintext;
 
-#ifdef GIT_SSH
-typedef LIBSSH2_USERAUTH_PUBLICKEY_SIGN_FUNC((*git_cred_sign_callback));
-typedef LIBSSH2_USERAUTH_KBDINT_RESPONSE_FUNC((*git_cred_ssh_interactive_callback));
-#else
-typedef int (*git_cred_sign_callback)(void *, ...);
-typedef int (*git_cred_ssh_interactive_callback)(void *, ...);
+
+/*
+ * If the user hasn't included libssh2.h before git2.h, we need to
+ * define a few types for the callback signatures.
+ */
+#ifndef LIBSSH2_VERSION
+typedef struct _LIBSSH2_SESSION LIBSSH2_SESSION;
+typedef struct _LIBSSH2_USERAUTH_KBDINT_PROMPT LIBSSH2_USERAUTH_KBDINT_PROMPT;
+typedef struct _LIBSSH2_USERAUTH_KBDINT_RESPONSE LIBSSH2_USERAUTH_KBDINT_RESPONSE;
 #endif
 
+typedef int (*git_cred_sign_callback)(LIBSSH2_SESSION *session, unsigned char **sig, size_t *sig_len, const unsigned char *data, size_t data_len, void **abstract);
+typedef void (*git_cred_ssh_interactive_callback)(const char* name, int name_len, const char* instruction, int instruction_len, int num_prompts, const LIBSSH2_USERAUTH_KBDINT_PROMPT* prompts, LIBSSH2_USERAUTH_KBDINT_RESPONSE* responses, void **abstract);
+
 /**
  * A ssh key from disk
  */
@@ -247,319 +245,6 @@ typedef int (*git_cred_acquire_cb)(
 	unsigned int allowed_types,
 	void *payload);
 
-/*
- *** End interface for credentials acquisition ***
- *** Begin base transport interface ***
- */
-
-typedef enum {
-	GIT_TRANSPORTFLAGS_NONE = 0,
-	/* If the connection is secured with SSL/TLS, the authenticity
-	 * of the server certificate should not be verified. */
-	GIT_TRANSPORTFLAGS_NO_CHECK_CERT = 1
-} git_transport_flags_t;
-
-typedef int (*git_transport_message_cb)(const char *str, int len, void *data);
-
-typedef struct git_transport git_transport;
-
-struct git_transport {
-	unsigned int version;
-	/* Set progress and error callbacks */
-	int (*set_callbacks)(
-		git_transport *transport,
-		git_transport_message_cb progress_cb,
-		git_transport_message_cb error_cb,
-		void *payload);
-
-	/* Connect the transport to the remote repository, using the given
-	 * direction. */
-	int (*connect)(
-		git_transport *transport,
-		const char *url,
-		git_cred_acquire_cb cred_acquire_cb,
-		void *cred_acquire_payload,
-		int direction,
-		int flags);
-
-	/* This function may be called after a successful call to
-	 * connect(). The array returned is owned by the transport and
-	 * is guranteed until the next call of a transport function. */
-	int (*ls)(
-		const git_remote_head ***out,
-		size_t *size,
-		git_transport *transport);
-
-	/* Executes the push whose context is in the git_push object. */
-	int (*push)(git_transport *transport, git_push *push);
-
-	/* This function may be called after a successful call to connect(), when
-	 * the direction is FETCH. The function performs a negotiation to calculate
-	 * the wants list for the fetch. */
-	int (*negotiate_fetch)(
-		git_transport *transport,
-		git_repository *repo,
-		const git_remote_head * const *refs,
-		size_t count);
-
-	/* This function may be called after a successful call to negotiate_fetch(),
-	 * when the direction is FETCH. This function retrieves the pack file for
-	 * the fetch from the remote end. */
-	int (*download_pack)(
-		git_transport *transport,
-		git_repository *repo,
-		git_transfer_progress *stats,
-		git_transfer_progress_cb progress_cb,
-		void *progress_payload);
-
-	/* Checks to see if the transport is connected */
-	int (*is_connected)(git_transport *transport);
-
-	/* Reads the flags value previously passed into connect() */
-	int (*read_flags)(git_transport *transport, int *flags);
-
-	/* Cancels any outstanding transport operation */
-	void (*cancel)(git_transport *transport);
-
-	/* This function is the reverse of connect() -- it terminates the
-	 * connection to the remote end. */
-	int (*close)(git_transport *transport);
-
-	/* Frees/destructs the git_transport object. */
-	void (*free)(git_transport *transport);
-};
-
-#define GIT_TRANSPORT_VERSION 1
-#define GIT_TRANSPORT_INIT {GIT_TRANSPORT_VERSION}
-
-/**
- * Initializes a `git_transport` with default values. Equivalent to
- * creating an instance with GIT_TRANSPORT_INIT.
- *
- * @param opts the `git_transport` struct to initialize
- * @param version Version of struct; pass `GIT_TRANSPORT_VERSION`
- * @return Zero on success; -1 on failure.
- */
-GIT_EXTERN(int) git_transport_init(
-	git_transport *opts,
-	unsigned int version);
-
-/**
- * Function to use to create a transport from a URL. The transport database
- * is scanned to find a transport that implements the scheme of the URI (i.e.
- * git:// or http://) and a transport object is returned to the caller.
- *
- * @param out The newly created transport (out)
- * @param owner The git_remote which will own this transport
- * @param url The URL to connect to
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_transport_new(git_transport **out, git_remote *owner, const char *url);
-
-/* Signature of a function which creates a transport */
-typedef int (*git_transport_cb)(git_transport **out, git_remote *owner, void *param);
-
-/**
- * Add a custom transport definition, to be used in addition to the built-in
- * set of transports that come with libgit2.
- *
- * The caller is responsible for synchronizing calls to git_transport_register
- * and git_transport_unregister with other calls to the library that
- * instantiate transports.
- *
- * @param prefix The scheme (ending in "://") to match, i.e. "git://"
- * @param priority The priority of this transport relative to others with
- *		the same prefix. Built-in transports have a priority of 1.
- * @param cb The callback used to create an instance of the transport
- * @param param A fixed parameter to pass to cb at creation time
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_transport_register(
-	const char *prefix,
-	unsigned priority,
-	git_transport_cb cb,
-	void *param);
-
-/**
- *
- * Unregister a custom transport definition which was previously registered
- * with git_transport_register.
- *
- * @param prefix From the previous call to git_transport_register
- * @param priority From the previous call to git_transport_register
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_transport_unregister(
-	const char *prefix,
-	unsigned priority);
-
-/* Transports which come with libgit2 (match git_transport_cb). The expected
- * value for "param" is listed in-line below. */
-
-/**
- * Create an instance of the dummy transport.
- *
- * @param out The newly created transport (out)
- * @param owner The git_remote which will own this transport
- * @param payload You must pass NULL for this parameter.
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_transport_dummy(
-	git_transport **out,
-	git_remote *owner,
-	/* NULL */ void *payload);
-
-/**
- * Create an instance of the local transport.
- *
- * @param out The newly created transport (out)
- * @param owner The git_remote which will own this transport
- * @param payload You must pass NULL for this parameter.
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_transport_local(
-	git_transport **out,
-	git_remote *owner,
-	/* NULL */ void *payload);
-
-/**
- * Create an instance of the smart transport.
- *
- * @param out The newly created transport (out)
- * @param owner The git_remote which will own this transport
- * @param payload A pointer to a git_smart_subtransport_definition
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_transport_smart(
-	git_transport **out,
-	git_remote *owner,
-	/* (git_smart_subtransport_definition *) */ void *payload);
-
-/*
- *** End of base transport interface ***
- *** Begin interface for subtransports for the smart transport ***
- */
-
-/* The smart transport knows how to speak the git protocol, but it has no
- * knowledge of how to establish a connection between it and another endpoint,
- * or how to move data back and forth. For this, a subtransport interface is
- * declared, and the smart transport delegates this work to the subtransports.
- * Three subtransports are implemented: git, http, and winhttp. (The http and
- * winhttp transports each implement both http and https.) */
-
-/* Subtransports can either be RPC = 0 (persistent connection) or RPC = 1
- * (request/response). The smart transport handles the differences in its own
- * logic. The git subtransport is RPC = 0, while http and winhttp are both
- * RPC = 1. */
-
-/* Actions that the smart transport can ask
- * a subtransport to perform */
-typedef enum {
-	GIT_SERVICE_UPLOADPACK_LS = 1,
-	GIT_SERVICE_UPLOADPACK = 2,
-	GIT_SERVICE_RECEIVEPACK_LS = 3,
-	GIT_SERVICE_RECEIVEPACK = 4,
-} git_smart_service_t;
-
-typedef struct git_smart_subtransport git_smart_subtransport;
-typedef struct git_smart_subtransport_stream git_smart_subtransport_stream;
-
-/* A stream used by the smart transport to read and write data
- * from a subtransport */
-struct git_smart_subtransport_stream {
-	/* The owning subtransport */
-	git_smart_subtransport *subtransport;
-
-	int (*read)(
-		git_smart_subtransport_stream *stream,
-		char *buffer,
-		size_t buf_size,
-		size_t *bytes_read);
-
-	int (*write)(
-		git_smart_subtransport_stream *stream,
-		const char *buffer,
-		size_t len);
-
-	void (*free)(
-		git_smart_subtransport_stream *stream);
-};
-
-/* An implementation of a subtransport which carries data for the
- * smart transport */
-struct git_smart_subtransport {
-	int (* action)(
-			git_smart_subtransport_stream **out,
-			git_smart_subtransport *transport,
-			const char *url,
-			git_smart_service_t action);
-
-	/* Subtransports are guaranteed a call to close() between
-	 * calls to action(), except for the following two "natural" progressions
-	 * of actions against a constant URL.
-	 *
-	 * 1. UPLOADPACK_LS -> UPLOADPACK
-	 * 2. RECEIVEPACK_LS -> RECEIVEPACK */
-	int (*close)(git_smart_subtransport *transport);
-
-	void (*free)(git_smart_subtransport *transport);
-};
-
-/* A function which creates a new subtransport for the smart transport */
-typedef int (*git_smart_subtransport_cb)(
-	git_smart_subtransport **out,
-	git_transport* owner);
-
-typedef struct git_smart_subtransport_definition {
-	/* The function to use to create the git_smart_subtransport */
-	git_smart_subtransport_cb callback;
-
-	/* True if the protocol is stateless; false otherwise. For example,
-	 * http:// is stateless, but git:// is not. */
-	unsigned rpc;
-} git_smart_subtransport_definition;
-
-/* Smart transport subtransports that come with libgit2 */
-
-/**
- * Create an instance of the http subtransport. This subtransport
- * also supports https. On Win32, this subtransport may be implemented
- * using the WinHTTP library.
- *
- * @param out The newly created subtransport
- * @param owner The smart transport to own this subtransport
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_smart_subtransport_http(
-	git_smart_subtransport **out,
-	git_transport* owner);
-
-/**
- * Create an instance of the git subtransport.
- *
- * @param out The newly created subtransport
- * @param owner The smart transport to own this subtransport
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_smart_subtransport_git(
-	git_smart_subtransport **out,
-	git_transport* owner);
-
-/**
- * Create an instance of the ssh subtransport.
- *
- * @param out The newly created subtransport
- * @param owner The smart transport to own this subtransport
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_smart_subtransport_ssh(
-	git_smart_subtransport **out,
-	git_transport* owner);
-
-/*
- *** End interface for subtransports for the smart transport ***
- */
-
 /** @} */
 GIT_END_DECL
 #endif
diff --git a/include/git2/tree.h b/include/git2/tree.h
index 56922d40b..42b68193e 100644
--- a/include/git2/tree.h
+++ b/include/git2/tree.h
@@ -301,8 +301,10 @@ GIT_EXTERN(const git_tree_entry *) git_treebuilder_get(
  * If an entry named `filename` already exists, its attributes
  * will be updated with the given ones.
  *
- * The optional pointer `out` can be used to retrieve a pointer to
- * the newly created/updated entry.  Pass NULL if you do not need it.
+ * The optional pointer `out` can be used to retrieve a pointer to the
+ * newly created/updated entry.  Pass NULL if you do not need it. The
+ * pointer may not be valid past the next operation in this
+ * builder. Duplicate the entry if you want to keep it.
  *
  * No attempt is being made to ensure that the provided oid points
  * to an existing git object in the object database, nor that the
diff --git a/include/git2/types.h b/include/git2/types.h
index 6295ebbfa..7ed1bcd4c 100644
--- a/include/git2/types.h
+++ b/include/git2/types.h
@@ -198,12 +198,12 @@ typedef enum {
 
 /** Valid modes for index and tree entries. */
 typedef enum {
-	GIT_FILEMODE_NEW					= 0000000,
-	GIT_FILEMODE_TREE					= 0040000,
-	GIT_FILEMODE_BLOB					= 0100644,
-	GIT_FILEMODE_BLOB_EXECUTABLE		= 0100755,
-	GIT_FILEMODE_LINK					= 0120000,
-	GIT_FILEMODE_COMMIT					= 0160000,
+	GIT_FILEMODE_UNREADABLE          = 0000000,
+	GIT_FILEMODE_TREE                = 0040000,
+	GIT_FILEMODE_BLOB                = 0100644,
+	GIT_FILEMODE_BLOB_EXECUTABLE     = 0100755,
+	GIT_FILEMODE_LINK                = 0120000,
+	GIT_FILEMODE_COMMIT              = 0160000,
 } git_filemode_t;
 
 typedef struct git_refspec git_refspec;
@@ -244,6 +244,16 @@ typedef struct git_transfer_progress {
 typedef int (*git_transfer_progress_cb)(const git_transfer_progress *stats, void *payload);
 
 /**
+ * Type for messages delivered by the transport.  Return a negative value
+ * to cancel the network operation.
+ *
+ * @param str The message from the transport
+ * @param len The length of the message
+ * @param payload Payload provided by the caller
+ */
+typedef int (*git_transport_message_cb)(const char *str, int len, void *payload);
+
+/**
  * Opaque structure representing a submodule.
  */
 typedef struct git_submodule git_submodule;