worktree: add ability to create worktree with pre-existing branch

Currently, we always create a new branch after the new worktree's name
when creating a worktree. In some workflows, though, the caller may want
to check out an already existing reference instead of creating a new
one, which is impossible to do right now.

Add a new option `ref` to the options structure for adding worktrees. In
case it is set, a branch and not already checked out by another
worktree, we will re-use this reference instead of creating a new one.

include/git2/worktree.h

@@ -78,10 +78,11 @@ typedef struct git_worktree_add_options {
 	unsigned int version;
 
 	int lock; /**< lock newly created worktree */
+	git_reference *ref; /**< reference to use for the new worktree HEAD */
 } git_worktree_add_options;
 
 #define GIT_WORKTREE_ADD_OPTIONS_VERSION 1
-#define GIT_WORKTREE_ADD_OPTIONS_INIT {GIT_WORKTREE_ADD_OPTIONS_VERSION,0}
+#define GIT_WORKTREE_ADD_OPTIONS_INIT {GIT_WORKTREE_ADD_OPTIONS_VERSION,0,NULL}
 
 /**
  * Initializes a `git_worktree_add_options` with default vaules.

src/worktree.c

@@ -348,13 +348,30 @@ int git_worktree_add(git_worktree **out, git_repository *repo,
 	    || (err = write_wtfile(gitdir.ptr, "gitdir", &buf)) < 0)
 		goto out;
 
-	/* Create new branch */
-	if ((err = git_repository_head(&head, repo)) < 0)
-		goto out;
-	if ((err = git_commit_lookup(&commit, repo, &head->target.oid)) < 0)
-		goto out;
-	if ((err = git_branch_create(&ref, repo, name, commit, false)) < 0)
-		goto out;
+	/* Set up worktree reference */
+	if (wtopts.ref) {
+		if (!git_reference_is_branch(wtopts.ref)) {
+			giterr_set(GITERR_WORKTREE, "reference is not a branch");
+			err = -1;
+			goto out;
+		}
+
+		if (git_branch_is_checked_out(wtopts.ref)) {
+			giterr_set(GITERR_WORKTREE, "reference is already checked out");
+			err = -1;
+			goto out;
+		}
+
+		if ((err = git_reference_dup(&ref, wtopts.ref)) < 0)
+			goto out;
+	} else {
+		if ((err = git_repository_head(&head, repo)) < 0)
+			goto out;
+		if ((err = git_commit_lookup(&commit, repo, &head->target.oid)) < 0)
+			goto out;
+		if ((err = git_branch_create(&ref, repo, name, commit, false)) < 0)
+			goto out;
+	}
 
 	/* Set worktree's HEAD */
 	if ((err = git_repository_create_head(gitdir.ptr, git_reference_name(ref))) < 0)

tests/worktree/worktree.c

@@ -273,6 +273,36 @@ void test_worktree_worktree__init_existing_branch(void)
 	git_reference_free(branch);
 }
 
+void test_worktree_worktree__add_with_explicit_branch(void)
+{
+	git_reference *head, *branch, *wthead;
+	git_commit *commit;
+	git_worktree *wt;
+	git_repository *wtrepo;
+	git_buf path = GIT_BUF_INIT;
+	git_worktree_add_options opts = GIT_WORKTREE_ADD_OPTIONS_INIT;
+
+	cl_git_pass(git_repository_head(&head, fixture.repo));
+	cl_git_pass(git_commit_lookup(&commit, fixture.repo, &head->target.oid));
+	cl_git_pass(git_branch_create(&branch, fixture.repo, "worktree-with-ref", commit, false));
+
+	opts.ref = branch;
+
+	cl_git_pass(git_buf_joinpath(&path, fixture.repo->workdir, "../worktree-with-different-name"));
+	cl_git_pass(git_worktree_add(&wt, fixture.repo, "worktree-with-different-name", path.ptr, &opts));
+	cl_git_pass(git_repository_open_from_worktree(&wtrepo, wt));
+	cl_git_pass(git_repository_head(&wthead, wtrepo));
+	cl_assert_equal_s(git_reference_name(wthead), "refs/heads/worktree-with-ref");
+
+	git_buf_free(&path);
+	git_commit_free(commit);
+	git_reference_free(head);
+	git_reference_free(branch);
+	git_reference_free(wthead);
+	git_repository_free(wtrepo);
+}
+
+
 void test_worktree_worktree__init_existing_worktree(void)
 {
 	git_worktree *wt;