git-submodule.html

   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" />
   6 <meta name="generator" content="AsciiDoc 8.2.5" />
   7 <style type="text/css">
   8 /* Debug borders */
   9 p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
  10 /*
  11   border: 1px solid red;
  12 */
  13 }
  14
  15 body {
  16   margin: 1em 5% 1em 5%;
  17 }
  18
  19 a {
  20   color: blue;
  21   text-decoration: underline;
  22 }
  23 a:visited {
  24   color: fuchsia;
  25 }
  26
  27 em {
  28   font-style: italic;
  29 }
  30
  31 strong {
  32   font-weight: bold;
  33 }
  34
  35 tt {
  36   color: navy;
  37 }
  38
  39 h1, 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
  47 h1, h2, h3 {
  48   border-bottom: 2px solid silver;
  49 }
  50 h2 {
  51   padding-top: 0.5em;
  52 }
  53 h3 {
  54   float: left;
  55 }
  56 h3 + * {
  57   clear: left;
  58 }
  59
  60 div.sectionbody {
  61   font-family: serif;
  62   margin-left: 0;
  63 }
  64
  65 hr {
  66   border: 1px solid silver;
  67 }
  68
  69 p {
  70   margin-top: 0.5em;
  71   margin-bottom: 0.5em;
  72 }
  73
  74 pre {
  75   padding: 0;
  76   margin: 0;
  77 }
  78
  79 span#author {
  80   color: #527bbd;
  81   font-family: sans-serif;
  82   font-weight: bold;
  83   font-size: 1.1em;
  84 }
  85 span#email {
  86 }
  87 span#revision {
  88   font-family: sans-serif;
  89 }
  90
  91 div#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 }
  98 div#footer-text {
  99   float: left;
 100   padding-bottom: 0.5em;
 101 }
 102 div#footer-badges {
 103   float: right;
 104   padding-bottom: 0.5em;
 105 }
 106
 107 div#preamble,
 108 div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
 109 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 110 div.admonitionblock {
 111   margin-right: 10%;
 112   margin-top: 1.5em;
 113   margin-bottom: 1.5em;
 114 }
 115 div.admonitionblock {
 116   margin-top: 2.5em;
 117   margin-bottom: 2.5em;
 118 }
 119
 120 div.content { /* Block element content. */
 121   padding: 0;
 122 }
 123
 124 /* Block element titles. */
 125 div.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 }
 132 div.title + * {
 133   margin-top: 0;
 134 }
 135
 136 td div.title:first-child {
 137   margin-top: 0.0em;
 138 }
 139 div.content div.title:first-child {
 140   margin-top: 0.0em;
 141 }
 142 div.content + div.title {
 143   margin-top: 0.0em;
 144 }
 145
 146 div.sidebarblock > div.content {
 147   background: #ffffee;
 148   border: 1px solid silver;
 149   padding: 0.5em;
 150 }
 151
 152 div.listingblock {
 153   margin-right: 0%;
 154 }
 155 div.listingblock > div.content {
 156   border: 1px solid silver;
 157   background: #f4f4f4;
 158   padding: 0.5em;
 159 }
 160
 161 div.quoteblock > div.content {
 162   padding-left: 2.0em;
 163 }
 164
 165 div.attribution {
 166   text-align: right;
 167 }
 168 div.verseblock + div.attribution {
 169   text-align: left;
 170 }
 171
 172 div.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 }
 180 div.admonitionblock td.content {
 181   padding-left: 0.5em;
 182   border-left: 2px solid silver;
 183 }
 184
 185 div.exampleblock > div.content {
 186   border-left: 2px solid silver;
 187   padding: 0.5em;
 188 }
 189
 190 div.verseblock div.content {
 191   white-space: pre;
 192 }
 193
 194 div.imageblock div.content { padding-left: 0; }
 195 div.imageblock img { border: 1px solid silver; }
 196 span.image img { border-style: none; }
 197
 198 dl {
 199   margin-top: 0.8em;
 200   margin-bottom: 0.8em;
 201 }
 202 dt {
 203   margin-top: 0.5em;
 204   margin-bottom: 0;
 205   font-style: italic;
 206 }
 207 dd > *:first-child {
 208   margin-top: 0;
 209 }
 210
 211 ul, ol {
 212     list-style-position: outside;
 213 }
 214 div.olist2 ol {
 215   list-style-type: lower-alpha;
 216 }
 217
 218 div.tableblock > table {
 219   border: 3px solid #527bbd;
 220 }
 221 thead {
 222   font-family: sans-serif;
 223   font-weight: bold;
 224 }
 225 tfoot {
 226   font-weight: bold;
 227 }
 228
 229 div.hlist {
 230   margin-top: 0.8em;
 231   margin-bottom: 0.8em;
 232 }
 233 div.hlist td {
 234   padding-bottom: 5px;
 235 }
 236 td.hlist1 {
 237   vertical-align: top;
 238   font-style: italic;
 239   padding-right: 0.8em;
 240 }
 241 td.hlist2 {
 242   vertical-align: top;
 243 }
 244
 245 @media print {
 246   div#footer-badges { display: none; }
 247 }
 248
 249 div#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
 258 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 259   margin-top: 0;
 260   margin-bottom: 0;
 261 }
 262 div.toclevel2 {
 263   margin-left: 2em;
 264   font-size: 0.9em;
 265 }
 266 div.toclevel3 {
 267   margin-left: 4em;
 268   font-size: 0.9em;
 269 }
 270 div.toclevel4 {
 271   margin-left: 6em;
 272   font-size: 0.9em;
 273 }
 274 include1::./stylesheets/xhtml11-manpage.css[]
 275 /* Workarounds for IE6's broken and incomplete CSS2. */
 276
 277 div.sidebar-content {
 278   background: #ffffee;
 279   border: 1px solid silver;
 280   padding: 0.5em;
 281 }
 282 div.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
 289 div.listingblock div.content {
 290   border: 1px solid silver;
 291   background: #f4f4f4;
 292   padding: 0.5em;
 293 }
 294
 295 div.quoteblock-content {
 296   padding-left: 2.0em;
 297 }
 298
 299 div.exampleblock-content {
 300   border-left: 2px solid silver;
 301   padding-left: 0.5em;
 302 }
 303
 304 /* IE6 sets dynamically generated links as visited. */
 305 div#toc a:visited { color: blue; }
 306 </style>
 307 <title>git-submodule(1)</title>
 308 </head>
 309 <body>
 310 <div id="header">
 311 <h1>
 312 git-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">
 323 <div class="verseblock">
 324 <div class="content"><em>git submodule</em> [--quiet] add [-b branch] [-f|--force]
 325               [--reference &lt;repository&gt;] [--] &lt;repository&gt; [&lt;path&gt;]
 326 <em>git submodule</em> [--quiet] status [--cached] [--recursive] [--] [&lt;path&gt;&#8230;]
 327 <em>git submodule</em> [--quiet] init [--] [&lt;path&gt;&#8230;]
 328 <em>git submodule</em> [--quiet] update [--init] [-N|--no-fetch] [--rebase]
 329               [--reference &lt;repository&gt;] [--merge] [--recursive] [--] [&lt;path&gt;&#8230;]
 330 <em>git submodule</em> [--quiet] summary [--cached|--files] [--summary-limit &lt;n&gt;] [commit] [--] [&lt;path&gt;&#8230;]
 331 <em>git submodule</em> [--quiet] foreach [--recursive] &lt;command&gt;
 332 <em>git submodule</em> [--quiet] sync [--] [&lt;path&gt;&#8230;]</div></div>
 333 </div>
 334 <h2 id="_description">DESCRIPTION</h2>
 335 <div class="sectionbody">
 336 <div class="para"><p>Submodules allow foreign repositories to be embedded within
 337 a dedicated subdirectory of the source tree, always pointed
 338 at a particular commit.</p></div>
 339 <div class="para"><p>They are not to be confused with remotes, which are meant mainly
 340 for branches of the same project; submodules are meant for
 341 different projects you would like to make part of your source tree,
 342 while the history of the two projects still stays completely
 343 independent and you cannot modify the contents of the submodule
 344 from within the main project.
 345 If you want to merge the project histories and want to treat the
 346 aggregated whole as a single project from then on, you may want to
 347 add a remote for the other project and use the <em>subtree</em> merge strategy,
 348 instead of treating the other project as a submodule. Directories
 349 that come from both projects can be cloned and checked out as a whole
 350 if you choose to go that route.</p></div>
 351 <div class="para"><p>Submodules are composed from a so-called <tt>gitlink</tt> tree entry
 352 in the main repository that refers to a particular commit object
 353 within the inner repository that is completely separate.
 354 A record in the <tt>.gitmodules</tt> file at the root of the source
 355 tree assigns a logical name to the submodule and describes
 356 the default URL the submodule shall be cloned from.
 357 The logical name can be used for overriding this URL within your
 358 local repository configuration (see <em>submodule init</em>).</p></div>
 359 <div class="para"><p>This command will manage the tree entries and contents of the
 360 gitmodules file for you, as well as inspect the status of your
 361 submodules and update them.
 362 When adding a new submodule to the tree, the <em>add</em> subcommand
 363 is to be used.  However, when pulling a tree containing submodules,
 364 these will not be checked out by default;
 365 the <em>init</em> and <em>update</em> subcommands will maintain submodules
 366 checked out and at appropriate revision in your working tree.
 367 You can briefly inspect the up-to-date status of your submodules
 368 using the <em>status</em> subcommand and get a detailed overview of the
 369 difference between the index and checkouts using the <em>summary</em>
 370 subcommand.</p></div>
 371 </div>
 372 <h2 id="_commands">COMMANDS</h2>
 373 <div class="sectionbody">
 374 <div class="vlist"><dl>
 375 <dt>
 376 add
 377 </dt>
 378 <dd>
 379 <p>
 380         Add the given repository as a submodule at the given path
 381         to the changeset to be committed next to the current
 382         project: the current project is termed the "superproject".
 383 </p>
 384 <div class="para"><p>This requires at least one argument: &lt;repository&gt;. The optional
 385 argument &lt;path&gt; is the relative location for the cloned submodule
 386 to exist in the superproject. If &lt;path&gt; is not given, the
 387 "humanish" part of the source repository is used ("repo" for
 388 "/path/to/repo.git" and "foo" for "host.xz:foo/.git").</p></div>
 389 <div class="para"><p>&lt;repository&gt; is the URL of the new submodule's origin repository.
 390 This may be either an absolute URL, or (if it begins with ./
 391 or ../), the location relative to the superproject's origin
 392 repository.</p></div>
 393 <div class="para"><p>&lt;path&gt; is the relative location for the cloned submodule to
 394 exist in the superproject. If &lt;path&gt; does not exist, then the
 395 submodule is created by cloning from the named URL. If &lt;path&gt; does
 396 exist and is already a valid git repository, then this is added
 397 to the changeset without cloning. This second form is provided
 398 to ease creating a new submodule from scratch, and presumes
 399 the user will later push the submodule to the given URL.</p></div>
 400 <div class="para"><p>In either case, the given URL is recorded into .gitmodules for
 401 use by subsequent users cloning the superproject. If the URL is
 402 given relative to the superproject's repository, the presumption
 403 is the superproject and submodule repositories will be kept
 404 together in the same relative location, and only the
 405 superproject's URL needs to be provided: git-submodule will correctly
 406 locate the submodule using the relative URL in .gitmodules.</p></div>
 407 </dd>
 408 <dt>
 409 status
 410 </dt>
 411 <dd>
 412 <p>
 413         Show the status of the submodules. This will print the SHA-1 of the
 414         currently checked out commit for each submodule, along with the
 415         submodule path and the output of <em>git describe</em> for the
 416         SHA-1. Each SHA-1 will be prefixed with <tt>-</tt> if the submodule is not
 417         initialized and <tt>+</tt> if the currently checked out submodule commit
 418         does not match the SHA-1 found in the index of the containing
 419         repository. This command is the default command for <em>git submodule</em>.
 420 </p>
 421 <div class="para"><p>If <em>--recursive</em> is specified, this command will recurse into nested
 422 submodules, and show their status as well.</p></div>
 423 </dd>
 424 <dt>
 425 init
 426 </dt>
 427 <dd>
 428 <p>
 429         Initialize the submodules, i.e. register each submodule name
 430         and url found in .gitmodules into .git/config.
 431         The key used in .git/config is <tt>submodule.$name.url</tt>.
 432         This command does not alter existing information in .git/config.
 433         You can then customize the submodule clone URLs in .git/config
 434         for your local setup and proceed to <tt>git submodule update</tt>;
 435         you can also just use <tt>git submodule update --init</tt> without
 436         the explicit <em>init</em> step if you do not intend to customize
 437         any submodule locations.
 438 </p>
 439 </dd>
 440 <dt>
 441 update
 442 </dt>
 443 <dd>
 444 <p>
 445         Update the registered submodules, i.e. clone missing submodules and
 446         checkout the commit specified in the index of the containing repository.
 447         This will make the submodules HEAD be detached unless <em>--rebase</em> or
 448         <em>--merge</em> is specified or the key <tt>submodule.$name.update</tt> is set to
 449         <tt>rebase</tt> or <tt>merge</tt>.
 450 </p>
 451 <div class="para"><p>If the submodule is not yet initialized, and you just want to use the
 452 setting as stored in .gitmodules, you can automatically initialize the
 453 submodule with the --init option.</p></div>
 454 <div class="para"><p>If <em>--recursive</em> is specified, this command will recurse into the
 455 registered submodules, and update any nested submodules within.</p></div>
 456 </dd>
 457 <dt>
 458 summary
 459 </dt>
 460 <dd>
 461 <p>
 462         Show commit summary between the given commit (defaults to HEAD) and
 463         working tree/index. For a submodule in question, a series of commits
 464         in the submodule between the given super project commit and the
 465         index or working tree (switched by --cached) are shown. If the option
 466         --files is given, show the series of commits in the submodule between
 467         the index of the super project and the working tree of the submodule
 468         (this option doesn't allow to use the --cached option or to provide an
 469         explicit commit).
 470 </p>
 471 </dd>
 472 <dt>
 473 foreach
 474 </dt>
 475 <dd>
 476 <p>
 477         Evaluates an arbitrary shell command in each checked out submodule.
 478         The command has access to the variables $name, $path, $sha1 and
 479         $toplevel:
 480         $name is the name of the relevant submodule section in .gitmodules,
 481         $path is the name of the submodule directory relative to the
 482         superproject, $sha1 is the commit as recorded in the superproject,
 483         and $toplevel is the absolute path to the top-level of the superproject.
 484         Any submodules defined in the superproject but not checked out are
 485         ignored by this command. Unless given --quiet, foreach prints the name
 486         of each submodule before evaluating the command.
 487         If --recursive is given, submodules are traversed recursively (i.e.
 488         the given shell command is evaluated in nested submodules as well).
 489         A non-zero return from the command in any submodule causes
 490         the processing to terminate. This can be overridden by adding <em>|| :</em>
 491         to the end of the command.
 492 </p>
 493 <div class="para"><p>As an example, +git submodule foreach 'echo $path &#96;git
 494 rev-parse HEAD&#96;'+ will show the path and currently checked out
 495 commit for each submodule.</p></div>
 496 </dd>
 497 <dt>
 498 sync
 499 </dt>
 500 <dd>
 501 <p>
 502         Synchronizes submodules' remote URL configuration setting
 503         to the value specified in .gitmodules.  This is useful when
 504         submodule URLs change upstream and you need to update your local
 505         repositories accordingly.
 506 </p>
 507 <div class="para"><p>"git submodule sync" synchronizes all submodules while
 508 "git submodule sync &#8212; A" synchronizes submodule "A" only.</p></div>
 509 </dd>
 510 </dl></div>
 511 </div>
 512 <h2 id="_options">OPTIONS</h2>
 513 <div class="sectionbody">
 514 <div class="vlist"><dl>
 515 <dt>
 516 -q
 517 </dt>
 518 <dt>
 519 --quiet
 520 </dt>
 521 <dd>
 522 <p>
 523         Only print error messages.
 524 </p>
 525 </dd>
 526 <dt>
 527 -b
 528 </dt>
 529 <dt>
 530 --branch
 531 </dt>
 532 <dd>
 533 <p>
 534         Branch of repository to add as submodule.
 535 </p>
 536 </dd>
 537 <dt>
 538 -f
 539 </dt>
 540 <dt>
 541 --force
 542 </dt>
 543 <dd>
 544 <p>
 545         This option is only valid for the add command.
 546         Allow adding an otherwise ignored submodule path.
 547 </p>
 548 </dd>
 549 <dt>
 550 --cached
 551 </dt>
 552 <dd>
 553 <p>
 554         This option is only valid for status and summary commands.  These
 555         commands typically use the commit found in the submodule HEAD, but
 556         with this option, the commit stored in the index is used instead.
 557 </p>
 558 </dd>
 559 <dt>
 560 --files
 561 </dt>
 562 <dd>
 563 <p>
 564         This option is only valid for the summary command. This command
 565         compares the commit in the index with that in the submodule HEAD
 566         when this option is used.
 567 </p>
 568 </dd>
 569 <dt>
 570 -n
 571 </dt>
 572 <dt>
 573 --summary-limit
 574 </dt>
 575 <dd>
 576 <p>
 577         This option is only valid for the summary command.
 578         Limit the summary size (number of commits shown in total).
 579         Giving 0 will disable the summary; a negative number means unlimited
 580         (the default). This limit only applies to modified submodules. The
 581         size is always limited to 1 for added/deleted/typechanged submodules.
 582 </p>
 583 </dd>
 584 <dt>
 585 -N
 586 </dt>
 587 <dt>
 588 --no-fetch
 589 </dt>
 590 <dd>
 591 <p>
 592         This option is only valid for the update command.
 593         Don't fetch new objects from the remote site.
 594 </p>
 595 </dd>
 596 <dt>
 597 --merge
 598 </dt>
 599 <dd>
 600 <p>
 601         This option is only valid for the update command.
 602         Merge the commit recorded in the superproject into the current branch
 603         of the submodule. If this option is given, the submodule's HEAD will
 604         not be detached. If a merge failure prevents this process, you will
 605         have to resolve the resulting conflicts within the submodule with the
 606         usual conflict resolution tools.
 607         If the key <tt>submodule.$name.update</tt> is set to <tt>merge</tt>, this option is
 608         implicit.
 609 </p>
 610 </dd>
 611 <dt>
 612 --rebase
 613 </dt>
 614 <dd>
 615 <p>
 616         This option is only valid for the update command.
 617         Rebase the current branch onto the commit recorded in the
 618         superproject. If this option is given, the submodule's HEAD will not
 619         be detached. If a merge failure prevents this process, you will have
 620         to resolve these failures with <a href="git-rebase.html">git-rebase(1)</a>.
 621         If the key <tt>submodule.$name.update</tt> is set to <tt>rebase</tt>, this option is
 622         implicit.
 623 </p>
 624 </dd>
 625 <dt>
 626 --reference &lt;repository&gt;
 627 </dt>
 628 <dd>
 629 <p>
 630         This option is only valid for add and update commands.  These
 631         commands sometimes need to clone a remote repository. In this case,
 632         this option will be passed to the <a href="git-clone.html">git-clone(1)</a> command.
 633 </p>
 634 <div class="para"><p><strong>NOTE</strong>: Do <strong>not</strong> use this option unless you have read the note
 635 for <a href="git-clone.html">git-clone(1)</a>'s --reference and --shared options carefully.</p></div>
 636 </dd>
 637 <dt>
 638 --recursive
 639 </dt>
 640 <dd>
 641 <p>
 642         This option is only valid for foreach, update and status commands.
 643         Traverse submodules recursively. The operation is performed not
 644         only in the submodules of the current repo, but also
 645         in any nested submodules inside those submodules (and so on).
 646 </p>
 647 </dd>
 648 <dt>
 649 &lt;path&gt;&#8230;
 650 </dt>
 651 <dd>
 652 <p>
 653         Paths to submodule(s). When specified this will restrict the command
 654         to only operate on the submodules found at the specified paths.
 655         (This argument is required with add).
 656 </p>
 657 </dd>
 658 </dl></div>
 659 </div>
 660 <h2 id="_files">FILES</h2>
 661 <div class="sectionbody">
 662 <div class="para"><p>When initializing submodules, a .gitmodules file in the top-level directory
 663 of the containing repository is used to find the url of each submodule.
 664 This file should be formatted in the same way as <tt>$GIT_DIR/config</tt>. The key
 665 to each submodule url is "submodule.$name.url".  See <a href="gitmodules.html">gitmodules(5)</a>
 666 for details.</p></div>
 667 </div>
 668 <h2 id="_author">AUTHOR</h2>
 669 <div class="sectionbody">
 670 <div class="para"><p>Written by Lars Hjemli &lt;hjemli@gmail.com&gt;</p></div>
 671 </div>
 672 <h2 id="_git">GIT</h2>
 673 <div class="sectionbody">
 674 <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
 675 </div>
 676 <div id="footer">
 677 <div id="footer-text">
 678 Last updated 2010-09-18 23:56:59 UTC
 679 </div>
 680 </div>
 681 </body>
 682 </html>