Finding the repository without git

How the repo and worktree scopes decide which repository a caller is in, why that no longer runs git, and what was decided for every layout git understands.

created:      2026-09-30T07:30:00-05:00
last-updated: 2026-09-30T07:30:00-05:00
status:       implemented

This is the decision record for the change. docs/container.md §3 is the short version; it lives here rather than under docs/decisions/ because that directory belongs to another area.

1. Two questions

A server scoped repo gets one process per clone – every linked worktree of one repository shares it. A server scoped worktree gets one per checkout. The keys are the answers to two questions git already has commands for:

Until this change mcpx asked exactly those, by forking git twice per directory and caching both answers – negative ones included – for the daemon’s lifetime. That had four costs, three of which were only found by testing the replacement:

1. 105 MB of the container image. Debian’s git depends on perl outright.
2. It did not work in the container anyway. A checkout mounted into the image is owned by the host’s uid, the image runs as uid 1000, and git refuses a repository someone else owns (safe.directory). Every mounted checkout, measured: fatal: detected dubious ownership in repository at '/work/proj'. The old image shipped git so that these scopes would work, and in the ordinary way of using it they fell back to per-directory keys.
3. The daemon’s environment leaked into every caller’s key. An autostarted daemon inherits the environment of whoever ran mcpx first. A git hook exports GIT_DIR; a hook that runs mcpx leaves a daemon carrying it for hours. With GIT_DIR absolute, every later caller – from any directory – was keyed to that one repository. With GIT_DIR=.git, as hooks set it, every caller outside a repository root degraded. Both are pinned by TestTheDaemonsOwnGitDirDoesNotPinEveryCaller, which fails against the old code.
4. The cache made the first answer permanent. A directory that became a repository after the first call there stayed “not a repository” until the daemon exited.

2. How it works now

Finding a repository is a walk up the directory tree reading a handful of small files. Git’s rules for that walk are fixed, and they are in its source: setup.c (setup_git_directory_gently_1, read_gitfile_gently, is_git_directory, check_repository_format_gently, the three setup_*_git_dir functions) and the config parser in config.c. internal/config/gitdiscover.go and gitformat.go are a port of those, from git v2.55.0, function by function and named after the originals so the two can be read side by side.

At each directory, starting from the caller’s cwd with every symlink resolved (git starts from getcwd(), which has already resolved them):

1. .git – a directory that is a repository, or a file naming one;
2. the directory itself, as a bare repository;
3. the parent, unless a ceiling or a filesystem boundary says stop.

Once found, the common directory comes from the commondir file if there is one, and the worktree from where .git was found – unless the repository’s config says otherwise through core.bare or core.worktree.

Native discovery reads HEAD, commondir, a .git file, and from config three keys – core.repositoryformatversion, core.bare, core.worktree – plus whatever extensions.* holds, since an unknown extension is what makes a repository unreadable. When extensions.worktreeConfig is on it reads the worktree’s config.worktree as well. It tests objects/ and refs/ for existence without reading them, which is the rest of what is_git_directory decides on. Nothing else, and it executes nothing.

Every outcome is one of four:

Git is the fallback only for “unsure”. It is asked once, as git rev-parse --path-format=absolute --git-common-dir --show-toplevel: the first answer is printed before the second fails, so a bare repository still yields its common directory from one process. It runs with git’s own list of repository-local variables removed (GIT_DIR, GIT_WORK_TREE, GIT_COMMON_DIR, GIT_OBJECT_DIRECTORY and eleven more – git rev-parse --local-env-vars), so it answers the question native discovery answers. With no git on PATH, “unsure” keys by directory, and the reason says what could not be read and that git is not there to ask.

Nothing is cached. One resolution five directories deep costs 0.073–0.081 ms (BenchmarkDiscoverGit, -benchtime 300x -count=5, M3 Pro / macOS / APFS); forking git rev-parse --show-toplevel from the same place costs 9.7 ms on the same machine, so the native answer is about 125× cheaper. A cache would save under a tenth of a millisecond per call and bring back the stale answers of §1.4.

