rugged 0.17.0.b7 → 0.18.0.b1

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009-2012 the libgit2 contributors
+ * 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.
@@ -15,32 +15,66 @@
  */
 GIT_BEGIN_DECL
 
+/**
+ * Kinds of reset operation
+ */
+typedef enum {
+	GIT_RESET_SOFT  = 1, /** Move the head to the given commit */
+	GIT_RESET_MIXED = 2, /** SOFT plus reset index to the commit */
+	GIT_RESET_HARD  = 3, /** MIXED plus changes in working tree discarded */
+} git_reset_t;
+
 /**
  * Sets the current head to the specified commit oid and optionally
  * resets the index and working tree to match.
  *
- * When specifying a Soft kind of reset, the head will be moved to the commit.
+ * SOFT reset means the Head will be moved to the commit.
  *
- * Specifying a Mixed kind of reset will trigger a Soft reset and the index will
- * be replaced with the content of the commit tree.
+ * MIXED reset will trigger a SOFT reset, plus the index will be replaced
+ * with the content of the commit tree.
  *
- * Specifying a Hard kind of reset will trigger a Mixed reset and the working
- * directory will be replaced with the content of the index.
+ * HARD reset will trigger a MIXED reset and the working directory will be
+ * replaced with the content of the index.  (Untracked and ignored files
+ * will be left alone, however.)
  *
  * TODO: Implement remaining kinds of resets.
  *
  * @param repo Repository where to perform the reset operation.
  *
- * @param target Object to which the Head should be moved to. This object
+ * @param target Committish to which the Head should be moved to. This object
  * must belong to the given `repo` and can either be a git_commit or a
  * git_tag. When a git_tag is being passed, it should be dereferencable
  * to a git_commit which oid will be used as the target of the branch.
  *
  * @param reset_type Kind of reset operation to perform.
  *
- * @return GIT_SUCCESS or an error code
+ * @return 0 on success or an error code
+ */
+GIT_EXTERN(int) git_reset(
+	git_repository *repo, git_object *target, git_reset_t reset_type);
+
+/**
+ * Updates some entries in the index from the target commit tree.
+ *
+ * The scope of the updated entries is determined by the paths
+ * being passed in the `pathspec` parameters.
+ *
+ * Passing a NULL `target` will result in removing
+ * entries in the index matching the provided pathspecs.
+ *
+ * @param repo Repository where to perform the reset operation.
+ *
+ * @param target The committish which content will be used to reset the content
+ * of the index.
+ *
+ * @param pathspecs List of pathspecs to operate on.
+ *
+ * @return 0 on success or an error code < 0
  */
-GIT_EXTERN(int) git_reset(git_repository *repo, git_object *target, git_reset_type reset_type);
+GIT_EXTERN(int) git_reset_default(
+    git_repository *repo,
+    git_object *target,
+    git_strarray* pathspecs);
 
 /** @} */
 GIT_END_DECL

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2012 the libgit2 contributors
+ * 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.
@@ -21,16 +21,60 @@
 GIT_BEGIN_DECL
 
 /**
- * Find an object, as specified by a revision string. See `man gitrevisions`, or the documentation
- * for `git rev-parse` for information on the syntax accepted.
+ * Find a single object, as specified by a revision string. See `man gitrevisions`,
+ * or http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for
+ * information on the syntax accepted.
  *
  * @param out pointer to output object
  * @param repo the repository to search in
  * @param spec the textual specification for an object
- * @return  on success, GIT_ERROR otherwise (use git_error_last for information about the error)
+ * @return 0 on success, GIT_ENOTFOUND, GIT_EAMBIGUOUS, GIT_EINVALIDSPEC or an error code
  */
 GIT_EXTERN(int) git_revparse_single(git_object **out, git_repository *repo, const char *spec);
 
