When switching branches with git checkout I would assume that most of the time you would want to update your submodules.
- In what situation do you not want to update submodules after switching?
- What would break if this was done automatically by git checkout?
Updated with example:
- Branch A has submodule S at 3852f1
- Branch B has submodule S at fd72d7
On branch A, git checkout B will result in a working copy of branch B with submodule S at 3852f1 (with a modified S). git submodule update will checkout S at fd72d7.
git checkout --recurse-submodules was added to git 2.13
This is mentioned on the release notes at: https://github.com/git/git/commit/e1104a5ee539408b81566066aaa6963cb87d5cd6#diff-c24776ff22455a30fbb78e378b7df0b0R139
submodule.recurse option was added to git 2.14
git config --global submodule.recurse true
man git-config says:
Specifies if commands recurse into submodules by default. This applies to all commands that have a
--recurse-submodulesoption. Defaults to false.
I feel that not updating modules by default is a bad Git default behavior that goes against most user's expectations and limits the adoption of submodules, I really wish the devs would change it.
I believe that the submodules not updating automatically is in line with the development goals of Git. Git is meant to work in a distributed mode and doesn't presume that you are even able to connect to a non-local repository unless you explicitly tell it to. Git not auto-refreshing a submodule would be the expected behavior when thought of that way.
With that being said, if you know that you always want those sub-modules to be pulled in and you know that you would never branch off of those submodules to another local repository, then it shouldn't break anything if you automatically refreshed them after a checkout.
With Git 2.27 (Q2 2020), the "
--recurse-submodules" option is better documented.
See commit acbfae3, commit 4da9e99, commit d09bc51, commit b3cec57, commit dd0cb7d (06 Apr 2020) by Damien Robert (
(Merged by Junio C Hamano --
gitster -- in commit cc908db, 28 Apr 2020)
--recurse-submodulesmostly applies to active submodules
Signed-off-by: Damien Robert
Helped-by: Philippe Blain
The documentation refers to "initialized" or "populated" submodules, to explain which submodules are affected by '
--recurse-submodules', but the real terminology here is '
active' submodules. Update the documentation accordingly.
- Active is defined in gitsubmodules(7), it only involves the configuration variables '
submodule.<name>.active' and '
submodule.c::is_submodule_activechecks that a submodule is active.
- Populated means that the submodule's working tree is present (and the gitfile correctly points to the submodule repository), i.e. either the superproject was cloned with
--recurse-submodules, or the user ran
git submodule update --init, or
git submodule init [<path>]and
git submodule update [<path>]separately which populated the submodule working tree.
This does not involve the 3 configuration variables above.
- Initialized (at least in the context of the man pages involved in this patch) means both "populated" and "active" as defined above, i.e. what
[git submodule update --init
--recurse-submodulesoption mostly affects active submodules.
An exception is
git fetchwhere the option affects populated submodules.
As a consequence, in
git pull --recurse-submodulesthe fetch affects populated submodules, but the resulting working tree update only affects active submodules.
In the documentation of
git-pull, let's distinguish between the fetching part which affects populated submodules, and the updating of worktrees, which only affects active submodules.
With Git 2.33 (Q3 2021), the documentation for
submodule.recurse is clearer:
doc: clarify description of 'submodule.recurse'
Signed-off-by: Philippe Blain
The doc for '
submodule.recurse' starts with "Specifies if commands recurse into submodles by default".
This is not exactly true of all commands that have a '
For example, '
git pull --recurse-submodules'(man) does not run '
git pull'(man) in each submodule, but rather runs '
git submodule update --recursive'(man) so that the submodule working trees after the pull matches the commits recorded in the superproject.
Clarify that by just saying that it enables '
Note that the way this setting interacts with '
fetch.recurseSubmodules' and '
push.recurseSubmodules', which can have other values than true or false, is already documented since 4da9e99 ("
doc: be more precise on (
.recurseSubmodules", 2020-04-06, Git v2.27.0-rc0 -- merge listed in batch #4).
git config now includes in its man page:
A boolean indicating if commands should enable the
--recurse-submodulesoption by default. Applies to all commands that support this option.
Is there a way to automatically have
git submodule update (or preferably
git submodule update --init called whenever
git pull is done?
Looking for a git config setting, or a git alias to help with this.
As of Git 2.14, you can use
git pull --recurse-submodules (and alias it to whatever you like).
You can do this globally by running:
git config --global submodule.recurse true
I'm surprised nobody mentioned using git hooks to do this!
Just add files named
post-merge to your
.git/hooks directory of the relevant repositories, and put the following into each of them:
#!/bin/sh git submodule update --init --recursive
Since you specfically asked for an alias, assuming you want to have this for many repositories, you can create an alias which adds these to a repository's
.git/hooks for you.