Hi,

this patch series refactors how we handle alternate object directories
so that the interface is structured around the object database source.

Next to being simpler to reason about, it also allows us to eventually
abstract handling of alternates to use different mechanisms based on the
specific backend used. In a world of pluggable object databases not
every backend may use a physical directory, so it may not be possible to
read alternates via "objects/info/alternates". Consequently, formats may
need a different mechanism entirely to make this list available.

Changes in v3:
  - Fix commit messages that still refer to `odb_add_source()`.
  - Fix intermediate commit that still refers to `odb_add_source()`.
  - Link to v2: https://lore.kernel.org/r/20251210-b4-pks-odb-alternates-via-source-v2-0-eb336815f9ab@pks.im (local)

Changes in v2:
  - Rename `odb_add_source()` to `odb_add_alternates_recursive()` to
    highlight that this function is recursive.
  - Link to v1: https://lore.kernel.org/r/20251208-b4-pks-odb-alternates-via-source-v1-0-e7ebb8b18c03@pks.im (local)

Thanks!

Patrick

---
Patrick Steinhardt (8):
      odb: refactor parsing of alternates to be self-contained
      odb: resolve relative alternative paths when parsing
      odb: move computation of normalized objdir into `alt_odb_usable()`
      odb: stop splitting alternate in `odb_add_to_alternates_file()`
      odb: remove mutual recursion when parsing alternates
      odb: drop forward declaration of `read_info_alternates()`
      odb: read alternates via sources
      odb: write alternates via sources

 odb.c | 307 ++++++++++++++++++++++++++++++++++--------------------------------
 1 file changed, 158 insertions(+), 149 deletions(-)

Range-diff versus v2:

1:  74d2596ef6 = 1:  4a85139a75 odb: refactor parsing of alternates to be self-contained
2:  16d6e482d7 = 2:  1b16c0a164 odb: resolve relative alternative paths when parsing
3:  16cce7f52e = 3:  ceb6e8494c odb: move computation of normalized objdir into `alt_odb_usable()`
4:  b8a7138a51 ! 4:  99dbd11c48 odb: adapt `odb_add_to_alternates_file()` to call `odb_add_source()`
    @@ Metadata
     Author: Patrick Steinhardt [off-list ref]
     
      ## Commit message ##
    -    odb: adapt `odb_add_to_alternates_file()` to call `odb_add_source()`
    +    odb: stop splitting alternate in `odb_add_to_alternates_file()`
     
         When calling `odb_add_to_alternates_file()` we know to add the newly
         added source to the object database in case we have already loaded
    @@ Commit message
         callers only ever pass a single directory to it. It's thus entirely
         surprising and a conceptual mismatch.
     
    -    Fix this issue by directly calling `odb_add_source()` instead.
    +    Fix this issue by directly calling `odb_add_alternate_recursively()`
    +    instead.
     
         Signed-off-by: Patrick Steinhardt [off-list ref]
     
    @@ odb.c: void odb_add_to_alternates_file(struct object_database *odb,
      			die_errno(_("unable to move new alternates file into place"));
      		if (odb->loaded_alternates)
     -			link_alt_odb_entries(odb, dir, '\n', NULL, 0);
    -+			odb_add_source(odb, dir, 0);
    ++			odb_add_alternate_recursively(odb, dir, 0);
      	}
      	free(alts);
      }
5:  2b2d4788bf ! 5:  b9300667a6 odb: remove mutual recursion when parsing alternates
    @@ Commit message
     
           2. `link_alt_odb_entries()` calls `parse_alternates()`.
     
    -      3. We then add each parsed alternate via `odb_add_source()`.
    +      3. We then add each alternate via `odb_add_alternate_recursively()`.
     
    -      4. `odb_add_source()` calls `link_alt_odb_entries()` again.
    +      4. `odb_add_alternate_recursively()` calls `link_alt_odb_entries()`
    +         again.
     
         This flow is somewhat hard to follow, but more importantly it means that
         parsing of alternates is somewhat tied to the recursive behaviour.
    @@ odb.c: static void read_info_alternates(struct object_database *odb,
      	strbuf_release(&buf);
      	free(path);
      }
    -@@ odb.c: void odb_add_to_alternates_file(struct object_database *odb,
    - 		if (commit_lock_file(&lock))
    - 			die_errno(_("unable to move new alternates file into place"));
    - 		if (odb->loaded_alternates)
    --			odb_add_source(odb, dir, 0);
    -+			odb_add_alternate_recursively(odb, dir, 0);
    - 	}
    - 	free(alts);
    - }
     @@ odb.c: int odb_for_each_alternate(struct object_database *odb,
      
      void odb_prepare_alternates(struct object_database *odb)
6:  3294336d85 = 6:  1e3a1fb081 odb: drop forward declaration of `read_info_alternates()`
7:  55ba5815d4 = 7:  1d6a9b3c1b odb: read alternates via sources
8:  225bcc37de ! 8:  79a053fb2b odb: write alternates via sources
    @@ Commit message
         allow us to have different logic for writing alternates depending on the
         backend used.
     
    -    Note that after the refactoring we start to call `odb_add_source()`
    -    unconditionally. This is fine though as we know to skip adding sources
    -    that are tracked already.
    +    Note that after the refactoring we start to call
    +    `odb_add_alternate_recursively()` unconditionally. This is fine though
    +    as we know to skip adding sources that are tracked already.
     
         Signed-off-by: Patrick Steinhardt [off-list ref]
     

---
base-commit: bdc5341ff65278a3cc80b2e8a02a2f02aa1fac06
change-id: 20251206-b4-pks-odb-alternates-via-source-802d87cbbda5