blob: ad78d44b776083fc014089ff39148887ec1630e3 [file] [log] [blame]
Junio C Hamano38b693c2007-06-03 08:40:141<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
5<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
Junio C Hamanoba4b9282008-07-06 05:20:316<meta name="generator" content="AsciiDoc 8.2.5" />
Junio C Hamano38b693c2007-06-03 08:40:147<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
Junio C Hamanoba4b9282008-07-06 05:20:3119a {
20 color: blue;
21 text-decoration: underline;
22}
23a:visited {
24 color: fuchsia;
25}
Junio C Hamano38b693c2007-06-03 08:40:1426
27em {
28 font-style: italic;
29}
30
31strong {
32 font-weight: bold;
33}
34
35tt {
36 color: navy;
37}
38
39h1, h2, h3, h4, h5, h6 {
40 color: #527bbd;
41 font-family: sans-serif;
42 margin-top: 1.2em;
43 margin-bottom: 0.5em;
44 line-height: 1.3;
45}
46
Junio C Hamanoba4b9282008-07-06 05:20:3147h1, h2, h3 {
Junio C Hamano38b693c2007-06-03 08:40:1448 border-bottom: 2px solid silver;
49}
50h2 {
Junio C Hamano38b693c2007-06-03 08:40:1451 padding-top: 0.5em;
52}
Junio C Hamanoba4b9282008-07-06 05:20:3153h3 {
54 float: left;
55}
56h3 + * {
57 clear: left;
58}
Junio C Hamano38b693c2007-06-03 08:40:1459
60div.sectionbody {
61 font-family: serif;
62 margin-left: 0;
63}
64
65hr {
66 border: 1px solid silver;
67}
68
69p {
70 margin-top: 0.5em;
71 margin-bottom: 0.5em;
72}
73
74pre {
75 padding: 0;
76 margin: 0;
77}
78
79span#author {
80 color: #527bbd;
81 font-family: sans-serif;
82 font-weight: bold;
Junio C Hamanoba4b9282008-07-06 05:20:3183 font-size: 1.1em;
Junio C Hamano38b693c2007-06-03 08:40:1484}
85span#email {
86}
87span#revision {
88 font-family: sans-serif;
89}
90
91div#footer {
92 font-family: sans-serif;
93 font-size: small;
94 border-top: 2px solid silver;
95 padding-top: 0.5em;
96 margin-top: 4.0em;
97}
98div#footer-text {
99 float: left;
100 padding-bottom: 0.5em;
101}
102div#footer-badges {
103 float: right;
104 padding-bottom: 0.5em;
105}
106
107div#preamble,
108div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
109div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
110div.admonitionblock {
111 margin-right: 10%;
112 margin-top: 1.5em;
113 margin-bottom: 1.5em;
114}
115div.admonitionblock {
116 margin-top: 2.5em;
117 margin-bottom: 2.5em;
118}
119
120div.content { /* Block element content. */
121 padding: 0;
122}
123
124/* Block element titles. */
125div.title, caption.title {
126 font-family: sans-serif;
127 font-weight: bold;
128 text-align: left;
129 margin-top: 1.0em;
130 margin-bottom: 0.5em;
131}
132div.title + * {
133 margin-top: 0;
134}
135
136td div.title:first-child {
137 margin-top: 0.0em;
138}
139div.content div.title:first-child {
140 margin-top: 0.0em;
141}
142div.content + div.title {
143 margin-top: 0.0em;
144}
145
146div.sidebarblock > div.content {
147 background: #ffffee;
148 border: 1px solid silver;
149 padding: 0.5em;
150}
151
Junio C Hamanoba4b9282008-07-06 05:20:31152div.listingblock {
153 margin-right: 0%;
154}
Junio C Hamano38b693c2007-06-03 08:40:14155div.listingblock > div.content {
156 border: 1px solid silver;
157 background: #f4f4f4;
158 padding: 0.5em;
159}
160
161div.quoteblock > div.content {
162 padding-left: 2.0em;
163}
Junio C Hamanoba4b9282008-07-06 05:20:31164
165div.attribution {
Junio C Hamano38b693c2007-06-03 08:40:14166 text-align: right;
167}
Junio C Hamanoba4b9282008-07-06 05:20:31168div.verseblock + div.attribution {
169 text-align: left;
170}
Junio C Hamano38b693c2007-06-03 08:40:14171
172div.admonitionblock .icon {
173 vertical-align: top;
174 font-size: 1.1em;
175 font-weight: bold;
176 text-decoration: underline;
177 color: #527bbd;
178 padding-right: 0.5em;
179}
180div.admonitionblock td.content {
181 padding-left: 0.5em;
182 border-left: 2px solid silver;
183}
184
185div.exampleblock > div.content {
186 border-left: 2px solid silver;
187 padding: 0.5em;
188}
189
190div.verseblock div.content {
191 white-space: pre;
192}
193
194div.imageblock div.content { padding-left: 0; }
195div.imageblock img { border: 1px solid silver; }
196span.image img { border-style: none; }
197
198dl {
199 margin-top: 0.8em;
200 margin-bottom: 0.8em;
201}
202dt {
203 margin-top: 0.5em;
204 margin-bottom: 0;
205 font-style: italic;
206}
207dd > *:first-child {
208 margin-top: 0;
209}
210
211ul, ol {
212 list-style-position: outside;
213}
Junio C Hamanoba4b9282008-07-06 05:20:31214div.olist2 ol {
Junio C Hamano38b693c2007-06-03 08:40:14215 list-style-type: lower-alpha;
216}
217
218div.tableblock > table {
Junio C Hamanoba4b9282008-07-06 05:20:31219 border: 3px solid #527bbd;
Junio C Hamano38b693c2007-06-03 08:40:14220}
221thead {
222 font-family: sans-serif;
223 font-weight: bold;
224}
225tfoot {
226 font-weight: bold;
227}
228
229div.hlist {
230 margin-top: 0.8em;
231 margin-bottom: 0.8em;
232}
Junio C Hamanoba4b9282008-07-06 05:20:31233div.hlist td {
234 padding-bottom: 5px;
235}
Junio C Hamano38b693c2007-06-03 08:40:14236td.hlist1 {
237 vertical-align: top;
238 font-style: italic;
239 padding-right: 0.8em;
240}
241td.hlist2 {
242 vertical-align: top;
243}
244
245@media print {
246 div#footer-badges { display: none; }
247}
Junio C Hamanoba4b9282008-07-06 05:20:31248
249div#toctitle {
250 color: #527bbd;
251 font-family: sans-serif;
252 font-size: 1.1em;
253 font-weight: bold;
254 margin-top: 1.0em;
255 margin-bottom: 0.1em;
256}
257
258div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
259 margin-top: 0;
260 margin-bottom: 0;
261}
262div.toclevel2 {
263 margin-left: 2em;
264 font-size: 0.9em;
265}
266div.toclevel3 {
267 margin-left: 4em;
268 font-size: 0.9em;
269}
270div.toclevel4 {
271 margin-left: 6em;
272 font-size: 0.9em;
273}
274include1::./stylesheets/xhtml11-manpage.css[]
Junio C Hamano38b693c2007-06-03 08:40:14275/* Workarounds for IE6's broken and incomplete CSS2. */
276
277div.sidebar-content {
278 background: #ffffee;
279 border: 1px solid silver;
280 padding: 0.5em;
281}
282div.sidebar-title, div.image-title {
283 font-family: sans-serif;
284 font-weight: bold;
285 margin-top: 0.0em;
286 margin-bottom: 0.5em;
287}
288
289div.listingblock div.content {
290 border: 1px solid silver;
291 background: #f4f4f4;
292 padding: 0.5em;
293}
294
295div.quoteblock-content {
296 padding-left: 2.0em;
297}
298
299div.exampleblock-content {
300 border-left: 2px solid silver;
301 padding-left: 0.5em;
302}
Junio C Hamanoba4b9282008-07-06 05:20:31303
304/* IE6 sets dynamically generated links as visited. */
305div#toc a:visited { color: blue; }
Junio C Hamano38b693c2007-06-03 08:40:14306</style>
307<title>git-submodule(1)</title>
308</head>
309<body>
310<div id="header">
311<h1>
312git-submodule(1) Manual Page
313</h1>
314<h2>NAME</h2>
315<div class="sectionbody">
316<p>git-submodule -
317 Initialize, update or inspect submodules
318</p>
319</div>
320</div>
321<h2>SYNOPSIS</h2>
322<div class="sectionbody">
Junio C Hamano7a4a2832007-07-07 21:53:22323<div class="verseblock">
Junio C Hamano38ddcce2008-07-15 15:49:03324<div class="content"><em>git submodule</em> [--quiet] add [-b branch] [--] &lt;repository&gt; &lt;path&gt;
Junio C Hamanofce7c7e2008-07-02 03:06:38325<em>git submodule</em> [--quiet] status [--cached] [--] [&lt;path&gt;&#8230;]
326<em>git submodule</em> [--quiet] init [--] [&lt;path&gt;&#8230;]
Junio C Hamano8bc410e2009-02-15 10:38:19327<em>git submodule</em> [--quiet] update [--init] [-N|--no-fetch] [--] [&lt;path&gt;&#8230;]
Junio C Hamano3f2f6e52008-08-21 10:34:22328<em>git submodule</em> [--quiet] summary [--summary-limit &lt;n&gt;] [commit] [--] [&lt;path&gt;&#8230;]
Junio C Hamanof9e04eb2008-08-28 02:50:50329<em>git submodule</em> [--quiet] foreach &lt;command&gt;
330<em>git submodule</em> [--quiet] sync [--] [&lt;path&gt;&#8230;]</div></div>
Junio C Hamano38b693c2007-06-03 08:40:14331</div>
Junio C Hamanof69a0a02008-07-17 08:08:47332<h2 id="_description">DESCRIPTION</h2>
333<div class="sectionbody">
Junio C Hamano915cd9b2008-07-20 01:24:17334<div class="para"><p>Submodules allow foreign repositories to be embedded within
335a dedicated subdirectory of the source tree, always pointed
336at a particular commit.</p></div>
337<div class="para"><p>They are not to be confused with remotes, which are meant mainly
338for branches of the same project; submodules are meant for
339different projects you would like to make part of your source tree,
340while the history of the two projects still stays completely
341independent and you cannot modify the contents of the submodule
342from within the main project.
343If you want to merge the project histories and want to treat the
344aggregated whole as a single project from then on, you may want to
345add a remote for the other project and use the <em>subtree</em> merge strategy,
346instead of treating the other project as a submodule. Directories
347that come from both projects can be cloned and checked out as a whole
348if you choose to go that route.</p></div>
349<div class="para"><p>Submodules are composed from a so-called <tt>gitlink</tt> tree entry
350in the main repository that refers to a particular commit object
351within the inner repository that is completely separate.
352A record in the <tt>.gitmodules</tt> file at the root of the source
353tree assigns a logical name to the submodule and describes
354the default URL the submodule shall be cloned from.
355The logical name can be used for overriding this URL within your
356local repository configuration (see <em>submodule init</em>).</p></div>
357<div class="para"><p>This command will manage the tree entries and contents of the
358gitmodules file for you, as well as inspect the status of your
359submodules and update them.
360When adding a new submodule to the tree, the <em>add</em> subcommand
361is to be used. However, when pulling a tree containing submodules,
362these will not be checked out by default;
363the <em>init</em> and <em>update</em> subcommands will maintain submodules
364checked out and at appropriate revision in your working tree.
365You can briefly inspect the up-to-date status of your submodules
366using the <em>status</em> subcommand and get a detailed overview of the
367difference between the index and checkouts using the <em>summary</em>
368subcommand.</p></div>
Junio C Hamanof69a0a02008-07-17 08:08:47369</div>
Junio C Hamanoba4b9282008-07-06 05:20:31370<h2 id="_commands">COMMANDS</h2>
Junio C Hamano38b693c2007-06-03 08:40:14371<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31372<div class="vlist"><dl>
Junio C Hamano38b693c2007-06-03 08:40:14373<dt>
Junio C Hamano1d90cb02007-07-03 07:05:31374add
375</dt>
376<dd>
377<p>
378 Add the given repository as a submodule at the given path
Junio C Hamano38ddcce2008-07-15 15:49:03379 to the changeset to be committed next to the current
Junio C Hamano85c71572008-07-28 00:03:31380 project: the current project is termed the "superproject".
Junio C Hamano1d90cb02007-07-03 07:05:31381</p>
Junio C Hamano38ddcce2008-07-15 15:49:03382<div class="para"><p>This requires two arguments: &lt;repository&gt; and &lt;path&gt;.</p></div>
383<div class="para"><p>&lt;repository&gt; is the URL of the new submodule's origin repository.
384This may be either an absolute URL, or (if it begins with ./
385or ../), the location relative to the superproject's origin
386repository.</p></div>
387<div class="para"><p>&lt;path&gt; is the relative location for the cloned submodule to
388exist in the superproject. If &lt;path&gt; does not exist, then the
389submodule is created by cloning from the named URL. If &lt;path&gt; does
390exist and is already a valid git repository, then this is added
391to the changeset without cloning. This second form is provided
392to ease creating a new submodule from scratch, and presumes
393the user will later push the submodule to the given URL.</p></div>
394<div class="para"><p>In either case, the given URL is recorded into .gitmodules for
395use by subsequent users cloning the superproject. If the URL is
396given relative to the superproject's repository, the presumption
397is the superproject and submodule repositories will be kept
398together in the same relative location, and only the
Junio C Hamano54bf1e22008-12-20 06:30:11399superproject's URL needs to be provided: git-submodule will correctly
Junio C Hamano38ddcce2008-07-15 15:49:03400locate the submodule using the relative URL in .gitmodules.</p></div>
Junio C Hamano1d90cb02007-07-03 07:05:31401</dd>
402<dt>
Junio C Hamano38b693c2007-06-03 08:40:14403status
404</dt>
405<dd>
406<p>
407 Show the status of the submodules. This will print the SHA-1 of the
408 currently checked out commit for each submodule, along with the
Junio C Hamanoba4b9282008-07-06 05:20:31409 submodule path and the output of <em>git-describe</em> for the
Junio C Hamano38b693c2007-06-03 08:40:14410 SHA-1. Each SHA-1 will be prefixed with <tt>-</tt> if the submodule is not
411 initialized and <tt>+</tt> if the currently checked out submodule commit
412 does not match the SHA-1 found in the index of the containing
Junio C Hamanoba4b9282008-07-06 05:20:31413 repository. This command is the default command for <em>git-submodule</em>.
Junio C Hamano38b693c2007-06-03 08:40:14414</p>
415</dd>
416<dt>
417init
418</dt>
419<dd>
420<p>
Junio C Hamano915cd9b2008-07-20 01:24:17421 Initialize the submodules, i.e. register each submodule name
422 and url found in .gitmodules into .git/config.
423 The key used in .git/config is <tt>submodule.$name.url</tt>.
424 This command does not alter existing information in .git/config.
425 You can then customize the submodule clone URLs in .git/config
426 for your local setup and proceed to <em>git submodule update</em>;
427 you can also just use <em>git submodule update --init</em> without
428 the explicit <em>init</em> step if you do not intend to customize
429 any submodule locations.
Junio C Hamano38b693c2007-06-03 08:40:14430</p>
431</dd>
432<dt>
433update
434</dt>
435<dd>
436<p>
Junio C Hamano16f98872007-06-12 16:09:14437 Update the registered submodules, i.e. clone missing submodules and
438 checkout the commit specified in the index of the containing repository.
439 This will make the submodules HEAD be detached.
Junio C Hamano38b693c2007-06-03 08:40:14440</p>
Junio C Hamanoba4b9282008-07-06 05:20:31441<div class="para"><p>If the submodule is not yet initialized, and you just want to use the
Junio C Hamano0f7b5a92008-05-17 06:12:23442setting as stored in .gitmodules, you can automatically initialize the
Junio C Hamanoba4b9282008-07-06 05:20:31443submodule with the --init option.</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14444</dd>
Junio C Hamano8b588d52008-03-15 09:48:37445<dt>
446summary
447</dt>
448<dd>
449<p>
450 Show commit summary between the given commit (defaults to HEAD) and
451 working tree/index. For a submodule in question, a series of commits
452 in the submodule between the given super project commit and the
453 index or working tree (switched by --cached) are shown.
454</p>
455</dd>
Junio C Hamano3f2f6e52008-08-21 10:34:22456<dt>
457foreach
458</dt>
459<dd>
460<p>
461 Evaluates an arbitrary shell command in each checked out submodule.
462 The command has access to the variables $path and $sha1:
463 $path is the name of the submodule directory relative to the
464 superproject, and $sha1 is the commit as recorded in the superproject.
465 Any submodules defined in the superproject but not checked out are
466 ignored by this command. Unless given --quiet, foreach prints the name
467 of each submodule before evaluating the command.
468 A non-zero return from the command in any submodule causes
469 the processing to terminate. This can be overridden by adding <em>|| :</em>
470 to the end of the command.
471</p>
472<div class="para"><p>As an example, "git submodule foreach <em>echo $path <tt>git rev-parse HEAD</tt></em> will
473show the path and currently checked out commit for each submodule.</p></div>
474</dd>
Junio C Hamanof9e04eb2008-08-28 02:50:50475<dt>
476sync
477</dt>
478<dd>
479<p>
480 Synchronizes submodules' remote URL configuration setting
481 to the value specified in .gitmodules. This is useful when
482 submodule URLs change upstream and you need to update your local
483 repositories accordingly.
484</p>
485<div class="para"><p>"git submodule sync" synchronizes all submodules while
486"git submodule sync &#8212; A" synchronizes submodule "A" only.</p></div>
487</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31488</dl></div>
Junio C Hamano38b693c2007-06-03 08:40:14489</div>
Junio C Hamanoba4b9282008-07-06 05:20:31490<h2 id="_options">OPTIONS</h2>
Junio C Hamano38b693c2007-06-03 08:40:14491<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31492<div class="vlist"><dl>
Junio C Hamano38b693c2007-06-03 08:40:14493<dt>
Junio C Hamanoeb415992008-06-08 22:49:47494-q
495</dt>
496<dt>
497--quiet
Junio C Hamano38b693c2007-06-03 08:40:14498</dt>
499<dd>
500<p>
501 Only print error messages.
502</p>
503</dd>
504<dt>
Junio C Hamanoeb415992008-06-08 22:49:47505-b
506</dt>
507<dt>
508--branch
Junio C Hamano1d90cb02007-07-03 07:05:31509</dt>
510<dd>
511<p>
512 Branch of repository to add as submodule.
513</p>
514</dd>
515<dt>
Junio C Hamano38b693c2007-06-03 08:40:14516--cached
517</dt>
518<dd>
519<p>
Junio C Hamano8b588d52008-03-15 09:48:37520 This option is only valid for status and summary commands. These
521 commands typically use the commit found in the submodule HEAD, but
522 with this option, the commit stored in the index is used instead.
523</p>
524</dd>
525<dt>
Junio C Hamanoeb415992008-06-08 22:49:47526-n
527</dt>
528<dt>
529--summary-limit
Junio C Hamano8b588d52008-03-15 09:48:37530</dt>
531<dd>
532<p>
533 This option is only valid for the summary command.
534 Limit the summary size (number of commits shown in total).
Junio C Hamano1bdd3b02008-04-13 05:33:18535 Giving 0 will disable the summary; a negative number means unlimited
Junio C Hamano8b588d52008-03-15 09:48:37536 (the default). This limit only applies to modified submodules. The
537 size is always limited to 1 for added/deleted/typechanged submodules.
Junio C Hamano38b693c2007-06-03 08:40:14538</p>
539</dd>
540<dt>
Junio C Hamano8bc410e2009-02-15 10:38:19541-N
542</dt>
543<dt>
544--no-fetch
545</dt>
546<dd>
547<p>
548 This option is only valid for the update command.
549 Don't fetch new objects from the remote site.
550</p>
551</dd>
552<dt>
Junio C Hamano9e395072008-07-31 22:11:21553&lt;path&gt;&#8230;
Junio C Hamano38b693c2007-06-03 08:40:14554</dt>
555<dd>
556<p>
Junio C Hamano9e395072008-07-31 22:11:21557 Paths to submodule(s). When specified this will restrict the command
Junio C Hamano38b693c2007-06-03 08:40:14558 to only operate on the submodules found at the specified paths.
Junio C Hamano38ddcce2008-07-15 15:49:03559 (This argument is required with add).
Junio C Hamano38b693c2007-06-03 08:40:14560</p>
561</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31562</dl></div>
Junio C Hamano38b693c2007-06-03 08:40:14563</div>
Junio C Hamanoba4b9282008-07-06 05:20:31564<h2 id="_files">FILES</h2>
Junio C Hamano38b693c2007-06-03 08:40:14565<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31566<div class="para"><p>When initializing submodules, a .gitmodules file in the top-level directory
Junio C Hamano38b693c2007-06-03 08:40:14567of the containing repository is used to find the url of each submodule.
Junio C Hamano91baf102007-12-31 09:44:26568This file should be formatted in the same way as <tt>$GIT_DIR/config</tt>. The key
Junio C Hamanoe66c6c02007-12-17 08:26:13569to each submodule url is "submodule.$name.url". See <a href="gitmodules.html">gitmodules(5)</a>
Junio C Hamanoba4b9282008-07-06 05:20:31570for details.</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14571</div>
Junio C Hamanoba4b9282008-07-06 05:20:31572<h2 id="_author">AUTHOR</h2>
Junio C Hamano38b693c2007-06-03 08:40:14573<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31574<div class="para"><p>Written by Lars Hjemli &lt;hjemli@gmail.com&gt;</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14575</div>
Junio C Hamanoba4b9282008-07-06 05:20:31576<h2 id="_git">GIT</h2>
Junio C Hamano38b693c2007-06-03 08:40:14577<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31578<div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14579</div>
580<div id="footer">
581<div id="footer-text">
Junio C Hamano9572e922009-04-02 06:52:03582Last updated 2009-04-02 06:50:05 UTC
Junio C Hamano38b693c2007-06-03 08:40:14583</div>
584</div>
585</body>
586</html>