1GITMODULES(5) Git Manual GITMODULES(5)
2
6 gitmodules - defining submodule properties
7
9 $GIT_WORK_DIR/.gitmodules
10
12 The .gitmodules file, located in the top-level directory of a Git
13 working tree, is a text file with a syntax matching the requirements of
14 git-config(1).
15 The file contains one subsection per submodule, and the subsection
17 value is the name of the submodule. The name is set to the path where
18 the submodule has been added unless it was customized with the --name
19 option of git submodule add. Each submodule section also contains the
20 following required keys:
21 submodule.<name>.path
23 Defines the path, relative to the top-level directory of the Git
24 working tree, where the submodule is expected to be checked out.
25 The path name must not end with a /. All submodule paths must be
26 unique within the .gitmodules file.
27 submodule.<name>.url
29 Defines a URL from which the submodule repository can be cloned.
30 This may be either an absolute URL ready to be passed to git-
31 clone(1) or (if it begins with ./ or ../) a location relative to
32 the superproject’s origin repository.
33 submodule.<name>.update
35 Defines what to do when the submodule is updated by the
36 superproject. If checkout (the default), the new commit specified
37 in the superproject will be checked out in the submodule on a
38 detached HEAD. If rebase, the current branch of the submodule will
39 be rebased onto the commit specified in the superproject. If merge,
40 the commit specified in the superproject will be merged into the
41 current branch in the submodule. If none, the submodule with name
42 $name will not be updated by default.
43 This config option is overridden if 'git submodule update' is given
45 the '--merge', '--rebase' or '--checkout' options.
46 submodule.<name>.branch
48 A remote branch name for tracking updates in the upstream
49 submodule. If the option is not specified, it defaults to master.
50 See the --remote documentation in git-submodule(1) for details.
51 submodule.<name>.fetchRecurseSubmodules
53 This option can be used to control recursive fetching of this
54 submodule. If this option is also present in the submodules entry
55 in .git/config of the superproject, the setting there will override
56 the one found in .gitmodules. Both settings can be overridden on
57 the command line by using the "--[no-]recurse-submodules" option to
58 "git fetch" and "git pull".
59 submodule.<name>.ignore
61 Defines under what circumstances "git status" and the diff family
62 show a submodule as modified. When set to "all", it will never be
63 considered modified, "dirty" will ignore all changes to the
64 submodules work tree and takes only differences between the HEAD of
65 the submodule and the commit recorded in the superproject into
66 account. "untracked" will additionally let submodules with modified
67 tracked files in their work tree show up. Using "none" (the default
68 when this option is not set) also shows submodules that have
69 untracked files in their work tree as changed. If this option is
70 also present in the submodules entry in .git/config of the
71 superproject, the setting there will override the one found in
72 .gitmodules. Both settings can be overridden on the command line by
73 using the "--ignore-submodule" option.
74
76 Consider the following .gitmodules file:
77 [submodule "libfoo"]
79 path = include/foo
80 url = git://foo.com/git/lib.git
81 [submodule "libbar"]
83 path = include/bar
84 url = git://bar.com/git/lib.git
85 This defines two submodules, libfoo and libbar. These are expected to
87 be checked out in the paths include/foo and include/bar, and for both
88 submodules a URL is specified which can be used for cloning the
89 submodules.
90
92 git-submodule(1) git-config(1)
93
95 Part of the git(1) suite
96Git 1.8.3.1 11/19/2018 GITMODULES(5)