]>
Commit | Line | Data |
---|---|---|
891dbc6e LH |
1 | gitmodules(5) |
2 | ============= | |
3 | ||
4 | NAME | |
5 | ---- | |
1b81d8cb | 6 | gitmodules - Defining submodule properties |
891dbc6e LH |
7 | |
8 | SYNOPSIS | |
9 | -------- | |
1f4e9319 | 10 | $GIT_WORK_TREE/.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 | |
1f4e9319 | 30 | be unique within the `.gitmodules` file. |
891dbc6e LH |
31 | |
32 | submodule.<name>.url:: | |
a7793a74 | 33 | Defines a URL from which the submodule repository can be cloned. |
47dc5d5f | 34 | This may be either an absolute URL ready to be passed to |
1f4e9319 | 35 | linkgit:git-clone[1] or (if it begins with `./` or `../`) a location |
47dc5d5f | 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 | 41 | Defines the default update procedure for the named submodule, |
1f4e9319 | 42 | i.e. how the submodule is updated by the `git submodule update` |
5c31acfb MS |
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 | |
e904deb8 JN |
47 | linkgit:git-submodule[1] for their meaning. For security |
48 | reasons, the '!command' form is not accepted here. | |
ca2cedba | 49 | |
06b1abb5 TK |
50 | submodule.<name>.branch:: |
51 | A remote branch name for tracking updates in the upstream submodule. | |
1f4e9319 | 52 | If the option is not specified, it defaults to the remote `HEAD`. |
f0a96e8d JS |
53 | A special value of `.` is used to indicate that the name of the branch |
54 | in the submodule should be the same name as the current branch in the | |
15ef7800 BW |
55 | current repository. See the `--remote` documentation in |
56 | linkgit:git-submodule[1] for details. | |
06b1abb5 | 57 | |
c1a3c364 | 58 | submodule.<name>.fetchRecurseSubmodules:: |
bf42b384 | 59 | This option can be used to control recursive fetching of this |
1f4e9319 PB |
60 | submodule. If this option is also present in the submodule's entry in |
61 | `.git/config` of the superproject, the setting there will override the | |
62 | one found in `.gitmodules`. | |
469bfc96 | 63 | Both settings can be overridden on the command line by using the |
1f4e9319 | 64 | `--[no-]recurse-submodules` option to `git fetch` and `git pull`. |
c1a3c364 | 65 | |
302ad7a9 | 66 | submodule.<name>.ignore:: |
1f4e9319 | 67 | Defines under what circumstances `git status` and the diff family show |
61e28242 | 68 | a submodule as modified. The following values are supported: |
ad471949 AH |
69 | + |
70 | -- | |
61e28242 SS |
71 | all;; The submodule will never be considered modified (but will |
72 | nonetheless show up in the output of status and commit when it has | |
73 | been staged). | |
74 | ||
75 | dirty;; All changes to the submodule's work tree will be ignored, only | |
1f4e9319 | 76 | committed differences between the `HEAD` of the submodule and its |
61e28242 SS |
77 | recorded state in the superproject are taken into account. |
78 | ||
79 | untracked;; Only untracked files in submodules will be ignored. | |
80 | Committed differences and modifications to tracked files will show | |
81 | up. | |
82 | ||
031fd4b9 | 83 | none;; No modifications to submodules are ignored, all of committed |
61e28242 SS |
84 | differences, and modifications to tracked and untracked files are |
85 | shown. This is the default option. | |
86 | ||
1f4e9319 | 87 | If this option is also present in the submodule's entry in `.git/config` |
ad471949 | 88 | of the superproject, the setting there will override the one found in |
1f4e9319 | 89 | `.gitmodules`. |
ad471949 AH |
90 | |
91 | Both settings can be overridden on the command line by using the | |
1f4e9319 | 92 | `--ignore-submodules` option. The `git submodule` commands are not |
ad471949 AH |
93 | affected by this setting. |
94 | -- | |
302ad7a9 | 95 | |
f6fb30a0 SB |
96 | submodule.<name>.shallow:: |
97 | When set to true, a clone of this submodule will be performed as a | |
8d3047cd SS |
98 | shallow clone (with a history depth of 1) unless the user explicitly |
99 | asks for a non-shallow clone. | |
f6fb30a0 | 100 | |
8ff06de1 JK |
101 | NOTES |
102 | ----- | |
103 | ||
104 | Git does not allow the `.gitmodules` file within a working tree to be a | |
105 | symbolic link, and will refuse to check out such a tree entry. This | |
106 | keeps behavior consistent when the file is accessed from the index or a | |
107 | tree versus from the filesystem, and helps Git reliably enforce security | |
108 | checks of the file contents. | |
891dbc6e LH |
109 | |
110 | EXAMPLES | |
111 | -------- | |
112 | ||
1f4e9319 | 113 | Consider the following `.gitmodules` file: |
891dbc6e | 114 | |
1925fe0c MÅ |
115 | ---- |
116 | [submodule "libfoo"] | |
117 | path = include/foo | |
118 | url = git://foo.com/git/lib.git | |
891dbc6e | 119 | |
1925fe0c MÅ |
120 | [submodule "libbar"] |
121 | path = include/bar | |
122 | url = git://bar.com/git/lib.git | |
123 | ---- | |
891dbc6e LH |
124 | |
125 | This defines two submodules, `libfoo` and `libbar`. These are expected to | |
68ed71b5 | 126 | be checked out in the paths `include/foo` and `include/bar`, and for both |
a7793a74 | 127 | submodules a URL is specified which can be used for cloning the submodules. |
891dbc6e LH |
128 | |
129 | SEE ALSO | |
130 | -------- | |
cc2bd5c4 | 131 | linkgit:git-submodule[1], linkgit:gitsubmodules[7], linkgit:git-config[1] |
891dbc6e | 132 | |
891dbc6e LH |
133 | GIT |
134 | --- | |
9e1f0a85 | 135 | Part of the linkgit:git[1] suite |