Hi,

I have a question about submodules and SSH authentication during the initial git submodule update --init step.

I understand that there are already a few ways to influence SSH behavior:

core.sshCommand at the repository level

GIT_SSH_COMMAND at the command level

SSH host aliases and other settings in ~/.ssh/config

However, I am running into a more specific problem with submodules.

My use case is that different submodules may need different SSH identities or different SSH command settings. For an already initialized submodule, this can be handled by entering the submodule repository and configuring it separately. But during the initial git submodule update --init, the submodule does not yet have its own local config, so there does not seem to be a clean per-submodule way to do this from Git itself.

In practice, the usual workaround seems to be putting the logic into SSH configuration and encoding it through host aliases or URL layout. That works, but it also means the authentication behavior is kept outside Git's submodule configuration, even though the submodule remote itself is already configured in Git.

So my questions are:

Is there already a recommended Git-native way to handle different sshCommand values for different submodules during initial clone/update?

If not, would support for something like a per-submodule sshCommand configuration be considered reasonable?

Has this been discussed before specifically in the context of submodule initialization, rather than per-remote SSH options in general?

I am not sending a patch yet. I first wanted to ask whether this is considered a real gap in current submodule behavior, or whether the expectation is that SSH configuration should remain the only solution here.

Best regards, Shibo Xia

Shibo Xia <sbxia25@gmail.com> writes:

Would it help to do "submodule init" separately from "submodule update"? Then you have a chance to tweak the submodule.*.url configuration items in the superproject repository before the clone actually happens, I would imagine?

Hi,

Yes, that would help as a workaround.

If I understand correctly, the idea would be to run:

git submodule init

then adjust submodule.<name>.url entries in the superproject config before the actual clone happens, and only then run:

git submodule update

That does seem workable.

My concern is that this still solves the problem indirectly through URL rewriting / SSH host aliasing, rather than allowing the submodule's SSH behavior itself to be configured more directly.

So I think this answers the practical "how can this be done today?" part, but I am still wondering whether there is a reason Git should not support a more direct per-submodule sshCommand-style configuration.

Thanks, Shibo Xia

Junio C Hamano <gitster@pobox.com> 于2026年4月14日周二 00:02写道：

On Tue, Apr 14, 2026 at 09:28:20AM +0800, Shibo Xia wrote:

For arbitrary per-submodule config, I can think of two approaches:

One is conditional includeIf directives in your ~/.gitconfig, matching based on the submodule names. Like:

  # replace PARENT and SUBMODULE with your filesystem names
  [includeIf "gitdir:**/PARENT/.git/modules/SUBMODULE"]
  path = .gitconfig-submodule

and then in ~/.gitconfig-submodule, you'd have:

  [core]
  sshCommand = whatever

This works, but it's kind of gross, as it depends on the module naming scheme (and isn't there a proposal to make these more opaque? I didn't follow it). And of course you're not actually putting the config in the submodule, but rather polluting your user-level config with it (which might or might not be preferable, depending on what you're trying to configure).

The second thought is that we faced the same problem with "git clone" itself: you might want to tweak some config after the repo is initialized but before we fetch anything. We added the "clone -c" option for that. It would seem reasonable to me to have a similar option that is passed along to git-clone under the hood. We already have ways to pass through options like --single-branch for the same reason.

And then presumably you could do:

  git submodule update --init -c core.sshCommand=whatever

In the meantime, as a workaround I suspect you could do it in two steps, like:

  # set it for the initial clone; this is using the one-shot "git -c",
  # not "clone -c" that will actually save the result in the
  # new repo
  git -c core.sshCommand=whatever submodule update --init

  # and then save it for subsequent fetches
  git submodule foreach 'git config core.sshCommand whatever'

It's rather unwieldy. And I think gets weird if you want to cover only a subset of paths, as it doesn't look like "submodule foreach" allows that. So you might be stuck with:

  git -c core.sshCommand=whatever submodule update --init some-path
  git -C .git/modules/some-path config core.sshCommand whatever

which is back to being overly intimate with the filesystem layout. There might be a better way to do a per-module command. I don't really use submodules myself.

-Peff

Thank you, this is very helpful.

The includeIf approach and the two-step workaround do seem workable, but they still feel awkward when different submodules need different settings during the initial clone.

I would like to try a small RFC patch for this.

My current direction is a general per-submodule config injection mechanism for submodule update --init, so that config can be passed to the underlying clone/fetch for one submodule without affecting others.

Does that sound like a reasonable direction for a first RFC patch?

Thanks, Shibo Xia

Jeff King <peff@peff.net> 于2026年4月14日周二 14:16写道：