+
+/**
+ * Revparse flags.  These indicate the intended behavior of the spec passed to
+ * git_revparse.
+ */
+typedef enum {
+	/** The spec targeted a single object. */
+	GIT_REVPARSE_SINGLE         = 1 << 0,
+	/** The spec targeted a range of commits. */
+	GIT_REVPARSE_RANGE          = 1 << 1,
+	/** The spec used the '...' operator, which invokes special semantics. */
+	GIT_REVPARSE_MERGE_BASE     = 1 << 2,
+} git_revparse_mode_t;
+
+/**
+ * Git Revision Spec: output of a `git_revparse` operation
+ */
+typedef struct {
+	/** The left element of the revspec; must be freed by the user */
+	git_object *from;
+	/** The right element of the revspec; must be freed by the user */
+	git_object *to;
+	/** The intent of the revspec */
+	unsigned int flags;
+} git_revspec;
+
+/**
+ * Parse a revision string for `from`, `to`, and intent. See `man gitrevisions` or
+ * http://git-scm.com/docs/git-rev-parse.html#_specifying_revisions for information
+ * on the syntax accepted.
+ *
+ * @param revspec Pointer to an user-allocated git_revspec struct where the result
+ *	of the rev-parse will be stored
+ * @param repo the repository to search in
+ * @param spec the rev-parse spec to parse
+ * @return 0 on success, GIT_INVALIDSPEC, GIT_ENOTFOUND, GIT_EAMBIGUOUS or an error code
+ */
+GIT_EXTERN(int) git_revparse(
+		git_revspec *revspec,
+		git_repository *repo,
+		const char *spec);
+
+
 /** @} */
 GIT_END_DECL
 #endif

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009-2012 the libgit2 contributors
+ * 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.
@@ -63,11 +63,11 @@ GIT_BEGIN_DECL
  * it is possible to have several revision walkers in
  * several different threads walking the same repository.
  *
- * @param walker pointer to the new revision walker
+ * @param out pointer to the new revision walker
  * @param repo the repo to walk through
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_revwalk_new(git_revwalk **walker, git_repository *repo);
+GIT_EXTERN(int) git_revwalk_new(git_revwalk **out, git_repository *repo);
 
 /**
  * Reset the revision walker for reuse.
@@ -92,14 +92,14 @@ GIT_EXTERN(void) git_revwalk_reset(git_revwalk *walker);
  *
  * The given commit will be used as one of the roots
  * when starting the revision walk. At least one commit
- * must be pushed the repository before a walk can
+ * must be pushed onto the walker before a walk can
  * be started.
  *
  * @param walk the walker being used for the traversal.
- * @param oid the oid of the commit to start from.
+ * @param id the oid of the commit to start from.
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *oid);
+GIT_EXTERN(int) git_revwalk_push(git_revwalk *walk, const git_oid *id);
 
 /**
  * Push matching references
@@ -134,10 +134,10 @@ GIT_EXTERN(int) git_revwalk_push_head(git_revwalk *walk);
  * output on the revision walk.
  *
  * @param walk the walker being used for the traversal.
- * @param oid the oid of commit that will be ignored during the traversal
+ * @param commit_id the oid of commit that will be ignored during the traversal
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *oid);
+GIT_EXTERN(int) git_revwalk_hide(git_revwalk *walk, const git_oid *commit_id);
 
 /**
  * Hide matching references.
@@ -198,12 +198,12 @@ GIT_EXTERN(int) git_revwalk_hide_ref(git_revwalk *walk, const char *refname);
  *
  * The revision walker is reset when the walk is over.
  *
- * @param oid Pointer where to store the oid of the next commit
+ * @param out Pointer where to store the oid of the next commit
  * @param walk the walker to pop the commit from.
  * @return 0 if the next commit was found;
  *	GIT_ITEROVER if there are no commits left to iterate
  */
