Google Git
Sign in
chromium / external / gitster / git-htmldocs / 46a38aa8be7b8f7b5afdeeea0744859b3e03d5a2 / . / git-submodule.html
blob: a222a7e4f4bedac03eeff48492c5fa9181a4f41e [file] [log] [blame]
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]1<!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:31[diff] [blame]6<meta name="generator" content="AsciiDoc 8.2.5" />
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]7<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:31[diff] [blame]19a {
20 color: blue;
21 text-decoration: underline;
22}
23a:visited {
24 color: fuchsia;
25}
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]26
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:31[diff] [blame]47h1, h2, h3 {
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]48 border-bottom: 2px solid silver;
49}
50h2 {
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]51 padding-top: 0.5em;
52}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]53h3 {
54 float: left;
55}
56h3 + * {
57 clear: left;
58}
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]59
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:31[diff] [blame]83 font-size: 1.1em;
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]84}
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:31[diff] [blame]152div.listingblock {
153 margin-right: 0%;
154}
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]155div.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:31[diff] [blame]164
165div.attribution {
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]166 text-align: right;
167}
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]168div.verseblock + div.attribution {
169 text-align: left;
170}
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]171
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:31[diff] [blame]214div.olist2 ol {
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]215 list-style-type: lower-alpha;
216}
217
218div.tableblock > table {
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]219 border: 3px solid #527bbd;
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]220}
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:31[diff] [blame]233div.hlist td {
234 padding-bottom: 5px;
235}
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]236td.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:31[diff] [blame]248
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:14[diff] [blame]275/* 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:31[diff] [blame]303
304/* IE6 sets dynamically generated links as visited. */
305div#toc a:visited { color: blue; }
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]306</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:22[diff] [blame]323<div class="verseblock">
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]324<div class="content"><em>git submodule</em> [--quiet] add [-b branch] [--] &lt;repository&gt; [&lt;path&gt;]
325<em>git submodule</em> [--quiet] status [--cached] [--] [&lt;path&gt;&#8230;]
326<em>git submodule</em> [--quiet] init [--] [&lt;path&gt;&#8230;]
327<em>git submodule</em> [--quiet] update [--init] [--] [&lt;path&gt;&#8230;]
328<em>git submodule</em> [--quiet] summary [--summary-limit &lt;n&gt;] [commit] [--] [&lt;path&gt;&#8230;]</div></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]329</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]330<h2 id="_commands">COMMANDS</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]331<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]332<div class="vlist"><dl>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]333<dt>
Junio C Hamano1d90cb02007-07-03 07:05:31[diff] [blame]334add
335</dt>
336<dd>
337<p>
338 Add the given repository as a submodule at the given path
Junio C Hamanobb343172008-03-09 10:39:09[diff] [blame]339 to the changeset to be committed next. If path is a valid
340 repository within the project, it is added as is. Otherwise,
341 repository is cloned at the specified path. path is added to the
Junio C Hamano1d90cb02007-07-03 07:05:31[diff] [blame]342 changeset and registered in .gitmodules. If no path is
343 specified, the path is deduced from the repository specification.
Junio C Hamano4fd58d42007-09-30 00:51:14[diff] [blame]344 If the repository url begins with ./ or ../, it is stored as
345 given but resolved as a relative path from the main project's
346 url when cloning.
Junio C Hamano1d90cb02007-07-03 07:05:31[diff] [blame]347</p>
348</dd>
349<dt>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]350status
351</dt>
352<dd>
353<p>
354 Show the status of the submodules. This will print the SHA-1 of the
355 currently checked out commit for each submodule, along with the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]356 submodule path and the output of <em>git-describe</em> for the
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]357 SHA-1. Each SHA-1 will be prefixed with <tt>-</tt> if the submodule is not
358 initialized and <tt>+</tt> if the currently checked out submodule commit
359 does not match the SHA-1 found in the index of the containing
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]360 repository. This command is the default command for <em>git-submodule</em>.
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]361</p>
362</dd>
363<dt>
364init
365</dt>
366<dd>
367<p>
Junio C Hamano16f98872007-06-12 16:09:14[diff] [blame]368 Initialize the submodules, i.e. register in .git/config each submodule
Junio C Hamano7a4a2832007-07-07 21:53:22[diff] [blame]369 name and url found in .gitmodules. The key used in .git/config is
370 <tt>submodule.$name.url</tt>. This command does not alter existing information
Junio C Hamano16f98872007-06-12 16:09:14[diff] [blame]371 in .git/config.
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]372</p>
373</dd>
374<dt>
375update
376</dt>
377<dd>
378<p>
Junio C Hamano16f98872007-06-12 16:09:14[diff] [blame]379 Update the registered submodules, i.e. clone missing submodules and
380 checkout the commit specified in the index of the containing repository.
381 This will make the submodules HEAD be detached.
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]382</p>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]383<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:23[diff] [blame]384setting as stored in .gitmodules, you can automatically initialize the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]385submodule with the --init option.</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]386</dd>
Junio C Hamano8b588d52008-03-15 09:48:37[diff] [blame]387<dt>
388summary
389</dt>
390<dd>
391<p>
392 Show commit summary between the given commit (defaults to HEAD) and
393 working tree/index. For a submodule in question, a series of commits
394 in the submodule between the given super project commit and the
395 index or working tree (switched by --cached) are shown.
396</p>
397</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]398</dl></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]399</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]400<h2 id="_options">OPTIONS</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]401<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]402<div class="vlist"><dl>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]403<dt>
Junio C Hamanoeb415992008-06-08 22:49:47[diff] [blame]404-q
405</dt>
406<dt>
407--quiet
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]408</dt>
409<dd>
410<p>
411 Only print error messages.
412</p>
413</dd>
414<dt>
Junio C Hamanoeb415992008-06-08 22:49:47[diff] [blame]415-b
416</dt>
417<dt>
418--branch
Junio C Hamano1d90cb02007-07-03 07:05:31[diff] [blame]419</dt>
420<dd>
421<p>
422 Branch of repository to add as submodule.
423</p>
424</dd>
425<dt>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]426--cached
427</dt>
428<dd>
429<p>
Junio C Hamano8b588d52008-03-15 09:48:37[diff] [blame]430 This option is only valid for status and summary commands. These
431 commands typically use the commit found in the submodule HEAD, but
432 with this option, the commit stored in the index is used instead.
433</p>
434</dd>
435<dt>
Junio C Hamanoeb415992008-06-08 22:49:47[diff] [blame]436-n
437</dt>
438<dt>
439--summary-limit
Junio C Hamano8b588d52008-03-15 09:48:37[diff] [blame]440</dt>
441<dd>
442<p>
443 This option is only valid for the summary command.
444 Limit the summary size (number of commits shown in total).
Junio C Hamano1bdd3b02008-04-13 05:33:18[diff] [blame]445 Giving 0 will disable the summary; a negative number means unlimited
Junio C Hamano8b588d52008-03-15 09:48:37[diff] [blame]446 (the default). This limit only applies to modified submodules. The
447 size is always limited to 1 for added/deleted/typechanged submodules.
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]448</p>
449</dd>
450<dt>
451&lt;path&gt;
452</dt>
453<dd>
454<p>
455 Path to submodule(s). When specified this will restrict the command
456 to only operate on the submodules found at the specified paths.
457</p>
458</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]459</dl></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]460</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]461<h2 id="_files">FILES</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]462<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]463<div class="para"><p>When initializing submodules, a .gitmodules file in the top-level directory
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]464of the containing repository is used to find the url of each submodule.
Junio C Hamano91baf102007-12-31 09:44:26[diff] [blame]465This file should be formatted in the same way as <tt>$GIT_DIR/config</tt>. The key
Junio C Hamanoe66c6c02007-12-17 08:26:13[diff] [blame]466to each submodule url is "submodule.$name.url". See <a href="gitmodules.html">gitmodules(5)</a>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]467for details.</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]468</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]469<h2 id="_author">AUTHOR</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]470<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]471<div class="para"><p>Written by Lars Hjemli &lt;hjemli@gmail.com&gt;</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]472</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]473<h2 id="_git">GIT</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]474<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]475<div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]476</div>
477<div id="footer">
478<div id="footer-text">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]479Last updated 2008-07-06 05:17:04 UTC
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]480</div>
481</div>
482</body>
483</html>