doc/source/en/TortoiseGit/git_doc/git-submodule.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <sect2 lang="en" id="git-submodule(1)">\r
   5     <title>git-submodule(1)</title>\r
   6 <indexterm>\r
   7 <primary>git-submodule(1)</primary>\r
   8 </indexterm>\r
   9 <simplesect id="git-submodule(1)__name">\r
  10 <title>NAME</title>\r
  11 <simpara>git-submodule - Initialize, update or inspect submodules</simpara>\r
  12 </simplesect>\r
  13 <simplesect id="git-submodule(1)__synopsis">\r
  14 <title>SYNOPSIS</title>\r
  15 <blockquote>\r
  16 <literallayout><emphasis>git submodule</emphasis> [--quiet] add [-b &lt;branch&gt;] [-f|--force] [--name &lt;name&gt;]\r
  17               [--reference &lt;repository&gt;] [--depth &lt;depth&gt;] [--] &lt;repository&gt; [&lt;path&gt;]\r
  18 <emphasis>git submodule</emphasis> [--quiet] status [--cached] [--recursive] [--] [&lt;path&gt;&#8230;]\r
  19 <emphasis>git submodule</emphasis> [--quiet] init [--] [&lt;path&gt;&#8230;]\r
  20 <emphasis>git submodule</emphasis> [--quiet] deinit [-f|--force] [--] &lt;path&gt;&#8230;\r
  21 <emphasis>git submodule</emphasis> [--quiet] update [--init] [--remote] [-N|--no-fetch]\r
  22               [-f|--force] [--rebase|--merge] [--reference &lt;repository&gt;]\r
  23               [--depth &lt;depth&gt;] [--recursive] [--jobs &lt;n&gt;] [--] [&lt;path&gt;&#8230;]\r
  24 <emphasis>git submodule</emphasis> [--quiet] summary [--cached|--files] [(-n|--summary-limit) &lt;n&gt;]\r
  25               [commit] [--] [&lt;path&gt;&#8230;]\r
  26 <emphasis>git submodule</emphasis> [--quiet] foreach [--recursive] &lt;command&gt;\r
  27 <emphasis>git submodule</emphasis> [--quiet] sync [--recursive] [--] [&lt;path&gt;&#8230;]</literallayout>\r
  28 </blockquote>\r
  29 </simplesect>\r
  30 <simplesect id="git-submodule(1)__description">\r
  31 <title>DESCRIPTION</title>\r
  32 <simpara>Inspects, updates and manages submodules.</simpara>\r
  33 <simpara>A submodule allows you to keep another Git repository in a subdirectory\r
  34 of your repository. The other repository has its own history, which does not\r
  35 interfere with the history of the current repository. This can be used to\r
  36 have external dependencies such as third party libraries for example.</simpara>\r
  37 <simpara>When cloning or pulling a repository containing submodules however,\r
  38 these will not be checked out by default; the <emphasis>init</emphasis> and <emphasis>update</emphasis>\r
  39 subcommands will maintain submodules checked out and at\r
  40 appropriate revision in your working tree.</simpara>\r
  41 <simpara>Submodules are composed from a so-called <emphasis>gitlink</emphasis> tree entry\r
  42 in the main repository that refers to a particular commit object\r
  43 within the inner repository that is completely separate.\r
  44 A record in the <emphasis>.gitmodules</emphasis> (see <xref linkend="gitmodules(5)" />) file at the\r
  45 root of the source tree assigns a logical name to the submodule and\r
  46 describes the default URL the submodule shall be cloned from.\r
  47 The logical name can be used for overriding this URL within your\r
  48 local repository configuration (see <emphasis>submodule init</emphasis>).</simpara>\r
  49 <simpara>Submodules are not to be confused with remotes, which are other\r
  50 repositories of the same project; submodules are meant for\r
  51 different projects you would like to make part of your source tree,\r
  52 while the history of the two projects still stays completely\r
  53 independent and you cannot modify the contents of the submodule\r
  54 from within the main project.\r
  55 If you want to merge the project histories and want to treat the\r
  56 aggregated whole as a single project from then on, you may want to\r
  57 add a remote for the other project and use the <emphasis>subtree</emphasis> merge strategy,\r
  58 instead of treating the other project as a submodule. Directories\r
  59 that come from both projects can be cloned and checked out as a whole\r
  60 if you choose to go that route.</simpara>\r
  61 </simplesect>\r
  62 <simplesect id="git-submodule(1)__commands">\r
  63 <title>COMMANDS</title>\r
  64 <variablelist>\r
  65 <varlistentry>\r
  66 <term>\r
  67 add\r
  68 </term>\r
  69 <listitem>\r
  70 <simpara>\r
  71         Add the given repository as a submodule at the given path\r
  72         to the changeset to be committed next to the current\r
  73         project: the current project is termed the "superproject".\r
  74 </simpara>\r
  75 <simpara>This requires at least one argument: &lt;repository&gt;. The optional\r
  76 argument &lt;path&gt; is the relative location for the cloned submodule\r
  77 to exist in the superproject. If &lt;path&gt; is not given, the\r
  78 "humanish" part of the source repository is used ("repo" for\r
  79 "/path/to/repo.git" and "foo" for "host.xz:foo/.git").\r
  80 The &lt;path&gt; is also used as the submodule's logical name in its\r
  81 configuration entries unless <emphasis>--name</emphasis> is used to specify a logical name.</simpara>\r
  82 <simpara>&lt;repository&gt; is the URL of the new submodule's origin repository.\r
  83 This may be either an absolute URL, or (if it begins with ./\r
  84 or ../), the location relative to the superproject's origin\r
  85 repository (Please note that to specify a repository <emphasis>foo.git</emphasis>\r
  86 which is located right next to a superproject <emphasis>bar.git</emphasis>, you'll\r
  87 have to use <emphasis>../foo.git</emphasis> instead of <emphasis>./foo.git</emphasis> - as one might expect\r
  88 when following the rules for relative URLs - because the evaluation\r
  89 of relative URLs in Git is identical to that of relative directories).\r
  90 If the superproject doesn't have an origin configured\r
  91 the superproject is its own authoritative upstream and the current\r
  92 working directory is used instead.</simpara>\r
  93 <simpara>&lt;path&gt; is the relative location for the cloned submodule to\r
  94 exist in the superproject. If &lt;path&gt; does not exist, then the\r
  95 submodule is created by cloning from the named URL. If &lt;path&gt; does\r
  96 exist and is already a valid Git repository, then this is added\r
  97 to the changeset without cloning. This second form is provided\r
  98 to ease creating a new submodule from scratch, and presumes\r
  99 the user will later push the submodule to the given URL.</simpara>\r
 100 <simpara>In either case, the given URL is recorded into .gitmodules for\r
 101 use by subsequent users cloning the superproject. If the URL is\r
 102 given relative to the superproject's repository, the presumption\r
 103 is the superproject and submodule repositories will be kept\r
 104 together in the same relative location, and only the\r
 105 superproject's URL needs to be provided: git-submodule will correctly\r
 106 locate the submodule using the relative URL in .gitmodules.</simpara>\r
 107 </listitem>\r
 108 </varlistentry>\r
 109 <varlistentry>\r
 110 <term>\r
 111 status\r
 112 </term>\r
 113 <listitem>\r
 114 <simpara>\r
 115         Show the status of the submodules. This will print the SHA-1 of the\r
 116         currently checked out commit for each submodule, along with the\r
 117         submodule path and the output of <emphasis>git describe</emphasis> for the\r
 118         SHA-1. Each SHA-1 will be prefixed with <emphasis>-</emphasis> if the submodule is not\r
 119         initialized, <emphasis>+</emphasis> if the currently checked out submodule commit\r
 120         does not match the SHA-1 found in the index of the containing\r
 121         repository and <emphasis>U</emphasis> if the submodule has merge conflicts.\r
 122 </simpara>\r
 123 <simpara>If <emphasis>--recursive</emphasis> is specified, this command will recurse into nested\r
 124 submodules, and show their status as well.</simpara>\r
 125 <simpara>If you are only interested in changes of the currently initialized\r
 126 submodules with respect to the commit recorded in the index or the HEAD,\r
 127 <xref linkend="git-status(1)" /> and <xref linkend="git-diff(1)" /> will provide that information\r
 128 too (and can also report changes to a submodule's work tree).</simpara>\r
 129 </listitem>\r
 130 </varlistentry>\r
 131 <varlistentry>\r
 132 <term>\r
 133 init\r
 134 </term>\r
 135 <listitem>\r
 136 <simpara>\r
 137         Initialize the submodules recorded in the index (which were\r
 138         added and committed elsewhere) by copying submodule\r
 139         names and urls from .gitmodules to .git/config.\r
 140         Optional &lt;path&gt; arguments limit which submodules will be initialized.\r
 141         It will also copy the value of <emphasis>submodule.$name.update</emphasis> into\r
 142         .git/config.\r
 143         The key used in .git/config is <emphasis>submodule.$name.url</emphasis>.\r
 144         This command does not alter existing information in .git/config.\r
 145         You can then customize the submodule clone URLs in .git/config\r
 146         for your local setup and proceed to <emphasis>git submodule update</emphasis>;\r
 147         you can also just use <emphasis>git submodule update --init</emphasis> without\r
 148         the explicit <emphasis>init</emphasis> step if you do not intend to customize\r
 149         any submodule locations.\r
 150 </simpara>\r
 151 </listitem>\r
 152 </varlistentry>\r
 153 <varlistentry>\r
 154 <term>\r
 155 deinit\r
 156 </term>\r
 157 <listitem>\r
 158 <simpara>\r
 159         Unregister the given submodules, i.e. remove the whole\r
 160         <emphasis>submodule.$name</emphasis> section from .git/config together with their work\r
 161         tree. Further calls to <emphasis>git submodule update</emphasis>, <emphasis>git submodule foreach</emphasis>\r
 162         and <emphasis>git submodule sync</emphasis> will skip any unregistered submodules until\r
 163         they are initialized again, so use this command if you don't want to\r
 164         have a local checkout of the submodule in your work tree anymore. If\r
 165         you really want to remove a submodule from the repository and commit\r
 166         that use <xref linkend="git-rm(1)" /> instead.\r
 167 </simpara>\r
 168 <simpara>If <emphasis>--force</emphasis> is specified, the submodule's work tree will be removed even if\r
 169 it contains local modifications.</simpara>\r
 170 </listitem>\r
 171 </varlistentry>\r
 172 <varlistentry>\r
 173 <term>\r
 174 update\r
 175 </term>\r
 176 <listitem>\r
 177 <simpara>Update the registered submodules to match what the superproject\r
 178 expects by cloning missing submodules and updating the working tree of\r
 179 the submodules. The "updating" can be done in several ways depending\r
 180 on command line options and the value of <emphasis>submodule.&lt;name&gt;.update</emphasis>\r
 181 configuration variable. Supported update procedures are:</simpara>\r
 182 <variablelist>\r
 183 <varlistentry>\r
 184 <term>\r
 185 checkout\r
 186 </term>\r
 187 <listitem>\r
 188 <simpara>\r
 189 the commit recorded in the superproject will be\r
 190             checked out in the submodule on a detached HEAD. This is\r
 191             done when <emphasis>--checkout</emphasis> option is given, or no option is\r
 192             given, and <emphasis>submodule.&lt;name&gt;.update</emphasis> is unset, or if it is\r
 193             set to <emphasis>checkout</emphasis>.\r
 194 </simpara>\r
 195 <simpara>If <emphasis>--force</emphasis> is specified, the submodule will be checked out (using\r
 196 <emphasis>git checkout --force</emphasis> if appropriate), even if the commit specified\r
 197 in the index of the containing repository already matches the commit\r
 198 checked out in the submodule.</simpara>\r
 199 </listitem>\r
 200 </varlistentry>\r
 201 <varlistentry>\r
 202 <term>\r
 203 rebase\r
 204 </term>\r
 205 <listitem>\r
 206 <simpara>\r
 207 the current branch of the submodule will be rebased\r
 208             onto the commit recorded in the superproject. This is done\r
 209             when <emphasis>--rebase</emphasis> option is given, or no option is given, and\r
 210             <emphasis>submodule.&lt;name&gt;.update</emphasis> is set to <emphasis>rebase</emphasis>.\r
 211 </simpara>\r
 212 </listitem>\r
 213 </varlistentry>\r
 214 <varlistentry>\r
 215 <term>\r
 216 merge\r
 217 </term>\r
 218 <listitem>\r
 219 <simpara>\r
 220 the commit recorded in the superproject will be merged\r
 221             into the current branch in the submodule. This is done\r
 222             when <emphasis>--merge</emphasis> option is given, or no option is given, and\r
 223             <emphasis>submodule.&lt;name&gt;.update</emphasis> is set to <emphasis>merge</emphasis>.\r
 224 </simpara>\r
 225 </listitem>\r
 226 </varlistentry>\r
 227 <varlistentry>\r
 228 <term>\r
 229 custom command\r
 230 </term>\r
 231 <listitem>\r
 232 <simpara>\r
 233 arbitrary shell command that takes a single\r
 234             argument (the sha1 of the commit recorded in the\r
 235             superproject) is executed. This is done when no option is\r
 236             given, and <emphasis>submodule.&lt;name&gt;.update</emphasis> has the form of\r
 237             <emphasis>!command</emphasis>.\r
 238 </simpara>\r
 239 </listitem>\r
 240 </varlistentry>\r
 241 </variablelist>\r
 242 <simpara>When no option is given and <emphasis>submodule.&lt;name&gt;.update</emphasis> is set to <emphasis>none</emphasis>,\r
 243 the submodule is not updated.</simpara>\r
 244 <simpara>If the submodule is not yet initialized, and you just want to use the\r
 245 setting as stored in .gitmodules, you can automatically initialize the\r
 246 submodule with the <emphasis>--init</emphasis> option.</simpara>\r
 247 <simpara>If <emphasis>--recursive</emphasis> is specified, this command will recurse into the\r
 248 registered submodules, and update any nested submodules within.</simpara>\r
 249 </listitem>\r
 250 </varlistentry>\r
 251 <varlistentry>\r
 252 <term>\r
 253 summary\r
 254 </term>\r
 255 <listitem>\r
 256 <simpara>\r
 257         Show commit summary between the given commit (defaults to HEAD) and\r
 258         working tree/index. For a submodule in question, a series of commits\r
 259         in the submodule between the given super project commit and the\r
 260         index or working tree (switched by <emphasis>--cached</emphasis>) are shown. If the option\r
 261         <emphasis>--files</emphasis> is given, show the series of commits in the submodule between\r
 262         the index of the super project and the working tree of the submodule\r
 263         (this option doesn't allow to use the <emphasis>--cached</emphasis> option or to provide an\r
 264         explicit commit).\r
 265 </simpara>\r
 266 <simpara>Using the <emphasis>--submodule=log</emphasis> option with <xref linkend="git-diff(1)" /> will provide that\r
 267 information too.</simpara>\r
 268 </listitem>\r
 269 </varlistentry>\r
 270 <varlistentry>\r
 271 <term>\r
 272 foreach\r
 273 </term>\r
 274 <listitem>\r
 275 <simpara>\r
 276         Evaluates an arbitrary shell command in each checked out submodule.\r
 277         The command has access to the variables $name, $path, $sha1 and\r
 278         $toplevel:\r
 279         $name is the name of the relevant submodule section in .gitmodules,\r
 280         $path is the name of the submodule directory relative to the\r
 281         superproject, $sha1 is the commit as recorded in the superproject,\r
 282         and $toplevel is the absolute path to the top-level of the superproject.\r
 283         Any submodules defined in the superproject but not checked out are\r
 284         ignored by this command. Unless given <emphasis>--quiet</emphasis>, foreach prints the name\r
 285         of each submodule before evaluating the command.\r
 286         If <emphasis>--recursive</emphasis> is given, submodules are traversed recursively (i.e.\r
 287         the given shell command is evaluated in nested submodules as well).\r
 288         A non-zero return from the command in any submodule causes\r
 289         the processing to terminate. This can be overridden by adding <emphasis>|| :</emphasis>\r
 290         to the end of the command.\r
 291 </simpara>\r
 292 <simpara>As an example, <literal>git submodule foreach 'echo $path &#96;git\r
 293 rev-parse HEAD&#96;'</literal> will show the path and currently checked out\r
 294 commit for each submodule.</simpara>\r
 295 </listitem>\r
 296 </varlistentry>\r
 297 <varlistentry>\r
 298 <term>\r
 299 sync\r
 300 </term>\r
 301 <listitem>\r
 302 <simpara>\r
 303         Synchronizes submodules' remote URL configuration setting\r
 304         to the value specified in .gitmodules. It will only affect those\r
 305         submodules which already have a URL entry in .git/config (that is the\r
 306         case when they are initialized or freshly added). This is useful when\r
 307         submodule URLs change upstream and you need to update your local\r
 308         repositories accordingly.\r
 309 </simpara>\r
 310 <simpara>"git submodule sync" synchronizes all submodules while\r
 311 "git submodule sync -- A" synchronizes submodule "A" only.</simpara>\r
 312 <simpara>If <emphasis>--recursive</emphasis> is specified, this command will recurse into the\r
 313 registered submodules, and sync any nested submodules within.</simpara>\r
 314 </listitem>\r
 315 </varlistentry>\r
 316 </variablelist>\r
 317 </simplesect>\r
 318 <simplesect id="git-submodule(1)__options">\r
 319 <title>OPTIONS</title>\r
 320 <variablelist>\r
 321 <varlistentry>\r
 322 <term>\r
 323 -q\r
 324 </term>\r
 325 <term>\r
 326 --quiet\r
 327 </term>\r
 328 <listitem>\r
 329 <simpara>\r
 330         Only print error messages.\r
 331 </simpara>\r
 332 </listitem>\r
 333 </varlistentry>\r
 334 <varlistentry>\r
 335 <term>\r
 336 -b\r
 337 </term>\r
 338 <term>\r
 339 --branch\r
 340 </term>\r
 341 <listitem>\r
 342 <simpara>\r
 343         Branch of repository to add as submodule.\r
 344         The name of the branch is recorded as <emphasis>submodule.&lt;name&gt;.branch</emphasis> in\r
 345         <emphasis>.gitmodules</emphasis> for <emphasis>update --remote</emphasis>.\r
 346 </simpara>\r
 347 </listitem>\r
 348 </varlistentry>\r
 349 <varlistentry>\r
 350 <term>\r
 351 -f\r
 352 </term>\r
 353 <term>\r
 354 --force\r
 355 </term>\r
 356 <listitem>\r
 357 <simpara>\r
 358         This option is only valid for add, deinit and update commands.\r
 359         When running add, allow adding an otherwise ignored submodule path.\r
 360         When running deinit the submodule work trees will be removed even if\r
 361         they contain local changes.\r
 362         When running update (only effective with the checkout procedure),\r
 363         throw away local changes in submodules when switching to a\r
 364         different commit; and always run a checkout operation in the\r
 365         submodule, even if the commit listed in the index of the\r
 366         containing repository matches the commit checked out in the\r
 367         submodule.\r
 368 </simpara>\r
 369 </listitem>\r
 370 </varlistentry>\r
 371 <varlistentry>\r
 372 <term>\r
 373 --cached\r
 374 </term>\r
 375 <listitem>\r
 376 <simpara>\r
 377         This option is only valid for status and summary commands.  These\r
 378         commands typically use the commit found in the submodule HEAD, but\r
 379         with this option, the commit stored in the index is used instead.\r
 380 </simpara>\r
 381 </listitem>\r
 382 </varlistentry>\r
 383 <varlistentry>\r
 384 <term>\r
 385 --files\r
 386 </term>\r
 387 <listitem>\r
 388 <simpara>\r
 389         This option is only valid for the summary command. This command\r
 390         compares the commit in the index with that in the submodule HEAD\r
 391         when this option is used.\r
 392 </simpara>\r
 393 </listitem>\r
 394 </varlistentry>\r
 395 <varlistentry>\r
 396 <term>\r
 397 -n\r
 398 </term>\r
 399 <term>\r
 400 --summary-limit\r
 401 </term>\r
 402 <listitem>\r
 403 <simpara>\r
 404         This option is only valid for the summary command.\r
 405         Limit the summary size (number of commits shown in total).\r
 406         Giving 0 will disable the summary; a negative number means unlimited\r
 407         (the default). This limit only applies to modified submodules. The\r
 408         size is always limited to 1 for added/deleted/typechanged submodules.\r
 409 </simpara>\r
 410 </listitem>\r
 411 </varlistentry>\r
 412 <varlistentry>\r
 413 <term>\r
 414 --remote\r
 415 </term>\r
 416 <listitem>\r
 417 <simpara>\r
 418         This option is only valid for the update command.  Instead of using\r
 419         the superproject's recorded SHA-1 to update the submodule, use the\r
 420         status of the submodule's remote-tracking branch.  The remote used\r
 421         is branch's remote (<emphasis>branch.&lt;name&gt;.remote</emphasis>), defaulting to <emphasis>origin</emphasis>.\r
 422         The remote branch used defaults to <emphasis>master</emphasis>, but the branch name may\r
 423         be overridden by setting the <emphasis>submodule.&lt;name&gt;.branch</emphasis> option in\r
 424         either <emphasis>.gitmodules</emphasis> or <emphasis>.git/config</emphasis> (with <emphasis>.git/config</emphasis> taking\r
 425         precedence).\r
 426 </simpara>\r
 427 <simpara>This works for any of the supported update procedures (<emphasis>--checkout</emphasis>,\r
 428 <emphasis>--rebase</emphasis>, etc.).  The only change is the source of the target SHA-1.\r
 429 For example, <emphasis>submodule update --remote --merge</emphasis> will merge upstream\r
 430 submodule changes into the submodules, while <emphasis>submodule update\r
 431 --merge</emphasis> will merge superproject gitlink changes into the submodules.</simpara>\r
 432 <simpara>In order to ensure a current tracking branch state, <emphasis>update --remote</emphasis>\r
 433 fetches the submodule's remote repository before calculating the\r
 434 SHA-1.  If you don't want to fetch, you should use <emphasis>submodule update\r
 435 --remote --no-fetch</emphasis>.</simpara>\r
 436 <simpara>Use this option to integrate changes from the upstream subproject with\r
 437 your submodule's current HEAD.  Alternatively, you can run <emphasis>git pull</emphasis>\r
 438 from the submodule, which is equivalent except for the remote branch\r
 439 name: <emphasis>update --remote</emphasis> uses the default upstream repository and\r
 440 <emphasis>submodule.&lt;name&gt;.branch</emphasis>, while <emphasis>git pull</emphasis> uses the submodule's\r
 441 <emphasis>branch.&lt;name&gt;.merge</emphasis>.  Prefer <emphasis>submodule.&lt;name&gt;.branch</emphasis> if you want\r
 442 to distribute the default upstream branch with the superproject and\r
 443 <emphasis>branch.&lt;name&gt;.merge</emphasis> if you want a more native feel while working in\r
 444 the submodule itself.</simpara>\r
 445 </listitem>\r
 446 </varlistentry>\r
 447 <varlistentry>\r
 448 <term>\r
 449 -N\r
 450 </term>\r
 451 <term>\r
 452 --no-fetch\r
 453 </term>\r
 454 <listitem>\r
 455 <simpara>\r
 456         This option is only valid for the update command.\r
 457         Don't fetch new objects from the remote site.\r
 458 </simpara>\r
 459 </listitem>\r
 460 </varlistentry>\r
 461 <varlistentry>\r
 462 <term>\r
 463 --checkout\r
 464 </term>\r
 465 <listitem>\r
 466 <simpara>\r
 467         This option is only valid for the update command.\r
 468         Checkout the commit recorded in the superproject on a detached HEAD\r
 469         in the submodule. This is the default behavior, the main use of\r
 470         this option is to override <emphasis>submodule.$name.update</emphasis> when set to\r
 471         a value other than <emphasis>checkout</emphasis>.\r
 472         If the key <emphasis>submodule.$name.update</emphasis> is either not explicitly set or\r
 473         set to <emphasis>checkout</emphasis>, this option is implicit.\r
 474 </simpara>\r
 475 </listitem>\r
 476 </varlistentry>\r
 477 <varlistentry>\r
 478 <term>\r
 479 --merge\r
 480 </term>\r
 481 <listitem>\r
 482 <simpara>\r
 483         This option is only valid for the update command.\r
 484         Merge the commit recorded in the superproject into the current branch\r
 485         of the submodule. If this option is given, the submodule's HEAD will\r
 486         not be detached. If a merge failure prevents this process, you will\r
 487         have to resolve the resulting conflicts within the submodule with the\r
 488         usual conflict resolution tools.\r
 489         If the key <emphasis>submodule.$name.update</emphasis> is set to <emphasis>merge</emphasis>, this option is\r
 490         implicit.\r
 491 </simpara>\r
 492 </listitem>\r
 493 </varlistentry>\r
 494 <varlistentry>\r
 495 <term>\r
 496 --rebase\r
 497 </term>\r
 498 <listitem>\r
 499 <simpara>\r
 500         This option is only valid for the update command.\r
 501         Rebase the current branch onto the commit recorded in the\r
 502         superproject. If this option is given, the submodule's HEAD will not\r
 503         be detached. If a merge failure prevents this process, you will have\r
 504         to resolve these failures with <xref linkend="git-rebase(1)" />.\r
 505         If the key <emphasis>submodule.$name.update</emphasis> is set to <emphasis>rebase</emphasis>, this option is\r
 506         implicit.\r
 507 </simpara>\r
 508 </listitem>\r
 509 </varlistentry>\r
 510 <varlistentry>\r
 511 <term>\r
 512 --init\r
 513 </term>\r
 514 <listitem>\r
 515 <simpara>\r
 516         This option is only valid for the update command.\r
 517         Initialize all submodules for which "git submodule init" has not been\r
 518         called so far before updating.\r
 519 </simpara>\r
 520 </listitem>\r
 521 </varlistentry>\r
 522 <varlistentry>\r
 523 <term>\r
 524 --name\r
 525 </term>\r
 526 <listitem>\r
 527 <simpara>\r
 528         This option is only valid for the add command. It sets the submodule's\r
 529         name to the given string instead of defaulting to its path. The name\r
 530         must be valid as a directory name and may not end with a <emphasis>/</emphasis>.\r
 531 </simpara>\r
 532 </listitem>\r
 533 </varlistentry>\r
 534 <varlistentry>\r
 535 <term>\r
 536 --reference &lt;repository&gt;\r
 537 </term>\r
 538 <listitem>\r
 539 <simpara>\r
 540         This option is only valid for add and update commands.  These\r
 541         commands sometimes need to clone a remote repository. In this case,\r
 542         this option will be passed to the <xref linkend="git-clone(1)" /> command.\r
 543 </simpara>\r
 544 <simpara><emphasis role="strong">NOTE</emphasis>: Do <emphasis role="strong">not</emphasis> use this option unless you have read the note\r
 545 for <xref linkend="git-clone(1)" />'s <emphasis>--reference</emphasis> and <emphasis>--shared</emphasis> options carefully.</simpara>\r
 546 </listitem>\r
 547 </varlistentry>\r
 548 <varlistentry>\r
 549 <term>\r
 550 --recursive\r
 551 </term>\r
 552 <listitem>\r
 553 <simpara>\r
 554         This option is only valid for foreach, update, status and sync commands.\r
 555         Traverse submodules recursively. The operation is performed not\r
 556         only in the submodules of the current repo, but also\r
 557         in any nested submodules inside those submodules (and so on).\r
 558 </simpara>\r
 559 </listitem>\r
 560 </varlistentry>\r
 561 <varlistentry>\r
 562 <term>\r
 563 --depth\r
 564 </term>\r
 565 <listitem>\r
 566 <simpara>\r
 567         This option is valid for add and update commands. Create a <emphasis>shallow</emphasis>\r
 568         clone with a history truncated to the specified number of revisions.\r
 569         See <xref linkend="git-clone(1)" />\r
 570 </simpara>\r
 571 </listitem>\r
 572 </varlistentry>\r
 573 <varlistentry>\r
 574 <term>\r
 575 -j &lt;n&gt;\r
 576 </term>\r
 577 <term>\r
 578 --jobs &lt;n&gt;\r
 579 </term>\r
 580 <listitem>\r
 581 <simpara>\r
 582         This option is only valid for the update command.\r
 583         Clone new submodules in parallel with as many jobs.\r
 584         Defaults to the <emphasis>submodule.fetchJobs</emphasis> option.\r
 585 </simpara>\r
 586 </listitem>\r
 587 </varlistentry>\r
 588 <varlistentry>\r
 589 <term>\r
 590 &lt;path&gt;&#8230;\r
 591 </term>\r
 592 <listitem>\r
 593 <simpara>\r
 594         Paths to submodule(s). When specified this will restrict the command\r
 595         to only operate on the submodules found at the specified paths.\r
 596         (This argument is required with add).\r
 597 </simpara>\r
 598 </listitem>\r
 599 </varlistentry>\r
 600 </variablelist>\r
 601 </simplesect>\r
 602 <simplesect id="git-submodule(1)__files">\r
 603 <title>FILES</title>\r
 604 <simpara>When initializing submodules, a .gitmodules file in the top-level directory\r
 605 of the containing repository is used to find the url of each submodule.\r
 606 This file should be formatted in the same way as <emphasis>$GIT_DIR/config</emphasis>. The key\r
 607 to each submodule url is "submodule.$name.url".  See <xref linkend="gitmodules(5)" />\r
 608 for details.</simpara>\r
 609 </simplesect>\r
 610 <simplesect id="git-submodule(1)__git">\r
 611 <title>GIT</title>\r
 612 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 613 </simplesect>\r
 614 </sect2>\r