rugged 0.17.0.b7 → 0.18.0.b1

data/vendor/libgit2/include/git2/reflog.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.
@@ -30,11 +30,11 @@ GIT_BEGIN_DECL
  * The reflog must be freed manually by using
  * git_reflog_free().
  *
- * @param reflog pointer to reflog
+ * @param out pointer to reflog
  * @param ref reference to read the reflog for
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reflog_read(git_reflog **reflog, git_reference *ref);
+GIT_EXTERN(int) git_reflog_read(git_reflog **out, const git_reference *ref);
 
 /**
  * Write an existing in-memory reflog object back to disk
@@ -51,23 +51,26 @@ GIT_EXTERN(int) git_reflog_write(git_reflog *reflog);
  * `msg` is optional and can be NULL.
  *
  * @param reflog an existing reflog object
- * @param new_oid the OID the reference is now pointing to
+ * @param id the OID the reference is now pointing to
  * @param committer the signature of the committer
  * @param msg the reflog message
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *new_oid, const git_signature *committer, const char *msg);
+GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const git_signature *committer, const char *msg);
 
 /**
  * Rename the reflog for the given reference
  *
  * The reflog to be renamed is expected to already exist
  *
+ * The new name will be checked for validity.
+ * See `git_reference_create_symbolic()` for rules about valid names.
+ *
  * @param ref the reference
- * @param new_name the new name of the reference
- * @return 0 or an error code
+ * @param name the new name of the reference
+ * @return 0 on success, GIT_EINVALIDSPEC or an error code
  */
-GIT_EXTERN(int) git_reflog_rename(git_reference *ref, const char *new_name);
+GIT_EXTERN(int) git_reflog_rename(git_reference *ref, const char *name);
 
 /**
  * Delete the reflog for the given reference
@@ -83,13 +86,17 @@ GIT_EXTERN(int) git_reflog_delete(git_reference *ref);
  * @param reflog the previously loaded reflog
  * @return the number of log entries
  */
-GIT_EXTERN(unsigned int) git_reflog_entrycount(git_reflog *reflog);
+GIT_EXTERN(size_t) git_reflog_entrycount(git_reflog *reflog);
 
 /**
  * Lookup an entry by its index
  *
+ * Requesting the reflog entry with an index of 0 (zero) will
+ * return the most recently created entry.
+ *
  * @param reflog a previously loaded reflog
- * @param idx the position to lookup
+ * @param idx the position of the entry to lookup. Should be greater than or
+ * equal to 0 (zero) and less than `git_reflog_entrycount()`.
  * @return the entry; NULL if not found
  */
 GIT_EXTERN(const git_reflog_entry *) git_reflog_entry_byindex(git_reflog *reflog, size_t idx);
