]>
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 | 21 | is the name of the submodule. The name is set to the path where the |
bcf9626a | 22 | submodule has been added unless it was customized with the `--name` |
73b0898d | 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 | |
43fda945 TK |
38 | In addition, there are a number of optional keys: |
39 | ||
32948425 | 40 | submodule.<name>.update:: |
5c31acfb MS |
41 | Defines the default update procedure for the named submodule, |
42 | i.e. how the submodule is updated by "git submodule update" | |
43 | command in the superproject. This is only used by `git | |
44 | submodule init` to initialize the configuration variable of | |
45 | the same name. Allowed values here are 'checkout', 'rebase', | |
46 | 'merge' or 'none'. See description of 'update' command in | |
47 | linkgit:git-submodule[1] for their meaning. Note that the | |
48 | '!command' form is intentionally ignored here for security | |
49 | reasons. | |
ca2cedba | 50 | |
06b1abb5 TK |
51 | submodule.<name>.branch:: |
52 | A remote branch name for tracking updates in the upstream submodule. | |
53 | If the option is not specified, it defaults to 'master'. See the | |
54 | `--remote` documentation in linkgit:git-submodule[1] for details. | |
55 | ||
c1a3c364 | 56 | submodule.<name>.fetchRecurseSubmodules:: |
bf42b384 | 57 | This option can be used to control recursive fetching of this |
c1a3c364 JL |
58 | submodule. If this option is also present in the submodules entry in |
59 | .git/config of the superproject, the setting there will override the | |
60 | one found in .gitmodules. | |
469bfc96 | 61 | Both settings can be overridden on the command line by using the |
bf42b384 | 62 | "--[no-]recurse-submodules" option to "git fetch" and "git pull". |
c1a3c364 | 63 | |
302ad7a9 JL |
64 | submodule.<name>.ignore:: |
65 | Defines under what circumstances "git status" and the diff family show | |
66 | a submodule as modified. When set to "all", it will never be considered | |
1d2f393a JL |
67 | modified (but will nonetheless show up in the output of status and |
68 | commit when it has been staged), "dirty" will ignore all changes | |
69 | to the submodules work tree and | |
302ad7a9 JL |
70 | takes only differences between the HEAD of the submodule and the commit |
71 | recorded in the superproject into account. "untracked" will additionally | |
72 | let submodules with modified tracked files in their work tree show up. | |
73 | Using "none" (the default when this option is not set) also shows | |
74 | submodules that have untracked files in their work tree as changed. | |
75 | If this option is also present in the submodules entry in .git/config of | |
76 | the superproject, the setting there will override the one found in | |
77 | .gitmodules. | |
3776ea9d | 78 | Both settings can be overridden on the command line by using the |
bb58b696 JL |
79 | "--ignore-submodule" option. The 'git submodule' commands are not |
80 | affected by this setting. | |
302ad7a9 | 81 | |
891dbc6e LH |
82 | |
83 | EXAMPLES | |
84 | -------- | |
85 | ||
86 | Consider the following .gitmodules file: | |
87 | ||
88 | [submodule "libfoo"] | |
89 | path = include/foo | |
90 | url = git://foo.com/git/lib.git | |
91 | ||
92 | [submodule "libbar"] | |
93 | path = include/bar | |
94 | url = git://bar.com/git/lib.git | |
95 | ||
96 | ||
97 | This defines two submodules, `libfoo` and `libbar`. These are expected to | |
98 | be checked out in the paths 'include/foo' and 'include/bar', and for both | |
a7793a74 | 99 | submodules a URL is specified which can be used for cloning the submodules. |
891dbc6e LH |
100 | |
101 | SEE ALSO | |
102 | -------- | |
5162e697 | 103 | linkgit:git-submodule[1] linkgit:git-config[1] |
891dbc6e | 104 | |
891dbc6e LH |
105 | GIT |
106 | --- | |
9e1f0a85 | 107 | Part of the linkgit:git[1] suite |