How should submodules use different sshCommand during initial update?

How should submodules use different sshCommand during initial update?

[Shibo Xia]

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

Re: How should submodules use different sshCommand during initial update?

[Junio C Hamano]

Shibo Xia <sbxia25@gmail.com> writes:

> My use case is that different submodules may need different SSH identities or
> different SSH command settings.

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?

Re: How should submodules use different sshCommand during initial update?

[Shibo Xia]

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写道：
>
> Shibo Xia <sbxia25@gmail.com> writes:
>
> > My use case is that different submodules may need different SSH identities or
> > different SSH command settings.
>
> 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?

Re: How should submodules use different sshCommand during initial update?

[Jeff King]

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

> 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.

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

Re: How should submodules use different sshCommand during initial update?

[Shibo Xia]

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写道：
>
> On Tue, Apr 14, 2026 at 09:28:20AM +0800, Shibo Xia wrote:
>
> > 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.
>
> 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