@@ -97,21 +104,23 @@ GIT_EXTERN(const git_reflog_entry *) git_reflog_entry_byindex(git_reflog *reflog
 /**
  * Remove an entry from the reflog by its index
  *
- * To ensure there's no gap in the log history, set the `rewrite_previosu_entry` to 1.
- * When deleting entry `n`, member old_oid of entry `n-1` (if any) will be updated with
- * the value of memeber new_oid of entry `n+1`.
+ * To ensure there's no gap in the log history, set `rewrite_previous_entry`
+ * param value to 1. When deleting entry `n`, member old_oid of entry `n-1`
+ * (if any) will be updated with the value of member new_oid of entry `n+1`.
  *
  * @param reflog a previously loaded reflog.
  *
- * @param idx the position of the entry to remove.
+ * @param idx the position of the entry to remove. Should be greater than or
+ * equal to 0 (zero) and less than `git_reflog_entrycount()`.
  *
  * @param rewrite_previous_entry 1 to rewrite the history; 0 otherwise.
  *
- * @return 0 on success or an error code.
+ * @return 0 on success, GIT_ENOTFOUND if the entry doesn't exist
+ * or an error code.
  */
 GIT_EXTERN(int) git_reflog_drop(
 	git_reflog *reflog,
-	unsigned int idx,
+	size_t idx,
 	int rewrite_previous_entry);
 
 /**
@@ -120,7 +129,7 @@ GIT_EXTERN(int) git_reflog_drop(
  * @param entry a reflog entry
  * @return the old oid
  */
-GIT_EXTERN(const git_oid *) git_reflog_entry_oidold(const git_reflog_entry *entry);
+GIT_EXTERN(const git_oid *) git_reflog_entry_id_old(const git_reflog_entry *entry);
 
 /**
  * Get the new oid
@@ -128,7 +137,7 @@ GIT_EXTERN(const git_oid *) git_reflog_entry_oidold(const git_reflog_entry *entr
  * @param entry a reflog entry
  * @return the new oid at this time
  */
-GIT_EXTERN(const git_oid *) git_reflog_entry_oidnew(const git_reflog_entry *entry);
+GIT_EXTERN(const git_oid *) git_reflog_entry_id_new(const git_reflog_entry *entry);
 
 /**
  * Get the committer of this entry
@@ -136,15 +145,15 @@ GIT_EXTERN(const git_oid *) git_reflog_entry_oidnew(const git_reflog_entry *entr
  * @param entry a reflog entry
  * @return the committer
  */
-GIT_EXTERN(git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry);
+GIT_EXTERN(const git_signature *) git_reflog_entry_committer(const git_reflog_entry *entry);
 
 /**
- * Get the log msg
+ * Get the log message
  *
  * @param entry a reflog entry
  * @return the log msg
  */
-GIT_EXTERN(char *) git_reflog_entry_msg(const git_reflog_entry *entry);
+GIT_EXTERN(const char *) git_reflog_entry_message(const git_reflog_entry *entry);
 
 /**
  * Free the reflog

data/vendor/libgit2/include/git2/refs.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.
@@ -22,175 +22,232 @@
 GIT_BEGIN_DECL
 
 /**
- * Lookup a reference by its name in a repository.
+ * Lookup a reference by name in a repository.
  *
- * The generated reference must be freed by the user.
+ * The returned reference must be freed by the user.
  *
- * @param reference_out pointer to the looked-up reference
+ * The name will be checked for validity.
+ * See `git_reference_create_symbolic()` for rules about valid names.
+ *
+ * @param out pointer to the looked-up reference
  * @param repo the repository to look up the reference
- * @param name the long name for the reference (e.g. HEAD, ref/heads/master, refs/tags/v0.1.0, ...)
- * @return 0 or an error code
+ * @param name the long name for the reference (e.g. HEAD, refs/heads/master, refs/tags/v0.1.0, ...)
+ * @return 0 on success, ENOTFOUND, EINVALIDSPEC or an error code.
  */
-GIT_EXTERN(int) git_reference_lookup(git_reference **reference_out, git_repository *repo, const char *name);
+GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, const char *name);
 
 /**
  * Lookup a reference by name and resolve immediately to OID.
  *
- * @param oid Pointer to oid to be filled in
+ * This function provides a quick way to resolve a reference name straight
+ * through to the object id that it refers to.  This avoids having to
+ * allocate or free any `git_reference` objects for simple situations.
+ *
+ * The name will be checked for validity.
+ * See `git_reference_symbolic_create()` for rules about valid names.
+ *
+ * @param out Pointer to oid to be filled in
  * @param repo The repository in which to look up the reference
  * @param name The long name for the reference
- * @return 0 on success, -1 if name could not be resolved
+ * @return 0 on success, ENOTFOUND, EINVALIDSPEC or an error code.
  */
