Git Reference ยท Configuration Options
submodule.* settings
Reference for submodule.* settings: submodule.recurse, submodule.<name>.update, branch, ignore, active and fetchJobs, and which file each one belongs in.
The submodule.* variables control how Git treats submodules, the repositories nested inside another repository. Some of them are global behavior switches (submodule.recurse, submodule.fetchJobs). Others come in a per-submodule form, submodule.<name>.<key>, where <name> is the logical name recorded in .gitmodules.
An important detail is where each setting lives. .gitmodules is committed and shared: it holds path, url, branch, and the shared policy update, ignore and fetchRecurseSubmodules. .git/config is private: git submodule init copies the url there, and your own overrides go there too.
git config --global submodule.recurse true git config submodule.libs/theme.update rebase git config -f .gitmodules submodule.libs/theme.branch main git config --global submodule.fetchJobs 4
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git config submodule.recurse <true | false> git config submodule.fetchJobs <n> git config submodule.active <pathspec> git config submodule.<name>.url <url> git config submodule.<name>.update <checkout | rebase | merge | none | !command> git config -f .gitmodules submodule.<name>.branch <branch | .> git config -f .gitmodules submodule.<name>.ignore <all | dirty | untracked | none> git config -f .gitmodules submodule.<name>.fetchRecurseSubmodules <true | false | on-demand> git config submodule.<name>.active <true | false>
| Setting | Description |
|---|---|
submodule.recurse |
Makes commands that touch the work tree (checkout, switch, reset, restore, pull, read-tree, merge, rebase...) also update submodules. Default false. It does not affect git submodule update itself, clone or fetch (use fetch.recurseSubmodules for the latter). |
submodule.fetchJobs |
Number of submodules fetched in parallel. Default 1. |
submodule.active |
Pathspec of submodules that count as active (multi-valued). Replaces having to run git submodule init for every one. |
submodule.<name>.url |
Where to clone from. In .gitmodules it is the suggestion; in .git/config it is what is really used. |
submodule.<name>.update |
How git submodule update brings the submodule to the recorded commit. The default checkout leaves a detached HEAD; rebase and merge keep your local branch. none skips it. A !command runs a custom command (local config only, for safety). |
submodule.<name>.branch |
Branch that git submodule update --remote follows. . means "the same branch name as the superproject". Default HEAD of the remote. |
submodule.<name>.ignore |
What git status, diff and log ignore about the submodule: none (default), untracked, dirty or all. |
submodule.<name>.fetchRecurseSubmodules |
Overrides fetch.recurseSubmodules for this submodule. |
submodule.<name>.active |
Marks one submodule active or not. Overrides submodule.active. |
Edge cases: a submodule is active if submodule.<name>.active is true, or if its path matches submodule.active, or if submodule.<name>.url exists in .git/config, in that order of precedence. File URLs between local repositories need protocol.file.allow=always on current Git versions, which is why the examples set it.
Usage notes
- Turn on
submodule.recurseglobally if you use submodules daily. Without it, switching branches leaves submodule working trees pointing at old commits, andgit statusthen shows them as modified. It is a convenience, not a cure: a submodule with uncommitted changes can still block the operation. update = noneand!commandare never honored from.gitmodules. A cloned repository must not be able to tell Git to execute commands, so these values only count in your own.git/config.ignore = allhides everything, including a changed commit. That makes accidental bumps invisible.dirtyoruntrackedis a gentler choice when build output lands inside a submodule.- Branch tracking is manual. Setting
branchdoes nothing until you rungit submodule update --remote, and the result still appears as a change in the superproject that you must commit. - Deinitializing (
git submodule deinit) removes the entries from.git/configbut leaves the.gitmodulesrecord and the stored repository under.git/modules. submodule.propagateBranches(experimental, Git 2.37 and later) creates matching branches in submodules when you create one in the superproject.- Security: submodule URLs and the
updatecommand come from repositories you may not trust. Review.gitmodulesbefore runninggit submodule update --initon a project you do not know.