refdb: initialize on-disk data structures via the backend

pks-t · pks-t · commit 72e29b9b0038 · 2025-08-04T16:34:02.000+02:00
The initialization of the on-disk state of refdbs is currently not
handled by the actual refdb backend, but it's implemented ad-hoc where
needed. This is problematic once we have multiple different refdbs as
the filesystem structure is of course not the same.

Introduce a new callback function `git_refdb_backend::init()`. If set,
this callback can be invoked via `git_refdb_init()` to initialize the
on-disk state of a refdb. Like this, each backend can decide for itself
how exactly to do this.

Note that the initialization of the refdb is a bit intricate. A
repository is only recognized as such when it has a "HEAD" file as well
as a "refs/" directory. Consequently, regardless of which refdb format
we use, those files must always be present. This also proves to be
problematic for us, as we cannot access the repository and thus don't
have access to the refdb if those files didn't exist.

To work around the issue we thus handle the creation of those files
outside of the refdb-specific logic. We actually use the same strategy
as Git does, and write the invalid reference "ref: refs/heads/.invalid"
into "HEAD". This looks almost like a ref, but the name of that ref
is not valid and should thus trip up Git clients that try to read that
ref in a repository that really uses a different format.

So while that invalid "HEAD" reference will of course get rewritten by
the "files" backend, other backends should just retain it as-is.
diff --git a/include/git2/sys/refdb_backend.h b/include/git2/sys/refdb_backend.h
@@ -56,10 +56,48 @@ struct git_reference_iterator {
 		git_reference_iterator *iter);
 };
 