-GIT_EXTERN(int) git_reference_name_to_oid(
+GIT_EXTERN(int) git_reference_name_to_id(
 	git_oid *out, git_repository *repo, const char *name);
 
 /**
  * Create a new symbolic reference.
  *
- * The reference will be created in the repository and written
- * to the disk.
+ * A symbolic reference is a reference name that refers to another
+ * reference name.  If the other name moves, the symbolic name will move,
+ * too.  As a simple example, the "HEAD" reference might refer to
+ * "refs/heads/master" while on the "master" branch of a repository.
  *
- * The generated reference must be freed by the user.
+ * The symbolic reference will be created in the repository and written to
+ * the disk.  The generated reference object must be freed by the user.
  *
- * If `force` is true and there already exists a reference
- * with the same name, it will be overwritten.
+ * Valid reference names must follow one of two patterns:
  *
- * @param ref_out Pointer to the newly created reference
+ * 1. Top-level names must contain only capital letters and underscores,
+ *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
+ * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
+ *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
+ *    sequences ".." and "@{" which have special meaning to revparse.
+ *
+ * This function will return an error if a reference already exists with the
+ * given name unless `force` is true, in which case it will be overwritten.
+ *
+ * @param out Pointer to the newly created reference
  * @param repo Repository where that reference will live
  * @param name The name of the reference
  * @param target The target of the reference
  * @param force Overwrite existing references
- * @return 0 or an error code
+ * @return 0 on success, EEXISTS, EINVALIDSPEC or an error code
  */
-GIT_EXTERN(int) git_reference_create_symbolic(git_reference **ref_out, git_repository *repo, const char *name, const char *target, int force);
+GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force);
 
 /**
- * Create a new object id reference.
+ * Create a new direct reference.
+ *
+ * A direct reference (also called an object id reference) refers directly
+ * to a specific object id (a.k.a. OID or SHA) in the repository.  The id
+ * permanently refers to the object (although the reference itself can be
+ * moved).  For example, in libgit2 the direct ref "refs/tags/v0.17.0"
+ * refers to OID 5b9fac39d8a76b9139667c26a63e6b3f204b3977.
  *
- * The reference will be created in the repository and written
- * to the disk.
+ * The direct reference will be created in the repository and written to
+ * the disk.  The generated reference object must be freed by the user.
  *
- * The generated reference must be freed by the user.
+ * Valid reference names must follow one of two patterns:
  *
- * If `force` is true and there already exists a reference
- * with the same name, it will be overwritten.
+ * 1. Top-level names must contain only capital letters and underscores,
+ *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
+ * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
+ *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
+ *    sequences ".." and "@{" which have special meaning to revparse.
  *
- * @param ref_out Pointer to the newly created reference
+ * This function will return an error if a reference already exists with the
+ * given name unless `force` is true, in which case it will be overwritten.
+ *
+ * @param out Pointer to the newly created reference
  * @param repo Repository where that reference will live
  * @param name The name of the reference
  * @param id The object id pointed to by the reference.
  * @param force Overwrite existing references
- * @return 0 or an error code
+ * @return 0 on success, EEXISTS, EINVALIDSPEC or an error code
+ */
+GIT_EXTERN(int) git_reference_create(git_reference **out, git_repository *repo, const char *name, const git_oid *id, int force);
+
+/**
+ * Get the OID pointed to by a direct reference.
+ *
+ * Only available if the reference is direct (i.e. an object id reference,
+ * not a symbolic one).
+ *
+ * To find the OID of a symbolic ref, call `git_reference_resolve()` and
+ * then this function (or maybe use `git_reference_name_to_id()` to
+ * directly resolve a reference name all the way through to an OID).
+ *
+ * @param ref The reference
+ * @return a pointer to the oid if available, NULL otherwise
  */
-GIT_EXTERN(int) git_reference_create_oid(git_reference **ref_out, git_repository *repo, const char *name, const git_oid *id, int force);
+GIT_EXTERN(const git_oid *) git_reference_target(const git_reference *ref);
 
 /**
- * Get the OID pointed to by a reference.
+ * Return the peeled OID target of this reference.
  *
- * Only available if the reference is direct (i.e. not symbolic)
+ * This peeled OID only applies to direct references that point to
+ * a hard Tag object: it is the result of peeling such Tag.
  *
  * @param ref The reference
  * @return a pointer to the oid if available, NULL otherwise
  */
-GIT_EXTERN(const git_oid *) git_reference_oid(git_reference *ref);
+GIT_EXTERN(const git_oid *) git_reference_target_peel(const git_reference *ref);
 
 /**
- * Get full name to the reference pointed by this reference
+ * Get full name to the reference pointed to by a symbolic reference.
  *
- * Only available if the reference is symbolic
+ * Only available if the reference is symbolic.
  *
  * @param ref The reference
  * @return a pointer to the name if available, NULL otherwise
  */
