1gitmodules(5)
2=============
34
NAME
5----
6gitmodules - defining submodule properties
78
SYNOPSIS
9--------
10$GIT_WORK_DIR/.gitmodules
1112
13
DESCRIPTION
14-----------
1516
The `.gitmodules` file, located in the top-level directory of a Git
17working tree, is a text file with a syntax matching the requirements
18of linkgit:git-config[1].
1920
The file contains one subsection per submodule, and the subsection value
21is the name of the submodule. The name is set to the path where the
22submodule has been added unless it was customized with the '--name'
23option of 'git submodule add'. Each submodule section also contains the
24following required keys:
2526
submodule.<name>.path::
27Defines the path, relative to the top-level directory of the Git
28working tree, where the submodule is expected to be checked out.
29The path name must not end with a `/`. All submodule paths must
30be unique within the .gitmodules file.
3132
submodule.<name>.url::
33Defines a URL from which the submodule repository can be cloned.
34This may be either an absolute URL ready to be passed to
35linkgit:git-clone[1] or (if it begins with ./ or ../) a location
36relative to the superproject's origin repository.
3738
In addition, there are a number of optional keys:
3940
submodule.<name>.update::
41Defines what to do when the submodule is updated by the superproject.
42If 'checkout' (the default), the new commit specified in the
43superproject will be checked out in the submodule on a detached HEAD.
44If 'rebase', the current branch of the submodule will be rebased onto
45the commit specified in the superproject. If 'merge', the commit
46specified in the superproject will be merged into the current branch
47in the submodule.
48If 'none', the submodule with name `$name` will not be updated
49by default.
5051
This config option is overridden if 'git submodule update' is given
52the '--merge', '--rebase' or '--checkout' options.
5354
submodule.<name>.branch::
55A remote branch name for tracking updates in the upstream submodule.
56If the option is not specified, it defaults to 'master'. See the
57`--remote` documentation in linkgit:git-submodule[1] for details.
58+
59This branch name is also used for the local branch created by
60non-checkout cloning updates. See the `update` documentation in
61linkgit:git-submodule[1] for details.
6263
submodule.<name>.fetchRecurseSubmodules::
64This option can be used to control recursive fetching of this
65submodule. If this option is also present in the submodules entry in
66.git/config of the superproject, the setting there will override the
67one found in .gitmodules.
68Both settings can be overridden on the command line by using the
69"--[no-]recurse-submodules" option to "git fetch" and "git pull".
7071
submodule.<name>.ignore::
72Defines under what circumstances "git status" and the diff family show
73a submodule as modified. When set to "all", it will never be considered
74modified, "dirty" will ignore all changes to the submodules work tree and
75takes only differences between the HEAD of the submodule and the commit
76recorded in the superproject into account. "untracked" will additionally
77let submodules with modified tracked files in their work tree show up.
78Using "none" (the default when this option is not set) also shows
79submodules that have untracked files in their work tree as changed.
80If this option is also present in the submodules entry in .git/config of
81the superproject, the setting there will override the one found in
82.gitmodules.
83Both settings can be overridden on the command line by using the
84"--ignore-submodule" option. The 'git submodule' commands are not
85affected by this setting.
8687
88
EXAMPLES
89--------
9091
Consider the following .gitmodules file:
9293
[submodule "libfoo"]
94path = include/foo
95url = git://foo.com/git/lib.git
9697
[submodule "libbar"]
98path = include/bar
99url = git://bar.com/git/lib.git
100101
102
This defines two submodules, `libfoo` and `libbar`. These are expected to
103be checked out in the paths 'include/foo' and 'include/bar', and for both
104submodules a URL is specified which can be used for cloning the submodules.
105106
SEE ALSO
107--------
108linkgit:git-submodule[1] linkgit:git-config[1]
109110
GIT
111---
112Part of the linkgit:git[1] suite