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