-GIT_EXTERN(const char *) git_reference_target(git_reference *ref);
+GIT_EXTERN(const char *) git_reference_symbolic_target(const git_reference *ref);
 
 /**
- * Get the type of a reference
+ * Get the type of a reference.
  *
  * Either direct (GIT_REF_OID) or symbolic (GIT_REF_SYMBOLIC)
  *
  * @param ref The reference
  * @return the type
  */
-GIT_EXTERN(git_ref_t) git_reference_type(git_reference *ref);
+GIT_EXTERN(git_ref_t) git_reference_type(const git_reference *ref);
 
 /**
- * Get the full name of a reference
+ * Get the full name of a reference.
+ *
+ * See `git_reference_create_symbolic()` for rules about valid names.
  *
  * @param ref The reference
  * @return the full name for the ref
  */
-GIT_EXTERN(const char *) git_reference_name(git_reference *ref);
+GIT_EXTERN(const char *) git_reference_name(const git_reference *ref);
 
 /**
- * Resolve a symbolic reference
+ * Resolve a symbolic reference to a direct reference.
  *
- * This method iteratively peels a symbolic reference
- * until it resolves to a direct reference to an OID.
+ * This method iteratively peels a symbolic reference until it resolves to
+ * a direct reference to an OID.
  *
- * The peeled reference is returned in the `resolved_ref`
- * argument, and must be freed manually once it's no longer
- * needed.
+ * The peeled reference is returned in the `resolved_ref` argument, and
+ * must be freed manually once it's no longer needed.
  *
- * If a direct reference is passed as an argument,
- * a copy of that reference is returned. This copy must
- * be manually freed too.
+ * If a direct reference is passed as an argument, a copy of that
+ * reference is returned. This copy must be manually freed too.
  *
  * @param resolved_ref Pointer to the peeled reference
  * @param ref The reference
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reference_resolve(git_reference **resolved_ref, git_reference *ref);
+GIT_EXTERN(int) git_reference_resolve(git_reference **out, const git_reference *ref);
 
 /**
- * Get the repository where a reference resides
+ * Get the repository where a reference resides.
  *
  * @param ref The reference
  * @return a pointer to the repo
  */
-GIT_EXTERN(git_repository *) git_reference_owner(git_reference *ref);
+GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref);
 
 /**
- * Set the symbolic target of a reference.
+ * Create a new reference with the same name as the given reference but a
+ * different symbolic target. The reference must be a symbolic reference,
+ * otherwise this will fail.
  *
- * The reference must be a symbolic reference, otherwise
- * this method will fail.
+ * The new reference will be written to disk, overwriting the given reference.
  *
- * The reference will be automatically updated in
- * memory and on disk.
+ * The target name will be checked for validity.
+ * See `git_reference_create_symbolic()` for rules about valid names.
  *
+ * @param out Pointer to the newly created reference
  * @param ref The reference
  * @param target The new target for the reference
- * @return 0 or an error code
+ * @return 0 on success, EINVALIDSPEC or an error code
  */
-GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const char *target);
+GIT_EXTERN(int) git_reference_symbolic_set_target(
+	git_reference **out,
+	git_reference *ref,
+	const char *target);
 
 /**
- * Set the OID target of a reference.
- *
- * The reference must be a direct reference, otherwise
- * this method will fail.
+ * Create a new reference with the same name as the given reference but a
+ * different OID target. The reference must be a direct reference, otherwise
+ * this will fail.
  *
- * The reference will be automatically updated in
- * memory and on disk.
+ * The new reference will be written to disk, overwriting the given reference.
  *
+ * @param out Pointer to the newly created reference
  * @param ref The reference
  * @param id The new target OID for the reference
  * @return 0 or an error code
  */
-GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id);
+GIT_EXTERN(int) git_reference_set_target(
+	git_reference **out,
+	git_reference *ref,
+	const git_oid *id);
 
 /**
- * Rename an existing reference
+ * Rename an existing reference.
  *
  * This method works for both direct and symbolic references.
- * The new name will be checked for validity and may be
- * modified into a normalized form.
  *
- * The given git_reference will be updated in place.
+ * The new name will be checked for validity.
+ * See `git_reference_create_symbolic()` for rules about valid names.
+ *
+ * On success, the given git_reference will be deleted from disk and a
+ * new `git_reference` will be returned.
  *
- * The reference will be immediately renamed in-memory
- * and on disk.
+ * The reference will be immediately renamed in-memory and on disk.
  *
  * If the `force` flag is not enabled, and there's already
  * a reference with the given name, the renaming will fail.
@@ -201,20 +258,23 @@ GIT_EXTERN(int) git_reference_set_oid(git_reference *ref, const git_oid *id);
  * the reflog if it exists.
  *
  * @param ref The reference to rename
- * @param new_name The new name for the reference
+ * @param name The new name for the reference
  * @param force Overwrite an existing reference
- * @return 0 or an error code
+ * @return 0 on success, EINVALIDSPEC, EEXISTS or an error code
  *
  */
-GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, int force);
+GIT_EXTERN(int) git_reference_rename(
+	git_reference **out,
+	git_reference *ref,
+	const char *new_name,
+	int force);
 
 /**
- * Delete an existing reference
- *
- * This method works for both direct and symbolic references.
+ * Delete an existing reference.
  *
- * The reference will be immediately removed on disk and from
- * memory. The given reference pointer will no longer be valid.
+ * This method works for both direct and symbolic references.  The reference
+ * will be immediately removed on disk but the memory will not be freed.
+ * Callers must call `git_reference_free`.
  *
  * @param ref The reference to remove
  * @return 0 or an error code
@@ -222,95 +282,56 @@ GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *new_name, i
 GIT_EXTERN(int) git_reference_delete(git_reference *ref);
 
 /**
- * Pack all the loose references in the repository
+ * Fill a list with all the references that can be found in a repository.
  *
- * This method will load into the cache all the loose
- * references on the repository and update the
- * `packed-refs` file with them.
+ * Using the `list_flags` parameter, the listed references may be filtered
+ * by type (`GIT_REF_OID` or `GIT_REF_SYMBOLIC`) or using a bitwise OR of
+ * `git_ref_t` values.  To include packed refs, include `GIT_REF_PACKED`.
+ * For convenience, use the value `GIT_REF_LISTALL` to obtain all
+ * references, including packed ones.
  *
- * Once the `packed-refs` file has been written properly,
- * the loose references will be removed from disk.
- *
- * @param repo Repository where the loose refs will be packed
- * @return 0 or an error code
- */
-GIT_EXTERN(int) git_reference_packall(git_repository *repo);
-
-/**
- * Fill a list with all the references that can be found
- * in a repository.
- *
- * The listed references may be filtered by type, or using
- * a bitwise OR of several types. Use the magic value
- * `GIT_REF_LISTALL` to obtain all references, including
- * packed ones.
- *
- * The string array will be filled with the names of all
- * references; these values are owned by the user and
- * should be free'd manually when no longer needed, using
- * `git_strarray_free`.
+ * The string array will be filled with the names of all references; these
+ * values are owned by the user and should be free'd manually when no
+ * longer needed, using `git_strarray_free()`.
  *
  * @param array Pointer to a git_strarray structure where
  *		the reference names will be stored
  * @param repo Repository where to find the refs
- * @param list_flags Filtering flags for the reference
- *		listing.
+ * @param list_flags Filtering flags for the reference listing
  * @return 0 or an error code
  */
 GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo, unsigned int list_flags);
 
