doc/source/en/TortoiseGit/git_doc/git-clone.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-clone(1)">\r
   5 <articleinfo>\r
   6     <title>git-clone(1)</title>\r
   7         <indexterm>\r
   8                 <primary>git-clone(1)</primary>\r
   9         </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-clone - Clone a repository into a new directory</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git clone</emphasis> [--template=&lt;template_directory&gt;]\r
  19           [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]\r
  20           [-o &lt;name&gt;] [-u &lt;upload-pack&gt;] [--reference &lt;repository&gt;]\r
  21           [--depth &lt;depth&gt;] [--] &lt;repository&gt; [&lt;directory&gt;]</literallayout>\r
  22 </blockquote>\r
  23 </simplesect>\r
  24 <simplesect id="_description">\r
  25 <title>DESCRIPTION</title>\r
  26 <simpara>Clones a repository into a newly created directory, creates\r
  27 remote-tracking branches for each branch in the cloned repository\r
  28 (visible using <literal>git branch -r</literal>), and creates and checks out an initial\r
  29 branch equal to the cloned repository&#8217;s currently active branch.</simpara>\r
  30 <simpara>After the clone, a plain <literal>git fetch</literal> without arguments will update\r
  31 all the remote-tracking branches, and a <literal>git pull</literal> without\r
  32 arguments will in addition merge the remote master branch into the\r
  33 current master branch, if any.</simpara>\r
  34 <simpara>This default configuration is achieved by creating references to\r
  35 the remote branch heads under <literal>$GIT_DIR/refs/remotes/origin</literal> and\r
  36 by initializing <literal>remote.origin.url</literal> and <literal>remote.origin.fetch</literal>\r
  37 configuration variables.</simpara>\r
  38 </simplesect>\r
  39 <simplesect id="_options">\r
  40 <title>OPTIONS</title>\r
  41 <variablelist>\r
  42 <varlistentry>\r
  43 <term>\r
  44 --local\r
  45 </term>\r
  46 <term>\r
  47 -l\r
  48 </term>\r
  49 <listitem>\r
  50 <simpara>\r
  51         When the repository to clone from is on a local machine,\r
  52         this flag bypasses normal "git aware" transport\r
  53         mechanism and clones the repository by making a copy of\r
  54         HEAD and everything under objects and refs directories.\r
  55         The files under <literal>.git/objects/</literal> directory are hardlinked\r
  56         to save space when possible.  This is now the default when\r
  57         the source repository is specified with <literal>/path/to/repo</literal>\r
  58         syntax, so it essentially is a no-op option.  To force\r
  59         copying instead of hardlinking (which may be desirable\r
  60         if you are trying to make a back-up of your repository),\r
  61         but still avoid the usual "git aware" transport\r
  62         mechanism, <literal>--no-hardlinks</literal> can be used.\r
  63 </simpara>\r
  64 </listitem>\r
  65 </varlistentry>\r
  66 <varlistentry>\r
  67 <term>\r
  68 --no-hardlinks\r
  69 </term>\r
  70 <listitem>\r
  71 <simpara>\r
  72         Optimize the cloning process from a repository on a\r
  73         local filesystem by copying files under <literal>.git/objects</literal>\r
  74         directory.\r
  75 </simpara>\r
  76 </listitem>\r
  77 </varlistentry>\r
  78 <varlistentry>\r
  79 <term>\r
  80 --shared\r
  81 </term>\r
  82 <term>\r
  83 -s\r
  84 </term>\r
  85 <listitem>\r
  86 <simpara>\r
  87         When the repository to clone is on the local machine,\r
  88         instead of using hard links, automatically setup\r
  89         .git/objects/info/alternates to share the objects\r
  90         with the source repository.  The resulting repository\r
  91         starts out without any object of its own.\r
  92 </simpara>\r
  93 <simpara><emphasis role="strong">NOTE</emphasis>: this is a possibly dangerous operation; do <emphasis role="strong">not</emphasis> use\r
  94 it unless you understand what it does. If you clone your\r
  95 repository using this option and then delete branches (or use any\r
  96 other git command that makes any existing commit unreferenced) in the\r
  97 source repository, some objects may become unreferenced (or dangling).\r
  98 These objects may be removed by normal git operations (such as <emphasis>git-commit</emphasis>)\r
  99 which automatically call <literal>git gc --auto</literal>. (See <xref linkend="git-gc(1)"/>.)\r
 100 If these objects are removed and were referenced by the cloned repository,\r
 101 then the cloned repository will become corrupt.</simpara>\r
 102 </listitem>\r
 103 </varlistentry>\r
 104 <varlistentry>\r
 105 <term>\r
 106 --reference &lt;repository&gt;\r
 107 </term>\r
 108 <listitem>\r
 109 <simpara>\r
 110         If the reference repository is on the local machine\r
 111         automatically setup .git/objects/info/alternates to\r
 112         obtain objects from the reference repository.  Using\r
 113         an already existing repository as an alternate will\r
 114         require fewer objects to be copied from the repository\r
 115         being cloned, reducing network and local storage costs.\r
 116 </simpara>\r
 117 <simpara><emphasis role="strong">NOTE</emphasis>: see NOTE to --shared option.</simpara>\r
 118 </listitem>\r
 119 </varlistentry>\r
 120 <varlistentry>\r
 121 <term>\r
 122 --quiet\r
 123 </term>\r
 124 <term>\r
 125 -q\r
 126 </term>\r
 127 <listitem>\r
 128 <simpara>\r
 129         Operate quietly.  This flag is also passed to the &#8216;rsync&#8217;\r
 130         command when given.\r
 131 </simpara>\r
 132 </listitem>\r
 133 </varlistentry>\r
 134 <varlistentry>\r
 135 <term>\r
 136 --verbose\r
 137 </term>\r
 138 <term>\r
 139 -v\r
 140 </term>\r
 141 <listitem>\r
 142 <simpara>\r
 143         Display the progressbar, even in case the standard output is not\r
 144         a terminal.\r
 145 </simpara>\r
 146 </listitem>\r
 147 </varlistentry>\r
 148 <varlistentry>\r
 149 <term>\r
 150 --no-checkout\r
 151 </term>\r
 152 <term>\r
 153 -n\r
 154 </term>\r
 155 <listitem>\r
 156 <simpara>\r
 157         No checkout of HEAD is performed after the clone is complete.\r
 158 </simpara>\r
 159 </listitem>\r
 160 </varlistentry>\r
 161 <varlistentry>\r
 162 <term>\r
 163 --bare\r
 164 </term>\r
 165 <listitem>\r
 166 <simpara>\r
 167         Make a <emphasis>bare</emphasis> GIT repository.  That is, instead of\r
 168         creating <literal>&lt;directory&gt;</literal> and placing the administrative\r
 169         files in <literal>&lt;directory&gt;/.git</literal>, make the <literal>&lt;directory&gt;</literal>\r
 170         itself the <literal>$GIT_DIR</literal>. This obviously implies the <literal>-n</literal>\r
 171         because there is nowhere to check out the working tree.\r
 172         Also the branch heads at the remote are copied directly\r
 173         to corresponding local branch heads, without mapping\r
 174         them to <literal>refs/remotes/origin/</literal>.  When this option is\r
 175         used, neither remote-tracking branches nor the related\r
 176         configuration variables are created.\r
 177 </simpara>\r
 178 </listitem>\r
 179 </varlistentry>\r
 180 <varlistentry>\r
 181 <term>\r
 182 --mirror\r
 183 </term>\r
 184 <listitem>\r
 185 <simpara>\r
 186         Set up a mirror of the remote repository.  This implies --bare.\r
 187 </simpara>\r
 188 </listitem>\r
 189 </varlistentry>\r
 190 <varlistentry>\r
 191 <term>\r
 192 --origin &lt;name&gt;\r
 193 </term>\r
 194 <term>\r
 195 -o &lt;name&gt;\r
 196 </term>\r
 197 <listitem>\r
 198 <simpara>\r
 199         Instead of using the remote name <emphasis>origin</emphasis> to keep track\r
 200         of the upstream repository, use &lt;name&gt; instead.\r
 201 </simpara>\r
 202 </listitem>\r
 203 </varlistentry>\r
 204 <varlistentry>\r
 205 <term>\r
 206 --upload-pack &lt;upload-pack&gt;\r
 207 </term>\r
 208 <term>\r
 209 -u &lt;upload-pack&gt;\r
 210 </term>\r
 211 <listitem>\r
 212 <simpara>\r
 213         When given, and the repository to clone from is accessed\r
 214         via ssh, this specifies a non-default path for the command\r
 215         run on the other end.\r
 216 </simpara>\r
 217 </listitem>\r
 218 </varlistentry>\r
 219 <varlistentry>\r
 220 <term>\r
 221 --template=&lt;template_directory&gt;\r
 222 </term>\r
 223 <listitem>\r
 224 <simpara>\r
 225         Specify the directory from which templates will be used;\r
 226         if unset the templates are taken from the installation\r
 227         defined default, typically <literal>/usr/share/git-core/templates</literal>.\r
 228 </simpara>\r
 229 </listitem>\r
 230 </varlistentry>\r
 231 <varlistentry>\r
 232 <term>\r
 233 --depth &lt;depth&gt;\r
 234 </term>\r
 235 <listitem>\r
 236 <simpara>\r
 237         Create a <emphasis>shallow</emphasis> clone with a history truncated to the\r
 238         specified number of revisions.  A shallow repository has a\r
 239         number of limitations (you cannot clone or fetch from\r
 240         it, nor push from nor into it), but is adequate if you\r
 241         are only interested in the recent history of a large project\r
 242         with a long history, and would want to send in fixes\r
 243         as patches.\r
 244 </simpara>\r
 245 </listitem>\r
 246 </varlistentry>\r
 247 <varlistentry>\r
 248 <term>\r
 249 &lt;repository&gt;\r
 250 </term>\r
 251 <listitem>\r
 252 <simpara>\r
 253         The (possibly remote) repository to clone from.  See the\r
 254         <link linkend="URLS">URLS</link> section below for more information on specifying\r
 255         repositories.\r
 256 </simpara>\r
 257 </listitem>\r
 258 </varlistentry>\r
 259 <varlistentry>\r
 260 <term>\r
 261 &lt;directory&gt;\r
 262 </term>\r
 263 <listitem>\r
 264 <simpara>\r
 265         The name of a new directory to clone into.  The "humanish"\r
 266         part of the source repository is used if no directory is\r
 267         explicitly given ("repo" for "/path/to/repo.git" and "foo"\r
 268         for "host.xz:foo/.git").  Cloning into an existing directory\r
 269         is not allowed.\r
 270 </simpara>\r
 271 </listitem>\r
 272 </varlistentry>\r
 273 </variablelist>\r
 274 </simplesect>\r
 275 <simplesect id="_git_urls_anchor_id_urls_xreflabel_urls">\r
 276 <title>GIT URLS<anchor id="URLS" xreflabel="[URLS]"/></title>\r
 277 <simpara>One of the following notations can be used\r
 278 to name the remote repository:</simpara>\r
 279 <informalexample>\r
 280 <itemizedlist>\r
 281 <listitem>\r
 282 <simpara>\r
 283 rsync://host.xz/path/to/repo.git/\r
 284 </simpara>\r
 285 </listitem>\r
 286 <listitem>\r
 287 <simpara>\r
 288 <ulink url="http://host.xz&#91;:port&#93;/path/to/repo.git/">http://host.xz&#91;:port&#93;/path/to/repo.git/</ulink>\r
 289 </simpara>\r
 290 </listitem>\r
 291 <listitem>\r
 292 <simpara>\r
 293 <ulink url="https://host.xz&#91;:port&#93;/path/to/repo.git/">https://host.xz&#91;:port&#93;/path/to/repo.git/</ulink>\r
 294 </simpara>\r
 295 </listitem>\r
 296 <listitem>\r
 297 <simpara>\r
 298 git://host.xz&#91;:port&#93;/path/to/repo.git/\r
 299 </simpara>\r
 300 </listitem>\r
 301 <listitem>\r
 302 <simpara>\r
 303 git://host.xz&#91;:port&#93;/~user/path/to/repo.git/\r
 304 </simpara>\r
 305 </listitem>\r
 306 <listitem>\r
 307 <simpara>\r
 308 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/path/to/repo.git/\r
 309 </simpara>\r
 310 </listitem>\r
 311 <listitem>\r
 312 <simpara>\r
 313 ssh://&#91;user@&#93;host.xz/path/to/repo.git/\r
 314 </simpara>\r
 315 </listitem>\r
 316 <listitem>\r
 317 <simpara>\r
 318 ssh://&#91;user@&#93;host.xz/~user/path/to/repo.git/\r
 319 </simpara>\r
 320 </listitem>\r
 321 <listitem>\r
 322 <simpara>\r
 323 ssh://&#91;user@&#93;host.xz/~/path/to/repo.git\r
 324 </simpara>\r
 325 </listitem>\r
 326 </itemizedlist>\r
 327 </informalexample>\r
 328 <simpara>SSH is the default transport protocol over the network.  You can\r
 329 optionally specify which user to log-in as, and an alternate,\r
 330 scp-like syntax is also supported.  Both syntaxes support\r
 331 username expansion, as does the native git protocol, but\r
 332 only the former supports port specification. The following\r
 333 three are identical to the last three above, respectively:</simpara>\r
 334 <informalexample>\r
 335 <itemizedlist>\r
 336 <listitem>\r
 337 <simpara>\r
 338 &#91;user@&#93;host.xz:/path/to/repo.git/\r
 339 </simpara>\r
 340 </listitem>\r
 341 <listitem>\r
 342 <simpara>\r
 343 &#91;user@&#93;host.xz:~user/path/to/repo.git/\r
 344 </simpara>\r
 345 </listitem>\r
 346 <listitem>\r
 347 <simpara>\r
 348 &#91;user@&#93;host.xz:path/to/repo.git\r
 349 </simpara>\r
 350 </listitem>\r
 351 </itemizedlist>\r
 352 </informalexample>\r
 353 <simpara>To sync with a local directory, you can use:</simpara>\r
 354 <informalexample>\r
 355 <itemizedlist>\r
 356 <listitem>\r
 357 <simpara>\r
 358 /path/to/repo.git/\r
 359 </simpara>\r
 360 </listitem>\r
 361 <listitem>\r
 362 <simpara>\r
 363 <ulink url="file:///path/to/repo.git/">file:///path/to/repo.git/</ulink>\r
 364 </simpara>\r
 365 </listitem>\r
 366 </itemizedlist>\r
 367 </informalexample>\r
 368 <simpara>They are equivalent, except the former implies --local option.</simpara>\r
 369 <simpara>If there are a large number of similarly-named remote repositories and\r
 370 you want to use a different format for them (such that the URLs you\r
 371 use will be rewritten into URLs that work), you can create a\r
 372 configuration section of the form:</simpara>\r
 373 <literallayout>        [url "&lt;actual url base&gt;"]\r
 374                 insteadOf = &lt;other url base&gt;</literallayout>\r
 375 <simpara>For example, with this:</simpara>\r
 376 <literallayout>        [url "git://git.host.xz/"]\r
 377                 insteadOf = host.xz:/path/to/\r
 378                 insteadOf = work:</literallayout>\r
 379 <simpara>a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be\r
 380 rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".</simpara>\r
 381 </simplesect>\r
 382 <simplesect id="_examples">\r
 383 <title>Examples</title>\r
 384 <variablelist>\r
 385 <varlistentry>\r
 386 <term>\r
 387 Clone from upstream\r
 388 </term>\r
 389 <listitem>\r
 390 <literallayout>$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6\r
 391 $ cd my2.6\r
 392 $ make</literallayout>\r
 393 </listitem>\r
 394 </varlistentry>\r
 395 <varlistentry>\r
 396 <term>\r
 397 Make a local clone that borrows from the current directory, without checking things out\r
 398 </term>\r
 399 <listitem>\r
 400 <literallayout>$ git clone -l -s -n . ../copy\r
 401 $ cd ../copy\r
 402 $ git show-branch</literallayout>\r
 403 </listitem>\r
 404 </varlistentry>\r
 405 <varlistentry>\r
 406 <term>\r
 407 Clone from upstream while borrowing from an existing local directory\r
 408 </term>\r
 409 <listitem>\r
 410 <literallayout>$ git clone --reference my2.6 \\r
 411         git://git.kernel.org/pub/scm/.../linux-2.7 \\r
 412         my2.7\r
 413 $ cd my2.7</literallayout>\r
 414 </listitem>\r
 415 </varlistentry>\r
 416 <varlistentry>\r
 417 <term>\r
 418 Create a bare repository to publish your changes to the public\r
 419 </term>\r
 420 <listitem>\r
 421 <literallayout>$ git clone --bare -l /home/proj/.git /pub/scm/proj.git</literallayout>\r
 422 </listitem>\r
 423 </varlistentry>\r
 424 <varlistentry>\r
 425 <term>\r
 426 Create a repository on the kernel.org machine that borrows from Linus\r
 427 </term>\r
 428 <listitem>\r
 429 <literallayout>$ git clone --bare -l -s /pub/scm/.../torvalds/linux-2.6.git \\r
 430     /pub/scm/.../me/subsys-2.6.git</literallayout>\r
 431 </listitem>\r
 432 </varlistentry>\r
 433 </variablelist>\r
 434 </simplesect>\r
 435 <simplesect id="_author">\r
 436 <title>Author</title>\r
 437 <simpara>Written by Linus Torvalds &lt;<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>&gt;</simpara>\r
 438 </simplesect>\r
 439 <simplesect id="_documentation">\r
 440 <title>Documentation</title>\r
 441 <simpara>Documentation by Junio C Hamano and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;.</simpara>\r
 442 </simplesect>\r
 443 <simplesect id="_git">\r
 444 <title>GIT</title>\r
 445 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>\r
 446 </simplesect>\r
 447 </article>\r