rugged 0.27.7 → 0.27.10

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

@@ -41,6 +41,80 @@ GIT_EXTERN(int) git_remote_create(
 		const char *name,
 		const char *url);
 
+/**
+ * Remote creation options flags
+ */
+typedef enum {
+	/** Ignore the repository apply.insteadOf configuration */
+	GIT_REMOTE_CREATE_SKIP_INSTEADOF = (1 << 0),
+
+	/** Don't build a fetchspec from the name if none is set */
+	GIT_REMOTE_CREATE_SKIP_DEFAULT_FETCHSPEC = (1 << 1),
+} git_remote_create_flags;
+
+/**
+ * Remote creation options structure
+ *
+ * Initialize with `GIT_REMOTE_CREATE_OPTIONS_INIT`. Alternatively, you can
+ * use `git_remote_create_options_init`.
+ *
+ */
+typedef struct git_remote_create_options {
+	unsigned int version;
+
+	/**
+	 * The repository that should own the remote.
+	 * Setting this to NULL results in a detached remote.
+	 */
+	git_repository *repository;
+
+	/**
+	 * The remote's name.
+	 * Setting this to NULL results in an in-memory/anonymous remote.
+	 */
+	const char *name;
+
+	/** The fetchspec the remote should use. */
+	const char *fetchspec;
+
+	/** Additional flags for the remote. See git_remote_create_flags. */
+	unsigned int flags;
+} git_remote_create_options;
+
+#define GIT_REMOTE_CREATE_OPTIONS_VERSION 1
+#define GIT_REMOTE_CREATE_OPTIONS_INIT {GIT_REMOTE_CREATE_OPTIONS_VERSION}
+
+/**
+ * Initialize git_remote_create_options structure
+ *
+ * Initializes a `git_remote_create_options` with default values. Equivalent to
+ * creating an instance with `GIT_REMOTE_CREATE_OPTIONS_INIT`.
+ *
+ * @param opts The `git_remote_create_options` struct to initialize.
+ * @param version The struct version; pass `GIT_REMOTE_CREATE_OPTIONS_VERSION`.
+ * @return Zero on success; -1 on failure.
+ */
+GIT_EXTERN(int) git_remote_create_options_init(
+		git_remote_create_options *opts,
+		unsigned int version);
+
+/**
+ * Create a remote, with options.
+ *
+ * This function allows more fine-grained control over the remote creation.
+ *
+ * Passing NULL as the opts argument will result in a detached remote.
+ *
+ * @param out the resulting remote
+ * @param url the remote's url
+ * @param opts the remote creation options
+ * @return 0, GIT_EINVALIDSPEC, GIT_EEXISTS or an error code
+ */
+GIT_EXTERN(int) git_remote_create_with_opts(
+		git_remote **out,
+		const char *url,
+		const git_remote_create_options *opts);
+
 /**
  * Add a remote with the provided fetch refspec (or default if NULL) to the repository's
  * configuration.
@@ -341,18 +415,19 @@ GIT_EXTERN(int) git_remote_list(git_strarray *out, git_repository *repo);
  * Argument to the completion callback which tells it which operation
  * finished.
  */
-typedef enum git_remote_completion_type {
+typedef enum git_remote_completion_t {
 	GIT_REMOTE_COMPLETION_DOWNLOAD,
 	GIT_REMOTE_COMPLETION_INDEXING,
 	GIT_REMOTE_COMPLETION_ERROR,
-} git_remote_completion_type;
+} git_remote_completion_t;
 
 /** Push network progress notification function */