+typedef int (*git_reference_foreach_cb)(const char *refname, void *payload);
+
 /**
- * Perform an operation on each reference in the repository
+ * Perform a callback on each reference in the repository.
  *
- * The processed references may be filtered by type, or using
- * a bitwise OR of several types. Use the magic value
- * `GIT_REF_LISTALL` to obtain all references, including
- * packed ones.
+ * Using the `list_flags` parameter, the references may be filtered by
+ * type (`GIT_REF_OID` or `GIT_REF_SYMBOLIC`) or using a bitwise OR of
+ * `git_ref_t` values.  To include packed refs, include `GIT_REF_PACKED`.
+ * For convenience, use the value `GIT_REF_LISTALL` to obtain all
+ * references, including packed ones.
  *
- * The `callback` function will be called for each of the references
- * in the repository, and will receive the name of the reference and
- * the `payload` value passed to this method.  Returning a non-zero
- * value from the callback will terminate the iteration.
+ * The `callback` function will be called for each reference in the
+ * repository, receiving the name of the reference and the `payload` value
+ * passed to this method.  Returning a non-zero value from the callback
+ * will terminate the iteration.
  *
  * @param repo Repository where to find the refs
- * @param list_flags Filtering flags for the reference
- *		listing.
+ * @param list_flags Filtering flags for the reference listing.
  * @param callback Function which will be called for every listed ref
  * @param payload Additional data to pass to the callback
  * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
-GIT_EXTERN(int) git_reference_foreach(git_repository *repo, unsigned int list_flags, int (*callback)(const char *, void *), void *payload);
-
-/**
- * Check if a reference has been loaded from a packfile
- *
- * @param ref A git reference
- * @return 0 in case it's not packed; 1 otherwise
- */
-GIT_EXTERN(int) git_reference_is_packed(git_reference *ref);
-
-/**
- * Reload a reference from disk
- *
- * Reference pointers may become outdated if the Git
- * repository is accessed simultaneously by other clients
- * while the library is open.
- *
- * This method forces a reload of the reference from disk,
- * to ensure that the provided information is still
- * reliable.
- *
- * If the reload fails (e.g. the reference no longer exists
- * on disk, or has become corrupted), an error code will be
- * returned and the reference pointer will be invalidated.
- *
- * @param ref The reference to reload
- * @return 0 on success, or an error code
- */
-GIT_EXTERN(int) git_reference_reload(git_reference *ref);
+GIT_EXTERN(int) git_reference_foreach(
+	git_repository *repo,
+	unsigned int list_flags,
+	git_reference_foreach_cb callback,
+	void *payload);
 
 /**
- * Free the given reference
+ * Free the given reference.
  *
  * @param ref git_reference
  */
@@ -326,36 +347,30 @@ GIT_EXTERN(void) git_reference_free(git_reference *ref);
 GIT_EXTERN(int) git_reference_cmp(git_reference *ref1, git_reference *ref2);
 
 /**
- * Loop over all the references and issue a callback for each one
- * which name matches the given glob pattern.
+ * Perform a callback on each reference in the repository whose name
+ * matches the given pattern.
  *
- * The processed references may be filtered by type, or using
- * a bitwise OR of several types. Use the magic value
- * `GIT_REF_LISTALL` to obtain all references, including
- * packed ones.
+ * This function acts like `git_reference_foreach()` with an additional
+ * pattern match being applied to the reference name before issuing the
+ * callback function.  See that function for more information.
  *
- * @param repo Repository where to find the references.
+ * The pattern is matched using fnmatch or "glob" style where a '*' matches
+ * any sequence of letters, a '?' matches any letter, and square brackets
+ * can be used to define character ranges (such as "[0-9]" for digits).
  *
- * @param glob Glob pattern references should match.
- *
- * @param list_flags Filtering flags for the reference
- * listing.
- *
- * @param callback Callback to invoke per found reference.
- *
- * @param payload Extra parameter to callback function.
- *
- * @return 0 or an error code.
+ * @param repo Repository where to find the refs
+ * @param glob Pattern to match (fnmatch-style) against reference name.
+ * @param list_flags Filtering flags for the reference listing.
+ * @param callback Function which will be called for every listed ref
+ * @param payload Additional data to pass to the callback
+ * @return 0 on success, GIT_EUSER on non-zero callback, or error code
  */
 GIT_EXTERN(int) git_reference_foreach_glob(
-		git_repository *repo,
-		const char *glob,
-		unsigned int list_flags,
-		int (*callback)(
-			const char *reference_name,
-			void *payload),
-		void *payload
-);
+	git_repository *repo,
+	const char *glob,
+	unsigned int list_flags,
+	git_reference_foreach_cb callback,
+	void *payload);
 
 /**
  * Check if a reflog exists for the specified reference.
@@ -387,7 +402,8 @@ GIT_EXTERN(int) git_reference_is_branch(git_reference *ref);
  */
 GIT_EXTERN(int) git_reference_is_remote(git_reference *ref);
 
