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

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-submodule(1)">\r
   5 <articleinfo>\r
   6     <title>git-submodule(1)</title>\r
   7         <indexterm>\r
   8                 <primary>git-submodule(1)</primary>\r
   9         </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-submodule - Initialize, update or inspect submodules</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git submodule</emphasis> [--quiet] add [-b branch] [--] &lt;repository&gt; &lt;path&gt;\r
  19 <emphasis>git submodule</emphasis> [--quiet] status [--cached] [--] [&lt;path&gt;&#8230;]\r
  20 <emphasis>git submodule</emphasis> [--quiet] init [--] [&lt;path&gt;&#8230;]\r
  21 <emphasis>git submodule</emphasis> [--quiet] update [--init] [-N|--no-fetch] [--] [&lt;path&gt;&#8230;]\r
  22 <emphasis>git submodule</emphasis> [--quiet] summary [--summary-limit &lt;n&gt;] [commit] [--] [&lt;path&gt;&#8230;]\r
  23 <emphasis>git submodule</emphasis> [--quiet] foreach &lt;command&gt;\r
  24 <emphasis>git submodule</emphasis> [--quiet] sync [--] [&lt;path&gt;&#8230;]</literallayout>\r
  25 </blockquote>\r
  26 </simplesect>\r
  27 <simplesect id="_description">\r
  28 <title>DESCRIPTION</title>\r
  29 <simpara>Submodules allow foreign repositories to be embedded within\r
  30 a dedicated subdirectory of the source tree, always pointed\r
  31 at a particular commit.</simpara>\r
  32 <simpara>They are not to be confused with remotes, which are meant mainly\r
  33 for branches of the same project; submodules are meant for\r
  34 different projects you would like to make part of your source tree,\r
  35 while the history of the two projects still stays completely\r
  36 independent and you cannot modify the contents of the submodule\r
  37 from within the main project.\r
  38 If you want to merge the project histories and want to treat the\r
  39 aggregated whole as a single project from then on, you may want to\r
  40 add a remote for the other project and use the <emphasis>subtree</emphasis> merge strategy,\r
  41 instead of treating the other project as a submodule. Directories\r
  42 that come from both projects can be cloned and checked out as a whole\r
  43 if you choose to go that route.</simpara>\r
  44 <simpara>Submodules are composed from a so-called <literal>gitlink</literal> tree entry\r
  45 in the main repository that refers to a particular commit object\r
  46 within the inner repository that is completely separate.\r
  47 A record in the <literal>.gitmodules</literal> file at the root of the source\r
  48 tree assigns a logical name to the submodule and describes\r
  49 the default URL the submodule shall be cloned from.\r
  50 The logical name can be used for overriding this URL within your\r
  51 local repository configuration (see <emphasis>submodule init</emphasis>).</simpara>\r
  52 <simpara>This command will manage the tree entries and contents of the\r
  53 gitmodules file for you, as well as inspect the status of your\r
  54 submodules and update them.\r
  55 When adding a new submodule to the tree, the <emphasis>add</emphasis> subcommand\r
  56 is to be used.  However, when pulling a tree containing submodules,\r
  57 these will not be checked out by default;\r
  58 the <emphasis>init</emphasis> and <emphasis>update</emphasis> subcommands will maintain submodules\r
  59 checked out and at appropriate revision in your working tree.\r
  60 You can briefly inspect the up-to-date status of your submodules\r
  61 using the <emphasis>status</emphasis> subcommand and get a detailed overview of the\r
  62 difference between the index and checkouts using the <emphasis>summary</emphasis>\r
  63 subcommand.</simpara>\r
  64 </simplesect>\r
  65 <simplesect id="_commands">\r
  66 <title>COMMANDS</title>\r
  67 <variablelist>\r
  68 <varlistentry>\r
  69 <term>\r
  70 add\r
  71 </term>\r
  72 <listitem>\r
  73 <simpara>\r
  74         Add the given repository as a submodule at the given path\r
  75         to the changeset to be committed next to the current\r
  76         project: the current project is termed the "superproject".\r
  77 </simpara>\r
  78 <simpara>This requires two arguments: &lt;repository&gt; and &lt;path&gt;.</simpara>\r
  79 <simpara>&lt;repository&gt; is the URL of the new submodule&#8217;s origin repository.\r
  80 This may be either an absolute URL, or (if it begins with ./\r
  81 or ../), the location relative to the superproject&#8217;s origin\r
  82 repository.</simpara>\r
  83 <simpara>&lt;path&gt; is the relative location for the cloned submodule to\r
  84 exist in the superproject. If &lt;path&gt; does not exist, then the\r
  85 submodule is created by cloning from the named URL. If &lt;path&gt; does\r
  86 exist and is already a valid git repository, then this is added\r
  87 to the changeset without cloning. This second form is provided\r
  88 to ease creating a new submodule from scratch, and presumes\r
  89 the user will later push the submodule to the given URL.</simpara>\r
  90 <simpara>In either case, the given URL is recorded into .gitmodules for\r
  91 use by subsequent users cloning the superproject. If the URL is\r
  92 given relative to the superproject&#8217;s repository, the presumption\r
  93 is the superproject and submodule repositories will be kept\r
  94 together in the same relative location, and only the\r
  95 superproject&#8217;s URL needs to be provided: git-submodule will correctly\r
  96 locate the submodule using the relative URL in .gitmodules.</simpara>\r
  97 </listitem>\r
  98 </varlistentry>\r
  99 <varlistentry>\r
 100 <term>\r
 101 status\r
 102 </term>\r
 103 <listitem>\r
 104 <simpara>\r
 105         Show the status of the submodules. This will print the SHA-1 of the\r
 106         currently checked out commit for each submodule, along with the\r
 107         submodule path and the output of <emphasis>git-describe</emphasis> for the\r
 108         SHA-1. Each SHA-1 will be prefixed with <literal>-</literal> if the submodule is not\r
 109         initialized and <literal>+</literal> if the currently checked out submodule commit\r
 110         does not match the SHA-1 found in the index of the containing\r
 111         repository. This command is the default command for <emphasis>git-submodule</emphasis>.\r
 112 </simpara>\r
 113 </listitem>\r
 114 </varlistentry>\r
 115 <varlistentry>\r
 116 <term>\r
 117 init\r
 118 </term>\r
 119 <listitem>\r
 120 <simpara>\r
 121         Initialize the submodules, i.e. register each submodule name\r
 122         and url found in .gitmodules into .git/config.\r
 123         The key used in .git/config is <literal>submodule.$name.url</literal>.\r
 124         This command does not alter existing information in .git/config.\r
 125         You can then customize the submodule clone URLs in .git/config\r
 126         for your local setup and proceed to <emphasis>git submodule update</emphasis>;\r
 127         you can also just use <emphasis>git submodule update --init</emphasis> without\r
 128         the explicit <emphasis>init</emphasis> step if you do not intend to customize\r
 129         any submodule locations.\r
 130 </simpara>\r
 131 </listitem>\r
 132 </varlistentry>\r
 133 <varlistentry>\r
 134 <term>\r
 135 update\r
 136 </term>\r
 137 <listitem>\r
 138 <simpara>\r
 139         Update the registered submodules, i.e. clone missing submodules and\r
 140         checkout the commit specified in the index of the containing repository.\r
 141         This will make the submodules HEAD be detached.\r
 142 </simpara>\r
 143 <simpara>If the submodule is not yet initialized, and you just want to use the\r
 144 setting as stored in .gitmodules, you can automatically initialize the\r
 145 submodule with the --init option.</simpara>\r
 146 </listitem>\r
 147 </varlistentry>\r
 148 <varlistentry>\r
 149 <term>\r
 150 summary\r
 151 </term>\r
 152 <listitem>\r
 153 <simpara>\r
 154         Show commit summary between the given commit (defaults to HEAD) and\r
 155         working tree/index. For a submodule in question, a series of commits\r
 156         in the submodule between the given super project commit and the\r
 157         index or working tree (switched by --cached) are shown.\r
 158 </simpara>\r
 159 </listitem>\r
 160 </varlistentry>\r
 161 <varlistentry>\r
 162 <term>\r
 163 foreach\r
 164 </term>\r
 165 <listitem>\r
 166 <simpara>\r
 167         Evaluates an arbitrary shell command in each checked out submodule.\r
 168         The command has access to the variables $path and $sha1:\r
 169         $path is the name of the submodule directory relative to the\r
 170         superproject, and $sha1 is the commit as recorded in the superproject.\r
 171         Any submodules defined in the superproject but not checked out are\r
 172         ignored by this command. Unless given --quiet, foreach prints the name\r
 173         of each submodule before evaluating the command.\r
 174         A non-zero return from the command in any submodule causes\r
 175         the processing to terminate. This can be overridden by adding <emphasis>|| :</emphasis>\r
 176         to the end of the command.\r
 177 </simpara>\r
 178 <simpara>As an example, "git submodule foreach <emphasis>echo $path <literal>git rev-parse HEAD</literal></emphasis> will\r
 179 show the path and currently checked out commit for each submodule.</simpara>\r
 180 </listitem>\r
 181 </varlistentry>\r
 182 <varlistentry>\r
 183 <term>\r
 184 sync\r
 185 </term>\r
 186 <listitem>\r
 187 <simpara>\r
 188         Synchronizes submodules' remote URL configuration setting\r
 189         to the value specified in .gitmodules.  This is useful when\r
 190         submodule URLs change upstream and you need to update your local\r
 191         repositories accordingly.\r
 192 </simpara>\r
 193 <simpara>"git submodule sync" synchronizes all submodules while\r
 194 "git submodule sync&#8201;&#8212;&#8201;A" synchronizes submodule "A" only.</simpara>\r
 195 </listitem>\r
 196 </varlistentry>\r
 197 </variablelist>\r
 198 </simplesect>\r
 199 <simplesect id="_options">\r
 200 <title>OPTIONS</title>\r
 201 <variablelist>\r
 202 <varlistentry>\r
 203 <term>\r
 204 -q\r
 205 </term>\r
 206 <term>\r
 207 --quiet\r
 208 </term>\r
 209 <listitem>\r
 210 <simpara>\r
 211         Only print error messages.\r
 212 </simpara>\r
 213 </listitem>\r
 214 </varlistentry>\r
 215 <varlistentry>\r
 216 <term>\r
 217 -b\r
 218 </term>\r
 219 <term>\r
 220 --branch\r
 221 </term>\r
 222 <listitem>\r
 223 <simpara>\r
 224         Branch of repository to add as submodule.\r
 225 </simpara>\r
 226 </listitem>\r
 227 </varlistentry>\r
 228 <varlistentry>\r
 229 <term>\r
 230 --cached\r
 231 </term>\r
 232 <listitem>\r
 233 <simpara>\r
 234         This option is only valid for status and summary commands.  These\r
 235         commands typically use the commit found in the submodule HEAD, but\r
 236         with this option, the commit stored in the index is used instead.\r
 237 </simpara>\r
 238 </listitem>\r
 239 </varlistentry>\r
 240 <varlistentry>\r
 241 <term>\r
 242 -n\r
 243 </term>\r
 244 <term>\r
 245 --summary-limit\r
 246 </term>\r
 247 <listitem>\r
 248 <simpara>\r
 249         This option is only valid for the summary command.\r
 250         Limit the summary size (number of commits shown in total).\r
 251         Giving 0 will disable the summary; a negative number means unlimited\r
 252         (the default). This limit only applies to modified submodules. The\r
 253         size is always limited to 1 for added/deleted/typechanged submodules.\r
 254 </simpara>\r
 255 </listitem>\r
 256 </varlistentry>\r
 257 <varlistentry>\r
 258 <term>\r
 259 -N\r
 260 </term>\r
 261 <term>\r
 262 --no-fetch\r
 263 </term>\r
 264 <listitem>\r
 265 <simpara>\r
 266         This option is only valid for the update command.\r
 267         Don&#8217;t fetch new objects from the remote site.\r
 268 </simpara>\r
 269 </listitem>\r
 270 </varlistentry>\r
 271 <varlistentry>\r
 272 <term>\r
 273 &lt;path&gt;&#8230;\r
 274 </term>\r
 275 <listitem>\r
 276 <simpara>\r
 277         Paths to submodule(s). When specified this will restrict the command\r
 278         to only operate on the submodules found at the specified paths.\r
 279         (This argument is required with add).\r
 280 </simpara>\r
 281 </listitem>\r
 282 </varlistentry>\r
 283 </variablelist>\r
 284 </simplesect>\r
 285 <simplesect id="_files">\r
 286 <title>FILES</title>\r
 287 <simpara>When initializing submodules, a .gitmodules file in the top-level directory\r
 288 of the containing repository is used to find the url of each submodule.\r
 289 This file should be formatted in the same way as <literal>$GIT_DIR/config</literal>. The key\r
 290 to each submodule url is "submodule.$name.url".  See <xref linkend="gitmodules(5)"/>\r
 291 for details.</simpara>\r
 292 </simplesect>\r
 293 <simplesect id="_author">\r
 294 <title>AUTHOR</title>\r
 295 <simpara>Written by Lars Hjemli &lt;<ulink url="mailto:hjemli@gmail.com">hjemli@gmail.com</ulink>&gt;</simpara>\r
 296 </simplesect>\r
 297 <simplesect id="_git">\r
 298 <title>GIT</title>\r
 299 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>\r
 300 </simplesect>\r
 301 </article>\r