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