Hi,

this patch series is the next set of refactorings to simplify how we
configure repositories in "setup.c".

The setup of the repository is essentially happening in two phases:

  1. We discover the location of the repository as well as its format.

  2. We then use this information to configure the repository.

So far so sensible. In our code base though these two phases are quite
intertwined with one another, as we continue to repeatedly call
`set_git_dir()` and `set_work_tree()` on the repository as we discover
its locations. This makes it hard to follow the logic, and it basically
leaves us with a partially-configured repository.

This patch series splits this up into two proper phases that are
completely separate from one another. The first phase now populates a
`struct repo_discovery` structure, without even having access to any
repository. The second phase then takes that structure and configures
the repository accordingly.

Ultimately, the motivation of this whole exercise is that eventually we
can unify configuration of the repository into `repo_init()` instead of
having bits and pieces thereof distributed across "repository.c" and
"setup.c".

This series is built on top of v2.55.0 with the following three branches
merged into it:

  - ps/refs-onbranch-fixes at d6522d01df (refs: protect against
    chicken-and-egg recursion, 2026-06-25).

  - ps/setup-drop-global-state at 1ceee7431b (treewide: drop
    USE_THE_REPOSITORY_VARIABLE, 2026-06-11).

  - jk/repo-info-path-keys at 3ac28d832a (repo: add path.gitdir with
    absolute and relative suffix formatting, 2026-06-24).

Changes in v2:
  - Expand commit message to talk about precedence order between
    the "GIT_SHALLOW_FILE" environment variable and the "--shallow-file"
    command line switch.
  - Remove a now-unused parameter in `set_alternate_shallow_file()`.
  - Fix a typo.
  - Link to v1: https://patch.msgid.link/20260630-pks-setup-split-discovery-and-setup-v1-0-13864eb5a032@pks.im

Thanks!

Patrick

---
Patrick Steinhardt (13):
      setup: rename `check_repository_format_gently()`
      setup: mark bogus worktree in `apply_repository_format()`
      setup: unify setup of shallow file
      setup: split up concerns of `setup_git_env_internal()`
      setup: introduce explicit repository discovery
      setup: embed repository format in discovery
      setup: move prefix into repository
      setup: drop static `cwd` variable
      setup: propagate prefix via repository discovery
      setup: make repository discovery self-contained
      setup: drop redundant configuration of `startup_info->have_repository`
      setup: pass worktree to `init_db()`
      setup: mark `set_git_work_tree()` as file-local

 builtin/clone.c        |   8 +-
 builtin/init-db.c      |  34 ++--
 builtin/repo.c         |   8 +-
 builtin/rev-parse.c    |   5 +-
 builtin/update-index.c |   4 +-
 common-init.c          |  20 +++
 git.c                  |   2 +-
 object-name.c          |   4 +-
 repository.c           |   1 +
 repository.h           |   8 +
 setup.c                | 419 ++++++++++++++++++++++++++-----------------------
 setup.h                |   7 +-
 shallow.c              |   4 +-
 shallow.h              |   2 +-
 trace.c                |   4 +-
 15 files changed, 285 insertions(+), 245 deletions(-)

