Google Git
Sign in
chromium / external / gitster / git-htmldocs / f69a0a065df32be5accdda5105d54c580c21e0ee / . / git-submodule.html
blob: 1ecc633ffe49dd2e8a16ceaf37a7adbf14672d33 [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 Hamano38ddcce2008-07-15 15:49:03[diff] [blame]324<div class="content"><em>git submodule</em> [--quiet] add [-b branch] [--] &lt;repository&gt; &lt;path&gt;
Junio C Hamanofce7c7e2008-07-02 03:06:38[diff] [blame]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 Hamanof69a0a02008-07-17 08:08:47[diff] [blame^]330<h2 id="_description">DESCRIPTION</h2>
331<div class="sectionbody">
332<div class="para"><p>Submodules are a special kind of tree entries which refer to a particular tree
333state in another repository. The tree entry describes
334the existence of a submodule with the given name and the exact revision that
335should be used, while an entry in <tt>.gitmodules</tt> file gives the location of
336the repository.</p></div>
337<div class="para"><p>When checked out, submodules will maintain their own independent repositories
338within their directories; the only link between the submodule and the "parent
339project" is the tree entry within the parent project mentioned above.</p></div>
340<div class="para"><p>This command will manage the tree entries and contents of the gitmodules file
341for you, as well as inspecting the status of your submodules and updating them.
342When adding a new submodule to the tree, the <em>add</em> subcommand is to be used.
343However, when pulling a tree containing submodules, these will not be checked
344out by default; the <em>init</em> and <em>update</em> subcommands will maintain submodules
345checked out and at appropriate revision in your working tree. You can inspect
346the current status of your submodules using the <em>submodule</em> subcommand and get
347an overview of changes <em>update</em> would perform using the <em>summary</em> subcommand.</p></div>
348</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]349<h2 id="_commands">COMMANDS</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]350<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]351<div class="vlist"><dl>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]352<dt>
Junio C Hamano1d90cb02007-07-03 07:05:31[diff] [blame]353add
354</dt>
355<dd>
356<p>
357 Add the given repository as a submodule at the given path
Junio C Hamano38ddcce2008-07-15 15:49:03[diff] [blame]358 to the changeset to be committed next to the current
359 project: the current project is termed termed the "superproject".
Junio C Hamano1d90cb02007-07-03 07:05:31[diff] [blame]360</p>
Junio C Hamano38ddcce2008-07-15 15:49:03[diff] [blame]361<div class="para"><p>This requires two arguments: &lt;repository&gt; and &lt;path&gt;.</p></div>
362<div class="para"><p>&lt;repository&gt; is the URL of the new submodule's origin repository.
363This may be either an absolute URL, or (if it begins with ./
364or ../), the location relative to the superproject's origin
365repository.</p></div>
366<div class="para"><p>&lt;path&gt; is the relative location for the cloned submodule to
367exist in the superproject. If &lt;path&gt; does not exist, then the
368submodule is created by cloning from the named URL. If &lt;path&gt; does
369exist and is already a valid git repository, then this is added
370to the changeset without cloning. This second form is provided
371to ease creating a new submodule from scratch, and presumes
372the user will later push the submodule to the given URL.</p></div>
373<div class="para"><p>In either case, the given URL is recorded into .gitmodules for
374use by subsequent users cloning the superproject. If the URL is
375given relative to the superproject's repository, the presumption
376is the superproject and submodule repositories will be kept
377together in the same relative location, and only the
378superproject's URL need be provided: git-submodule will correctly
379locate the submodule using the relative URL in .gitmodules.</p></div>
Junio C Hamano1d90cb02007-07-03 07:05:31[diff] [blame]380</dd>
381<dt>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]382status
383</dt>
384<dd>
385<p>
386 Show the status of the submodules. This will print the SHA-1 of the
387 currently checked out commit for each submodule, along with the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]388 submodule path and the output of <em>git-describe</em> for the
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]389 SHA-1. Each SHA-1 will be prefixed with <tt>-</tt> if the submodule is not
390 initialized and <tt>+</tt> if the currently checked out submodule commit
391 does not match the SHA-1 found in the index of the containing
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]392 repository. This command is the default command for <em>git-submodule</em>.
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]393</p>
394</dd>
395<dt>
396init
397</dt>
398<dd>
399<p>
Junio C Hamano16f98872007-06-12 16:09:14[diff] [blame]400 Initialize the submodules, i.e. register in .git/config each submodule
Junio C Hamano7a4a2832007-07-07 21:53:22[diff] [blame]401 name and url found in .gitmodules. The key used in .git/config is
402 <tt>submodule.$name.url</tt>. This command does not alter existing information
Junio C Hamano16f98872007-06-12 16:09:14[diff] [blame]403 in .git/config.
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]404</p>
405</dd>
406<dt>
407update
408</dt>
409<dd>
410<p>
Junio C Hamano16f98872007-06-12 16:09:14[diff] [blame]411 Update the registered submodules, i.e. clone missing submodules and
412 checkout the commit specified in the index of the containing repository.
413 This will make the submodules HEAD be detached.
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]414</p>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]415<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]416setting as stored in .gitmodules, you can automatically initialize the
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]417submodule with the --init option.</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]418</dd>
Junio C Hamano8b588d52008-03-15 09:48:37[diff] [blame]419<dt>
420summary
421</dt>
422<dd>
423<p>
424 Show commit summary between the given commit (defaults to HEAD) and
425 working tree/index. For a submodule in question, a series of commits
426 in the submodule between the given super project commit and the
427 index or working tree (switched by --cached) are shown.
428</p>
429</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]430</dl></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]431</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]432<h2 id="_options">OPTIONS</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]433<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]434<div class="vlist"><dl>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]435<dt>
Junio C Hamanoeb415992008-06-08 22:49:47[diff] [blame]436-q
437</dt>
438<dt>
439--quiet
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]440</dt>
441<dd>
442<p>
443 Only print error messages.
444</p>
445</dd>
446<dt>
Junio C Hamanoeb415992008-06-08 22:49:47[diff] [blame]447-b
448</dt>
449<dt>
450--branch
Junio C Hamano1d90cb02007-07-03 07:05:31[diff] [blame]451</dt>
452<dd>
453<p>
454 Branch of repository to add as submodule.
455</p>
456</dd>
457<dt>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]458--cached
459</dt>
460<dd>
461<p>
Junio C Hamano8b588d52008-03-15 09:48:37[diff] [blame]462 This option is only valid for status and summary commands. These
463 commands typically use the commit found in the submodule HEAD, but
464 with this option, the commit stored in the index is used instead.
465</p>
466</dd>
467<dt>
Junio C Hamanoeb415992008-06-08 22:49:47[diff] [blame]468-n
469</dt>
470<dt>
471--summary-limit
Junio C Hamano8b588d52008-03-15 09:48:37[diff] [blame]472</dt>
473<dd>
474<p>
475 This option is only valid for the summary command.
476 Limit the summary size (number of commits shown in total).
Junio C Hamano1bdd3b02008-04-13 05:33:18[diff] [blame]477 Giving 0 will disable the summary; a negative number means unlimited
Junio C Hamano8b588d52008-03-15 09:48:37[diff] [blame]478 (the default). This limit only applies to modified submodules. The
479 size is always limited to 1 for added/deleted/typechanged submodules.
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]480</p>
481</dd>
482<dt>
483&lt;path&gt;
484</dt>
485<dd>
486<p>
487 Path to submodule(s). When specified this will restrict the command
488 to only operate on the submodules found at the specified paths.
Junio C Hamano38ddcce2008-07-15 15:49:03[diff] [blame]489 (This argument is required with add).
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]490</p>
491</dd>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]492</dl></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]493</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]494<h2 id="_files">FILES</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]495<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]496<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]497of the containing repository is used to find the url of each submodule.
Junio C Hamano91baf102007-12-31 09:44:26[diff] [blame]498This 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]499to 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]500for details.</p></div>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]501</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]502<h2 id="_author">AUTHOR</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]503<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]504<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]505</div>
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]506<h2 id="_git">GIT</h2>
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]507<div class="sectionbody">
Junio C Hamanoba4b9282008-07-06 05:20:31[diff] [blame]508<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]509</div>
510<div id="footer">
511<div id="footer-text">
Junio C Hamanof69a0a02008-07-17 08:08:47[diff] [blame^]512Last updated 2008-07-17 08:08:29 UTC
Junio C Hamano38b693c2007-06-03 08:40:14[diff] [blame]513</div>
514</div>
515</body>
516</html>