-GIT_EXTERN(int) git_revwalk_next(git_oid *oid, git_revwalk *walk);
+GIT_EXTERN(int) git_revwalk_next(git_oid *out, git_revwalk *walk);
 
 /**
  * Change the sorting mode when iterating through the
@@ -216,6 +216,21 @@ GIT_EXTERN(int) git_revwalk_next(git_oid *oid, git_revwalk *walk);
  */
 GIT_EXTERN(void) git_revwalk_sorting(git_revwalk *walk, unsigned int sort_mode);
 
+/**
+ * Push and hide the respective endpoints of the given range.
+ *
+ * The range should be of the form
+ *   <commit>..<commit>
+ * where each <commit> is in the form accepted by 'git_revparse_single'.
+ * The left-hand commit will be hidden and the right-hand commit pushed.
+ *
+ * @param walk the walker being used for the traversal
+ * @param range the range
+ * @return 0 or an error code
+ *
+ */
+GIT_EXTERN(int) git_revwalk_push_range(git_revwalk *walk, const char *range);
+
 /**
  * Free a revision walker previously allocated.
  *

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009-2012 the libgit2 contributors
+ * 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.
@@ -20,44 +20,52 @@
 GIT_BEGIN_DECL
 
 /**
- * Create a new action signature. The signature must be freed
- * manually or using git_signature_free
+ * Create a new action signature.
+ *
+ * Call `git_signature_free()` to free the data.
  *
  * Note: angle brackets ('<' and '>') characters are not allowed
  * to be used in either the `name` or the `email` parameter.
  *
- * @param sig_out new signature, in case of error NULL
+ * @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
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_signature_new(git_signature **sig_out, const char *name, const char *email, git_time_t time, int offset);
+GIT_EXTERN(int) git_signature_new(git_signature **out, const char *name, const char *email, git_time_t time, int offset);
 
 /**
- * Create a new action signature with a timestamp of 'now'. The
- * signature must be freed manually or using git_signature_free
+ * Create a new action signature with a timestamp of 'now'.
+ *
+ * Call `git_signature_free()` to free the data.
  *
- * @param sig_out new signature, in case of error NULL
+ * @param out new signature, in case of error NULL
  * @param name name of the person
  * @param email email of the person
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_signature_now(git_signature **sig_out, const char *name, const char *email);
+GIT_EXTERN(int) git_signature_now(git_signature **out, const char *name, const char *email);
 
 
 /**
- * Create a copy of an existing signature.
+ * Create a copy of an existing signature.  All internal strings are also
+ * duplicated.
+ *
+ * Call `git_signature_free()` to free the data.
  *
- * All internal strings are also duplicated.
  * @param sig signature to duplicated
  * @return a copy of sig, NULL on out of memory
  */
 GIT_EXTERN(git_signature *) git_signature_dup(const git_signature *sig);
 
 /**
- * Free an existing signature
+ * Free an existing signature.
+ *
+ * Because the signature is not an opaque structure, it is legal to free it
+ * manually, but be sure to free the "name" and "email" strings in addition
+ * to the structure itself.
  *
  * @param sig signature to free
  */

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