Range-diff versus v1:

 1:  19230b18cf =  1:  f4db0a6a10 setup: rename `check_repository_format_gently()`
 2:  246e8caf8f !  2:  72f51e01ff setup: mark bogus worktree in `apply_repository_format()`
    @@ setup.c: static const char *setup_explicit_git_dir(struct repository *repo,
     +		 * The environment variable overrides "core.worktree". This
     +		 * also has the consequence that we don't want to flag cases as
     +		 * bogus where we have both "core.worktree" and "core.bare", so
    -+		 * we have to exlicitly unset the configuration.
    ++		 * we have to explicitly unset the configuration.
     +		 */
     +		FREE_AND_NULL(repo_fmt->work_tree);
      		set_git_work_tree(repo, work_tree_env);
 3:  06ea13242f !  3:  1542e52523 setup: unify setup of shallow file
    @@ Commit message
         of this patch series. Consequently, it will become possible for us to
         completely discard `the_repository` and populate it anew.
     
    +    Note that on first sight, this change looks like it might change the
    +    precedence order. Before this change, we used to configure the shallow
    +    file in the arguments handler first, and then it looks like we override
    +    it via the environment variable. What's important to note though is the
    +    last parameter to `set_alternate_shallow_file()`, which tells us whether
    +    we want to overwrite a preexisting value, and when applying the value
    +    from the environment we tell it not to overwrite preexisting values. So
    +    in effect, the command line has precedence over the environment. After
    +    this change, we now overwrite preexisting environment variables when we
    +    see the argument, and consequently we keep the precedence order in tact.
    +
    +    With this change though we don't need the final parameter anymore that
    +    tells `set_alternate_shallow_file()` whether or not to overwrite. We
    +    only have a single callsite for this function now, and that function is
    +    itself only ever called exactly once. Remove that parameter.
    +
         Signed-off-by: Patrick Steinhardt [off-list ref]
     
      ## git.c ##
    @@ setup.c: int apply_repository_format(struct repository *repo,
      		alternate_object_directories = xstrdup_or_null(getenv(ALTERNATE_DB_ENVIRONMENT));
     +		shallow_file = getenv(GIT_SHALLOW_FILE_ENVIRONMENT);
     +		if (shallow_file)
    -+			set_alternate_shallow_file(repo, shallow_file, 0);
    ++			set_alternate_shallow_file(repo, shallow_file);
      	}
      
      	repo->bare_cfg = format->is_bare;
    +
    + ## shallow.c ##
    +@@
    + #include "statinfo.h"
    + #include "trace.h"
    + 
    +-void set_alternate_shallow_file(struct repository *r, const char *path, int override)
    ++void set_alternate_shallow_file(struct repository *r, const char *path)
    + {
    + 	if (r->parsed_objects->is_shallow != -1)
    + 		BUG("is_repository_shallow must not be called before set_alternate_shallow_file");
    +-	if (r->parsed_objects->alternate_shallow_file && !override)
    +-		return;
    + 	free(r->parsed_objects->alternate_shallow_file);
    + 	r->parsed_objects->alternate_shallow_file = xstrdup_or_null(path);
    + }
    +
    + ## shallow.h ##
    +@@
    + struct oid_array;
    + struct strvec;
    + 
    +-void set_alternate_shallow_file(struct repository *r, const char *path, int override);
    ++void set_alternate_shallow_file(struct repository *r, const char *path);
    + int register_shallow(struct repository *r, const struct object_id *oid);
    + int unregister_shallow(const struct object_id *oid);
    + int is_repository_shallow(struct repository *r);
 4:  add8007726 =  4:  5a2b4132a1 setup: split up concerns of `setup_git_env_internal()`
 5:  4bc374b957 !  5:  8190a24acf setup: introduce explicit repository discovery
    @@ setup.c: static void apply_and_export_relative_gitdir(struct repository *repo, c
      	int offset;
      
     @@ setup.c: static const char *setup_explicit_git_dir(struct repository *repo,
    - 		 * we have to exlicitly unset the configuration.
    + 		 * we have to explicitly unset the configuration.
      		 */
      		FREE_AND_NULL(repo_fmt->work_tree);
     -		set_git_work_tree(repo, work_tree_env);
 6:  687443fcac !  6:  869b6cf7cb setup: embed repository format in discovery
    @@ setup.c: static const char *repo_discover_explicit_gitdir(struct repo_discovery
      	}
     @@ setup.c: static const char *repo_discover_explicit_gitdir(struct repo_discovery *discover
      		 * bogus where we have both "core.worktree" and "core.bare", so
    - 		 * we have to exlicitly unset the configuration.
    + 		 * we have to explicitly unset the configuration.
      		 */
     -		FREE_AND_NULL(repo_fmt->work_tree);
     +		FREE_AND_NULL(discovery->format.work_tree);
 7:  6e2e1caf30 =  7:  af482fd82c setup: move prefix into repository
 8:  9dda7f521b =  8:  8ad046bc79 setup: drop static `cwd` variable
 9:  4fc0bbd6a2 =  9:  231c98255b setup: propagate prefix via repository discovery
10:  54ddf6a854 = 10:  ee241b765d setup: make repository discovery self-contained
11:  46dbc1ac4c = 11:  4fa953a970 setup: drop redundant configuration of `startup_info->have_repository`
12:  c42085145a = 12:  4299a4aadb setup: pass worktree to `init_db()`
13:  9a9a4dea01 = 13:  1add08fce7 setup: mark `set_git_work_tree()` as file-local

---
base-commit: b340fc4c4f3850656b726ff757b42d2020215378
change-id: 20260618-pks-setup-split-discovery-and-setup-d7f23831803c