DESCRIPTION
-----------
-The `.gitmodules` file, located in the top-level directory of a git
+The `.gitmodules` file, located in the top-level directory of a Git
working tree, is a text file with a syntax matching the requirements
of linkgit:git-config[1].
following required keys:
submodule.<name>.path::
- Defines the path, relative to the top-level directory of the git
+ Defines the path, relative to the top-level directory of the Git
working tree, where the submodule is expected to be checked out.
The path name must not end with a `/`. All submodule paths must
be unique within the .gitmodules file.
linkgit:git-clone[1] or (if it begins with ./ or ../) a location
relative to the superproject's origin repository.
+In addition, there are a number of optional keys:
+
submodule.<name>.update::
Defines what to do when the submodule is updated by the superproject.
If 'checkout' (the default), the new commit specified in the
This config option is overridden if 'git submodule update' is given
the '--merge', '--rebase' or '--checkout' options.
+submodule.<name>.branch::
+ A remote branch name for tracking updates in the upstream submodule.
+ If the option is not specified, it defaults to 'master'. See the
+ `--remote` documentation in linkgit:git-submodule[1] for details.
+
submodule.<name>.fetchRecurseSubmodules::
This option can be used to control recursive fetching of this
submodule. If this option is also present in the submodules entry in
the superproject, the setting there will override the one found in
.gitmodules.
Both settings can be overridden on the command line by using the
- "--ignore-submodule" option.
+ "--ignore-submodule" option. The 'git submodule' commands are not
+ affected by this setting.
EXAMPLES