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