Proxy Routing for Git Submodules

A successful clone of the main repository does not test its submodules. A submodule is another Git repository, possibly on another host and possibly using another transport.

Start by reading the declared URLs:

git -C project config --file .gitmodules --get-regexp '^submodule\..*\.url$'
git -C project submodule status --recursive

A parent fetched over HTTPS can contain a submodule using git@host:. An HTTP proxy setting does not configure that SSH connection. Relative submodule URLs also need to be resolved against the superproject's appropriate remote, not against whichever web address you assumed from the project name.

Repository-local settings have a scope

A local http.proxy entry belongs to the repository whose configuration file contains it. Do not assume that inspecting only the parent tells you every effective setting used inside an initialized child repository.

For a temporary HTTPS proxy override across a recursive update, Git's command-line configuration can be supplied to that invocation:

git -C project -c http.proxy=http://203.0.113.10:8080 \
  submodule update --init --recursive

Replace the example endpoint. For public HTTPS submodules on a route that permits public proxies, the HTTP proxy list supplies candidate addresses. This does not convert SSH submodule URLs to HTTPS, and a more specific URL-based configuration still deserves inspection when the selected route is surprising.

When the recorded URL changed

Git registers submodule configuration locally during initialization. If the project's submodule URL has changed, compare the current declaration with the locally registered value before deciding that a proxy is dead. The documented sync operation updates registered URLs from the project declaration; it is not a network-proxy setting itself.

For nested failures, note the exact submodule path and remote named in the error. A recursive operation may contact several hosts, and an internal host may require a direct exception while a public host uses the proxy.

Keep transport errors separate from repository errors. An unavailable commit, access denied by the repository, and a failed connection to the proxy are different reasons for the same high-level “submodule update failed” result.