Written by Claude (Claude Code) on behalf of Matt Edmondson. The analysis and proposed shape below are Claude's, filed at Matt's request.
There is no way to check out the commits a superproject's gitlinks record, which is the operation git submodule update --init --recursive performs. grep -rn 'submodule' GitIntegration --include='*.cs' (excluding obj/) returns nothing.
Assumes submodules are now in scope for the local layer — see the submodule listing issue for the scope note.
Suggested shape
git submodule update produces only human prose, with no porcelain alternative. Per CLAUDE.md architecture point 8, that means it returns GitCompleted rather than a parsed result, exactly as Pull does. A caller who needs to know what moved asks Submodules() before and after.
IGitSubmoduleUpdateBuilder : IGitCommandBuilder<GitCompleted> in Builders/.- Options, each mapping to one git flag:
Initialise() (--init), Recursive() (--recursive), FromRemote() (--remote, which uses the branch configured in .gitmodules instead of the recorded gitlink), Force() (--force), and WithDepth(int) (--depth) to match GitFetchBuilder and GitCloneBuilder.
ReportingProgress(IProgress<string>), since this is a network operation and the three existing network verbs (Fetch, Clone, Push) all offer it.GitRepository.UpdateSubmodules().
The partial-state outcome deserves explicit documentation
A submodule update that fails after the superproject has already advanced leaves the repository in a state that is neither the old one nor the intended new one: the branch has moved, and one or more submodules are on the wrong commit. A caller that reports only the submodule failure implies the repository is untouched, which is wrong and actively misleading.
GitCommandException carries enough for a caller to act (exit code, argument vector, diagnostic), so a dedicated exception type is probably unnecessary. But the builder's remarks should state plainly that a failure here does not imply the superproject is unchanged, in the same spirit as GitPushBuilder's remarks explaining why its two entry points diverge. Without that note, the natural reading of an exception is "nothing happened", and here that reading is false.
Interaction with --recurse-submodules
pull --recurse-submodules and this verb overlap but are not equivalent: the flag updates submodules as part of the pull, whereas this verb also initialises newly added ones (--init), which the flag does on its own only from git 2.13 onward and only for submodules already registered in .gitmodules. Both are worth having. See the --recurse-submodules issue.
Written by Claude (Claude Code) on behalf of Matt Edmondson. The analysis and proposed shape below are Claude's, filed at Matt's request.
There is no way to check out the commits a superproject's gitlinks record, which is the operation
git submodule update --init --recursiveperforms.grep -rn 'submodule' GitIntegration --include='*.cs'(excludingobj/) returns nothing.Assumes submodules are now in scope for the local layer — see the submodule listing issue for the scope note.
Suggested shape
git submodule updateproduces only human prose, with no porcelain alternative. PerCLAUDE.mdarchitecture point 8, that means it returnsGitCompletedrather than a parsed result, exactly asPulldoes. A caller who needs to know what moved asksSubmodules()before and after.IGitSubmoduleUpdateBuilder : IGitCommandBuilder<GitCompleted>inBuilders/.Initialise()(--init),Recursive()(--recursive),FromRemote()(--remote, which uses the branch configured in.gitmodulesinstead of the recorded gitlink),Force()(--force), andWithDepth(int)(--depth) to matchGitFetchBuilderandGitCloneBuilder.ReportingProgress(IProgress<string>), since this is a network operation and the three existing network verbs (Fetch,Clone,Push) all offer it.GitRepository.UpdateSubmodules().The partial-state outcome deserves explicit documentation
A submodule update that fails after the superproject has already advanced leaves the repository in a state that is neither the old one nor the intended new one: the branch has moved, and one or more submodules are on the wrong commit. A caller that reports only the submodule failure implies the repository is untouched, which is wrong and actively misleading.
GitCommandExceptioncarries enough for a caller to act (exit code, argument vector, diagnostic), so a dedicated exception type is probably unnecessary. But the builder's remarks should state plainly that a failure here does not imply the superproject is unchanged, in the same spirit asGitPushBuilder's remarks explaining why its two entry points diverge. Without that note, the natural reading of an exception is "nothing happened", and here that reading is false.Interaction with
--recurse-submodulespull --recurse-submodulesand this verb overlap but are not equivalent: the flag updates submodules as part of the pull, whereas this verb also initialises newly added ones (--init), which the flag does on its own only from git 2.13 onward and only for submodules already registered in.gitmodules. Both are worth having. See the--recurse-submodulesissue.