]>
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 | ||
2de9b711 | 16 | The `.gitmodules` file, located in the top-level directory of a Git |
891dbc6e | 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 | |
73b0898d JL |
21 | is the name of the submodule. The name is set to the path where the |
22 | submodule has been added unless it was customized with the '--name' | |
23 | option of 'git submodule add'. Each submodule section also contains the | |
891dbc6e LH |
24 | following required keys: |
25 | ||
26 | submodule.<name>.path:: | |
2de9b711 | 27 | Defines the path, relative to the top-level directory of the Git |
891dbc6e LH |
28 | working tree, where the submodule is expected to be checked out. |
29 | The path name must not end with a `/`. All submodule paths must | |
30 | be unique within the .gitmodules file. | |
31 | ||
32 | submodule.<name>.url:: | |
a7793a74 | 33 | Defines a URL from which the submodule repository can be cloned. |
47dc5d5f JN |
34 | This may be either an absolute URL ready to be passed to |
35 | linkgit:git-clone[1] or (if it begins with ./ or ../) a location | |
36 | relative to the superproject's origin repository. | |
891dbc6e | 37 | |
32948425 JH |
38 | submodule.<name>.update:: |
39 | Defines what to do when the submodule is updated by the superproject. | |
40 | If 'checkout' (the default), the new commit specified in the | |
41 | superproject will be checked out in the submodule on a detached HEAD. | |
42 | If 'rebase', the current branch of the submodule will be rebased onto | |
42b49178 JH |
43 | the commit specified in the superproject. If 'merge', the commit |
44 | specified in the superproject will be merged into the current branch | |
45 | in the submodule. | |
e6a1c43a HV |
46 | If 'none', the submodule with name `$name` will not be updated |
47 | by default. | |
48 | ||
32948425 | 49 | This config option is overridden if 'git submodule update' is given |
e6a1c43a | 50 | the '--merge', '--rebase' or '--checkout' options. |
ca2cedba | 51 | |
06b1abb5 TK |
52 | submodule.<name>.branch:: |
53 | A remote branch name for tracking updates in the upstream submodule. | |
54 | If the option is not specified, it defaults to 'master'. See the | |
55 | `--remote` documentation in linkgit:git-submodule[1] for details. | |
56 | ||
c1a3c364 | 57 | submodule.<name>.fetchRecurseSubmodules:: |
bf42b384 | 58 | This option can be used to control recursive fetching of this |
c1a3c364 JL |
59 | submodule. If this option is also present in the submodules entry in |
60 | .git/config of the superproject, the setting there will override the | |
61 | one found in .gitmodules. | |
469bfc96 | 62 | Both settings can be overridden on the command line by using the |
bf42b384 | 63 | "--[no-]recurse-submodules" option to "git fetch" and "git pull". |
c1a3c364 | 64 | |
302ad7a9 JL |
65 | submodule.<name>.ignore:: |
66 | Defines under what circumstances "git status" and the diff family show | |
67 | a submodule as modified. When set to "all", it will never be considered | |
68 | modified, "dirty" will ignore all changes to the submodules work tree and | |
69 | takes only differences between the HEAD of the submodule and the commit | |
70 | recorded in the superproject into account. "untracked" will additionally | |
71 | let submodules with modified tracked files in their work tree show up. | |
72 | Using "none" (the default when this option is not set) also shows | |
73 | submodules that have untracked files in their work tree as changed. | |
74 | If this option is also present in the submodules entry in .git/config of | |
75 | the superproject, the setting there will override the one found in | |
76 | .gitmodules. | |
3776ea9d | 77 | Both settings can be overridden on the command line by using the |
bb58b696 JL |
78 | "--ignore-submodule" option. The 'git submodule' commands are not |
79 | affected by this setting. | |
302ad7a9 | 80 | |
891dbc6e LH |
81 | |
82 | EXAMPLES | |
83 | -------- | |
84 | ||
85 | Consider the following .gitmodules file: | |
86 | ||
87 | [submodule "libfoo"] | |
88 | path = include/foo | |
89 | url = git://foo.com/git/lib.git | |
90 | ||
91 | [submodule "libbar"] | |
92 | path = include/bar | |
93 | url = git://bar.com/git/lib.git | |
94 | ||
95 | ||
96 | This defines two submodules, `libfoo` and `libbar`. These are expected to | |
97 | be checked out in the paths 'include/foo' and 'include/bar', and for both | |
a7793a74 | 98 | submodules a URL is specified which can be used for cloning the submodules. |
891dbc6e LH |
99 | |
100 | SEE ALSO | |
101 | -------- | |
5162e697 | 102 | linkgit:git-submodule[1] linkgit:git-config[1] |
891dbc6e | 103 | |
891dbc6e LH |
104 | GIT |
105 | --- | |
9e1f0a85 | 106 | Part of the linkgit:git[1] suite |