-enum {
+
+typedef enum {
 	GIT_REF_FORMAT_NORMAL = 0,
 
 	/**
@@ -406,27 +422,27 @@ enum {
 	 * (e.g., foo/<star>/bar but not foo/bar<star>).
 	 */
 	GIT_REF_FORMAT_REFSPEC_PATTERN = (1 << 1),
-};
+} git_reference_normalize_t;
 
 /**
- * Normalize the reference name by removing any leading
- * slash (/) characters and collapsing runs of adjacent slashes
- * between name components into a single slash.
- *
- * Once normalized, if the reference name is valid, it will be
- * returned in the user allocated buffer.
+ * Normalize reference name and check validity.
  *
- * @param buffer_out The user allocated buffer where the
- * normalized name will be stored.
+ * This will normalize the reference name by removing any leading slash
+ * '/' characters and collapsing runs of adjacent slashes between name
+ * components into a single slash.
  *
- * @param buffer_size buffer_out size
+ * Once normalized, if the reference name is valid, it will be returned in
+ * the user allocated buffer.
  *
- * @param name name to be checked.
+ * See `git_reference_create_symbolic()` for rules about valid names.
  *
- * @param flags Flags to determine the options to be applied while
- * checking the validatity of the name.
- *
- * @return 0 or an error code.
+ * @param buffer_out User allocated buffer to store normalized name
+ * @param buffer_size Size of buffer_out
+ * @param name Reference name to be checked.
+ * @param flags Flags to constrain name validation rules - see the
+ *              GIT_REF_FORMAT constants above.
+ * @return 0 on success, GIT_EBUFS if buffer is too small, EINVALIDSPEC
+ * or an error code.
  */
 GIT_EXTERN(int) git_reference_normalize_name(
 	char *buffer_out,
@@ -435,8 +451,7 @@ GIT_EXTERN(int) git_reference_normalize_name(
 	unsigned int flags);
 
 /**
- * Recursively peel an reference until an object of the
- * specified type is met.
+ * Recursively peel reference until object of the specified type is found.
  *
  * The retrieved `peeled` object is owned by the repository
  * and should be closed with the `git_object_free` method.
@@ -446,8 +461,9 @@ GIT_EXTERN(int) git_reference_normalize_name(
  *
  * @param peeled Pointer to the peeled git_object
  * @param ref The reference to be processed
- * @param target_type The type of the requested object
- * @return 0 or an error code
+ * @param target_type The type of the requested object (GIT_OBJ_COMMIT,
+ * GIT_OBJ_TAG, GIT_OBJ_TREE, GIT_OBJ_BLOB or GIT_OBJ_ANY).
+ * @return 0 on success, GIT_EAMBIGUOUS, GIT_ENOTFOUND or an error code
  */
 GIT_EXTERN(int) git_reference_peel(
 	git_object **out,
@@ -457,12 +473,18 @@ GIT_EXTERN(int) git_reference_peel(
 /**
  * Ensure the reference name is well-formed.
  *
- * @param refname name to be checked.
+ * Valid reference names must follow one of two patterns:
+ *
+ * 1. Top-level names must contain only capital letters and underscores,
+ *    and must begin and end with a letter. (e.g. "HEAD", "ORIG_HEAD").
+ * 2. Names prefixed with "refs/" can be almost anything.  You must avoid
+ *    the characters '~', '^', ':', '\\', '?', '[', and '*', and the
+ *    sequences ".." and "@{" which have special meaning to revparse.
  *
+ * @param refname name to be checked.
  * @return 1 if the reference name is acceptable; 0 if it isn't
  */
-GIT_EXTERN(int) git_reference_is_valid_name(
-	const char *refname);
+GIT_EXTERN(int) git_reference_is_valid_name(const char *refname);
 
 /** @} */
 GIT_END_DECL