NAME
----
-gitmodules - defining submodule properties
+gitmodules - Defining submodule properties
SYNOPSIS
--------
-$GIT_WORK_DIR/.gitmodules
+$GIT_WORK_TREE/.gitmodules
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].
The file contains one subsection per submodule, and the subsection value
-is the name of the submodule. Each submodule section also contains the
+is the name of the submodule. The name is set to the path where the
+submodule has been added unless it was customized with the `--name`
+option of 'git submodule add'. Each submodule section also contains the
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.
+ be unique within the `.gitmodules` file.
submodule.<name>.url::
Defines a URL from which the submodule repository can be cloned.
This may be either an absolute URL ready to be passed to
- linkgit:git-clone[1] or (if it begins with ./ or ../) a location
+ 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
- superproject will be checked out in the submodule on a detached HEAD.
- If 'rebase', the current branch of the submodule will be rebased onto
- the commit specified in the superproject. If 'merge', the commit
- specified in the superproject will be merged into the current branch
- in the submodule.
- If 'none', the submodule with name `$name` will not be updated
- by default.
-
- This config option is overridden if 'git submodule update' is given
- the '--merge', '--rebase' or '--checkout' options.
+ Defines the default update procedure for the named submodule,
+ i.e. how the submodule is updated by the `git submodule update`
+ command in the superproject. This is only used by `git
+ submodule init` to initialize the configuration variable of
+ the same name. Allowed values here are 'checkout', 'rebase',
+ 'merge' or 'none'. See description of 'update' command in
+ linkgit:git-submodule[1] for their meaning. For security
+ reasons, the '!command' form is not accepted here.
+
+submodule.<name>.branch::
+ A remote branch name for tracking updates in the upstream submodule.
+ If the option is not specified, it defaults to the remote `HEAD`.
+ A special value of `.` is used to indicate that the name of the branch
+ in the submodule should be the same name as the current branch in the
+ current repository. 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
- .git/config of the superproject, the setting there will override the
- one found in .gitmodules.
+ submodule. If this option is also present in the submodule's entry in
+ `.git/config` of the superproject, the setting there will override the
+ one found in `.gitmodules`.
Both settings can be overridden on the command line by using the
- "--[no-]recurse-submodules" option to "git fetch" and "git pull".
+ `--[no-]recurse-submodules` option to `git fetch` and `git pull`.
submodule.<name>.ignore::
- Defines under what circumstances "git status" and the diff family show
- a submodule as modified. When set to "all", it will never be considered
- modified, "dirty" will ignore all changes to the submodules work tree and
- takes only differences between the HEAD of the submodule and the commit
- recorded in the superproject into account. "untracked" will additionally
- let submodules with modified tracked files in their work tree show up.
- Using "none" (the default when this option is not set) also shows
- submodules that have untracked files in their work tree as changed.
- If this option is also present in the submodules entry in .git/config of
- 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.
+ Defines under what circumstances `git status` and the diff family show
+ a submodule as modified. The following values are supported:
++
+--
+ all;; The submodule will never be considered modified (but will
+ nonetheless show up in the output of status and commit when it has
+ been staged).
+
+ dirty;; All changes to the submodule's work tree will be ignored, only
+ committed differences between the `HEAD` of the submodule and its
+ recorded state in the superproject are taken into account.
+
+ untracked;; Only untracked files in submodules will be ignored.
+ Committed differences and modifications to tracked files will show
+ up.
+
+ none;; No modifications to submodules are ignored, all of committed
+ differences, and modifications to tracked and untracked files are
+ shown. This is the default option.
+
+If this option is also present in the submodule's entry in `.git/config`
+of 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-submodules` option. The `git submodule` commands are not
+affected by this setting.
+--
+
+submodule.<name>.shallow::
+ When set to true, a clone of this submodule will be performed as a
+ shallow clone (with a history depth of 1) unless the user explicitly
+ asks for a non-shallow clone.
EXAMPLES
--------
-Consider the following .gitmodules file:
-
- [submodule "libfoo"]
- path = include/foo
- url = git://foo.com/git/lib.git
+Consider the following `.gitmodules` file:
- [submodule "libbar"]
- path = include/bar
- url = git://bar.com/git/lib.git
+----
+[submodule "libfoo"]
+ path = include/foo
+ url = git://foo.com/git/lib.git
+[submodule "libbar"]
+ path = include/bar
+ url = git://bar.com/git/lib.git
+----
This defines two submodules, `libfoo` and `libbar`. These are expected to
-be checked out in the paths 'include/foo' and 'include/bar', and for both
+be checked out in the paths `include/foo` and `include/bar`, and for both
submodules a URL is specified which can be used for cloning the submodules.
SEE ALSO
--------
-linkgit:git-submodule[1] linkgit:git-config[1]
+linkgit:git-submodule[1], linkgit:gitsubmodules[7], linkgit:git-config[1]
GIT
---
projects / platform / upstream / git.git / blobdiff