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