+typedef enum {
+	/**
+	 * The refdb that is to be initialized is for a worktree.
+	 */
+	GIT_REFDB_BACKEND_INIT_IS_WORKTREE = (1u << 0),
+
+	/*
+	 * Force-overwrite HEAD in case the refdb is already (partially)
+	 * initialized.
+	 */
+	GIT_REFDB_BACKEND_INIT_FORCE_HEAD = (1u << 1)
+} git_refdb_backend_init_flag_t;
+
 /** An instance for a custom backend */
 struct git_refdb_backend {
 	unsigned int version; /**< The backend API version */
 
+	/**
+	 * Create a new refdb and initialize its structures.
+	 *
+	 * A refdb implementation may provide this function; if it is not
+	 * provided, no data structures will be initialized for the refdb when
+	 * a new repository is created.
+	 *
+	 * @param path The path of the Git directory that shall be initialized.
+	 * @param initial_head The target that HEAD should point to. This value
+	 *             should only be applied when there isn't yet a HEAD
+	 *             reference, or when `GIT_REFDB_BACKEND_INIT_FORCE_HEAD`
+	 *             is passed. Optional, if unset the backend should not set
+	 *             up HEAD, either.
+	 * @param mode The mode that shall be used to create files and
+	 *             directories. May be one of `git_repository_init_mode_t`
+	 *             or normal Unix permission bits.
+	 * @param flags A combination of `git_refdb_backend_init_flag_t` flags.
+	 * @return `0` on success, a negative error value code.
+	 */
+	int GIT_CALLBACK(init)(
+		git_refdb_backend *backend,
+		const char *head_target,
+		mode_t mode,
+		uint32_t flags);
+
 	/**
 	 * Queries the refdb backend for the existence of a reference.
 	 *
diff --git a/src/libgit2/refdb.c b/src/libgit2/refdb.c
@@ -122,6 +122,16 @@ void git_refdb_free(git_refdb *db)
 	GIT_REFCOUNT_DEC(db, git_refdb__free);
 }
 
+int git_refdb_init(git_refdb *refdb, const char *head_target, mode_t mode, uint32_t flags)
+{
+	GIT_ASSERT_ARG(refdb);
+	GIT_ASSERT_ARG(refdb->backend);
+
+	if (!refdb->backend->init)
+		return 0;
+	return refdb->backend->init(refdb->backend, head_target, mode, flags);
+}
+
 int git_refdb_exists(int *exists, git_refdb *refdb, const char *ref_name)
 {
 	GIT_ASSERT_ARG(exists);
diff --git a/src/libgit2/refdb.h b/src/libgit2/refdb.h
@@ -12,6 +12,8 @@
 #include "git2/refdb.h"
 #include "repository.h"
 
+#define GIT_INVALID_HEAD "refs/heads/.invalid"
+
 struct git_refdb {
 	git_refcount rc;
 	git_repository *repo;
@@ -20,6 +22,11 @@ struct git_refdb {
 
 void git_refdb__free(git_refdb *db);
 
+int git_refdb_init(git_refdb *refdb,
+		   const char *head_target,
+		   mode_t mode,
+		   uint32_t flags);
+
 int git_refdb_exists(
 	int *exists,
 	git_refdb *refdb,
diff --git a/src/libgit2/refdb_fs.c b/src/libgit2/refdb_fs.c
@@ -344,6 +344,60 @@ static int packed_loadloose(refdb_fs_backend *backend)
 	return error;
 }
 
+static int refdb_fs_backend__init(struct git_refdb_backend *_backend,
+				  const char *head_target,
+				  mode_t mode,
+				  uint32_t flags)
+{
+	refdb_fs_backend *backend = GIT_CONTAINER_OF(_backend, refdb_fs_backend, parent);
+	git_str path = GIT_STR_INIT, content = GIT_STR_INIT;
+	int error;
+
+	/*
+	 * As most references are per repository and not per worktree we don't
+	 * want to set up the typical "refs/" hierarchy in worktrees.
+	 */
+	if ((flags & GIT_REFDB_BACKEND_INIT_IS_WORKTREE) == 0) {
+		mode_t dmode;
+
+		if (mode == GIT_REPOSITORY_INIT_SHARED_UMASK)
+			dmode = 0777;
+		else if (mode == GIT_REPOSITORY_INIT_SHARED_GROUP)
+			dmode = (0775 | S_ISGID);
+		else if (mode == GIT_REPOSITORY_INIT_SHARED_ALL)
+			dmode = (0777 | S_ISGID);
+		else
+			dmode = mode;
+
+		if ((error = git_str_joinpath(&path, backend->gitpath, GIT_REFS_HEADS_DIR)) < 0 ||
+		    (error = git_futils_mkdir(path.ptr, dmode, 0) < 0) ||
+		    (error = git_str_joinpath(&path, backend->gitpath, GIT_REFS_TAGS_DIR)) < 0 ||
+		    (error = git_futils_mkdir(path.ptr, dmode, 0) < 0))
+			goto out;
+	}
+
+	if (head_target) {
+		if ((error = git_str_joinpath(&path, backend->gitpath, GIT_HEAD_FILE)) < 0)
+			goto out;
+
+		if ((flags & GIT_REFDB_BACKEND_INIT_FORCE_HEAD) == 0 &&
+		    git_fs_path_exists(path.ptr))
+			goto out;
+
+		if ((error = git_str_printf(&content, GIT_SYMREF "%s\n", head_target)) < 0 ||
+		    (error = git_futils_writebuffer(&content, path.ptr, 0, mode)) < 0)
+			goto out;
+	}
+
+	error = 0;
+
+out:
+	git_str_dispose(&content);
+	git_str_dispose(&path);
+
+	return error;
+}
+
 static int refdb_fs_backend__exists(
 	int *exists,
 	git_refdb_backend *_backend,
@@ -2545,6 +2599,7 @@ int git_refdb_backend_fs(
 		backend->fsync = 1;
 	backend->iterator_flags |= GIT_ITERATOR_DESCEND_SYMLINKS;
 
+	backend->parent.init = &refdb_fs_backend__init;
 	backend->parent.exists = &refdb_fs_backend__exists;
 	backend->parent.lookup = &refdb_fs_backend__lookup;
 	backend->parent.iterator = &refdb_fs_backend__iterator;
diff --git a/src/libgit2/repo_template.h b/src/libgit2/repo_template.h
@@ -45,8 +45,6 @@ typedef struct {
 static repo_template_item repo_template[] = {
 	{ GIT_OBJECTS_INFO_DIR, GIT_OBJECT_DIR_MODE, NULL }, /* '/objects/info/' */
 	{ GIT_OBJECTS_PACK_DIR, GIT_OBJECT_DIR_MODE, NULL }, /* '/objects/pack/' */
-	{ GIT_REFS_HEADS_DIR, GIT_REFS_DIR_MODE, NULL },     /* '/refs/heads/' */
-	{ GIT_REFS_TAGS_DIR, GIT_REFS_DIR_MODE, NULL },      /* '/refs/tags/' */
 	{ GIT_HOOKS_DIR, GIT_HOOKS_DIR_MODE, NULL },         /* '/hooks/' */
 	{ GIT_INFO_DIR, GIT_INFO_DIR_MODE, NULL },           /* '/info/' */
 	{ GIT_DESC_FILE, GIT_DESC_MODE, GIT_DESC_CONTENT },
diff --git a/src/libgit2/repository.c b/src/libgit2/repository.c
@@ -10,6 +10,7 @@
 #include <ctype.h>
 
 #include "git2/object.h"
+#include "git2/sys/refdb_backend.h"
 #include "git2/sys/repository.h"
 
 #include "buf.h"
@@ -2160,32 +2161,6 @@ void git_repository__free_extensions(void)
 	git_vector_dispose_deep(&user_extensions);
 }
 
-int git_repository_create_head(const char *git_dir, const char *ref_name)
-{
-	git_str ref_path = GIT_STR_INIT;
-	git_filebuf ref = GIT_FILEBUF_INIT;
-	const char *fmt;
-	int error;
-
-	if ((error = git_str_joinpath(&ref_path, git_dir, GIT_HEAD_FILE)) < 0 ||
-	    (error = git_filebuf_open(&ref, ref_path.ptr, 0, GIT_REFS_FILE_MODE)) < 0)
-		goto out;
-
-	if (git__prefixcmp(ref_name, GIT_REFS_DIR) == 0)
-		fmt = "ref: %s\n";
-	else
-		fmt = "ref: " GIT_REFS_HEADS_DIR "%s\n";
-
-	if ((error = git_filebuf_printf(&ref, fmt, ref_name)) < 0 ||
-	    (error = git_filebuf_commit(&ref)) < 0)
-		goto out;
-
-out:
-	git_str_dispose(&ref_path);
-	git_filebuf_cleanup(&ref);
-	return error;
-}
-
 static bool is_chmod_supported(const char *file_path)
 {
 	struct stat st1, st2;
@@ -2860,40 +2835,42 @@ static int repo_init_directories(
 	return error;
 }
 
-static int repo_init_head(const char *repo_dir, const char *given)
+static int get_initial_head(char **out, uint32_t *flags,
+			    git_repository_init_options *opts)
 {
-	git_config *cfg = NULL;
-	git_str head_path = GIT_STR_INIT, cfg_branch = GIT_STR_INIT;
+	git_str cfg_branch = GIT_STR_INIT, prefixed = GIT_STR_INIT;
 	const char *initial_head = NULL;
+	git_config *cfg = NULL;
 	int error;
 
-	if ((error = git_str_joinpath(&head_path, repo_dir, GIT_HEAD_FILE)) < 0)
-		goto out;
-
-	/*
-	 * A template may have set a HEAD; use that unless it's been
-	 * overridden by the caller's given initial head setting.
-	 */
-	if (git_fs_path_exists(head_path.ptr) && !given)
-		goto out;
-
-	if (given) {
-		initial_head = given;
-	} else if ((error = git_config_open_default(&cfg)) >= 0 &&
-	           (error = git_config__get_string_buf(&cfg_branch, cfg, "init.defaultbranch")) >= 0 &&
+	if (opts->initial_head) {
+		initial_head = opts->initial_head;
+		*flags |= GIT_REFDB_BACKEND_INIT_FORCE_HEAD;
+	} else if (git_config_open_default(&cfg) >= 0 &&
+	           git_config__get_string_buf(&cfg_branch, cfg, "init.defaultbranch") >= 0 &&
 	           *cfg_branch.ptr) {
 		initial_head = cfg_branch.ptr;
 	}
 
 	if (!initial_head)
 		initial_head = GIT_BRANCH_DEFAULT;
 
-	error = git_repository_create_head(repo_dir, initial_head);
+	if (git__prefixcmp(initial_head, GIT_REFS_DIR) != 0) {
+		git_str_printf(&prefixed, GIT_REFS_HEADS_DIR "%s", initial_head);
+		initial_head = prefixed.ptr;
+	}
+
+	if ((*out = git__strdup(initial_head)) == NULL) {
+		error = -1;
+		goto out;
+	}
+
+	error = 0;
 
 out:
-	git_config_free(cfg);
-	git_str_dispose(&head_path);
 	git_str_dispose(&cfg_branch);
+	git_str_dispose(&prefixed);
+	git_config_free(cfg);
 
 	return error;
 }
@@ -2928,11 +2905,14 @@ int git_repository_init_ext(
 	git_repository_init_options *opts)
 {
 	git_str repo_path = GIT_STR_INIT, wd_path = GIT_STR_INIT,
-		common_path = GIT_STR_INIT;
+		common_path = GIT_STR_INIT, path = GIT_STR_INIT;
 	const char *wd;
+	git_refdb *refdb;
 	bool is_valid;
 	git_oid_t oid_type = GIT_OID_DEFAULT;
 	git_refdb_t refdb_type = GIT_REFDB_FILES;
+	char *initial_head = NULL;
+	uint32_t refdb_init_flags = 0;
 	int error;
 
 	GIT_ASSERT_ARG(out);
@@ -2970,18 +2950,75 @@ int git_repository_init_ext(
 					      oid_type, refdb_type)) < 0)
 			goto out;
 
+		/*
+		 * If we are re-initializing an existing repository we only
+		 * want to reset HEAD in case the user explicitly provided a
+		 * new target.
+		 */
+		if (opts->initial_head &&
+		    (error = get_initial_head(&initial_head, &refdb_init_flags, opts)) < 0)
+			goto out;
+
 		/* TODO: reinitialize the templates */
 	} else {
+		git_str content = GIT_STR_INIT_CONST("ref: " GIT_INVALID_HEAD,
+						     strlen("ref: " GIT_INVALID_HEAD));
+		mode_t dmode = pick_dir_mode(opts);
+
 		if ((error = repo_init_structure(repo_path.ptr, wd, opts)) < 0 ||
 		    (error = repo_init_config(repo_path.ptr, wd, opts->flags, opts->mode,
-					      oid_type, refdb_type)) < 0 ||
-		    (error = repo_init_head(repo_path.ptr, opts->initial_head)) < 0)
+					      oid_type, refdb_type)) < 0)
+			goto out;
+
+		/*
+		 * Both HEAD and "refs/" must exist in a repository regardless
+		 * of its ref format, otherwise it won't be recognized as a Git
+		 * repository. As such, we create these now so that we can open
+		 * the repository and properly initialize its refdb.
+		 */
+		if ((error = git_str_joinpath(&path, repo_path.ptr, GIT_HEAD_FILE)) < 0)
+			goto out;
+
+		/* Only overwrite HEAD if it wasn't created by the template. */
+		if (!git_fs_path_exists(path.ptr)) {
+			if ((error = git_futils_writebuffer(&content, path.ptr, 0,
+							    GIT_REFS_FILE_MODE)) < 0)
+				goto out;
+
+			/*
+			 * Ask the backend to force-overwrite the invalid HEAD
+			 * we have just written.
+			 */
+			refdb_init_flags |= GIT_REFDB_BACKEND_INIT_FORCE_HEAD;
+		}
+
+		if ((error = git_str_joinpath(&path, repo_path.ptr, GIT_REFS_DIR)) < 0 ||
+		    (error = git_futils_mkdir(path.ptr, dmode, 0)) < 0)
+			goto out;
+
+		/*
+		 * Note that we also compute the initial HEAD in case the file
+		 * already exists. This is done because the file HEAD may not
+		 * actually be relevant to the backend. E.g. reftables do not
+		 * care for this file at all, so we would end up with no HEAD
+		 * at all if we didn't ask the backend to write one in that
+		 * case.
+		 *
+		 * That being said, we don't force-overwrite HEAD so that the
+		 * backends can first check whether the templates have already
+		 * created a HEAD.
+		 */
+		if ((error = get_initial_head(&initial_head, &refdb_init_flags, opts)) < 0)
 			goto out;
 	}
 
 	if ((error = git_repository_open(out, repo_path.ptr)) < 0)
 		goto out;
 
+	if ((error = git_repository_refdb__weakptr(&refdb, *out)) < 0 ||
+	    (error = git_refdb_init(refdb, initial_head, opts->mode, refdb_init_flags)) < 0)
+		goto out;
+
 	if (opts->origin_url &&
 	    (error = repo_init_create_origin(*out, opts->origin_url)) < 0)
 		goto out;
@@ -2990,6 +3027,8 @@ int git_repository_init_ext(
 	git_str_dispose(&common_path);
 	git_str_dispose(&repo_path);
 	git_str_dispose(&wd_path);
+	git_str_dispose(&path);
+	git__free(initial_head);
 
 	return error;
 }
diff --git a/src/libgit2/repository.h b/src/libgit2/repository.h
@@ -179,7 +179,6 @@ GIT_INLINE(git_attr_cache *) git_repository_attr_cache(git_repository *repo)
 
 int git_repository_head_commit(git_commit **commit, git_repository *repo);
 int git_repository_head_tree(git_tree **tree, git_repository *repo);
-int git_repository_create_head(const char *git_dir, const char *ref_name);
 
 typedef int (*git_repository_foreach_worktree_cb)(git_repository *, void *);
 
diff --git a/src/libgit2/worktree.c b/src/libgit2/worktree.c
