]>
Commit | Line | Data |
---|---|---|
70c7ac22 LH |
1 | git-submodule(1) |
2 | ================ | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-submodule - Initialize, update or inspect submodules | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
b2493649 | 11 | [verse] |
eb2f2f5f | 12 | 'git submodule' [--quiet] add [<options>] [--] <repository> [<path>] |
64b19ffe | 13 | 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] |
b1889c36 | 14 | 'git submodule' [--quiet] init [--] [<path>...] |
f6a52799 | 15 | 'git submodule' [--quiet] deinit [-f|--force] (--all|[--] <path>...) |
eb2f2f5f SB |
16 | 'git submodule' [--quiet] update [<options>] [--] [<path>...] |
17 | 'git submodule' [--quiet] summary [<options>] [--] [<path>...] | |
15fc56a8 | 18 | 'git submodule' [--quiet] foreach [--recursive] <command> |
9393ae79 | 19 | 'git submodule' [--quiet] sync [--recursive] [--] [<path>...] |
f6f85861 | 20 | 'git submodule' [--quiet] absorbgitdirs [--] [<path>...] |
70c7ac22 LH |
21 | |
22 | ||
e38953ab PB |
23 | DESCRIPTION |
24 | ----------- | |
ec48a763 | 25 | Inspects, updates and manages submodules. |
c47f1024 | 26 | |
d4803455 | 27 | For more information about submodules, see linkgit:gitsubmodules[7]. |
e38953ab | 28 | |
70c7ac22 LH |
29 | COMMANDS |
30 | -------- | |
eb2f2f5f | 31 | add [-b <branch>] [-f|--force] [--name <name>] [--reference <repository>] [--depth <depth>] [--] <repository> [<path>]:: |
ecda0723 | 32 | Add the given repository as a submodule at the given path |
ec05df35 | 33 | to the changeset to be committed next to the current |
77ef80a8 | 34 | project: the current project is termed the "superproject". |
ec05df35 | 35 | + |
ec05df35 ML |
36 | <repository> is the URL of the new submodule's origin repository. |
37 | This may be either an absolute URL, or (if it begins with ./ | |
d1b3b81a | 38 | or ../), the location relative to the superproject's default remote |
9e6ed475 JL |
39 | repository (Please note that to specify a repository 'foo.git' |
40 | which is located right next to a superproject 'bar.git', you'll | |
41 | have to use '../foo.git' instead of './foo.git' - as one might expect | |
42 | when following the rules for relative URLs - because the evaluation | |
43 | of relative URLs in Git is identical to that of relative directories). | |
d1b3b81a | 44 | + |
30aa96cd RD |
45 | The default remote is the remote of the remote-tracking branch |
46 | of the current branch. If no such remote-tracking branch exists or | |
d1b3b81a SB |
47 | the HEAD is detached, "origin" is assumed to be the default remote. |
48 | If the superproject doesn't have a default remote configured | |
4d689320 JL |
49 | the superproject is its own authoritative upstream and the current |
50 | working directory is used instead. | |
ec05df35 | 51 | + |
beebc6df KS |
52 | The optional argument <path> is the relative location for the cloned |
53 | submodule to exist in the superproject. If <path> is not given, the | |
54 | canonical part of the source repository is used ("repo" for | |
55 | "/path/to/repo.git" and "foo" for "host.xz:foo/.git"). If <path> | |
56 | exists and is already a valid Git repository, then it is staged | |
57 | for commit without cloning. The <path> is also used as the submodule's | |
58 | logical name in its configuration entries unless `--name` is used | |
59 | to specify a logical name. | |
ec05df35 | 60 | + |
beebc6df KS |
61 | The given URL is recorded into `.gitmodules` for use by subsequent users |
62 | cloning the superproject. If the URL is given relative to the | |
63 | superproject's repository, the presumption is the superproject and | |
64 | submodule repositories will be kept together in the same relative | |
65 | location, and only the superproject's URL needs to be provided. | |
66 | git-submodule will correctly locate the submodule using the relative | |
67 | URL in `.gitmodules`. | |
ecda0723 | 68 | |
eb2f2f5f | 69 | status [--cached] [--recursive] [--] [<path>...]:: |
70c7ac22 LH |
70 | Show the status of the submodules. This will print the SHA-1 of the |
71 | currently checked out commit for each submodule, along with the | |
0b444cdb | 72 | submodule path and the output of 'git describe' for the |
e1b3f3dd KS |
73 | SHA-1. Each SHA-1 will possibly be prefixed with `-` if the submodule is |
74 | not initialized, `+` if the currently checked out submodule commit | |
70c7ac22 | 75 | does not match the SHA-1 found in the index of the containing |
313ee0d6 | 76 | repository and `U` if the submodule has merge conflicts. |
64b19ffe | 77 | + |
402e8a6d | 78 | If `--recursive` is specified, this command will recurse into nested |
64b19ffe | 79 | submodules, and show their status as well. |
402e8a6d JL |
80 | + |
81 | If you are only interested in changes of the currently initialized | |
82 | submodules with respect to the commit recorded in the index or the HEAD, | |
83 | linkgit:git-status[1] and linkgit:git-diff[1] will provide that information | |
84 | too (and can also report changes to a submodule's work tree). | |
70c7ac22 | 85 | |
eb2f2f5f | 86 | init [--] [<path>...]:: |
3244eb9b | 87 | Initialize the submodules recorded in the index (which were |
d1b3b81a | 88 | added and committed elsewhere) by setting `submodule.$name.url` |
beebc6df | 89 | in .git/config. It uses the same setting from `.gitmodules` as |
d1b3b81a SB |
90 | a template. If the URL is relative, it will be resolved using |
91 | the default remote. If there is no default remote, the current | |
92 | repository will be assumed to be upstream. | |
93 | + | |
94 | Optional <path> arguments limit which submodules will be initialized. | |
3e7eaed0 BW |
95 | If no path is specified and submodule.active has been configured, submodules |
96 | configured to be active will be initialized, otherwise all submodules are | |
97 | initialized. | |
d1b3b81a SB |
98 | + |
99 | When present, it will also copy the value of `submodule.$name.update`. | |
100 | This command does not alter existing information in .git/config. | |
101 | You can then customize the submodule clone URLs in .git/config | |
102 | for your local setup and proceed to `git submodule update`; | |
103 | you can also just use `git submodule update --init` without | |
104 | the explicit 'init' step if you do not intend to customize | |
105 | any submodule locations. | |
106 | + | |
64127575 | 107 | See the add subcommand for the definition of default remote. |
70c7ac22 | 108 | |
eb2f2f5f | 109 | deinit [-f|--force] (--all|[--] <path>...):: |
cf419828 JL |
110 | Unregister the given submodules, i.e. remove the whole |
111 | `submodule.$name` section from .git/config together with their work | |
112 | tree. Further calls to `git submodule update`, `git submodule foreach` | |
113 | and `git submodule sync` will skip any unregistered submodules until | |
114 | they are initialized again, so use this command if you don't want to | |
d4803455 | 115 | have a local checkout of the submodule in your working tree anymore. |
cf419828 | 116 | + |
f6a52799 SB |
117 | When the command is run without pathspec, it errors out, |
118 | instead of deinit-ing everything, to prevent mistakes. | |
119 | + | |
120 | If `--force` is specified, the submodule's working tree will | |
121 | be removed even if it contains local modifications. | |
d4803455 SB |
122 | + |
123 | If you really want to remove a submodule from the repository and commit | |
124 | that use linkgit:git-rm[1] instead. See linkgit:gitsubmodules[7] for removal | |
125 | options. | |
cf419828 | 126 | |
eb2f2f5f | 127 | update [--init] [--remote] [-N|--no-fetch] [--[no-]recommend-shallow] [-f|--force] [--checkout|--rebase|--merge] [--reference <repository>] [--depth <depth>] [--recursive] [--jobs <n>] [--] [<path>...]:: |
be4d2c83 | 128 | + |
5c31acfb MS |
129 | -- |
130 | Update the registered submodules to match what the superproject | |
131 | expects by cloning missing submodules and updating the working tree of | |
132 | the submodules. The "updating" can be done in several ways depending | |
133 | on command line options and the value of `submodule.<name>.update` | |
fc01a5d2 | 134 | configuration variable. The command line option takes precedence over |
e1b3f3dd KS |
135 | the configuration variable. If neither is given, a 'checkout' is performed. |
136 | The 'update' procedures supported both from the command line as well as | |
137 | through the `submodule.<name>.update` configuration are: | |
5c31acfb MS |
138 | |
139 | checkout;; the commit recorded in the superproject will be | |
fc01a5d2 | 140 | checked out in the submodule on a detached HEAD. |
5c31acfb MS |
141 | + |
142 | If `--force` is specified, the submodule will be checked out (using | |
e1b3f3dd | 143 | `git checkout --force`), even if the commit specified |
5c31acfb MS |
144 | in the index of the containing repository already matches the commit |
145 | checked out in the submodule. | |
146 | ||
147 | rebase;; the current branch of the submodule will be rebased | |
fc01a5d2 | 148 | onto the commit recorded in the superproject. |
5c31acfb MS |
149 | |
150 | merge;; the commit recorded in the superproject will be merged | |
fc01a5d2 SB |
151 | into the current branch in the submodule. |
152 | ||
e1b3f3dd KS |
153 | The following 'update' procedures are only available via the |
154 | `submodule.<name>.update` configuration variable: | |
5c31acfb MS |
155 | |
156 | custom command;; arbitrary shell command that takes a single | |
157 | argument (the sha1 of the commit recorded in the | |
fc01a5d2 SB |
158 | superproject) is executed. When `submodule.<name>.update` |
159 | is set to '!command', the remainder after the exclamation mark | |
160 | is the custom command. | |
5c31acfb | 161 | |
fc01a5d2 | 162 | none;; the submodule is not updated. |
5c31acfb | 163 | |
be4d2c83 | 164 | If the submodule is not yet initialized, and you just want to use the |
beebc6df | 165 | setting as stored in `.gitmodules`, you can automatically initialize the |
402e8a6d | 166 | submodule with the `--init` option. |
5c31acfb | 167 | |
402e8a6d | 168 | If `--recursive` is specified, this command will recurse into the |
b13fd5c1 | 169 | registered submodules, and update any nested submodules within. |
5c31acfb | 170 | -- |
eb2f2f5f | 171 | summary [--cached|--files] [(-n|--summary-limit) <n>] [commit] [--] [<path>...]:: |
925e7f62 PY |
172 | Show commit summary between the given commit (defaults to HEAD) and |
173 | working tree/index. For a submodule in question, a series of commits | |
174 | in the submodule between the given super project commit and the | |
402e8a6d JL |
175 | index or working tree (switched by `--cached`) are shown. If the option |
176 | `--files` is given, show the series of commits in the submodule between | |
ef92e1a4 | 177 | the index of the super project and the working tree of the submodule |
402e8a6d | 178 | (this option doesn't allow to use the `--cached` option or to provide an |
1c244f6e | 179 | explicit commit). |
402e8a6d JL |
180 | + |
181 | Using the `--submodule=log` option with linkgit:git-diff[1] will provide that | |
182 | information too. | |
70c7ac22 | 183 | |
eb2f2f5f | 184 | foreach [--recursive] <command>:: |
19a31f9c | 185 | Evaluates an arbitrary shell command in each checked out submodule. |
f030c96d ÆAB |
186 | The command has access to the variables $name, $path, $sha1 and |
187 | $toplevel: | |
beebc6df | 188 | $name is the name of the relevant submodule section in `.gitmodules`, |
19a31f9c | 189 | $path is the name of the submodule directory relative to the |
f030c96d ÆAB |
190 | superproject, $sha1 is the commit as recorded in the superproject, |
191 | and $toplevel is the absolute path to the top-level of the superproject. | |
19a31f9c | 192 | Any submodules defined in the superproject but not checked out are |
402e8a6d | 193 | ignored by this command. Unless given `--quiet`, foreach prints the name |
19a31f9c | 194 | of each submodule before evaluating the command. |
402e8a6d | 195 | If `--recursive` is given, submodules are traversed recursively (i.e. |
15fc56a8 | 196 | the given shell command is evaluated in nested submodules as well). |
19a31f9c ML |
197 | A non-zero return from the command in any submodule causes |
198 | the processing to terminate. This can be overridden by adding '|| :' | |
199 | to the end of the command. | |
200 | + | |
e91461b3 JK |
201 | As an example, the command below will show the path and currently |
202 | checked out commit for each submodule: | |
203 | + | |
204 | -------------- | |
205 | git submodule foreach 'echo $path `git rev-parse HEAD`' | |
206 | -------------- | |
19a31f9c | 207 | |
eb2f2f5f | 208 | sync [--recursive] [--] [<path>...]:: |
2327f61e | 209 | Synchronizes submodules' remote URL configuration setting |
beebc6df | 210 | to the value specified in `.gitmodules`. It will only affect those |
a7793a74 | 211 | submodules which already have a URL entry in .git/config (that is the |
ccee6086 | 212 | case when they are initialized or freshly added). This is useful when |
2327f61e DA |
213 | submodule URLs change upstream and you need to update your local |
214 | repositories accordingly. | |
215 | + | |
216 | "git submodule sync" synchronizes all submodules while | |
565e135a | 217 | "git submodule sync \-- A" synchronizes submodule "A" only. |
e7220c40 SB |
218 | + |
219 | If `--recursive` is specified, this command will recurse into the | |
220 | registered submodules, and sync any nested submodules within. | |
19a31f9c | 221 | |
f6f85861 SB |
222 | absorbgitdirs:: |
223 | If a git directory of a submodule is inside the submodule, | |
224 | move the git directory of the submodule into its superprojects | |
225 | `$GIT_DIR/modules` path and then connect the git directory and | |
226 | its working directory by setting the `core.worktree` and adding | |
227 | a .git file pointing to the git directory embedded in the | |
228 | superprojects git directory. | |
229 | + | |
230 | A repository that was cloned independently and later added as a submodule or | |
231 | old setups have the submodules git directory inside the submodule instead of | |
232 | embedded into the superprojects git directory. | |
233 | + | |
234 | This command is recursive by default. | |
235 | ||
70c7ac22 LH |
236 | OPTIONS |
237 | ------- | |
3240240f SB |
238 | -q:: |
239 | --quiet:: | |
70c7ac22 LH |
240 | Only print error messages. |
241 | ||
f6a52799 SB |
242 | --all:: |
243 | This option is only valid for the deinit command. Unregister all | |
244 | submodules in the working tree. | |
245 | ||
3240240f SB |
246 | -b:: |
247 | --branch:: | |
ecda0723 | 248 | Branch of repository to add as submodule. |
15d64936 | 249 | The name of the branch is recorded as `submodule.<name>.branch` in |
15ef7800 BW |
250 | `.gitmodules` for `update --remote`. A special value of `.` is used to |
251 | indicate that the name of the branch in the submodule should be the | |
252 | same name as the current branch in the current repository. | |
ecda0723 | 253 | |
d27b876b JL |
254 | -f:: |
255 | --force:: | |
cf419828 | 256 | This option is only valid for add, deinit and update commands. |
9db31bdf | 257 | When running add, allow adding an otherwise ignored submodule path. |
f6a52799 SB |
258 | When running deinit the submodule working trees will be removed even |
259 | if they contain local changes. | |
5c31acfb MS |
260 | When running update (only effective with the checkout procedure), |
261 | throw away local changes in submodules when switching to a | |
262 | different commit; and always run a checkout operation in the | |
263 | submodule, even if the commit listed in the index of the | |
264 | containing repository matches the commit checked out in the | |
265 | submodule. | |
d27b876b | 266 | |
70c7ac22 | 267 | --cached:: |
925e7f62 PY |
268 | This option is only valid for status and summary commands. These |
269 | commands typically use the commit found in the submodule HEAD, but | |
270 | with this option, the commit stored in the index is used instead. | |
271 | ||
1c244f6e JL |
272 | --files:: |
273 | This option is only valid for the summary command. This command | |
274 | compares the commit in the index with that in the submodule HEAD | |
275 | when this option is used. | |
276 | ||
3240240f SB |
277 | -n:: |
278 | --summary-limit:: | |
925e7f62 PY |
279 | This option is only valid for the summary command. |
280 | Limit the summary size (number of commits shown in total). | |
51836e9e | 281 | Giving 0 will disable the summary; a negative number means unlimited |
925e7f62 PY |
282 | (the default). This limit only applies to modified submodules. The |
283 | size is always limited to 1 for added/deleted/typechanged submodules. | |
70c7ac22 | 284 | |
06b1abb5 TK |
285 | --remote:: |
286 | This option is only valid for the update command. Instead of using | |
287 | the superproject's recorded SHA-1 to update the submodule, use the | |
d6ac1d21 | 288 | status of the submodule's remote-tracking branch. The remote used |
06b1abb5 TK |
289 | is branch's remote (`branch.<name>.remote`), defaulting to `origin`. |
290 | The remote branch used defaults to `master`, but the branch name may | |
291 | be overridden by setting the `submodule.<name>.branch` option in | |
292 | either `.gitmodules` or `.git/config` (with `.git/config` taking | |
293 | precedence). | |
294 | + | |
295 | This works for any of the supported update procedures (`--checkout`, | |
296 | `--rebase`, etc.). The only change is the source of the target SHA-1. | |
297 | For example, `submodule update --remote --merge` will merge upstream | |
298 | submodule changes into the submodules, while `submodule update | |
299 | --merge` will merge superproject gitlink changes into the submodules. | |
300 | + | |
301 | In order to ensure a current tracking branch state, `update --remote` | |
302 | fetches the submodule's remote repository before calculating the | |
303 | SHA-1. If you don't want to fetch, you should use `submodule update | |
304 | --remote --no-fetch`. | |
9937e65d TK |
305 | + |
306 | Use this option to integrate changes from the upstream subproject with | |
307 | your submodule's current HEAD. Alternatively, you can run `git pull` | |
308 | from the submodule, which is equivalent except for the remote branch | |
309 | name: `update --remote` uses the default upstream repository and | |
310 | `submodule.<name>.branch`, while `git pull` uses the submodule's | |
311 | `branch.<name>.merge`. Prefer `submodule.<name>.branch` if you want | |
312 | to distribute the default upstream branch with the superproject and | |
313 | `branch.<name>.merge` if you want a more native feel while working in | |
314 | the submodule itself. | |
06b1abb5 | 315 | |
31ca3ac3 FF |
316 | -N:: |
317 | --no-fetch:: | |
318 | This option is only valid for the update command. | |
319 | Don't fetch new objects from the remote site. | |
320 | ||
893a9764 JL |
321 | --checkout:: |
322 | This option is only valid for the update command. | |
323 | Checkout the commit recorded in the superproject on a detached HEAD | |
324 | in the submodule. This is the default behavior, the main use of | |
325 | this option is to override `submodule.$name.update` when set to | |
5c31acfb | 326 | a value other than `checkout`. |
893a9764 JL |
327 | If the key `submodule.$name.update` is either not explicitly set or |
328 | set to `checkout`, this option is implicit. | |
329 | ||
42b49178 JH |
330 | --merge:: |
331 | This option is only valid for the update command. | |
332 | Merge the commit recorded in the superproject into the current branch | |
333 | of the submodule. If this option is given, the submodule's HEAD will | |
334 | not be detached. If a merge failure prevents this process, you will | |
335 | have to resolve the resulting conflicts within the submodule with the | |
336 | usual conflict resolution tools. | |
337 | If the key `submodule.$name.update` is set to `merge`, this option is | |
338 | implicit. | |
339 | ||
ca2cedba PH |
340 | --rebase:: |
341 | This option is only valid for the update command. | |
342 | Rebase the current branch onto the commit recorded in the | |
343 | superproject. If this option is given, the submodule's HEAD will not | |
6a5d0b0a | 344 | be detached. If a merge failure prevents this process, you will have |
ca2cedba | 345 | to resolve these failures with linkgit:git-rebase[1]. |
32948425 | 346 | If the key `submodule.$name.update` is set to `rebase`, this option is |
ca2cedba PH |
347 | implicit. |
348 | ||
402e8a6d JL |
349 | --init:: |
350 | This option is only valid for the update command. | |
351 | Initialize all submodules for which "git submodule init" has not been | |
352 | called so far before updating. | |
353 | ||
73b0898d JL |
354 | --name:: |
355 | This option is only valid for the add command. It sets the submodule's | |
356 | name to the given string instead of defaulting to its path. The name | |
357 | must be valid as a directory name and may not end with a '/'. | |
358 | ||
d92a3959 MT |
359 | --reference <repository>:: |
360 | This option is only valid for add and update commands. These | |
361 | commands sometimes need to clone a remote repository. In this case, | |
362 | this option will be passed to the linkgit:git-clone[1] command. | |
363 | + | |
364 | *NOTE*: Do *not* use this option unless you have read the note | |
402e8a6d | 365 | for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. |
d92a3959 | 366 | |
15fc56a8 | 367 | --recursive:: |
e7220c40 | 368 | This option is only valid for foreach, update, status and sync commands. |
15fc56a8 JH |
369 | Traverse submodules recursively. The operation is performed not |
370 | only in the submodules of the current repo, but also | |
371 | in any nested submodules inside those submodules (and so on). | |
372 | ||
275cd184 FG |
373 | --depth:: |
374 | This option is valid for add and update commands. Create a 'shallow' | |
375 | clone with a history truncated to the specified number of revisions. | |
376 | See linkgit:git-clone[1] | |
377 | ||
abed000a SB |
378 | --[no-]recommend-shallow:: |
379 | This option is only valid for the update command. | |
380 | The initial clone of a submodule will use the recommended | |
beebc6df | 381 | `submodule.<name>.shallow` as provided by the `.gitmodules` file |
abed000a SB |
382 | by default. To ignore the suggestions use `--no-recommend-shallow`. |
383 | ||
2335b870 SB |
384 | -j <n>:: |
385 | --jobs <n>:: | |
386 | This option is only valid for the update command. | |
387 | Clone new submodules in parallel with as many jobs. | |
388 | Defaults to the `submodule.fetchJobs` option. | |
275cd184 | 389 | |
f448e24e AMS |
390 | <path>...:: |
391 | Paths to submodule(s). When specified this will restrict the command | |
70c7ac22 | 392 | to only operate on the submodules found at the specified paths. |
ec05df35 | 393 | (This argument is required with add). |
70c7ac22 LH |
394 | |
395 | FILES | |
396 | ----- | |
beebc6df | 397 | When initializing submodules, a `.gitmodules` file in the top-level directory |
70c7ac22 | 398 | of the containing repository is used to find the url of each submodule. |
c4585701 | 399 | This file should be formatted in the same way as `$GIT_DIR/config`. The key |
5162e697 | 400 | to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] |
6fbe42c7 | 401 | for details. |
70c7ac22 | 402 | |
d4803455 SB |
403 | SEE ALSO |
404 | -------- | |
405 | linkgit:gitsubmodules[7], linkgit:gitmodules[5]. | |
406 | ||
70c7ac22 LH |
407 | GIT |
408 | --- | |
9e1f0a85 | 409 | Part of the linkgit:git[1] suite |