diff options
Diffstat (limited to 'include/git2')
| -rw-r--r-- | include/git2/branch.h | 15 | ||||
| -rw-r--r-- | include/git2/errors.h | 1 | ||||
| -rw-r--r-- | include/git2/object.h | 5 | ||||
| -rw-r--r-- | include/git2/reflog.h | 5 | ||||
| -rw-r--r-- | include/git2/refs.h | 39 | ||||
| -rw-r--r-- | include/git2/remote.h | 22 | ||||
| -rw-r--r-- | include/git2/revparse.h | 3 | ||||
| -rw-r--r-- | include/git2/tag.h | 16 |
8 files changed, 76 insertions, 30 deletions
diff --git a/include/git2/branch.h b/include/git2/branch.h index c9ae9cc5d..f55903cd6 100644 --- a/include/git2/branch.h +++ b/include/git2/branch.h @@ -29,6 +29,9 @@ GIT_BEGIN_DECL * * The returned reference must be freed by the user. * + * The branch name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param out Pointer where to store the underlying reference. * * @param branch_name Name for the branch; this name is @@ -42,7 +45,7 @@ GIT_BEGIN_DECL * * @param force Overwrite existing branch. * - * @return 0 or an error code. + * @return 0, GIT_EINVALIDSPEC or an error code. * A proper reference is written in the refs/heads namespace * pointing to the provided target commit. */ @@ -94,6 +97,9 @@ GIT_EXTERN(int) git_branch_foreach( /** * Move/rename an existing local branch reference. * + * The new branch name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param branch Current underlying reference of the branch. * * @param new_branch_name Target name of the branch once the move @@ -101,7 +107,7 @@ GIT_EXTERN(int) git_branch_foreach( * * @param force Overwrite existing branch. * - * @return 0 on success, or an error code. + * @return 0 on success, GIT_EINVALIDSPEC or an error code. */ GIT_EXTERN(int) git_branch_move( git_reference *branch, @@ -113,6 +119,9 @@ GIT_EXTERN(int) git_branch_move( * * The generated reference must be freed by the user. * + * The branch name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param out pointer to the looked-up branch reference * * @param repo the repository to look up the branch @@ -124,7 +133,7 @@ GIT_EXTERN(int) git_branch_move( * be valued with either GIT_BRANCH_LOCAL or GIT_BRANCH_REMOTE. * * @return 0 on success; GIT_ENOTFOUND when no matching branch - * exists, otherwise an error code. + * exists, GIT_EINVALIDSPEC, otherwise an error code. */ GIT_EXTERN(int) git_branch_lookup( git_reference **out, diff --git a/include/git2/errors.h b/include/git2/errors.h index 9dd42f0c4..63b6bc8ee 100644 --- a/include/git2/errors.h +++ b/include/git2/errors.h @@ -30,6 +30,7 @@ enum { GIT_EORPHANEDHEAD = -9, GIT_EUNMERGED = -10, GIT_ENONFASTFORWARD = -11, + GIT_EINVALIDSPEC = -12, GIT_PASSTHROUGH = -30, GIT_ITEROVER = -31, diff --git a/include/git2/object.h b/include/git2/object.h index fcc56cb27..e5ca17e16 100644 --- a/include/git2/object.h +++ b/include/git2/object.h @@ -179,8 +179,9 @@ GIT_EXTERN(size_t) git_object__size(git_otype type); * * @param peeled Pointer to the peeled git_object * @param object The object 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_object_peel( git_object **peeled, diff --git a/include/git2/reflog.h b/include/git2/reflog.h index 45dff2165..418826d1d 100644 --- a/include/git2/reflog.h +++ b/include/git2/reflog.h @@ -63,9 +63,12 @@ GIT_EXTERN(int) git_reflog_append(git_reflog *reflog, const git_oid *id, const g * * 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 name the new name of the reference - * @return 0 or an error code + * @return 0 on success, GIT_EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_reflog_rename(git_reference *ref, const char *name); diff --git a/include/git2/refs.h b/include/git2/refs.h index c92646115..f3082102f 100644 --- a/include/git2/refs.h +++ b/include/git2/refs.h @@ -26,13 +26,13 @@ GIT_BEGIN_DECL * * The returned reference must be freed by the user. * - * See `git_reference_create_symbolic()` for documentation about valid - * reference names. + * 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, refs/heads/master, refs/tags/v0.1.0, ...) - * @return 0 or an error code (ENOTFOUND, EINVALIDSPEC) + * @return 0 on success, ENOTFOUND, EINVALIDSPEC or an error code. */ GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, const char *name); @@ -43,11 +43,13 @@ GIT_EXTERN(int) git_reference_lookup(git_reference **out, git_repository *repo, * 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_create_symbolic()` 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 (EINVALIDSPEC, - * ENOTFOUND, etc) + * @return 0 on success, ENOTFOUND, EINVALIDSPEC or an error code. */ GIT_EXTERN(int) git_reference_name_to_id( git_oid *out, git_repository *repo, const char *name); @@ -79,7 +81,7 @@ GIT_EXTERN(int) git_reference_name_to_id( * @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 (EEXISTS, EINVALIDSPEC) + * @return 0 on success, EEXISTS, EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repository *repo, const char *name, const char *target, int force); @@ -111,7 +113,7 @@ GIT_EXTERN(int) git_reference_symbolic_create(git_reference **out, git_repositor * @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 (EINVALIDSPEC, EEXISTS) + * @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); @@ -193,9 +195,12 @@ GIT_EXTERN(git_repository *) git_reference_owner(const git_reference *ref); * * 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 ref The reference * @param target The new target for the reference - * @return 0 or an error code (EINVALIDSPEC) + * @return 0 on success, EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_reference_symbolic_set_target(git_reference *ref, const char *target); @@ -216,8 +221,9 @@ GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const git_oid *id); * 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 new name will be checked for validity. + * See `git_reference_create_symbolic()` for rules about valid names. * * The given git_reference will be updated in place. * @@ -234,7 +240,7 @@ GIT_EXTERN(int) git_reference_set_target(git_reference *ref, const git_oid *id); * @param ref The reference to rename * @param name The new name for the reference * @param force Overwrite an existing reference - * @return 0 or an error code (EINVALIDSPEC, EEXISTS) + * @return 0 on success, EINVALIDSPEC, EEXISTS or an error code * */ GIT_EXTERN(int) git_reference_rename(git_reference *ref, const char *name, int force); @@ -446,13 +452,15 @@ typedef enum { * Once normalized, if the reference name is valid, it will be returned in * the user allocated buffer. * + * See `git_reference_create_symbolic()` for rules about valid names. + * * @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 or error code (GIT_EBUFS if buffer is too small, -1 - * if reference is invalid) + * @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, @@ -471,8 +479,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, diff --git a/include/git2/remote.h b/include/git2/remote.h index 6c70d7fbc..0483cfc4b 100644 --- a/include/git2/remote.h +++ b/include/git2/remote.h @@ -39,30 +39,39 @@ typedef int (*git_remote_rename_problem_cb)(const char *problematic_refspec, voi * Create a remote with the default refspecs in memory. You can use * this when you have a URL instead of a remote's name. * + * The name, when provided, will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param out pointer to the new remote object * @param repo the associated repository - * @param name the remote's name + * @param name the optional remote's name * @param url the remote repository's URL * @param fetch the fetch refspec to use for this remote - * @return 0 or an error code + * @return 0, GIT_EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_remote_new(git_remote **out, git_repository *repo, const char *name, const char *url, const char *fetch); /** * Get the information for a particular remote * + * The name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param out pointer to the new remote object * @param repo the associated repository * @param name the remote's name - * @return 0 or an error code + * @return 0, GIT_ENOTFOUND, GIT_EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_remote_load(git_remote **out, git_repository *repo, const char *name); /** * Save a remote to its repository's configuration * + * One can't save a nameless inmemory remote. Doing so will + * result in a GIT_EINVALIDSPEC being returned. + * * @param remote the remote to save to config - * @return 0 or an error code + * @return 0, GIT_EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_remote_save(const git_remote *remote); @@ -391,12 +400,15 @@ GIT_EXTERN(void) git_remote_set_autotag( * All remote-tracking branches and configuration settings * for the remote are updated. * + * The new name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param remote the remote to rename * @param new_name the new name the remote should bear * @param callback Optional callback to notify the consumer of fetch refspecs * that haven't been automatically updated and need potential manual tweaking. * @param payload Additional data to pass to the callback - * @return 0 or an error code + * @return 0, GIT_EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_remote_rename( git_remote *remote, diff --git a/include/git2/revparse.h b/include/git2/revparse.h index 4567027e5..3df6fef7f 100644 --- a/include/git2/revparse.h +++ b/include/git2/revparse.h @@ -27,7 +27,8 @@ GIT_BEGIN_DECL * @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); diff --git a/include/git2/tag.h b/include/git2/tag.h index f82a6c9f9..a9773be56 100644 --- a/include/git2/tag.h +++ b/include/git2/tag.h @@ -144,6 +144,10 @@ GIT_EXTERN(const char *) git_tag_message(const git_tag *tag); * The message will not be cleaned up. This can be achieved * through `git_message_prettify()`. * + * The tag name will be checked for validity. You must avoid + * the characters '~', '^', ':', '\\', '?', '[', and '*', and the + * sequences ".." and "@{" which have special meaning to revparse. + * * @param oid Pointer where to store the OID of the * newly created tag. If the tag already exists, this parameter * will be the oid of the existing tag, and the function will @@ -165,7 +169,7 @@ GIT_EXTERN(const char *) git_tag_message(const git_tag *tag); * * @param force Overwrite existing references * - * @return 0 or an error code + * @return 0 on success, GIT_EINVALIDSPEC or an error code * A tag object is written to the ODB, and a proper reference * is written in the /refs/tags folder, pointing to it */ @@ -200,6 +204,9 @@ GIT_EXTERN(int) git_tag_create_frombuffer( * this target object. If `force` is true and a reference * already exists with the given name, it'll be replaced. * + * The tag name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param oid Pointer where to store the OID of the provided * target object. If the tag already exists, this parameter * will be filled with the oid of the existing pointed object @@ -216,7 +223,7 @@ GIT_EXTERN(int) git_tag_create_frombuffer( * * @param force Overwrite existing references * - * @return 0 or an error code + * @return 0 on success, GIT_EINVALIDSPEC or an error code * A proper reference is written in the /refs/tags folder, * pointing to the provided target object */ @@ -230,12 +237,15 @@ GIT_EXTERN(int) git_tag_create_lightweight( /** * Delete an existing tag reference. * + * The tag name will be checked for validity. + * See `git_tag_create()` for rules about valid names. + * * @param repo Repository where lives the tag * * @param tag_name Name of the tag to be deleted; * this name is validated for consistency. * - * @return 0 or an error code + * @return 0 on success, GIT_EINVALIDSPEC or an error code */ GIT_EXTERN(int) git_tag_delete( git_repository *repo, |