[PATCH v4 0/9] odb: write alternates at creation time

Hi,

writing alternates into the object database currently happens via
`odb_source_write_alternate()`. But while that creates the ability to
create alternates at arbitrary points of a source's lifetime, we don't
use that functionality in the first place. Instead, we only ever write
alternates when creating a new repository.

This design is suboptimal due to a couple of reasons:

  - It requires us to have a `write_alternates()` callback, which is
    overblown as we never even write alternates to an object database
    after it has been created.

  - We're about to make alternates an implementation detail of the
    object database's backend in a future patch series, so alternate
    implementations may not even support them.

  - The backend has more flexibility with how exactly alternates are
    configured when it itself is in full control over their setup at the
    time where it creates the object database itself.

This patch series thus refactors how we handle alternates so that we
don't write them ad-hoc anymore. Instead, the series introduces a new
option for `odb_source_create_on_disk()` that makes it handle those
alternates at creation time.

This is part of the bigger goal of moving handling of alternates into
the "files" backend.

This series is built on top of 2c3adbb2c4 (The 18th batch, 2026-08-24)
with ps/odb-eagerly-load-alternates at 0076dc9f81 (odb: drop
`alternates_db` field, 2026-08-17) merged into it.

Changes in v4:
  - Add documentation for the different functions that play a role in
    creating repositories.
  - Link to v3: https://patch.msgid.link/20260907-pks-odb-write-alternates-at-creation-time-v3-0-735d0b5b3e00@pks.im

Changes in v3:
  - Refactor `init_db()` to not create the reference and object database
    at all anymore. Instead, it's now called `create_repository()` and
    it is responsible for creating the initial repository skeleton,
    only. This allows us to get rid of the flags and overall makes the
    logic more straight-forward by moving the command-specific logic
    into the respective commands.
  - A couple of typo fixes.
  - Link to v2: https://patch.msgid.link/20260831-pks-odb-write-alternates-at-creation-time-v2-0-aecd2382ba1c@pks.im

Changes in v2:
  - Use a lockfile to write "info/alternates" during creation time.
  - Remove useless "strvec.h" include by reordering declarations a bit.
  - Link to v1: https://patch.msgid.link/20260825-pks-odb-write-alternates-at-creation-time-v1-0-911513ba95c3@pks.im

Thanks!

Patrick

---
Patrick Steinhardt (9):
      setup: split up concerns of `init_db()`
      builtin/clone: defer setup of the object database
      builtin/clone: move around `setup_reference()`
      builtin/clone: refactor handling of "--reference{,-if-able}"
      builtin/clone: move setup of alternates for shared local clones
      builtin/clone: move setup of alternates for non-shared local clones
      odb/source: support writing alternates when creating the database
      builtin/clone: write alternates via `odb_create_on_disk()`
      odb/source: remove the ability to write alternates

 builtin/clone.c            | 111 +++++++++++++++++++++++---------------
 builtin/init-db.c          |  32 ++++++++---
 odb.c                      |   9 ----
 odb.h                      |   7 ---
 odb/source-files.c         | 130 ++++++++++++++++++++++++++-------------------
 odb/source-inmemory.c      |   7 ---
 odb/source-loose.c         |   7 ---
 odb/source-packed.c        |   7 ---
 odb/source.h               |  43 +++++----------
 setup.c                    |  61 ++++++++-------------
 setup.h                    |  47 +++++++++++-----
 t/t5604-clone-reference.sh |  25 +++++++++
 12 files changed, 264 insertions(+), 222 deletions(-)

Range-diff versus v3:

 1:  b0e8d52235 !  1:  e6a17864eb setup: split up concerns of `init_db()`
    @@ setup.h: int apply_repository_format(struct repository *repo,
     -	    enum ref_storage_format ref_storage_format,
     -	    const char *initial_branch, int init_shared_repository,
     -	    unsigned int flags);
    ++/*
    ++ * Create the repository by creating the necessary directory structures,
    ++ * setting up the configuration and configuring the repository's format. If
    ++ * `template_dir` is set, copy over templates from that directory. Furthermore,
    ++ * if and only if `reinit_ok` is a non-NULL pointer, then the function may
    ++ * reinitialize a preexisting repository. In that case, the pointer will be set
    ++ * to `1` in case the repo was reinitialized and `0` if it didn't exist yet.
    ++ *
    ++ * Note that this function does not create the reference and object databases.
    ++ */
     +void create_repository(struct repository *repo,
     +		       const char *git_dir,
     +		       const char *real_git_dir,
    @@ setup.h: int apply_repository_format(struct repository *repo,
     +		       enum ref_storage_format ref_storage_format,
     +		       int init_shared_repository,
     +		       int *reinit_ok);
    ++
      void initialize_repository_version(struct repository *repo,
      				   int hash_algo,
      				   enum ref_storage_format ref_storage_format,
      				   int reinit);
    ++
    ++/*
    ++ * Create the reference database for the repository. The repository and its ref
    ++ * storage format must have already been configured properly before calling
    ++ * this function. When set, `initial_branch` overrides the default branch that
    ++ * HEAD will point to.
    ++ */
      void create_reference_database(struct repository *repo, const char *initial_branch, int quiet);
    -+void create_object_database(struct repository *repo);
      
    ++/*
    ++ * Create the object database for the repository. The repository must have
    ++ * already been configured properly before calling this function.
    ++ */
    ++void create_object_database(struct repository *repo);
    ++
      /*
       * NOTE NOTE NOTE!!
    +  *
 2:  4fc3a45d2d =  2:  45ae2231ad builtin/clone: defer setup of the object database
 3:  fd875b60b9 =  3:  92f00f1905 builtin/clone: move around `setup_reference()`
 4:  1ca710255b =  4:  b6860d41fb builtin/clone: refactor handling of "--reference{,-if-able}"
 5:  08a3a7a682 =  5:  070558b0b8 builtin/clone: move setup of alternates for shared local clones
 6:  afe84c063b =  6:  8e767a103a builtin/clone: move setup of alternates for non-shared local clones
 7:  8f0d3b13d5 =  7:  39ee1b828d odb/source: support writing alternates when creating the database
 8:  75d1e1e34c !  8:  531152ee93 builtin/clone: write alternates via `odb_create_on_disk()`
    @@ setup.c: static int create_default_files(struct repository *repo,
      	 * Create the "objects" directory in the common directory. This is done
     
      ## setup.h ##
    -@@ setup.h: void initialize_repository_version(struct repository *repo,
    - 				   enum ref_storage_format ref_storage_format,
    - 				   int reinit);
    - void create_reference_database(struct repository *repo, const char *initial_branch, int quiet);
    +@@ setup.h: void create_reference_database(struct repository *repo, const char *initial_bran
    + 
    + /*
    +  * Create the object database for the repository. The repository must have
    +- * already been configured properly before calling this function.
    ++ * already been configured properly before calling this function. When set,
    ++ * `alternates` is the list of alternates that should be written into the
    ++ * object database.
    +  */
     -void create_object_database(struct repository *repo);
     +void create_object_database(struct repository *repo, const struct strvec *alternates);
      
 9:  a674c3af3c =  9:  25bd93544e odb/source: remove the ability to write alternates

---
base-commit: afa255aeb620346d56a2c01fb5ae9163513c56d7
change-id: 20260813-pks-odb-write-alternates-at-creation-time-64010deb94a0