@@ -0,0 +1,121 @@
+/*
+ * 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_stash_h__
+#define INCLUDE_git_stash_h__
+
+#include "common.h"
+#include "types.h"
+
+/**
+ * @file git2/stash.h
+ * @brief Git stash management routines
+ * @ingroup Git
+ * @{
+ */
+GIT_BEGIN_DECL
+
+typedef enum {
+	GIT_STASH_DEFAULT = 0,
+
+	/* All changes already added to the index
+	 * are left intact in the working directory
+	 */
+	GIT_STASH_KEEP_INDEX = (1 << 0),
+
+	/* All untracked files are also stashed and then
+	 * cleaned up from the working directory
+	 */
+	GIT_STASH_INCLUDE_UNTRACKED = (1 << 1),
+
+	/* All ignored files are also stashed and then
+	 * cleaned up from the working directory
+	 */
+	GIT_STASH_INCLUDE_IGNORED = (1 << 2),
+} git_stash_flags;
+
+/**
+ * Save the local modifications to a new stash.
+ *
+ * @param out Object id of the commit containing the stashed state.
+ * This commit is also the target of the direct reference refs/stash.
+ *
+ * @param repo The owning repository.
+ *
+ * @param stasher The identity of the person performing the stashing.
+ *
+ * @param message Optional description along with the stashed state.
+ *
+ * @param flags Flags to control the stashing process. (see GIT_STASH_* above)
+ *
+ * @return 0 on success, GIT_ENOTFOUND where there's nothing to stash,
+ * or error code.
+ */
+GIT_EXTERN(int) git_stash_save(
+	git_oid *out,
+	git_repository *repo,
+	git_signature *stasher,
+	const char *message,
+	unsigned int flags);
+
+/**
+ * When iterating over all the stashed states, callback that will be
+ * issued per entry.
+ *
+ * @param index The position within the stash list. 0 points to the
+ * most recent stashed state.
+ *
+ * @param message The stash message.
+ *
+ * @param stash_id The commit oid of the stashed state.
+ *
+ * @param payload Extra parameter to callback function.
+ *
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ */
+typedef int (*git_stash_cb)(
+	size_t index,
+	const char* message,
+	const git_oid *stash_id,
+	void *payload);
+
+/**
+ * Loop over all the stashed states and issue a callback for each one.
+ *
+ * If the callback returns a non-zero value, this will stop looping.
+ *
+ * @param repo Repository where to find the stash.
+ *
+ * @param callabck Callback to invoke per found stashed state. The most recent
+ * stash state will be enumerated first.
+ *
+ * @param payload Extra parameter to callback function.
+ *
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
+ */
+GIT_EXTERN(int) git_stash_foreach(
+	git_repository *repo,
+	git_stash_cb callback,
+	void *payload);
+
+/**
+ * Remove a single stashed state from the stash list.
+ *
+ * @param repo The owning repository.
+ *
+ * @param index The position within the stash list. 0 points to the
+ * most recent stashed state.
+ *
+ * @return 0 on success, or error code
+ */
+
+GIT_EXTERN(int) git_stash_drop(
+	git_repository *repo,
+	size_t index);
+
+/** @} */
+GIT_END_DECL
+#endif

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

@@ -1,5 +1,5 @@
 /*
- * Copyright (C) 2009-2012 the libgit2 contributors
+ * 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.
@@ -19,6 +19,16 @@
  */
 GIT_BEGIN_DECL
 