mcpx doctor reports what the two scopes resolve to from the current directory and what resolved them. A missing git is not a warning; it becomes one only when a repository here needs it.

3. Every case, and what was decided

“Parity” means the case is built with the real git and native’s answer is compared with git rev-parse for both questions. Test names are in internal/config/gitdiscover_test.go unless marked e2e.

Checkouts

Git directories

.git files and entries git refuses

Git stops at these rather than skipping them, so mcpx does too – skipping would find the enclosing repository and share its instance. Every one is built inside a real repository so that skipping would be caught.

The repository’s config

Environment

Deliberate differences from git

Windows is not handled: drive letters, \, and //server/share ceilings are not ported, because mcpx does not build there (internal/runner uses Setpgid and Kill).

4. How it was tested

Parity. 54 subtests in six TestGitParity* functions build repositories with the real git in a fenced temporary root – GIT_CEILING_DIRECTORIES at its parent, a private global config, no system config, none of the local variables – and compare native discovery with git rev-parse for both questions. A case that expects git to refuse first checks that it does, so a fixture that accidentally built a valid repository cannot pass as a refusal. They skip only when git is absent (the Nix sandbox) or older than a feature they need. With git 2.55 on macOS none skip; with Debian’s git 2.39 on Linux (the golang:*-bookworm builder image, as a non-root user) 52 pass and the two needing 2.45 and 2.48 skip. That run found the one portability gap so far: git 2.39 counts GIT_INTERNAL_SUPER_PREFIX as repository-local and newer git does not, so the scrub list is the union.

Without git. TestScopesResolveWithoutGit and three siblings clear PATH and build repositories by hand – HEAD, objects/, refs/, and the two files git worktree add writes – so they run in the Nix sandbox too. The e2e TestRepoAndWorktreeScopesResolveWithNoGitInstalled does the same through the real binary and a live daemon, with call and exec, and reads the keys from mcpx status and the answer from mcpx doctor.

Falsified. Every test that asserts new behaviour was run against code without it:

• The three e2e tests, against the unchanged origin/main: all fail, for the reasons they name (keys are cwd: without git; every caller keyed to other/.git under an absolute GIT_DIR; the shared instance gone after an exec).
• The unit tests, by mutation: 44 single-line changes to the port – the walk order, the ceiling arithmetic, each gitfile refusal, each HEAD rule, has_common, the config parser’s quoting, trimming and subsections, the format checks, the environment scrub – each run against the suite on the final code. 41 are killed, each by a named test. The three that survive cannot change behaviour: two treat relative GIT_CEILING_DIRECTORIES entries differently, but a relative entry can never be a prefix of the absolute path discovery walks; the third reads the fallback’s second line even when git fails, and git prints no second line when it fails. Five mutations first written so that they did not compile were rewritten, since a compile error proves nothing about a test. The first runs found five gaps, now covered: the order of the .git and bare checks at one level, a section whose subsection is core, HEAD values that are almost valid, a .git that cannot be stat’d, and a .git file over the size ceiling.

In the image. §3 of docs/container.md, “No git”.

5. Found along the way

• A sessionless mcpx exec stopped every shared instance it touched. CallContext.CallerOwned returned true for any key when the session was ephemeral, so the release at the end of a run stopped the global, repo and worktree instances too – contradicting ReleaseCaller’s own comment. Fixed in scope.go: an ephemeral caller owns its session’s key and its pid’s key, nothing shared. TestOnlyKeysTheCallerMintedAreCallerOwned, e2e TestASessionlessExecLeavesASharedInstanceRunning.
• The degraded-scope log line says “per-call” when the key is the directory: #191. Not fixed here; internal/daemon/registry.go is another area’s.
• Debian bookworm’s git (2.39) refuses a checkout made by a current git that used worktree.useRelativePaths: unknown repository extension found: relativeworktrees. Native discovery reads it, so the image is now more capable than the git it used to ship.