Autogenerated HTML docs for v1.6.6-69-gc18d
[git/jnareb-git.git] / git-clone.html
bloba40e45f5d31482040add027d09995c1f027f8e85
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 {
11 border: 1px solid red;
15 body {
16 margin: 1em 5% 1em 5%;
19 a {
20 color: blue;
21 text-decoration: underline;
23 a:visited {
24 color: fuchsia;
27 em {
28 font-style: italic;
31 strong {
32 font-weight: bold;
35 tt {
36 color: navy;
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;
47 h1, h2, h3 {
48 border-bottom: 2px solid silver;
50 h2 {
51 padding-top: 0.5em;
53 h3 {
54 float: left;
56 h3 + * {
57 clear: left;
60 div.sectionbody {
61 font-family: serif;
62 margin-left: 0;
65 hr {
66 border: 1px solid silver;
69 p {
70 margin-top: 0.5em;
71 margin-bottom: 0.5em;
74 pre {
75 padding: 0;
76 margin: 0;
79 span#author {
80 color: #527bbd;
81 font-family: sans-serif;
82 font-weight: bold;
83 font-size: 1.1em;
85 span#email {
87 span#revision {
88 font-family: sans-serif;
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;
98 div#footer-text {
99 float: left;
100 padding-bottom: 0.5em;
102 div#footer-badges {
103 float: right;
104 padding-bottom: 0.5em;
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;
115 div.admonitionblock {
116 margin-top: 2.5em;
117 margin-bottom: 2.5em;
120 div.content { /* Block element content. */
121 padding: 0;
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;
132 div.title + * {
133 margin-top: 0;
136 td div.title:first-child {
137 margin-top: 0.0em;
139 div.content div.title:first-child {
140 margin-top: 0.0em;
142 div.content + div.title {
143 margin-top: 0.0em;
146 div.sidebarblock > div.content {
147 background: #ffffee;
148 border: 1px solid silver;
149 padding: 0.5em;
152 div.listingblock {
153 margin-right: 0%;
155 div.listingblock > div.content {
156 border: 1px solid silver;
157 background: #f4f4f4;
158 padding: 0.5em;
161 div.quoteblock > div.content {
162 padding-left: 2.0em;
165 div.attribution {
166 text-align: right;
168 div.verseblock + div.attribution {
169 text-align: left;
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;
180 div.admonitionblock td.content {
181 padding-left: 0.5em;
182 border-left: 2px solid silver;
185 div.exampleblock > div.content {
186 border-left: 2px solid silver;
187 padding: 0.5em;
190 div.verseblock div.content {
191 white-space: pre;
194 div.imageblock div.content { padding-left: 0; }
195 div.imageblock img { border: 1px solid silver; }
196 span.image img { border-style: none; }
198 dl {
199 margin-top: 0.8em;
200 margin-bottom: 0.8em;
202 dt {
203 margin-top: 0.5em;
204 margin-bottom: 0;
205 font-style: italic;
207 dd > *:first-child {
208 margin-top: 0;
211 ul, ol {
212 list-style-position: outside;
214 div.olist2 ol {
215 list-style-type: lower-alpha;
218 div.tableblock > table {
219 border: 3px solid #527bbd;
221 thead {
222 font-family: sans-serif;
223 font-weight: bold;
225 tfoot {
226 font-weight: bold;
229 div.hlist {
230 margin-top: 0.8em;
231 margin-bottom: 0.8em;
233 div.hlist td {
234 padding-bottom: 5px;
236 td.hlist1 {
237 vertical-align: top;
238 font-style: italic;
239 padding-right: 0.8em;
241 td.hlist2 {
242 vertical-align: top;
245 @media print {
246 div#footer-badges { display: none; }
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;
258 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
259 margin-top: 0;
260 margin-bottom: 0;
262 div.toclevel2 {
263 margin-left: 2em;
264 font-size: 0.9em;
266 div.toclevel3 {
267 margin-left: 4em;
268 font-size: 0.9em;
270 div.toclevel4 {
271 margin-left: 6em;
272 font-size: 0.9em;
274 include1::./stylesheets/xhtml11-manpage.css[]
275 /* Workarounds for IE6's broken and incomplete CSS2. */
277 div.sidebar-content {
278 background: #ffffee;
279 border: 1px solid silver;
280 padding: 0.5em;
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;
289 div.listingblock div.content {
290 border: 1px solid silver;
291 background: #f4f4f4;
292 padding: 0.5em;
295 div.quoteblock-content {
296 padding-left: 2.0em;
299 div.exampleblock-content {
300 border-left: 2px solid silver;
301 padding-left: 0.5em;
304 /* IE6 sets dynamically generated links as visited. */
305 div#toc a:visited { color: blue; }
306 </style>
307 <title>git-clone(1)</title>
308 </head>
309 <body>
310 <div id="header">
311 <h1>
312 git-clone(1) Manual Page
313 </h1>
314 <h2>NAME</h2>
315 <div class="sectionbody">
316 <p>git-clone -
317 Clone a repository into a new directory
318 </p>
319 </div>
320 </div>
321 <h2>SYNOPSIS</h2>
322 <div class="sectionbody">
323 <div class="verseblock">
324 <div class="content"><em>git clone</em> [--template=&lt;template_directory&gt;]
325 [-l] [-s] [--no-hardlinks] [-q] [-n] [--bare] [--mirror]
326 [-o &lt;name&gt;] [-b &lt;name&gt;] [-u &lt;upload-pack&gt;] [--reference &lt;repository&gt;]
327 [--depth &lt;depth&gt;] [--recursive] [--] &lt;repository&gt; [&lt;directory&gt;]</div></div>
328 </div>
329 <h2 id="_description">DESCRIPTION</h2>
330 <div class="sectionbody">
331 <div class="para"><p>Clones a repository into a newly created directory, creates
332 remote-tracking branches for each branch in the cloned repository
333 (visible using <tt>git branch -r</tt>), and creates and checks out an
334 initial branch that is forked from the cloned repository's
335 currently active branch.</p></div>
336 <div class="para"><p>After the clone, a plain <tt>git fetch</tt> without arguments will update
337 all the remote-tracking branches, and a <tt>git pull</tt> without
338 arguments will in addition merge the remote master branch into the
339 current master branch, if any.</p></div>
340 <div class="para"><p>This default configuration is achieved by creating references to
341 the remote branch heads under <tt>$GIT_DIR/refs/remotes/origin</tt> and
342 by initializing <tt>remote.origin.url</tt> and <tt>remote.origin.fetch</tt>
343 configuration variables.</p></div>
344 </div>
345 <h2 id="_options">OPTIONS</h2>
346 <div class="sectionbody">
347 <div class="vlist"><dl>
348 <dt>
349 --local
350 </dt>
351 <dt>
353 </dt>
354 <dd>
356 When the repository to clone from is on a local machine,
357 this flag bypasses the normal "git aware" transport
358 mechanism and clones the repository by making a copy of
359 HEAD and everything under objects and refs directories.
360 The files under <tt>.git/objects/</tt> directory are hardlinked
361 to save space when possible. This is now the default when
362 the source repository is specified with <tt>/path/to/repo</tt>
363 syntax, so it essentially is a no-op option. To force
364 copying instead of hardlinking (which may be desirable
365 if you are trying to make a back-up of your repository),
366 but still avoid the usual "git aware" transport
367 mechanism, <tt>--no-hardlinks</tt> can be used.
368 </p>
369 </dd>
370 <dt>
371 --no-hardlinks
372 </dt>
373 <dd>
375 Optimize the cloning process from a repository on a
376 local filesystem by copying files under <tt>.git/objects</tt>
377 directory.
378 </p>
379 </dd>
380 <dt>
381 --shared
382 </dt>
383 <dt>
385 </dt>
386 <dd>
388 When the repository to clone is on the local machine,
389 instead of using hard links, automatically setup
390 <tt>.git/objects/info/alternates</tt> to share the objects
391 with the source repository. The resulting repository
392 starts out without any object of its own.
393 </p>
394 <div class="para"><p><strong>NOTE</strong>: this is a possibly dangerous operation; do <strong>not</strong> use
395 it unless you understand what it does. If you clone your
396 repository using this option and then delete branches (or use any
397 other git command that makes any existing commit unreferenced) in the
398 source repository, some objects may become unreferenced (or dangling).
399 These objects may be removed by normal git operations (such as <tt>git commit</tt>)
400 which automatically call <tt>git gc --auto</tt>. (See <a href="git-gc.html">git-gc(1)</a>.)
401 If these objects are removed and were referenced by the cloned repository,
402 then the cloned repository will become corrupt.</p></div>
403 <div class="para"><p>Note that running <tt>git repack</tt> without the <tt>-l</tt> option in a repository
404 cloned with <tt>-s</tt> will copy objects from the source repository into a pack
405 in the cloned repository, removing the disk space savings of <tt>clone -s</tt>.
406 It is safe, however, to run <tt>git gc</tt>, which uses the <tt>-l</tt> option by
407 default.</p></div>
408 <div class="para"><p>If you want to break the dependency of a repository cloned with <tt>-s</tt> on
409 its source repository, you can simply run <tt>git repack -a</tt> to copy all
410 objects from the source repository into a pack in the cloned repository.</p></div>
411 </dd>
412 <dt>
413 --reference &lt;repository&gt;
414 </dt>
415 <dd>
417 If the reference repository is on the local machine,
418 automatically setup <tt>.git/objects/info/alternates</tt> to
419 obtain objects from the reference repository. Using
420 an already existing repository as an alternate will
421 require fewer objects to be copied from the repository
422 being cloned, reducing network and local storage costs.
423 </p>
424 <div class="para"><p><strong>NOTE</strong>: see the NOTE for the <tt>--shared</tt> option.</p></div>
425 </dd>
426 <dt>
427 --quiet
428 </dt>
429 <dt>
431 </dt>
432 <dd>
434 Operate quietly. This flag is also passed to the `rsync'
435 command when given.
436 </p>
437 </dd>
438 <dt>
439 --verbose
440 </dt>
441 <dt>
443 </dt>
444 <dd>
446 Display the progress bar, even in case the standard output is not
447 a terminal.
448 </p>
449 </dd>
450 <dt>
451 --no-checkout
452 </dt>
453 <dt>
455 </dt>
456 <dd>
458 No checkout of HEAD is performed after the clone is complete.
459 </p>
460 </dd>
461 <dt>
462 --bare
463 </dt>
464 <dd>
466 Make a <em>bare</em> GIT repository. That is, instead of
467 creating <tt>&lt;directory&gt;</tt> and placing the administrative
468 files in <tt>&lt;directory&gt;/.git</tt>, make the <tt>&lt;directory&gt;</tt>
469 itself the <tt>$GIT_DIR</tt>. This obviously implies the <tt>-n</tt>
470 because there is nowhere to check out the working tree.
471 Also the branch heads at the remote are copied directly
472 to corresponding local branch heads, without mapping
473 them to <tt>refs/remotes/origin/</tt>. When this option is
474 used, neither remote-tracking branches nor the related
475 configuration variables are created.
476 </p>
477 </dd>
478 <dt>
479 --mirror
480 </dt>
481 <dd>
483 Set up a mirror of the remote repository. This implies <tt>--bare</tt>.
484 </p>
485 </dd>
486 <dt>
487 --origin &lt;name&gt;
488 </dt>
489 <dt>
490 -o &lt;name&gt;
491 </dt>
492 <dd>
494 Instead of using the remote name <tt>origin</tt> to keep track
495 of the upstream repository, use <tt>&lt;name&gt;</tt>.
496 </p>
497 </dd>
498 <dt>
499 --branch &lt;name&gt;
500 </dt>
501 <dt>
502 -b &lt;name&gt;
503 </dt>
504 <dd>
506 Instead of pointing the newly created HEAD to the branch pointed
507 to by the cloned repository's HEAD, point to <tt>&lt;name&gt;</tt> branch
508 instead. In a non-bare repository, this is the branch that will
509 be checked out.
510 </p>
511 </dd>
512 <dt>
513 --upload-pack &lt;upload-pack&gt;
514 </dt>
515 <dt>
516 -u &lt;upload-pack&gt;
517 </dt>
518 <dd>
520 When given, and the repository to clone from is accessed
521 via ssh, this specifies a non-default path for the command
522 run on the other end.
523 </p>
524 </dd>
525 <dt>
526 --template=&lt;template_directory&gt;
527 </dt>
528 <dd>
530 Specify the directory from which templates will be used;
531 if unset the templates are taken from the installation
532 defined default, typically <tt>/usr/share/git-core/templates</tt>.
533 </p>
534 </dd>
535 <dt>
536 --depth &lt;depth&gt;
537 </dt>
538 <dd>
540 Create a <em>shallow</em> clone with a history truncated to the
541 specified number of revisions. A shallow repository has a
542 number of limitations (you cannot clone or fetch from
543 it, nor push from nor into it), but is adequate if you
544 are only interested in the recent history of a large project
545 with a long history, and would want to send in fixes
546 as patches.
547 </p>
548 </dd>
549 <dt>
550 --recursive
551 </dt>
552 <dd>
554 After the clone is created, initialize all submodules within,
555 using their default settings. This is equivalent to running
556 <tt>git submodule update --init --recursive</tt> immediately after
557 the clone is finished. This option is ignored if the cloned
558 repository does not have a worktree/checkout (i.e. if any of
559 <tt>--no-checkout</tt>/<tt>-n</tt>, <tt>--bare</tt>, or <tt>--mirror</tt> is given)
560 </p>
561 </dd>
562 <dt>
563 &lt;repository&gt;
564 </dt>
565 <dd>
567 The (possibly remote) repository to clone from. See the
568 <a href="#URLS">URLS</a> section below for more information on specifying
569 repositories.
570 </p>
571 </dd>
572 <dt>
573 &lt;directory&gt;
574 </dt>
575 <dd>
577 The name of a new directory to clone into. The "humanish"
578 part of the source repository is used if no directory is
579 explicitly given (<tt>repo</tt> for <tt>/path/to/repo.git</tt> and <tt>foo</tt>
580 for <tt>host.xz:foo/.git</tt>). Cloning into an existing directory
581 is only allowed if the directory is empty.
582 </p>
583 </dd>
584 </dl></div>
585 </div>
586 <h2 id="_git_urls_a_id_urls_a">GIT URLS<a id="URLS"></a></h2>
587 <div class="sectionbody">
588 <div class="para"><p>One of the following notations can be used
589 to name the remote repository:</p></div>
590 <div class="exampleblock">
591 <div class="exampleblock-content">
592 <div class="ilist"><ul>
593 <li>
595 rsync://host.xz/path/to/repo.git/
596 </p>
597 </li>
598 <li>
600 http://host.xz&#91;:port&#93;/path/to/repo.git/
601 </p>
602 </li>
603 <li>
605 https://host.xz&#91;:port&#93;/path/to/repo.git/
606 </p>
607 </li>
608 <li>
610 git://host.xz&#91;:port&#93;/path/to/repo.git/
611 </p>
612 </li>
613 <li>
615 git://host.xz&#91;:port&#93;/~user/path/to/repo.git/
616 </p>
617 </li>
618 <li>
620 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/path/to/repo.git/
621 </p>
622 </li>
623 <li>
625 ssh://&#91;user@&#93;host.xz/path/to/repo.git/
626 </p>
627 </li>
628 <li>
630 ssh://&#91;user@&#93;host.xz/~user/path/to/repo.git/
631 </p>
632 </li>
633 <li>
635 ssh://&#91;user@&#93;host.xz/~/path/to/repo.git
636 </p>
637 </li>
638 </ul></div>
639 </div></div>
640 <div class="para"><p>SSH is the default transport protocol over the network. You can
641 optionally specify which user to log-in as, and an alternate,
642 scp-like syntax is also supported. Both syntaxes support
643 username expansion, as does the native git protocol, but
644 only the former supports port specification. The following
645 three are identical to the last three above, respectively:</p></div>
646 <div class="exampleblock">
647 <div class="exampleblock-content">
648 <div class="ilist"><ul>
649 <li>
651 &#91;user@&#93;host.xz:/path/to/repo.git/
652 </p>
653 </li>
654 <li>
656 &#91;user@&#93;host.xz:~user/path/to/repo.git/
657 </p>
658 </li>
659 <li>
661 &#91;user@&#93;host.xz:path/to/repo.git
662 </p>
663 </li>
664 </ul></div>
665 </div></div>
666 <div class="para"><p>To sync with a local directory, you can use:</p></div>
667 <div class="exampleblock">
668 <div class="exampleblock-content">
669 <div class="ilist"><ul>
670 <li>
672 /path/to/repo.git/
673 </p>
674 </li>
675 <li>
677 file:///path/to/repo.git/
678 </p>
679 </li>
680 </ul></div>
681 </div></div>
682 <div class="para"><p>They are equivalent, except the former implies --local option.</p></div>
683 <div class="para"><p>If there are a large number of similarly-named remote repositories and
684 you want to use a different format for them (such that the URLs you
685 use will be rewritten into URLs that work), you can create a
686 configuration section of the form:</p></div>
687 <div class="listingblock">
688 <div class="content">
689 <pre><tt> [url "&lt;actual url base&gt;"]
690 insteadOf = &lt;other url base&gt;</tt></pre>
691 </div></div>
692 <div class="para"><p>For example, with this:</p></div>
693 <div class="listingblock">
694 <div class="content">
695 <pre><tt> [url "git://git.host.xz/"]
696 insteadOf = host.xz:/path/to/
697 insteadOf = work:</tt></pre>
698 </div></div>
699 <div class="para"><p>a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
700 rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".</p></div>
701 <div class="para"><p>If you want to rewrite URLs for push only, you can create a
702 configuration section of the form:</p></div>
703 <div class="listingblock">
704 <div class="content">
705 <pre><tt> [url "&lt;actual url base&gt;"]
706 pushInsteadOf = &lt;other url base&gt;</tt></pre>
707 </div></div>
708 <div class="para"><p>For example, with this:</p></div>
709 <div class="listingblock">
710 <div class="content">
711 <pre><tt> [url "ssh://example.org/"]
712 pushInsteadOf = git://example.org/</tt></pre>
713 </div></div>
714 <div class="para"><p>a URL like "git://example.org/path/to/repo.git" will be rewritten to
715 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
716 use the original URL.</p></div>
717 </div>
718 <h2 id="_examples">Examples</h2>
719 <div class="sectionbody">
720 <div class="vlist"><dl>
721 <dt>
722 Clone from upstream
723 </dt>
724 <dd>
725 <div class="listingblock">
726 <div class="content">
727 <pre><tt>$ git clone git://git.kernel.org/pub/scm/.../linux-2.6 my2.6
728 $ cd my2.6
729 $ make</tt></pre>
730 </div></div>
731 </dd>
732 <dt>
733 Make a local clone that borrows from the current directory, without checking things out
734 </dt>
735 <dd>
736 <div class="listingblock">
737 <div class="content">
738 <pre><tt>$ git clone -l -s -n . ../copy
739 $ cd ../copy
740 $ git show-branch</tt></pre>
741 </div></div>
742 </dd>
743 <dt>
744 Clone from upstream while borrowing from an existing local directory
745 </dt>
746 <dd>
747 <div class="listingblock">
748 <div class="content">
749 <pre><tt>$ git clone --reference my2.6 \
750 git://git.kernel.org/pub/scm/.../linux-2.7 \
751 my2.7
752 $ cd my2.7</tt></pre>
753 </div></div>
754 </dd>
755 <dt>
756 Create a bare repository to publish your changes to the public
757 </dt>
758 <dd>
759 <div class="listingblock">
760 <div class="content">
761 <pre><tt>$ git clone --bare -l /home/proj/.git /pub/scm/proj.git</tt></pre>
762 </div></div>
763 </dd>
764 <dt>
765 Create a repository on the kernel.org machine that borrows from Linus
766 </dt>
767 <dd>
768 <div class="listingblock">
769 <div class="content">
770 <pre><tt>$ git clone --bare -l -s /pub/scm/.../torvalds/linux-2.6.git \
771 /pub/scm/.../me/subsys-2.6.git</tt></pre>
772 </div></div>
773 </dd>
774 </dl></div>
775 </div>
776 <h2 id="_author">Author</h2>
777 <div class="sectionbody">
778 <div class="para"><p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt;</p></div>
779 </div>
780 <h2 id="_documentation">Documentation</h2>
781 <div class="sectionbody">
782 <div class="para"><p>Documentation by Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p></div>
783 </div>
784 <h2 id="_git">GIT</h2>
785 <div class="sectionbody">
786 <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
787 </div>
788 <div id="footer">
789 <div id="footer-text">
790 Last updated 2009-12-03 09:12:29 UTC
791 </div>
792 </div>
793 </body>
794 </html>