diff options
Diffstat (limited to 'include/git2')
| -rw-r--r-- | include/git2/refs.h | 57 | ||||
| -rw-r--r-- | include/git2/repository.h | 13 | ||||
| -rw-r--r-- | include/git2/sys/refdb_backend.h | 64 | ||||
| -rw-r--r-- | include/git2/types.h | 4 |
4 files changed, 101 insertions, 37 deletions
diff --git a/include/git2/refs.h b/include/git2/refs.h index e1d425352..754bda785 100644 --- a/include/git2/refs.h +++ b/include/git2/refs.h @@ -55,6 +55,19 @@ GIT_EXTERN(int) git_reference_name_to_id( git_oid *out, git_repository *repo, const char *name); /** + * Lookup a reference by DWIMing its short name + * + * Apply the git precendence rules to the given shorthand to determine + * which reference the user is refering to. + * + * @param out pointer in which to store the reference + * @param repo the repository in which to look + * @param shrothand the short name for the reference + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reference_dwim(git_reference **out, git_repository *repo, const char *shorthand); + +/** * Create a new symbolic reference. * * A symbolic reference is a reference name that refers to another @@ -284,12 +297,6 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref); /** * Fill a list with all the references that can be found in a repository. * - * 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. - * * 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()`. @@ -297,36 +304,27 @@ GIT_EXTERN(int) git_reference_delete(git_reference *ref); * @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 * @return 0 or an error code */ -GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo, unsigned int list_flags); +GIT_EXTERN(int) git_reference_list(git_strarray *array, git_repository *repo); typedef int (*git_reference_foreach_cb)(const char *refname, void *payload); /** * Perform a callback on each reference in the repository. * - * 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 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 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, git_reference_foreach_cb callback, void *payload); @@ -347,6 +345,31 @@ GIT_EXTERN(void) git_reference_free(git_reference *ref); GIT_EXTERN(int) git_reference_cmp(git_reference *ref1, git_reference *ref2); /** + * Create an iterator for the repo's references + * + * @param out pointer in which to store the iterator + * @param repo the repository + * @return 0 or an error code + */ +GIT_EXTERN(int) git_reference_iterator_new(git_reference_iterator **out, git_repository *repo); + +/** + * Get the next reference name + * + * @param out pointer in which to store the string + * @param iter the iterator + * @param 0, GIT_ITEROVER if there are no more; or an error code + */ +GIT_EXTERN(int) git_reference_next(const char **out, git_reference_iterator *iter); + +/** + * Free the iterator and its associated resources + * + * @param iter the iterator to free + */ +GIT_EXTERN(void) git_reference_iterator_free(git_reference_iterator *iter); + +/** * Perform a callback on each reference in the repository whose name * matches the given pattern. * @@ -360,7 +383,6 @@ GIT_EXTERN(int) git_reference_cmp(git_reference *ref1, git_reference *ref2); * * @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 @@ -368,7 +390,6 @@ GIT_EXTERN(int) git_reference_cmp(git_reference *ref1, git_reference *ref2); GIT_EXTERN(int) git_reference_foreach_glob( git_repository *repo, const char *glob, - unsigned int list_flags, git_reference_foreach_cb callback, void *payload); diff --git a/include/git2/repository.h b/include/git2/repository.h index cd238e17c..e0464c63f 100644 --- a/include/git2/repository.h +++ b/include/git2/repository.h @@ -460,10 +460,19 @@ GIT_EXTERN(int) git_repository_index(git_index **out, git_repository *repo); * Use this function to get the contents of this file. Don't forget to * remove the file after you create the commit. * + * If the repository message exists and there are no errors reading it, this + * returns the bytes needed to store the message in memory (i.e. message + * file size plus one terminating NUL byte). That value is returned even if + * `out` is NULL or `len` is shorter than the necessary size. + * + * The `out` buffer will *always* be NUL terminated, even if truncation + * occurs. + * * @param out Buffer to write data into or NULL to just read required size - * @param len Length of buffer in bytes + * @param len Length of `out` buffer in bytes * @param repo Repository to read prepared message from - * @return Bytes written to buffer, GIT_ENOTFOUND if no message, or -1 on error + * @return GIT_ENOUTFOUND if no message exists, other value < 0 for other + * errors, or total bytes in message (may be > `len`) on success */ GIT_EXTERN(int) git_repository_message(char *out, size_t len, git_repository *repo); diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h index d5f599fec..8dbf38ca9 100644 --- a/include/git2/sys/refdb_backend.h +++ b/include/git2/sys/refdb_backend.h @@ -20,6 +20,23 @@ */ GIT_BEGIN_DECL + +/** + * Every backend's iterator must have a pointer to itself as the first + * element, so the API can talk to it. You'd define your iterator as + * + * struct my_iterator { + * git_reference_iterator parent; + * ... + * } + * + * and assign `iter->parent.backend` to your `git_refdb_backend`. + */ +struct git_reference_iterator { + git_refdb_backend *backend; + char *glob; +}; + /** An instance for a custom backend */ struct git_refdb_backend { unsigned int version; @@ -43,29 +60,42 @@ struct git_refdb_backend { const char *ref_name); /** - * Enumerates each reference in the refdb. A refdb implementation must - * provide this function. + * Allocate an iterator object for the backend. + * + * A refdb implementation must provide this function. */ - int (*foreach)( - git_refdb_backend *backend, - unsigned int list_flags, - git_reference_foreach_cb callback, - void *payload); + int (*iterator)( + git_reference_iterator **iter, + struct git_refdb_backend *backend); /** - * Enumerates each reference in the refdb that matches the given - * glob string. A refdb implementation may provide this function; - * if it is not provided, foreach will be used and the results filtered - * against the glob. + * Allocate a glob-filtering iterator object for the backend. + * + * A refdb implementation may provide this function. If it's + * not available, the glob matching will be done by the frontend. */ - int (*foreach_glob)( - git_refdb_backend *backend, - const char *glob, - unsigned int list_flags, - git_reference_foreach_cb callback, - void *payload); + int (*iterator_glob)( + git_reference_iterator **iter, + struct git_refdb_backend *backend, + const char *glob); + + /** + * Return the current value and advance the iterator. + * + * A refdb implementation must provide this function. + */ + int (*next)( + const char **name, + git_reference_iterator *iter); /** + * Free the iterator + * + * A refdb implementation must provide this function. + */ + void (*iterator_free)( + git_reference_iterator *iter); + /* * Writes the given reference to the refdb. A refdb implementation * must provide this function. */ diff --git a/include/git2/types.h b/include/git2/types.h index aca9ed927..43751d3b0 100644 --- a/include/git2/types.h +++ b/include/git2/types.h @@ -165,6 +165,10 @@ typedef struct git_signature { /** In-memory representation of a reference. */ typedef struct git_reference git_reference; +/** Iterator for references */ +typedef struct git_reference_iterator git_reference_iterator; + + /** Basic type of any Git reference. */ typedef enum { GIT_REF_INVALID = 0, /** Invalid reference */ |