]>
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] |
d27b876b | 12 | 'git submodule' [--quiet] add [-b branch] [-f|--force] |
1414e578 | 13 | [--reference <repository>] [--] <repository> [<path>] |
64b19ffe | 14 | 'git submodule' [--quiet] status [--cached] [--recursive] [--] [<path>...] |
b1889c36 | 15 | 'git submodule' [--quiet] init [--] [<path>...] |
7d40f891 | 16 | 'git submodule' [--quiet] update [--init] [-N|--no-fetch] [--rebase] |
b13fd5c1 | 17 | [--reference <repository>] [--merge] [--recursive] [--] [<path>...] |
402e8a6d JL |
18 | 'git submodule' [--quiet] summary [--cached|--files] [(-n|--summary-limit) <n>] |
19 | [commit] [--] [<path>...] | |
15fc56a8 | 20 | 'git submodule' [--quiet] foreach [--recursive] <command> |
2327f61e | 21 | 'git submodule' [--quiet] sync [--] [<path>...] |
70c7ac22 LH |
22 | |
23 | ||
e38953ab PB |
24 | DESCRIPTION |
25 | ----------- | |
c47f1024 PB |
26 | Submodules allow foreign repositories to be embedded within |
27 | a dedicated subdirectory of the source tree, always pointed | |
28 | at a particular commit. | |
29 | ||
30 | They are not to be confused with remotes, which are meant mainly | |
31 | for branches of the same project; submodules are meant for | |
32 | different projects you would like to make part of your source tree, | |
33 | while the history of the two projects still stays completely | |
34 | independent and you cannot modify the contents of the submodule | |
35 | from within the main project. | |
36 | If you want to merge the project histories and want to treat the | |
37 | aggregated whole as a single project from then on, you may want to | |
38 | add a remote for the other project and use the 'subtree' merge strategy, | |
39 | instead of treating the other project as a submodule. Directories | |
40 | that come from both projects can be cloned and checked out as a whole | |
41 | if you choose to go that route. | |
42 | ||
43 | Submodules are composed from a so-called `gitlink` tree entry | |
44 | in the main repository that refers to a particular commit object | |
45 | within the inner repository that is completely separate. | |
46 | A record in the `.gitmodules` file at the root of the source | |
47 | tree assigns a logical name to the submodule and describes | |
48 | the default URL the submodule shall be cloned from. | |
49 | The logical name can be used for overriding this URL within your | |
50 | local repository configuration (see 'submodule init'). | |
51 | ||
52 | This command will manage the tree entries and contents of the | |
53 | gitmodules file for you, as well as inspect the status of your | |
54 | submodules and update them. | |
55 | When adding a new submodule to the tree, the 'add' subcommand | |
56 | is to be used. However, when pulling a tree containing submodules, | |
57 | these will not be checked out by default; | |
58 | the 'init' and 'update' subcommands will maintain submodules | |
59 | checked out and at appropriate revision in your working tree. | |
60 | You can briefly inspect the up-to-date status of your submodules | |
61 | using the 'status' subcommand and get a detailed overview of the | |
62 | difference between the index and checkouts using the 'summary' | |
63 | subcommand. | |
e38953ab PB |
64 | |
65 | ||
70c7ac22 LH |
66 | COMMANDS |
67 | -------- | |
ecda0723 SV |
68 | add:: |
69 | Add the given repository as a submodule at the given path | |
ec05df35 | 70 | to the changeset to be committed next to the current |
77ef80a8 | 71 | project: the current project is termed the "superproject". |
ec05df35 | 72 | + |
1414e578 JL |
73 | This requires at least one argument: <repository>. The optional |
74 | argument <path> is the relative location for the cloned submodule | |
75 | to exist in the superproject. If <path> is not given, the | |
76 | "humanish" part of the source repository is used ("repo" for | |
77 | "/path/to/repo.git" and "foo" for "host.xz:foo/.git"). | |
ec05df35 ML |
78 | + |
79 | <repository> is the URL of the new submodule's origin repository. | |
80 | This may be either an absolute URL, or (if it begins with ./ | |
81 | or ../), the location relative to the superproject's origin | |
4d689320 JL |
82 | repository. If the superproject doesn't have an origin configured |
83 | the superproject is its own authoritative upstream and the current | |
84 | working directory is used instead. | |
ec05df35 ML |
85 | + |
86 | <path> is the relative location for the cloned submodule to | |
87 | exist in the superproject. If <path> does not exist, then the | |
88 | submodule is created by cloning from the named URL. If <path> does | |
89 | exist and is already a valid git repository, then this is added | |
90 | to the changeset without cloning. This second form is provided | |
91 | to ease creating a new submodule from scratch, and presumes | |
92 | the user will later push the submodule to the given URL. | |
93 | + | |
94 | In either case, the given URL is recorded into .gitmodules for | |
95 | use by subsequent users cloning the superproject. If the URL is | |
96 | given relative to the superproject's repository, the presumption | |
97 | is the superproject and submodule repositories will be kept | |
98 | together in the same relative location, and only the | |
04c8ce9c | 99 | superproject's URL needs to be provided: git-submodule will correctly |
ec05df35 | 100 | locate the submodule using the relative URL in .gitmodules. |
ecda0723 | 101 | |
70c7ac22 LH |
102 | status:: |
103 | Show the status of the submodules. This will print the SHA-1 of the | |
104 | currently checked out commit for each submodule, along with the | |
0b444cdb | 105 | submodule path and the output of 'git describe' for the |
70c7ac22 | 106 | SHA-1. Each SHA-1 will be prefixed with `-` if the submodule is not |
313ee0d6 | 107 | initialized, `+` if the currently checked out submodule commit |
70c7ac22 | 108 | does not match the SHA-1 found in the index of the containing |
313ee0d6 NMC |
109 | repository and `U` if the submodule has merge conflicts. |
110 | This command is the default command for 'git submodule'. | |
64b19ffe | 111 | + |
402e8a6d | 112 | If `--recursive` is specified, this command will recurse into nested |
64b19ffe | 113 | submodules, and show their status as well. |
402e8a6d JL |
114 | + |
115 | If you are only interested in changes of the currently initialized | |
116 | submodules with respect to the commit recorded in the index or the HEAD, | |
117 | linkgit:git-status[1] and linkgit:git-diff[1] will provide that information | |
118 | too (and can also report changes to a submodule's work tree). | |
70c7ac22 LH |
119 | |
120 | init:: | |
c47f1024 PB |
121 | Initialize the submodules, i.e. register each submodule name |
122 | and url found in .gitmodules into .git/config. | |
123 | The key used in .git/config is `submodule.$name.url`. | |
124 | This command does not alter existing information in .git/config. | |
125 | You can then customize the submodule clone URLs in .git/config | |
ca768288 TR |
126 | for your local setup and proceed to `git submodule update`; |
127 | you can also just use `git submodule update --init` without | |
c47f1024 PB |
128 | the explicit 'init' step if you do not intend to customize |
129 | any submodule locations. | |
70c7ac22 LH |
130 | |
131 | update:: | |
211b7f19 LH |
132 | Update the registered submodules, i.e. clone missing submodules and |
133 | checkout the commit specified in the index of the containing repository. | |
402e8a6d JL |
134 | This will make the submodules HEAD be detached unless `--rebase` or |
135 | `--merge` is specified or the key `submodule.$name.update` is set to | |
42b49178 | 136 | `rebase` or `merge`. |
be4d2c83 JS |
137 | + |
138 | If the submodule is not yet initialized, and you just want to use the | |
139 | setting as stored in .gitmodules, you can automatically initialize the | |
402e8a6d | 140 | submodule with the `--init` option. |
b13fd5c1 | 141 | + |
402e8a6d | 142 | If `--recursive` is specified, this command will recurse into the |
b13fd5c1 | 143 | registered submodules, and update any nested submodules within. |
70c7ac22 | 144 | |
925e7f62 PY |
145 | summary:: |
146 | Show commit summary between the given commit (defaults to HEAD) and | |
147 | working tree/index. For a submodule in question, a series of commits | |
148 | in the submodule between the given super project commit and the | |
402e8a6d JL |
149 | index or working tree (switched by `--cached`) are shown. If the option |
150 | `--files` is given, show the series of commits in the submodule between | |
ef92e1a4 | 151 | the index of the super project and the working tree of the submodule |
402e8a6d | 152 | (this option doesn't allow to use the `--cached` option or to provide an |
1c244f6e | 153 | explicit commit). |
402e8a6d JL |
154 | + |
155 | Using the `--submodule=log` option with linkgit:git-diff[1] will provide that | |
156 | information too. | |
70c7ac22 | 157 | |
19a31f9c ML |
158 | foreach:: |
159 | Evaluates an arbitrary shell command in each checked out submodule. | |
f030c96d ÆAB |
160 | The command has access to the variables $name, $path, $sha1 and |
161 | $toplevel: | |
1e7f2aad | 162 | $name is the name of the relevant submodule section in .gitmodules, |
19a31f9c | 163 | $path is the name of the submodule directory relative to the |
f030c96d ÆAB |
164 | superproject, $sha1 is the commit as recorded in the superproject, |
165 | and $toplevel is the absolute path to the top-level of the superproject. | |
19a31f9c | 166 | Any submodules defined in the superproject but not checked out are |
402e8a6d | 167 | ignored by this command. Unless given `--quiet`, foreach prints the name |
19a31f9c | 168 | of each submodule before evaluating the command. |
402e8a6d | 169 | If `--recursive` is given, submodules are traversed recursively (i.e. |
15fc56a8 | 170 | the given shell command is evaluated in nested submodules as well). |
19a31f9c ML |
171 | A non-zero return from the command in any submodule causes |
172 | the processing to terminate. This can be overridden by adding '|| :' | |
173 | to the end of the command. | |
174 | + | |
1c3acfcd MV |
175 | As an example, +git submodule foreach \'echo $path {backtick}git |
176 | rev-parse HEAD{backtick}'+ will show the path and currently checked out | |
177 | commit for each submodule. | |
19a31f9c | 178 | |
2327f61e DA |
179 | sync:: |
180 | Synchronizes submodules' remote URL configuration setting | |
ccee6086 JH |
181 | to the value specified in .gitmodules. It will only affect those |
182 | submodules which already have an url entry in .git/config (that is the | |
183 | case when they are initialized or freshly added). This is useful when | |
2327f61e DA |
184 | submodule URLs change upstream and you need to update your local |
185 | repositories accordingly. | |
186 | + | |
187 | "git submodule sync" synchronizes all submodules while | |
565e135a | 188 | "git submodule sync \-- A" synchronizes submodule "A" only. |
19a31f9c | 189 | |
70c7ac22 LH |
190 | OPTIONS |
191 | ------- | |
3240240f SB |
192 | -q:: |
193 | --quiet:: | |
70c7ac22 LH |
194 | Only print error messages. |
195 | ||
3240240f SB |
196 | -b:: |
197 | --branch:: | |
ecda0723 SV |
198 | Branch of repository to add as submodule. |
199 | ||
d27b876b JL |
200 | -f:: |
201 | --force:: | |
9db31bdf NMC |
202 | This option is only valid for add and update commands. |
203 | When running add, allow adding an otherwise ignored submodule path. | |
204 | When running update, throw away local changes in submodules when | |
205 | switching to a different commit. | |
d27b876b | 206 | |
70c7ac22 | 207 | --cached:: |
925e7f62 PY |
208 | This option is only valid for status and summary commands. These |
209 | commands typically use the commit found in the submodule HEAD, but | |
210 | with this option, the commit stored in the index is used instead. | |
211 | ||
1c244f6e JL |
212 | --files:: |
213 | This option is only valid for the summary command. This command | |
214 | compares the commit in the index with that in the submodule HEAD | |
215 | when this option is used. | |
216 | ||
3240240f SB |
217 | -n:: |
218 | --summary-limit:: | |
925e7f62 PY |
219 | This option is only valid for the summary command. |
220 | Limit the summary size (number of commits shown in total). | |
51836e9e | 221 | Giving 0 will disable the summary; a negative number means unlimited |
925e7f62 PY |
222 | (the default). This limit only applies to modified submodules. The |
223 | size is always limited to 1 for added/deleted/typechanged submodules. | |
70c7ac22 | 224 | |
31ca3ac3 FF |
225 | -N:: |
226 | --no-fetch:: | |
227 | This option is only valid for the update command. | |
228 | Don't fetch new objects from the remote site. | |
229 | ||
42b49178 JH |
230 | --merge:: |
231 | This option is only valid for the update command. | |
232 | Merge the commit recorded in the superproject into the current branch | |
233 | of the submodule. If this option is given, the submodule's HEAD will | |
234 | not be detached. If a merge failure prevents this process, you will | |
235 | have to resolve the resulting conflicts within the submodule with the | |
236 | usual conflict resolution tools. | |
237 | If the key `submodule.$name.update` is set to `merge`, this option is | |
238 | implicit. | |
239 | ||
ca2cedba PH |
240 | --rebase:: |
241 | This option is only valid for the update command. | |
242 | Rebase the current branch onto the commit recorded in the | |
243 | superproject. If this option is given, the submodule's HEAD will not | |
6a5d0b0a | 244 | be detached. If a merge failure prevents this process, you will have |
ca2cedba | 245 | to resolve these failures with linkgit:git-rebase[1]. |
32948425 | 246 | If the key `submodule.$name.update` is set to `rebase`, this option is |
ca2cedba PH |
247 | implicit. |
248 | ||
402e8a6d JL |
249 | --init:: |
250 | This option is only valid for the update command. | |
251 | Initialize all submodules for which "git submodule init" has not been | |
252 | called so far before updating. | |
253 | ||
d92a3959 MT |
254 | --reference <repository>:: |
255 | This option is only valid for add and update commands. These | |
256 | commands sometimes need to clone a remote repository. In this case, | |
257 | this option will be passed to the linkgit:git-clone[1] command. | |
258 | + | |
259 | *NOTE*: Do *not* use this option unless you have read the note | |
402e8a6d | 260 | for linkgit:git-clone[1]'s `--reference` and `--shared` options carefully. |
d92a3959 | 261 | |
15fc56a8 | 262 | --recursive:: |
64b19ffe | 263 | This option is only valid for foreach, update and status commands. |
15fc56a8 JH |
264 | Traverse submodules recursively. The operation is performed not |
265 | only in the submodules of the current repo, but also | |
266 | in any nested submodules inside those submodules (and so on). | |
267 | ||
f448e24e AMS |
268 | <path>...:: |
269 | Paths to submodule(s). When specified this will restrict the command | |
70c7ac22 | 270 | to only operate on the submodules found at the specified paths. |
ec05df35 | 271 | (This argument is required with add). |
70c7ac22 LH |
272 | |
273 | FILES | |
274 | ----- | |
211b7f19 | 275 | When initializing submodules, a .gitmodules file in the top-level directory |
70c7ac22 | 276 | of the containing repository is used to find the url of each submodule. |
c4585701 | 277 | This file should be formatted in the same way as `$GIT_DIR/config`. The key |
5162e697 | 278 | to each submodule url is "submodule.$name.url". See linkgit:gitmodules[5] |
6fbe42c7 | 279 | for details. |
70c7ac22 | 280 | |
70c7ac22 LH |
281 | GIT |
282 | --- | |
9e1f0a85 | 283 | Part of the linkgit:git[1] suite |