+/**
+ * Status flags for a single file.
+ *
+ * A combination of these values will be returned to indicate the status of
+ * a file.  Status compares the working directory, the index, and the
+ * current HEAD of the repository.  The `GIT_STATUS_INDEX` set of flags
+ * represents the status of file in the index relative to the HEAD, and the
+ * `GIT_STATUS_WT` set of flags represent the status of the file in the
+ * working directory relative to the index.
+ */
 typedef enum {
 	GIT_STATUS_CURRENT = 0,
 
@@ -36,24 +46,40 @@ typedef enum {
 	GIT_STATUS_IGNORED          = (1u << 14),
 } git_status_t;
 
+/**
+ * Function pointer to receive status on individual files
+ *
+ * `path` is the relative path to the file from the root of the repository.
+ *
+ * `status_flags` is a combination of `git_status_t` values that apply.
+ *
+ * `payload` is the value you passed to the foreach function as payload.
+ */
+typedef int (*git_status_cb)(
+	const char *path, unsigned int status_flags, void *payload);
+
 /**
  * Gather file statuses and run a callback for each one.
  *
- * The callback is passed the path of the file, the status and the data
- * pointer passed to this function. If the callback returns something other
- * than 0, this function will stop looping and return GIT_EUSER.
+ * The callback is passed the path of the file, the status (a combination of
+ * the `git_status_t` values above) and the `payload` data pointer passed
+ * into this function.
  *
- * @param repo a repository object
- * @param callback the function to call on each file
+ * If the callback returns a non-zero value, this function will stop looping
+ * and return GIT_EUSER.
+ *
+ * @param repo A repository object
+ * @param callback The function to call on each file
+ * @param payload Pointer to pass through to callback function
  * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_status_foreach(
 	git_repository *repo,
-	int (*callback)(const char *, unsigned int, void *),
+	git_status_cb callback,
 	void *payload);
 
 /**
- * Select the files on which to report status.
+ * For extended status, select the files on which to report status.
  *
  * - GIT_STATUS_SHOW_INDEX_AND_WORKDIR is the default.  This is the
  *   rough equivalent of `git status --porcelain` where each file
@@ -81,65 +107,108 @@ typedef enum {
 /**
  * Flags to control status callbacks
  *
- * - GIT_STATUS_OPT_INCLUDE_UNTRACKED says that callbacks should
- *   be made on untracked files.  These will only be made if the
- *   workdir files are included in the status "show" option.
- * - GIT_STATUS_OPT_INCLUDE_IGNORED says that ignored files should
- *   get callbacks.  Again, these callbacks will only be made if
- *   the workdir files are included in the status "show" option.
- *   Right now, there is no option to include all files in
- *   directories that are ignored completely.
- * - GIT_STATUS_OPT_INCLUDE_UNMODIFIED indicates that callback
- *   should be made even on unmodified files.
- * - GIT_STATUS_OPT_EXCLUDE_SUBMODULES indicates that directories
- *   which appear to be submodules should just be skipped over.
- * - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS indicates that the
- *   contents of untracked directories should be included in the
- *   status.  Normally if an entire directory is new, then just
- *   the top-level directory will be included (with a trailing
- *   slash on the entry name).  Given this flag, the directory
- *   itself will not be included, but all the files in it will.
- * - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH indicates that the given
- *   path will be treated as a literal path, and not as a pathspec.
+ * - GIT_STATUS_OPT_INCLUDE_UNTRACKED says that callbacks should be made
+ *   on untracked files.  These will only be made if the workdir files are
+ *   included in the status "show" option.
+ * - GIT_STATUS_OPT_INCLUDE_IGNORED says that ignored files should get
+ *   callbacks.  Again, these callbacks will only be made if the workdir
+ *   files are included in the status "show" option.  Right now, there is
+ *   no option to include all files in directories that are ignored
+ *   completely.
+ * - GIT_STATUS_OPT_INCLUDE_UNMODIFIED indicates that callback should be
+ *   made even on unmodified files.
+ * - GIT_STATUS_OPT_EXCLUDE_SUBMODULES indicates that directories which
+ *   appear to be submodules should just be skipped over.
+ * - GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS indicates that the contents of
+ *   untracked directories should be included in the status.  Normally if
+ *   an entire directory is new, then just the top-level directory will be
+ *   included (with a trailing slash on the entry name).  Given this flag,
+ *   the directory itself will not be included, but all the files in it
+ *   will.
+ * - GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH indicates that the given path
+ *   will be treated as a literal path, and not as a pathspec.
+ * - GIT_STATUS_OPT_RECURSE_IGNORED_DIRS indicates that the contents of
+ *   ignored directories should be included in the status.  This is like
+ *   doing `git ls-files -o -i --exclude-standard` with core git.
+ *
+ * Calling `git_status_foreach()` is like calling the extended version
+ * with: GIT_STATUS_OPT_INCLUDE_IGNORED, GIT_STATUS_OPT_INCLUDE_UNTRACKED,
+ * and GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS.  Those options are bundled
+ * 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_t;
 
-enum {
-	GIT_STATUS_OPT_INCLUDE_UNTRACKED = (1 << 0),
-	GIT_STATUS_OPT_INCLUDE_IGNORED = (1 << 1),
-	GIT_STATUS_OPT_INCLUDE_UNMODIFIED = (1 << 2),
-	GIT_STATUS_OPT_EXCLUDE_SUBMODULES = (1 << 3),
-	GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS = (1 << 4),
-	GIT_STATUS_OPT_DISABLE_PATHSPEC_MATCH = (1 << 5),
-};
+#define GIT_STATUS_OPT_DEFAULTS \
+	(GIT_STATUS_OPT_INCLUDE_IGNORED | \
+	GIT_STATUS_OPT_INCLUDE_UNTRACKED | \
+	GIT_STATUS_OPT_RECURSE_UNTRACKED_DIRS)
 
 /**
- * Options to control how callbacks will be made by
- * `git_status_foreach_ext()`.
+ * 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.
+ *
+ * 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.
  */
 typedef struct {
+	unsigned int      version;
 	git_status_show_t show;
-	unsigned int flags;
-	git_strarray pathspec;
+	unsigned int      flags;
+	git_strarray      pathspec;
 } git_status_options;
 
+#define GIT_STATUS_OPTIONS_VERSION 1
+#define GIT_STATUS_OPTIONS_INIT {GIT_STATUS_OPTIONS_VERSION}
+
 /**
  * Gather file status information and run callbacks as requested.
+ *
+ * This is an extended version of the `git_status_foreach()` API that
+ * allows for more granular control over which paths will be processed and
+ * in what order.  See the `git_status_options` structure for details
+ * about the additional controls that this makes available.
+ *
+ * @param repo Repository object
+ * @param opts Status options structure
+ * @param callback The function to call on each file
+ * @param payload Pointer to pass through to callback function
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_status_foreach_ext(
 	git_repository *repo,
 	const git_status_options *opts,
-	int (*callback)(const char *, unsigned int, void *),
+	git_status_cb callback,
 	void *payload);
 
 /**
- * Get file status for a single file
- *
- * @param status_flags the status value
- * @param repo a repository object
- * @param path the file to retrieve status for, rooted at the repo's workdir
- * @return GIT_EINVALIDPATH when `path` points at a folder, GIT_ENOTFOUND when
- *		the file doesn't exist in any of HEAD, the index or the worktree,
- *		0 otherwise
+ * Get file status for a single file.
+ *
+ * This is not quite the same as calling `git_status_foreach_ext()` with
+ * the pathspec set to the specified path.
+ *
+ * @param status_flags The status value for the file
+ * @param repo A repository object
+ * @param path The file to retrieve status for, rooted at the repo's workdir
+ * @return 0 on success, GIT_ENOTFOUND if the file is not found in the HEAD,
+ *      index, and work tree, GIT_EINVALIDPATH if `path` points at a folder,
+ *      GIT_EAMBIGUOUS if "path" matches multiple files, -1 on other error.
  */
 GIT_EXTERN(int) git_status_file(
 	unsigned int *status_flags,
@@ -151,14 +220,14 @@ GIT_EXTERN(int) git_status_file(
  *
  * This function checks the ignore rules to see if they would apply to the
  * given file.  This indicates if the file would be ignored regardless of
- * whether the file is already in the index or commited to the repository.
+ * whether the file is already in the index or committed to the repository.
  *
  * One way to think of this is if you were to do "git add ." on the
  * directory containing the file, would it be added or not?
  *
- * @param ignored boolean returning 0 if the file is not ignored, 1 if it is
- * @param repo a repository object
- * @param path the file to check ignores for, rooted at the repo's workdir.
+ * @param ignored Boolean returning 0 if the file is not ignored, 1 if it is
+ * @param repo A repository object
+ * @param path The file to check ignores for, rooted at the repo's workdir.
  * @return 0 if ignore rules could be processed for the file (regardless
  *         of whether it exists or not), or an error < 0 if they could not.
  */