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;] [--] &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] update [--init] [-N|--no-fetch] [--rebase]\r
  21               [--reference &lt;repository&gt;] [--merge] [--recursive] [--] [&lt;path&gt;&#8230;]\r
  22 <emphasis>git submodule</emphasis> [--quiet] summary [--cached|--files] [(-n|--summary-limit) &lt;n&gt;]\r
  23               [commit] [--] [&lt;path&gt;&#8230;]\r
  24 <emphasis>git submodule</emphasis> [--quiet] foreach [--recursive] &lt;command&gt;\r
  25 <emphasis>git submodule</emphasis> [--quiet] sync [--] [&lt;path&gt;&#8230;]</literallayout>\r
  26 </blockquote>\r
  27 </simplesect>\r
  28 <simplesect id="git-submodule(1)__description">\r
  29 <title>DESCRIPTION</title>\r
  30 <simpara>Submodules allow foreign repositories to be embedded within\r
  31 a dedicated subdirectory of the source tree, always pointed\r
  32 at a particular commit.</simpara>\r
  33 <simpara>They are not to be confused with remotes, which are meant mainly\r
  34 for branches of the same project; submodules are meant for\r
  35 different projects you would like to make part of your source tree,\r
  36 while the history of the two projects still stays completely\r
  37 independent and you cannot modify the contents of the submodule\r
  38 from within the main project.\r
  39 If you want to merge the project histories and want to treat the\r
  40 aggregated whole as a single project from then on, you may want to\r
  41 add a remote for the other project and use the <emphasis>subtree</emphasis> merge strategy,\r
  42 instead of treating the other project as a submodule. Directories\r
  43 that come from both projects can be cloned and checked out as a whole\r
  44 if you choose to go that route.</simpara>\r
  45 <simpara>Submodules are composed from a so-called <emphasis>gitlink</emphasis> tree entry\r
  46 in the main repository that refers to a particular commit object\r
  47 within the inner repository that is completely separate.\r
  48 A record in the <emphasis>.gitmodules</emphasis> (see <xref linkend="gitmodules(5)" />) file at the\r
  49 root of the source tree assigns a logical name to the submodule and\r
  50 describes the default URL the submodule shall be cloned from.\r
  51 The logical name can be used for overriding this URL within your\r
  52 local repository configuration (see <emphasis>submodule init</emphasis>).</simpara>\r
  53 <simpara>This command will manage the tree entries and contents of the\r
  54 gitmodules file for you, as well as inspect the status of your\r
  55 submodules and update them.\r
  56 When adding a new submodule to the tree, the <emphasis>add</emphasis> subcommand\r
  57 is to be used.  However, when pulling a tree containing submodules,\r
  58 these will not be checked out by default;\r
  59 the <emphasis>init</emphasis> and <emphasis>update</emphasis> subcommands will maintain submodules\r
  60 checked out and at appropriate revision in your working tree.\r
  61 You can briefly inspect the up-to-date status of your submodules\r
  62 using the <emphasis>status</emphasis> subcommand and get a detailed overview of the\r
  63 difference between the index and checkouts using the <emphasis>summary</emphasis>\r
  64 subcommand.</simpara>\r
  65 </simplesect>\r
  66 <simplesect id="git-submodule(1)__commands">\r
  67 <title>COMMANDS</title>\r
  68 <variablelist>\r
  69 <varlistentry>\r
  70 <term>\r
  71 add\r
  72 </term>\r
  73 <listitem>\r
  74 <simpara>\r
  75         Add the given repository as a submodule at the given path\r
  76         to the changeset to be committed next to the current\r
  77         project: the current project is termed the "superproject".\r
  78 </simpara>\r
  79 <simpara>This requires at least one argument: &lt;repository&gt;. The optional\r
  80 argument &lt;path&gt; is the relative location for the cloned submodule\r
  81 to exist in the superproject. If &lt;path&gt; is not given, the\r
  82 "humanish" part of the source repository is used ("repo" for\r
  83 "/path/to/repo.git" and "foo" for "host.xz:foo/.git").</simpara>\r
  84 <simpara>&lt;repository&gt; is the URL of the new submodule's origin repository.\r
  85 This may be either an absolute URL, or (if it begins with ./\r
  86 or ../), the location relative to the superproject's origin\r
  87 repository (Please note that to specify a repository <emphasis>foo.git</emphasis>\r
  88 which is located right next to a superproject <emphasis>bar.git</emphasis>, you'll\r
  89 have to use <emphasis>../foo.git</emphasis> instead of <emphasis>./foo.git</emphasis> - as one might expect\r
  90 when following the rules for relative URLs - because the evaluation\r
  91 of relative URLs in Git is identical to that of relative directories).\r
  92 If the superproject doesn't have an origin configured\r
  93 the superproject is its own authoritative upstream and the current\r
  94 working directory is used instead.</simpara>\r
  95 <simpara>&lt;path&gt; is the relative location for the cloned submodule to\r
  96 exist in the superproject. If &lt;path&gt; does not exist, then the\r
  97 submodule is created by cloning from the named URL. If &lt;path&gt; does\r
  98 exist and is already a valid git repository, then this is added\r
  99 to the changeset without cloning. This second form is provided\r
 100 to ease creating a new submodule from scratch, and presumes\r
 101 the user will later push the submodule to the given URL.</simpara>\r
 102 <simpara>In either case, the given URL is recorded into .gitmodules for\r
 103 use by subsequent users cloning the superproject. If the URL is\r
 104 given relative to the superproject's repository, the presumption\r
 105 is the superproject and submodule repositories will be kept\r
 106 together in the same relative location, and only the\r
 107 superproject's URL needs to be provided: git-submodule will correctly\r
 108 locate the submodule using the relative URL in .gitmodules.</simpara>\r
 109 </listitem>\r
 110 </varlistentry>\r
 111 <varlistentry>\r
 112 <term>\r
 113 status\r
 114 </term>\r
 115 <listitem>\r
 116 <simpara>\r
 117         Show the status of the submodules. This will print the SHA-1 of the\r
 118         currently checked out commit for each submodule, along with the\r
 119         submodule path and the output of <emphasis>git describe</emphasis> for the\r
 120         SHA-1. Each SHA-1 will be prefixed with <emphasis>-</emphasis> if the submodule is not\r
 121         initialized, <emphasis>+</emphasis> if the currently checked out submodule commit\r
 122         does not match the SHA-1 found in the index of the containing\r
 123         repository and <emphasis>U</emphasis> if the submodule has merge conflicts.\r
 124 </simpara>\r
 125 <simpara>If <emphasis>--recursive</emphasis> is specified, this command will recurse into nested\r
 126 submodules, and show their status as well.</simpara>\r
 127 <simpara>If you are only interested in changes of the currently initialized\r
 128 submodules with respect to the commit recorded in the index or the HEAD,\r
 129 <xref linkend="git-status(1)" /> and <xref linkend="git-diff(1)" /> will provide that information\r
 130 too (and can also report changes to a submodule's work tree).</simpara>\r
 131 </listitem>\r
 132 </varlistentry>\r
 133 <varlistentry>\r
 134 <term>\r
 135 init\r
 136 </term>\r
 137 <listitem>\r
 138 <simpara>\r
 139         Initialize the submodules, i.e. register each submodule name\r
 140         and url found in .gitmodules into .git/config.\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 update\r
 156 </term>\r
 157 <listitem>\r
 158 <simpara>\r
 159         Update the registered submodules, i.e. clone missing submodules and\r
 160         checkout the commit specified in the index of the containing repository.\r
 161         This will make the submodules HEAD be detached unless <emphasis>--rebase</emphasis> or\r
 162         <emphasis>--merge</emphasis> is specified or the key <emphasis>submodule.$name.update</emphasis> is set to\r
 163         <emphasis>rebase</emphasis>, <emphasis>merge</emphasis> or <emphasis>none</emphasis>. <emphasis>none</emphasis> can be overridden by specifying\r
 164         <emphasis>--checkout</emphasis>.\r
 165 </simpara>\r
 166 <simpara>If the submodule is not yet initialized, and you just want to use the\r
 167 setting as stored in .gitmodules, you can automatically initialize the\r
 168 submodule with the <emphasis>--init</emphasis> option.</simpara>\r
 169 <simpara>If <emphasis>--recursive</emphasis> is specified, this command will recurse into the\r
 170 registered submodules, and update any nested submodules within.</simpara>\r
 171 <simpara>If <emphasis>--force</emphasis> is specified, the submodule will be checked out (using\r
 172 <emphasis>git checkout --force</emphasis> if appropriate), even if the commit specified in the\r
 173 index of the containing repository already matches the commit checked out in\r
 174 the submodule.</simpara>\r
 175 </listitem>\r
 176 </varlistentry>\r
 177 <varlistentry>\r
 178 <term>\r
 179 summary\r
 180 </term>\r
 181 <listitem>\r
 182 <simpara>\r
 183         Show commit summary between the given commit (defaults to HEAD) and\r
 184         working tree/index. For a submodule in question, a series of commits\r
 185         in the submodule between the given super project commit and the\r
 186         index or working tree (switched by <emphasis>--cached</emphasis>) are shown. If the option\r
 187         <emphasis>--files</emphasis> is given, show the series of commits in the submodule between\r
 188         the index of the super project and the working tree of the submodule\r
 189         (this option doesn't allow to use the <emphasis>--cached</emphasis> option or to provide an\r
 190         explicit commit).\r
 191 </simpara>\r
 192 <simpara>Using the <emphasis>--submodule=log</emphasis> option with <xref linkend="git-diff(1)" /> will provide that\r
 193 information too.</simpara>\r
 194 </listitem>\r
 195 </varlistentry>\r
 196 <varlistentry>\r
 197 <term>\r
 198 foreach\r
 199 </term>\r
 200 <listitem>\r
 201 <simpara>\r
 202         Evaluates an arbitrary shell command in each checked out submodule.\r
 203         The command has access to the variables $name, $path, $sha1 and\r
 204         $toplevel:\r
 205         $name is the name of the relevant submodule section in .gitmodules,\r
 206         $path is the name of the submodule directory relative to the\r
 207         superproject, $sha1 is the commit as recorded in the superproject,\r
 208         and $toplevel is the absolute path to the top-level of the superproject.\r
 209         Any submodules defined in the superproject but not checked out are\r
 210         ignored by this command. Unless given <emphasis>--quiet</emphasis>, foreach prints the name\r
 211         of each submodule before evaluating the command.\r
 212         If <emphasis>--recursive</emphasis> is given, submodules are traversed recursively (i.e.\r
 213         the given shell command is evaluated in nested submodules as well).\r
 214         A non-zero return from the command in any submodule causes\r
 215         the processing to terminate. This can be overridden by adding <emphasis>|| :</emphasis>\r
 216         to the end of the command.\r
 217 </simpara>\r
 218 <simpara>As an example, <literal>git submodule foreach 'echo $path &#96;git\r
 219 rev-parse HEAD&#96;'</literal> will show the path and currently checked out\r
 220 commit for each submodule.</simpara>\r
 221 </listitem>\r
 222 </varlistentry>\r
 223 <varlistentry>\r
 224 <term>\r
 225 sync\r
 226 </term>\r
 227 <listitem>\r
 228 <simpara>\r
 229         Synchronizes submodules' remote URL configuration setting\r
 230         to the value specified in .gitmodules. It will only affect those\r
 231         submodules which already have a URL entry in .git/config (that is the\r
 232         case when they are initialized or freshly added). This is useful when\r
 233         submodule URLs change upstream and you need to update your local\r
 234         repositories accordingly.\r
 235 </simpara>\r
 236 <simpara>"git submodule sync" synchronizes all submodules while\r
 237 "git submodule sync -- A" synchronizes submodule "A" only.</simpara>\r
 238 </listitem>\r
 239 </varlistentry>\r
 240 </variablelist>\r
 241 </simplesect>\r
 242 <simplesect id="git-submodule(1)__options">\r
 243 <title>OPTIONS</title>\r
 244 <variablelist>\r
 245 <varlistentry>\r
 246 <term>\r
 247 -q\r
 248 </term>\r
 249 <term>\r
 250 --quiet\r
 251 </term>\r
 252 <listitem>\r
 253 <simpara>\r
 254         Only print error messages.\r
 255 </simpara>\r
 256 </listitem>\r
 257 </varlistentry>\r
 258 <varlistentry>\r
 259 <term>\r
 260 -b\r
 261 </term>\r
 262 <term>\r
 263 --branch\r
 264 </term>\r
 265 <listitem>\r
 266 <simpara>\r
 267         Branch of repository to add as submodule.\r
 268 </simpara>\r
 269 </listitem>\r
 270 </varlistentry>\r
 271 <varlistentry>\r
 272 <term>\r
 273 -f\r
 274 </term>\r
 275 <term>\r
 276 --force\r
 277 </term>\r
 278 <listitem>\r
 279 <simpara>\r
 280         This option is only valid for add and update commands.\r
 281         When running add, allow adding an otherwise ignored submodule path.\r
 282         When running update, throw away local changes in submodules when\r
 283         switching to a different commit; and always run a checkout operation\r
 284         in the submodule, even if the commit listed in the index of the\r
 285         containing repository matches the commit checked out in the submodule.\r
 286 </simpara>\r
 287 </listitem>\r
 288 </varlistentry>\r
 289 <varlistentry>\r
 290 <term>\r
 291 --cached\r
 292 </term>\r
 293 <listitem>\r
 294 <simpara>\r
 295         This option is only valid for status and summary commands.  These\r
 296         commands typically use the commit found in the submodule HEAD, but\r
 297         with this option, the commit stored in the index is used instead.\r
 298 </simpara>\r
 299 </listitem>\r
 300 </varlistentry>\r
 301 <varlistentry>\r
 302 <term>\r
 303 --files\r
 304 </term>\r
 305 <listitem>\r
 306 <simpara>\r
 307         This option is only valid for the summary command. This command\r
 308         compares the commit in the index with that in the submodule HEAD\r
 309         when this option is used.\r
 310 </simpara>\r
 311 </listitem>\r
 312 </varlistentry>\r
 313 <varlistentry>\r
 314 <term>\r
 315 -n\r
 316 </term>\r
 317 <term>\r
 318 --summary-limit\r
 319 </term>\r
 320 <listitem>\r
 321 <simpara>\r
 322         This option is only valid for the summary command.\r
 323         Limit the summary size (number of commits shown in total).\r
 324         Giving 0 will disable the summary; a negative number means unlimited\r
 325         (the default). This limit only applies to modified submodules. The\r
 326         size is always limited to 1 for added/deleted/typechanged submodules.\r
 327 </simpara>\r
 328 </listitem>\r
 329 </varlistentry>\r
 330 <varlistentry>\r
 331 <term>\r
 332 -N\r
 333 </term>\r
 334 <term>\r
 335 --no-fetch\r
 336 </term>\r
 337 <listitem>\r
 338 <simpara>\r
 339         This option is only valid for the update command.\r
 340         Don't fetch new objects from the remote site.\r
 341 </simpara>\r
 342 </listitem>\r
 343 </varlistentry>\r
 344 <varlistentry>\r
 345 <term>\r
 346 --merge\r
 347 </term>\r
 348 <listitem>\r
 349 <simpara>\r
 350         This option is only valid for the update command.\r
 351         Merge the commit recorded in the superproject into the current branch\r
 352         of the submodule. If this option is given, the submodule's HEAD will\r
 353         not be detached. If a merge failure prevents this process, you will\r
 354         have to resolve the resulting conflicts within the submodule with the\r
 355         usual conflict resolution tools.\r
 356         If the key <emphasis>submodule.$name.update</emphasis> is set to <emphasis>merge</emphasis>, this option is\r
 357         implicit.\r
 358 </simpara>\r
 359 </listitem>\r
 360 </varlistentry>\r
 361 <varlistentry>\r
 362 <term>\r
 363 --rebase\r
 364 </term>\r
 365 <listitem>\r
 366 <simpara>\r
 367         This option is only valid for the update command.\r
 368         Rebase the current branch onto the commit recorded in the\r
 369         superproject. If this option is given, the submodule's HEAD will not\r
 370         be detached. If a merge failure prevents this process, you will have\r
 371         to resolve these failures with <xref linkend="git-rebase(1)" />.\r
 372         If the key <emphasis>submodule.$name.update</emphasis> is set to <emphasis>rebase</emphasis>, this option is\r
 373         implicit.\r
 374 </simpara>\r
 375 </listitem>\r
 376 </varlistentry>\r
 377 <varlistentry>\r
 378 <term>\r
 379 --init\r
 380 </term>\r
 381 <listitem>\r
 382 <simpara>\r
 383         This option is only valid for the update command.\r
 384         Initialize all submodules for which "git submodule init" has not been\r
 385         called so far before updating.\r
 386 </simpara>\r
 387 </listitem>\r
 388 </varlistentry>\r
 389 <varlistentry>\r
 390 <term>\r
 391 --name\r
 392 </term>\r
 393 <listitem>\r
 394 <simpara>\r
 395         This option is only valid for the add command. It sets the submodule's\r
 396         name to the given string instead of defaulting to its path. The name\r
 397         must be valid as a directory name and may not end with a <emphasis>/</emphasis>.\r
 398 </simpara>\r
 399 </listitem>\r
 400 </varlistentry>\r
 401 <varlistentry>\r
 402 <term>\r
 403 --reference &lt;repository&gt;\r
 404 </term>\r
 405 <listitem>\r
 406 <simpara>\r
 407         This option is only valid for add and update commands.  These\r
 408         commands sometimes need to clone a remote repository. In this case,\r
 409         this option will be passed to the <xref linkend="git-clone(1)" /> command.\r
 410 </simpara>\r
 411 <simpara><emphasis role="strong">NOTE</emphasis>: Do <emphasis role="strong">not</emphasis> use this option unless you have read the note\r
 412 for <xref linkend="git-clone(1)" />'s <emphasis>--reference</emphasis> and <emphasis>--shared</emphasis> options carefully.</simpara>\r
 413 </listitem>\r
 414 </varlistentry>\r
 415 <varlistentry>\r
 416 <term>\r
 417 --recursive\r
 418 </term>\r
 419 <listitem>\r
 420 <simpara>\r
 421         This option is only valid for foreach, update and status commands.\r
 422         Traverse submodules recursively. The operation is performed not\r
 423         only in the submodules of the current repo, but also\r
 424         in any nested submodules inside those submodules (and so on).\r
 425 </simpara>\r
 426 </listitem>\r
 427 </varlistentry>\r
 428 <varlistentry>\r
 429 <term>\r
 430 &lt;path&gt;&#8230;\r
 431 </term>\r
 432 <listitem>\r
 433 <simpara>\r
 434         Paths to submodule(s). When specified this will restrict the command\r
 435         to only operate on the submodules found at the specified paths.\r
 436         (This argument is required with add).\r
 437 </simpara>\r
 438 </listitem>\r
 439 </varlistentry>\r
 440 </variablelist>\r
 441 </simplesect>\r
 442 <simplesect id="git-submodule(1)__files">\r
 443 <title>FILES</title>\r
 444 <simpara>When initializing submodules, a .gitmodules file in the top-level directory\r
 445 of the containing repository is used to find the url of each submodule.\r
 446 This file should be formatted in the same way as <emphasis>$GIT_DIR/config</emphasis>. The key\r
 447 to each submodule url is "submodule.$name.url".  See <xref linkend="gitmodules(5)" />\r
 448 for details.</simpara>\r
 449 </simplesect>\r
 450 <simplesect id="git-submodule(1)__git">\r
 451 <title>GIT</title>\r
 452 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
 453 </simplesect>\r
 454 </sect2>\r