]>
Commit | Line | Data |
---|---|---|
891dbc6e LH |
1 | gitmodules(5) |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | gitmodules - defining submodule properties | |
7 | ||
8 | SYNOPSIS | |
9 | -------- | |
e5b5c1d2 | 10 | $GIT_WORK_DIR/.gitmodules |
891dbc6e LH |
11 | |
12 | ||
13 | DESCRIPTION | |
14 | ----------- | |
15 | ||
16 | The `.gitmodules` file, located in the top-level directory of a git | |
17 | working tree, is a text file with a syntax matching the requirements | |
5162e697 | 18 | of linkgit:git-config[1]. |
891dbc6e LH |
19 | |
20 | The file contains one subsection per submodule, and the subsection value | |
21 | is the name of the submodule. Each submodule section also contains the | |
22 | following required keys: | |
23 | ||
24 | submodule.<name>.path:: | |
25 | Defines the path, relative to the top-level directory of the git | |
26 | working tree, where the submodule is expected to be checked out. | |
27 | The path name must not end with a `/`. All submodule paths must | |
28 | be unique within the .gitmodules file. | |
29 | ||
30 | submodule.<name>.url:: | |
31 | Defines an url from where the submodule repository can be cloned. | |
47dc5d5f JN |
32 | This may be either an absolute URL ready to be passed to |
33 | linkgit:git-clone[1] or (if it begins with ./ or ../) a location | |
34 | relative to the superproject's origin repository. | |
891dbc6e | 35 | |
32948425 JH |
36 | submodule.<name>.update:: |
37 | Defines what to do when the submodule is updated by the superproject. | |
38 | If 'checkout' (the default), the new commit specified in the | |
39 | superproject will be checked out in the submodule on a detached HEAD. | |
40 | If 'rebase', the current branch of the submodule will be rebased onto | |
42b49178 JH |
41 | the commit specified in the superproject. If 'merge', the commit |
42 | specified in the superproject will be merged into the current branch | |
43 | in the submodule. | |
32948425 | 44 | This config option is overridden if 'git submodule update' is given |
42b49178 | 45 | the '--merge' or '--rebase' options. |
ca2cedba | 46 | |
c1a3c364 JL |
47 | submodule.<name>.fetchRecurseSubmodules:: |
48 | This option can be used to enable/disable recursive fetching of this | |
49 | submodule. If this option is also present in the submodules entry in | |
50 | .git/config of the superproject, the setting there will override the | |
51 | one found in .gitmodules. | |
469bfc96 | 52 | Both settings can be overridden on the command line by using the |
c1a3c364 JL |
53 | "--[no-]recurse-submodules" option to "git fetch" and "git pull".. |
54 | ||
302ad7a9 JL |
55 | submodule.<name>.ignore:: |
56 | Defines under what circumstances "git status" and the diff family show | |
57 | a submodule as modified. When set to "all", it will never be considered | |
58 | modified, "dirty" will ignore all changes to the submodules work tree and | |
59 | takes only differences between the HEAD of the submodule and the commit | |
60 | recorded in the superproject into account. "untracked" will additionally | |
61 | let submodules with modified tracked files in their work tree show up. | |
62 | Using "none" (the default when this option is not set) also shows | |
63 | submodules that have untracked files in their work tree as changed. | |
64 | If this option is also present in the submodules entry in .git/config of | |
65 | the superproject, the setting there will override the one found in | |
66 | .gitmodules. | |
3776ea9d | 67 | Both settings can be overridden on the command line by using the |
302ad7a9 JL |
68 | "--ignore-submodule" option. |
69 | ||
891dbc6e LH |
70 | |
71 | EXAMPLES | |
72 | -------- | |
73 | ||
74 | Consider the following .gitmodules file: | |
75 | ||
76 | [submodule "libfoo"] | |
77 | path = include/foo | |
78 | url = git://foo.com/git/lib.git | |
79 | ||
80 | [submodule "libbar"] | |
81 | path = include/bar | |
82 | url = git://bar.com/git/lib.git | |
83 | ||
84 | ||
85 | This defines two submodules, `libfoo` and `libbar`. These are expected to | |
86 | be checked out in the paths 'include/foo' and 'include/bar', and for both | |
87 | submodules an url is specified which can be used for cloning the submodules. | |
88 | ||
89 | SEE ALSO | |
90 | -------- | |
5162e697 | 91 | linkgit:git-submodule[1] linkgit:git-config[1] |
891dbc6e | 92 | |
891dbc6e LH |
93 | GIT |
94 | --- | |
9e1f0a85 | 95 | Part of the linkgit:git[1] suite |