branches: introduce flag to skip enumeration of certain HEADs

Right now, the function `git_repository_foreach_head` will always
iterate over all HEADs of the main repository and its worktrees. In some
cases, it might be required to skip either of those, though. Add a flag
in preparation for the following commit that enables this behaviour.

src/branch.c

@@ -159,7 +159,7 @@ int git_branch_is_checked_out(const git_reference *branch)
 		return 0;
 
 	return git_repository_foreach_head(git_reference_owner(branch),
-		branch_equals, (void *) branch) == 1;
+		branch_equals, 0, (void *) branch) == 1;
 }
 
 int git_branch_delete(git_reference *branch)

src/refs.c

@@ -692,7 +692,7 @@ static int reference__rename(git_reference **out, git_reference *ref, const char
 		payload.old_name = ref->name;
 		memcpy(&payload.new_name, &normalized, sizeof(normalized));
 
-		error = git_repository_foreach_head(repo, update_wt_heads, &payload);
+		error = git_repository_foreach_head(repo, update_wt_heads, 0, &payload);
 	}
 
 	return error;

src/repository.c

@@ -2210,24 +2210,30 @@ out:
 	return error;
 }
 
-int git_repository_foreach_head(git_repository *repo, git_repository_foreach_head_cb cb, void *payload)
+int git_repository_foreach_head(git_repository *repo,
+				git_repository_foreach_head_cb cb,
+				int flags, void *payload)
 {
 	git_strarray worktrees = GIT_VECTOR_INIT;
 	git_buf path = GIT_BUF_INIT;
 	int error;
 	size_t i;
 
-	/* Execute callback for HEAD of commondir */
+
+	if (!(flags & GIT_REPOSITORY_FOREACH_HEAD_SKIP_REPO)) {
+		/* Gather HEAD of main repository */
 		if ((error = git_buf_joinpath(&path, repo->commondir, GIT_HEAD_FILE)) < 0 ||
 		    (error = cb(repo, path.ptr, payload) != 0))
 			goto out;
+	}
 
+	if (!(flags & GIT_REPOSITORY_FOREACH_HEAD_SKIP_WORKTREES)) {
 		if ((error = git_worktree_list(&worktrees, repo)) < 0) {
 			error = 0;
 			goto out;
 		}
 
-	/* Execute callback for all worktree HEADs */
+		/* Gather HEADs of all worktrees */
 		for (i = 0; i < worktrees.count; i++) {
 			if (get_worktree_file_path(&path, repo, worktrees.strings[i], GIT_HEAD_FILE) < 0)
 				continue;
@@ -2235,6 +2241,7 @@ int git_repository_foreach_head(git_repository *repo, git_repository_foreach_hea
 			if ((error = cb(repo, path.ptr, payload)) != 0)
 				goto out;
 		}
+	}
 
 out:
 	git_buf_dispose(&path);

src/repository.h

@@ -176,6 +176,13 @@ int git_repository_create_head(const char *git_dir, const char *ref_name);
  */
 typedef int (*git_repository_foreach_head_cb)(git_repository *repo, const char *path, void *payload);
 
+enum {
+	/* Skip enumeration of the main repository HEAD */
+	GIT_REPOSITORY_FOREACH_HEAD_SKIP_REPO      = (1u << 0),
+	/* Skip enumeration of worktree HEADs */
+	GIT_REPOSITORY_FOREACH_HEAD_SKIP_WORKTREES = (1u << 1),
+};
+
 /*
  * Iterate over repository and all worktree HEADs.
  *
@@ -184,7 +191,9 @@ typedef int (*git_repository_foreach_head_cb)(git_repository *repo, const char *
  * executed with the given payload. The return value equals the
  * return value of the last executed callback function.
  */
-int git_repository_foreach_head(git_repository *repo, git_repository_foreach_head_cb cb, void *payload);
+int git_repository_foreach_head(git_repository *repo,
+				git_repository_foreach_head_cb cb,
+				int flags, void *payload);
 
 /*
  * Weak pointers to repository internals.

tests/worktree/worktree.c

@@ -604,8 +604,8 @@ void test_worktree_worktree__foreach_head_gives_same_results_in_wt_and_repo(void
 	cl_git_pass(git_reference_lookup(&heads[0], fixture.repo, GIT_HEAD_FILE));
 	cl_git_pass(git_reference_lookup(&heads[1], fixture.worktree, GIT_HEAD_FILE));
 
-	cl_git_pass(git_repository_foreach_head(fixture.repo, read_head_ref, &repo_refs));
-	cl_git_pass(git_repository_foreach_head(fixture.worktree, read_head_ref, &worktree_refs));
+	cl_git_pass(git_repository_foreach_head(fixture.repo, read_head_ref, 0, &repo_refs));
+	cl_git_pass(git_repository_foreach_head(fixture.worktree, read_head_ref, 0, &worktree_refs));
 
 	cl_assert_equal_i(repo_refs.length, ARRAY_SIZE(heads));
 	cl_assert_equal_i(worktree_refs.length, ARRAY_SIZE(heads));