branch: Deploy EINVALIDSPEC usage

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,

tests-clar/refs/branches/create.c

@@ -65,3 +65,12 @@ void test_refs_branches_create__can_force_create_over_an_existing_branch(void)
 	cl_git_pass(git_oid_cmp(git_reference_target(branch), git_commit_id(target)));
 	cl_assert_equal_s("refs/heads/br2", git_reference_name(branch));
 }
+
+
+void test_refs_branches_create__creating_a_branch_with_an_invalid_name_returns_EINVALIDSPEC(void)
+{
+	retrieve_known_commit(&target, repo);
+
+	cl_assert_equal_i(GIT_EINVALIDSPEC,
+		git_branch_create(&branch, repo, "inv@{id", target, 0));
+}
\ No newline at end of file

tests-clar/refs/branches/lookup.c

@@ -35,3 +35,11 @@ void test_refs_branches_lookup__trying_to_retrieve_an_unknown_branch_returns_ENO
 	cl_assert_equal_i(GIT_ENOTFOUND, git_branch_lookup(&branch, repo, "where/are/you", GIT_BRANCH_LOCAL));
 	cl_assert_equal_i(GIT_ENOTFOUND, git_branch_lookup(&branch, repo, "over/here", GIT_BRANCH_REMOTE));
 }
+
+void test_refs_branches_lookup__trying_to_retrieve_a_branch_with_an_invalid_name_returns_EINVALIDSPEC(void)
+{
+	cl_assert_equal_i(GIT_EINVALIDSPEC,
+		git_branch_lookup(&branch, repo, "are/you/inv@{id", GIT_BRANCH_LOCAL));
+	cl_assert_equal_i(GIT_EINVALIDSPEC,
+		git_branch_lookup(&branch, repo, "yes/i am", GIT_BRANCH_REMOTE));
+}

tests-clar/refs/branches/move.c

@@ -51,6 +51,11 @@ void test_refs_branches_move__can_not_move_a_branch_if_its_destination_name_coll
 	cl_assert_equal_i(GIT_EEXISTS, git_branch_move(ref, "master", 0));
 }
 
+void test_refs_branches_move__moving_a_branch_with_an_invalid_name_returns_EINVALIDSPEC(void)
+{
+	cl_assert_equal_i(GIT_EINVALIDSPEC, git_branch_move(ref, "Inv@{id", 0));
+}
+
 void test_refs_branches_move__can_not_move_a_non_branch(void)
 {
 	git_reference *tag;