-typedef int (*git_push_transfer_progress)(
+typedef int GIT_CALLBACK(git_push_transfer_progress_cb)(
 	unsigned int current,
 	unsigned int total,
 	size_t bytes,
 	void* payload);
+
 /**
  * Represents an update which will be performed on the remote during push
  */
@@ -383,7 +458,7 @@ typedef struct {
  * @param len number of elements in `updates`
  * @param payload Payload provided by the caller
  */
-typedef int (*git_push_negotiation)(const git_push_update **updates, size_t len, void *payload);
+typedef int GIT_CALLBACK(git_push_negotiation)(const git_push_update **updates, size_t len, void *payload);
 
 /**
  * Callback used to inform of the update status from the remote.
@@ -397,7 +472,21 @@ typedef int (*git_push_negotiation)(const git_push_update **updates, size_t len,
  * @param data data provided by the caller
  * @return 0 on success, otherwise an error
  */
-typedef int (*git_push_update_reference_cb)(const char *refname, const char *status, void *data);
+typedef int GIT_CALLBACK(git_push_update_reference_cb)(const char *refname, const char *status, void *data);
+
+/**
+ * Callback to resolve URLs before connecting to remote
+ *
+ * If you return GIT_PASSTHROUGH, you don't need to write anything to
+ * url_resolved.
+ *
+ * @param url_resolved The buffer to write the resolved URL to
+ * @param url The URL to resolve
+ * @param direction GIT_DIRECTION_FETCH or GIT_DIRECTION_PUSH
+ * @param payload Payload provided by the caller
+ * @return 0 on success, GIT_PASSTHROUGH or an error
+ */
+typedef int GIT_CALLBACK(git_url_resolve_cb)(git_buf *url_resolved, const char *url, int direction, void *payload);
 
 /**
  * The callback settings structure
@@ -406,7 +495,8 @@ typedef int (*git_push_update_reference_cb)(const char *refname, const char *sta
  * about the progress of the network operations.
  */
 struct git_remote_callbacks {
-	unsigned int version;
+	unsigned int version; /**< The version */
+
 	/**
 	 * Textual progress from the remote. Text send over the
 	 * progress side-band will be passed to this function (this is
@@ -418,7 +508,7 @@ struct git_remote_callbacks {
 	 * Completion is called when different parts of the download
 	 * process are done (currently unused).
 	 */
-	int (*completion)(git_remote_completion_type type, void *data);
+	int GIT_CALLBACK(completion)(git_remote_completion_t type, void *data);
 
 	/**
 	 * This will be called if the remote host requires
@@ -442,13 +532,13 @@ struct git_remote_callbacks {
 	 * called with the current count of progress done by the
 	 * indexer.
 	 */
-	git_transfer_progress_cb transfer_progress;
+	git_indexer_progress_cb transfer_progress;
 
 	/**
 	 * Each time a reference is updated locally, this function
 	 * will be called with information about it.
 	 */
-	int (*update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data);
+	int GIT_CALLBACK(update_tips)(const char *refname, const git_oid *a, const git_oid *b, void *data);
 
 	/**
 	 * Function to call with progress information during pack
@@ -463,7 +553,7 @@ struct git_remote_callbacks {
 	 * inline with pack building operations, so performance may be
 	 * affected.
 	 */
-	git_push_transfer_progress push_transfer_progress;
+	git_push_transfer_progress_cb push_transfer_progress;
 
 	/**
 	 * See documentation of git_push_update_reference_cb
@@ -487,6 +577,12 @@ struct git_remote_callbacks {
 	 * as the last parameter.
 	 */
 	void *payload;
+
+	/**
+	 * Resolve URL before connecting to remote.
+	 * The returned URL will be used to connect to the remote instead.
+	 */
+	git_url_resolve_cb resolve_url;
 };
 
 #define GIT_REMOTE_CALLBACKS_VERSION 1
@@ -504,6 +600,7 @@ GIT_EXTERN(int) git_remote_init_callbacks(
 	git_remote_callbacks *opts,
 	unsigned int version);
 
+/** Acceptable prune settings when fetching */
 typedef enum {
 	/**
 	 * Use the setting from the configuration
@@ -605,7 +702,7 @@ typedef struct {
  * @param version The struct version; pass `GIT_FETCH_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_fetch_init_options(
+GIT_EXTERN(int) git_fetch_options_init(
 	git_fetch_options *opts,
 	unsigned int version);
 
@@ -643,7 +740,7 @@ typedef struct {
 } git_push_options;
 
 #define GIT_PUSH_OPTIONS_VERSION 1
-#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 0, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
+#define GIT_PUSH_OPTIONS_INIT { GIT_PUSH_OPTIONS_VERSION, 1, GIT_REMOTE_CALLBACKS_INIT, GIT_PROXY_OPTIONS_INIT }
 
 /**
  * Initialize git_push_options structure
@@ -655,7 +752,7 @@ typedef struct {
  * @param version The struct version; pass `GIT_PUSH_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_push_init_options(
+GIT_EXTERN(int) git_push_options_init(
 	git_push_options *opts,
 	unsigned int version);
 
@@ -758,7 +855,7 @@ GIT_EXTERN(int) git_remote_push(git_remote *remote,
 /**
  * Get the statistics structure that is filled in by the fetch operation.
  */
-GIT_EXTERN(const git_transfer_progress *) git_remote_stats(git_remote *remote);
+GIT_EXTERN(const git_indexer_progress *) git_remote_stats(git_remote *remote);
 
 /**
  * Retrieve the tag auto-follow setting

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

@@ -94,40 +94,53 @@ GIT_EXTERN(int) git_repository_discover(
 
 /**
  * Option flags for `git_repository_open_ext`.
- *
- * * GIT_REPOSITORY_OPEN_NO_SEARCH - Only open the repository if it can be
- *   immediately found in the start_path.  Do not walk up from the
- *   start_path looking at parent directories.
- * * GIT_REPOSITORY_OPEN_CROSS_FS - Unless this flag is set, open will not
- *   continue searching across filesystem boundaries (i.e. when `st_dev`
- *   changes from the `stat` system call).  (E.g. Searching in a user's home
- *   directory "/home/user/source/" will not return "/.git/" as the found
- *   repo if "/" is a different filesystem than "/home".)
- * * GIT_REPOSITORY_OPEN_BARE - Open repository as a bare repo regardless
- *   of core.bare config, and defer loading config file for faster setup.
- *   Unlike `git_repository_open_bare`, this can follow gitlinks.
- * * GIT_REPOSITORY_OPEN_NO_DOTGIT - Do not check for a repository by
- *   appending /.git to the start_path; only open the repository if
- *   start_path itself points to the git directory.
- * * GIT_REPOSITORY_OPEN_FROM_ENV - Find and open a git repository,
- *   respecting the environment variables used by the git command-line
- *   tools. If set, `git_repository_open_ext` will ignore the other
- *   flags and the `ceiling_dirs` argument, and will allow a NULL `path`
- *   to use `GIT_DIR` or search from the current directory. The search
- *   for a repository will respect $GIT_CEILING_DIRECTORIES and
- *   $GIT_DISCOVERY_ACROSS_FILESYSTEM.  The opened repository will
- *   respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and
- *   $GIT_ALTERNATE_OBJECT_DIRECTORIES.  In the future, this flag will
- *   also cause `git_repository_open_ext` to respect $GIT_WORK_TREE and
- *   $GIT_COMMON_DIR; currently, `git_repository_open_ext` with this
- *   flag will error out if either $GIT_WORK_TREE or $GIT_COMMON_DIR is
- *   set.
  */
 typedef enum {
+	/**
+	 * Only open the repository if it can be immediately found in the
+	 * start_path. Do not walk up from the start_path looking at parent
+	 * directories.
+	 */
 	GIT_REPOSITORY_OPEN_NO_SEARCH = (1 << 0),
+
+	/**
+	 * Unless this flag is set, open will not continue searching across
+	 * filesystem boundaries (i.e. when `st_dev` changes from the `stat`
+	 * system call).  For example, searching in a user's home directory at
+	 * "/home/user/source/" will not return "/.git/" as the found repo if
+	 * "/" is a different filesystem than "/home".
+	 */
 	GIT_REPOSITORY_OPEN_CROSS_FS  = (1 << 1),
+
+	/**
+	 * Open repository as a bare repo regardless of core.bare config, and
+	 * defer loading config file for faster setup.
+	 * Unlike `git_repository_open_bare`, this can follow gitlinks.
+	 */
 	GIT_REPOSITORY_OPEN_BARE      = (1 << 2),
+
+	/**
+	 * Do not check for a repository by appending /.git to the start_path;
+	 * only open the repository if start_path itself points to the git
+	 * directory.
+	 */
 	GIT_REPOSITORY_OPEN_NO_DOTGIT = (1 << 3),
+
+	/**
+	 * Find and open a git repository, respecting the environment variables
+	 * used by the git command-line tools.
+	 * If set, `git_repository_open_ext` will ignore the other flags and
+	 * the `ceiling_dirs` argument, and will allow a NULL `path` to use
+	 * `GIT_DIR` or search from the current directory.
+	 * The search for a repository will respect $GIT_CEILING_DIRECTORIES and
+	 * $GIT_DISCOVERY_ACROSS_FILESYSTEM.  The opened repository will
+	 * respect $GIT_INDEX_FILE, $GIT_NAMESPACE, $GIT_OBJECT_DIRECTORY, and
+	 * $GIT_ALTERNATE_OBJECT_DIRECTORIES.
+	 * In the future, this flag will also cause `git_repository_open_ext`
+	 * to respect $GIT_WORK_TREE and $GIT_COMMON_DIR; currently,
+	 * `git_repository_open_ext` with this flag will error out if either
+	 * $GIT_WORK_TREE or $GIT_COMMON_DIR is set.
+	 */
 	GIT_REPOSITORY_OPEN_FROM_ENV  = (1 << 4),
 } git_repository_open_flag_t;
 
@@ -310,7 +323,7 @@ typedef struct {
  * @param version The struct version; pass `GIT_REPOSITORY_INIT_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_repository_init_init_options(
+GIT_EXTERN(int) git_repository_init_options_init(
 	git_repository_init_options *opts,
 	unsigned int version);
 
@@ -425,7 +438,8 @@ typedef enum {
 	GIT_REPOSITORY_ITEM_HOOKS,
 	GIT_REPOSITORY_ITEM_LOGS,
 	GIT_REPOSITORY_ITEM_MODULES,
-	GIT_REPOSITORY_ITEM_WORKTREES
+	GIT_REPOSITORY_ITEM_WORKTREES,
+	GIT_REPOSITORY_ITEM__LAST
 } git_repository_item_t;
 
 /**
@@ -627,7 +641,19 @@ GIT_EXTERN(int) git_repository_message_remove(git_repository *repo);
  */
 GIT_EXTERN(int) git_repository_state_cleanup(git_repository *repo);
 
-typedef int (*git_repository_fetchhead_foreach_cb)(const char *ref_name,
+/**
+ * Callback used to iterate over each FETCH_HEAD entry
+ *
+ * @see git_repository_fetchhead_foreach
+ *
+ * @param ref_name The reference name
+ * @param remote_url The remote URL
+ * @param oid The reference target OID
+ * @param is_merge Was the reference the result of a merge
+ * @param payload Payload passed to git_repository_fetchhead_foreach
+ * @return non-zero to terminate the iteration
+ */
+typedef int GIT_CALLBACK(git_repository_fetchhead_foreach_cb)(const char *ref_name,
 	const char *remote_url,
 	const git_oid *oid,
 	unsigned int is_merge,
@@ -649,7 +675,16 @@ GIT_EXTERN(int) git_repository_fetchhead_foreach(
 	git_repository_fetchhead_foreach_cb callback,
 	void *payload);
 
-typedef int (*git_repository_mergehead_foreach_cb)(const git_oid *oid,
+/**
+ * Callback used to iterate over each MERGE_HEAD entry
+ *
+ * @see git_repository_mergehead_foreach
+ *
+ * @param oid The merge OID
+ * @param payload Payload passed to git_repository_mergehead_foreach
+ * @return non-zero to terminate the iteration
+ */
+typedef int GIT_CALLBACK(git_repository_mergehead_foreach_cb)(const git_oid *oid,
 	void *payload);
 
 /**
@@ -685,7 +720,7 @@ GIT_EXTERN(int) git_repository_mergehead_foreach(
  * @param repo Repository pointer
  * @param path Path to file on disk whose contents should be hashed. If the
  *             repository is not NULL, this can be a relative path.
- * @param type The object type to hash as (e.g. GIT_OBJ_BLOB)
+ * @param type The object type to hash as (e.g. GIT_OBJECT_BLOB)
  * @param as_path The path to use to look up filtering rules. If this is
  *             NULL, then the `path` parameter will be used instead. If
  *             this is passed as the empty string, then no filters will be
@@ -696,7 +731,7 @@ GIT_EXTERN(int) git_repository_hashfile(
 	git_oid *out,
 	git_repository *repo,
 	const char *path,
-	git_otype type,
+	git_object_t type,
 	const char *as_path);
 
 /**

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

@@ -46,7 +46,7 @@ typedef struct {
  * @param version The struct version; pass `GIT_REVERT_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_revert_init_options(
+GIT_EXTERN(int) git_revert_options_init(
 	git_revert_options *opts,
 	unsigned int version);
 

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

@@ -25,15 +25,15 @@ GIT_BEGIN_DECL
  */
 typedef enum {
 	/**
-	 * Sort the output with the same default time-order method from git.
-	 * This is the default sorting for new walkers.
+	 * Sort the output with the same default method from `git`: reverse
+	 * chronological order. This is the default sorting for new walkers.
 	 */
 	GIT_SORT_NONE = 0,
 
 	/**
-	 * Sort the repository contents in topological order (parents before
-	 * children); this sorting mode can be combined with time sorting to
-	 * produce git's "time-order".
+	 * Sort the repository contents in topological order (no parents before
+	 * all of its children are shown); this sorting mode can be combined
+	 * with time sorting to produce `git`'s `--date-order``.
 	 */
 	GIT_SORT_TOPOLOGICAL = 1 << 0,
 
@@ -274,12 +274,12 @@ GIT_EXTERN(git_repository *) git_revwalk_repository(git_revwalk *walk);
  * @param commit_id oid of Commit
  * @param payload User-specified pointer to data to be passed as data payload
  */
-typedef int(*git_revwalk_hide_cb)(
+typedef int GIT_CALLBACK(git_revwalk_hide_cb)(
 	const git_oid *commit_id,
 	void *payload);
 
 /**
- * Adds a callback function to hide a commit and its parents
+ * Adds, changes or removes a callback function to hide a commit and its parents
  *
  * @param walk the revision walker
  * @param hide_cb  callback function to hide a commit and its parents

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

@@ -30,8 +30,8 @@ GIT_BEGIN_DECL
  * @param out new signature, in case of error NULL
  * @param name name of the person
  * @param email email of the person
- * @param time time when the action happened
- * @param offset timezone offset in minutes for the time
+ * @param time time (in seconds from epoch) when the action happened
+ * @param offset timezone offset (in minutes) for the time
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset);

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

@@ -112,7 +112,7 @@ typedef enum {
  * Return 0 to continue processing, or a negative value to
  * abort the stash application.
  */
-typedef int (*git_stash_apply_progress_cb)(
+typedef int GIT_CALLBACK(git_stash_apply_progress_cb)(
 	git_stash_apply_progress_t progress,
 	void *payload);
 
@@ -120,14 +120,14 @@ typedef int (*git_stash_apply_progress_cb)(
  * Stash application options structure
  *
  * Initialize with `GIT_STASH_APPLY_OPTIONS_INIT`. Alternatively, you can
- * use `git_stash_apply_init_options`.
+ * use `git_stash_apply_options_init`.
  *
  */
 typedef struct git_stash_apply_options {
 	unsigned int version;
 
 	/** See `git_stash_apply_flags_t`, above. */
-	git_stash_apply_flags flags;
+	uint32_t flags;
 
 	/** Options to use when writing files to the working directory. */
 	git_checkout_options checkout_options;
@@ -153,7 +153,7 @@ typedef struct git_stash_apply_options {
  * @param version The struct version; pass `GIT_STASH_APPLY_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_stash_apply_init_options(
+GIT_EXTERN(int) git_stash_apply_options_init(
 	git_stash_apply_options *opts, unsigned int version);
 
 /**
@@ -198,7 +198,7 @@ GIT_EXTERN(int) git_stash_apply(
  * @param payload Extra parameter to callback function.
  * @return 0 to continue iterating or non-zero to stop.
  */
-typedef int (*git_stash_cb)(
+typedef int GIT_CALLBACK(git_stash_cb)(
 	size_t index,
 	const char* message,
 	const git_oid *stash_id,

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

@@ -60,7 +60,7 @@ typedef enum {
  *
  * `payload` is the value you passed to the foreach function as payload.
  */
-typedef int (*git_status_cb)(
+typedef int GIT_CALLBACK(git_status_cb)(
 	const char *path, unsigned int status_flags, void *payload);
 
 /**
@@ -163,27 +163,36 @@ typedef enum {
 /**
  * Options to control how `git_status_foreach_ext()` will issue callbacks.
  *
- * This structure is set so that zeroing it out will give you relatively
- * sane defaults.
+ * Initialize with `GIT_STATUS_OPTIONS_INIT`. Alternatively, you can
+ * use `git_status_options_init`.
  *
- * The `show` value is one of the `git_status_show_t` constants that
- * control which files to scan and in what order.
- *
- * The `flags` value is an OR'ed combination of the `git_status_opt_t`
- * values above.
- *
- * The `pathspec` is an array of path patterns to match (using
- * fnmatch-style matching), or just an array of paths to match exactly if
- * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
- *
- * The `baseline` is the tree to be used for comparison to the working directory
- * and index; defaults to HEAD.
  */
 typedef struct {
-	unsigned int      version;
+	unsigned int      version; /**< The version */
+
+	/**
+	 * The `show` value is one of the `git_status_show_t` constants that
+	 * control which files to scan and in what order.
+	 */
 	git_status_show_t show;
+
+	/**
+	 * The `flags` value is an OR'ed combination of the `git_status_opt_t`
+	 * values above.
+	 */
 	unsigned int      flags;
+
+	/**
+	 * The `pathspec` is an array of path patterns to match (using
+	 * fnmatch-style matching), or just an array of paths to match exactly if
+	 * `GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH` is specified in the flags.
+	 */
 	git_strarray      pathspec;
+
+	/**
+	 * The `baseline` is the tree to be used for comparison to the working directory
+	 * and index; defaults to HEAD.
+	 */
 	git_tree          *baseline;
 } git_status_options;
 
@@ -200,7 +209,7 @@ typedef struct {
  * @param version The struct version; pass `GIT_STATUS_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_status_init_options(
+GIT_EXTERN(int) git_status_options_init(
 	git_status_options *opts,
 	unsigned int version);
 

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

@@ -115,14 +115,14 @@ typedef enum {
  * @param payload value you passed to the foreach function as payload
  * @return 0 on success or error code
  */
-typedef int (*git_submodule_cb)(
+typedef int GIT_CALLBACK(git_submodule_cb)(
 	git_submodule *sm, const char *name, void *payload);
 
 /**
  * Submodule update options structure
  *
  * Initialize with `GIT_SUBMODULE_UPDATE_OPTIONS_INIT`. Alternatively, you can
- * use `git_submodule_update_init_options`.
+ * use `git_submodule_update_options_init`.
  *
  */
 typedef struct git_submodule_update_options {
@@ -133,7 +133,7 @@ typedef struct git_submodule_update_options {
 	 * checkout, set the `checkout_strategy` to
 	 * `GIT_CHECKOUT_NONE`. Generally you will want the use
 	 * GIT_CHECKOUT_SAFE to update files in the working
-	 * directory. 
+	 * directory.
 	 */
 	git_checkout_options checkout_opts;
 
@@ -168,7 +168,7 @@ typedef struct git_submodule_update_options {
  * @param version The struct version; pass `GIT_SUBMODULE_UPDATE_OPTIONS_VERSION`.
  * @return Zero on success; -1 on failure.
  */
-GIT_EXTERN(int) git_submodule_update_init_options(
+GIT_EXTERN(int) git_submodule_update_options_init(
 	git_submodule_update_options *opts, unsigned int version);
 
 /**
@@ -187,7 +187,7 @@ GIT_EXTERN(int) git_submodule_update_init_options(
  *        function works as though GIT_SUBMODULE_UPDATE_OPTIONS_INIT was passed.
  * @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_error_last` for a detailed error message).
  */
 GIT_EXTERN(int) git_submodule_update(git_submodule *submodule, int init, git_submodule_update_options *options);
 
@@ -263,7 +263,8 @@ GIT_EXTERN(int) git_submodule_foreach(
  * from the working directory to the new repo.
  *
  * To fully emulate "git submodule add" call this function, then open the
- * submodule repo and perform the clone step as needed.  Lastly, call
+ * submodule repo and perform the clone step as needed (if you don't need
+ * anything custom see `git_submodule_add_clone()`). Lastly, call
  * `git_submodule_add_finalize()` to wrap up adding the new submodule and
  * .gitmodules to the index to be ready to commit.
  *
@@ -285,6 +286,22 @@ GIT_EXTERN(int) git_submodule_add_setup(
 	const char *path,
 	int use_gitlink);
 
+/**
+ * Perform the clone step for a newly created submodule.
+ *
+ * This performs the necessary `git_clone` to setup a newly-created submodule.
+ *
+ * @param out The newly created repository object. Optional.
+ * @param submodule The submodule currently waiting for its clone.
+ * @param opts The options to use.
+ *
+ * @return 0 on success, -1 on other errors (see git_clone).
+ */
+GIT_EXTERN(int) git_submodule_clone(
+	git_repository **out,
+	git_submodule *submodule,
+	const git_submodule_update_options *opts);
+
 /**
  * Resolve the setup of a new git submodule.
  *