Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
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

Bash submodule.recurse and submodule.branch

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.

Bash Silence a submodule with ignore and mark it inactive

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

Terminal
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.recurse globally if you use submodules daily. Without it, switching branches leaves submodule working trees pointing at old commits, and git status then shows them as modified. It is a convenience, not a cure: a submodule with uncommitted changes can still block the operation.
  • update = none and !command are 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 = all hides everything, including a changed commit. That makes accidental bumps invisible. dirty or untracked is a gentler choice when build output lands inside a submodule.
  • Branch tracking is manual. Setting branch does nothing until you run git 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/config but leaves the .gitmodules record 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 update command come from repositories you may not trust. Review .gitmodules before running git submodule update --init on a project you do not know.