blob: 121ee7d7f1850a25c28140178936c69086660943 [file] [log] [blame]
Junio C Hamano1a4e8412005-12-27 08:17:231<!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" />
Junio C Hamano40f2f8d2006-02-07 08:04:396<meta name="generator" content="AsciiDoc 7.0.2" />
Junio C Hamano1a4e8412005-12-27 08:17:237<style type="text/css">
8/* Debug borders */
9p, li, dt, dd, div, pre, h1, h2, h3, h4, h5, h6 {
10/*
11 border: 1px solid red;
12*/
13}
14
15body {
16 margin: 1em 5% 1em 5%;
17}
18
19a { color: blue; }
20a:visited { color: fuchsia; }
21
22em {
23 font-style: italic;
24}
25
26strong {
27 font-weight: bold;
28}
29
30tt {
31 color: navy;
32}
33
34h1, h2, h3, h4, h5, h6 {
35 color: #527bbd;
36 font-family: sans-serif;
37 margin-top: 1.2em;
38 margin-bottom: 0.5em;
39 line-height: 1.3;
40}
41
42h1 {
43 border-bottom: 2px solid silver;
44}
45h2 {
46 border-bottom: 2px solid silver;
47 padding-top: 0.5em;
48}
49
50div.sectionbody {
51 font-family: serif;
52 margin-left: 0;
53}
54
55hr {
56 border: 1px solid silver;
57}
58
59p {
60 margin-top: 0.5em;
61 margin-bottom: 0.5em;
62}
63
64pre {
65 padding: 0;
66 margin: 0;
67}
68
69span#author {
70 color: #527bbd;
71 font-family: sans-serif;
72 font-weight: bold;
73 font-size: 1.2em;
74}
75span#email {
76}
77span#revision {
78 font-family: sans-serif;
79}
80
81div#footer {
82 font-family: sans-serif;
83 font-size: small;
84 border-top: 2px solid silver;
85 padding-top: 0.5em;
86 margin-top: 4.0em;
87}
88div#footer-text {
89 float: left;
90 padding-bottom: 0.5em;
91}
92div#footer-badges {
93 float: right;
94 padding-bottom: 0.5em;
95}
96
97div#preamble,
98div.tableblock, div.imageblock, div.exampleblock, div.verseblock,
99div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
100div.admonitionblock {
101 margin-right: 10%;
102 margin-top: 1.5em;
103 margin-bottom: 1.5em;
104}
105div.admonitionblock {
106 margin-top: 2.5em;
107 margin-bottom: 2.5em;
108}
109
110div.content { /* Block element content. */
111 padding: 0;
112}
113
114/* Block element titles. */
115div.title, caption.title {
116 font-family: sans-serif;
117 font-weight: bold;
118 text-align: left;
119 margin-top: 1.0em;
120 margin-bottom: 0.5em;
121}
122div.title + * {
123 margin-top: 0;
124}
125
126td div.title:first-child {
127 margin-top: 0.0em;
128}
129div.content div.title:first-child {
130 margin-top: 0.0em;
131}
132div.content + div.title {
133 margin-top: 0.0em;
134}
135
136div.sidebarblock > div.content {
137 background: #ffffee;
138 border: 1px solid silver;
139 padding: 0.5em;
140}
141
142div.listingblock > div.content {
143 border: 1px solid silver;
144 background: #f4f4f4;
145 padding: 0.5em;
146}
147
148div.quoteblock > div.content {
149 padding-left: 2.0em;
150}
151div.quoteblock .attribution {
152 text-align: right;
153}
154
155div.admonitionblock .icon {
156 vertical-align: top;
157 font-size: 1.1em;
158 font-weight: bold;
159 text-decoration: underline;
160 color: #527bbd;
161 padding-right: 0.5em;
162}
163div.admonitionblock td.content {
164 padding-left: 0.5em;
165 border-left: 2px solid silver;
166}
167
168div.exampleblock > div.content {
169 border-left: 2px solid silver;
170 padding: 0.5em;
171}
172
173div.verseblock div.content {
174 white-space: pre;
175}
176
177div.imageblock div.content { padding-left: 0; }
178div.imageblock img { border: 1px solid silver; }
179span.image img { border-style: none; }
180
181dl {
182 margin-top: 0.8em;
183 margin-bottom: 0.8em;
184}
185dt {
186 margin-top: 0.5em;
187 margin-bottom: 0;
188 font-style: italic;
189}
190dd > *:first-child {
191 margin-top: 0;
192}
193
194ul, ol {
195 list-style-position: outside;
196}
197ol.olist2 {
198 list-style-type: lower-alpha;
199}
200
201div.tableblock > table {
202 border-color: #527bbd;
203 border-width: 3px;
204}
205thead {
206 font-family: sans-serif;
207 font-weight: bold;
208}
209tfoot {
210 font-weight: bold;
211}
212
213div.hlist {
214 margin-top: 0.8em;
215 margin-bottom: 0.8em;
216}
217td.hlist1 {
218 vertical-align: top;
219 font-style: italic;
220 padding-right: 0.8em;
221}
222td.hlist2 {
223 vertical-align: top;
224}
225
226@media print {
227 div#footer-badges { display: none; }
228}
229include::./stylesheets/xhtml11-manpage.css[]
230/* Workarounds for IE6's broken and incomplete CSS2. */
231
232div.sidebar-content {
233 background: #ffffee;
234 border: 1px solid silver;
235 padding: 0.5em;
236}
237div.sidebar-title, div.image-title {
238 font-family: sans-serif;
239 font-weight: bold;
240 margin-top: 0.0em;
241 margin-bottom: 0.5em;
242}
243
244div.listingblock div.content {
245 border: 1px solid silver;
246 background: #f4f4f4;
247 padding: 0.5em;
248}
249
250div.quoteblock-content {
251 padding-left: 2.0em;
252}
253
254div.exampleblock-content {
255 border-left: 2px solid silver;
256 padding-left: 0.5em;
257}
258</style>
259<title>git-fetch(1)</title>
260</head>
261<body>
262<div id="header">
263<h1>
264git-fetch(1) Manual Page
265</h1>
266<h2>NAME</h2>
267<div class="sectionbody">
268<p>git-fetch -
269 Download objects and a head from another repository.
270</p>
271</div>
272</div>
273<h2>SYNOPSIS</h2>
274<div class="sectionbody">
275<p><em>git-fetch</em> &lt;options&gt; &lt;repository&gt; &lt;refspec&gt;&#8230;</p>
276</div>
277<h2>DESCRIPTION</h2>
278<div class="sectionbody">
279<p>Fetches named heads or tags from another repository, along with
280the objects necessary to complete them.</p>
281<p>The ref names and their object names of fetched refs are stored
282in <tt>.git/FETCH_HEAD</tt>. This information is left for a later merge
283operation done by "git merge".</p>
284</div>
285<h2>OPTIONS</h2>
286<div class="sectionbody">
287<dl>
288<dt>
289-a, --append
290</dt>
291<dd>
292<p>
293 Append ref names and object names of fetched refs to the
294 existing contents of <tt>.git/FETCH_HEAD</tt>. Without this
295 option old data in <tt>.git/FETCH_HEAD</tt> will be overwritten.
296</p>
297</dd>
298<dt>
Junio C Hamanoe663a7a2006-01-25 12:37:28299--upload-pack &lt;upload-pack&gt;
300</dt>
Junio C Hamanoe663a7a2006-01-25 12:37:28301<dd>
302<p>
303 When given, and the repository to fetch from is handled
304 by <em>git-fetch-pack</em>, <em>--exec=&lt;upload-pack&gt;</em> is passed to
305 the command to specify non-default path for the command
306 run on the other end.
307</p>
308</dd>
309<dt>
Junio C Hamano1a4e8412005-12-27 08:17:23310-f, --force
311</dt>
312<dd>
313<p>
314 When <tt>git-fetch</tt> is used with <tt>&lt;rbranch&gt;:&lt;lbranch&gt;</tt>
315 refspec, it refuses to update the local branch
316 <tt>&lt;lbranch&gt;</tt> unless the remote branch <tt>&lt;rbranch&gt;</tt> it
317 fetches is a descendant of <tt>&lt;lbranch&gt;</tt>. This option
318 overrides that check.
319</p>
320</dd>
321<dt>
Junio C Hamano4d04a402006-01-09 00:53:28322--no-tags
323</dt>
324<dd>
325<p>
326 By default, <tt>git-fetch</tt> fetches tags that point at
327 objects that are downloaded from the remote repository
328 and stores them locally. This option disables this
329 automatic tag following.
330</p>
331</dd>
332<dt>
Junio C Hamano1a4e8412005-12-27 08:17:23333-t, --tags
334</dt>
335<dd>
336<p>
Junio C Hamano4d04a402006-01-09 00:53:28337 Most of the tags are fetched automatically as branch
338 heads are downloaded, but tags that do not point at
339 objects reachable from the branch heads that are being
340 tracked will not be fetched by this mechanism. This
341 flag lets all tags and their associated objects be
342 downloaded.
Junio C Hamano1a4e8412005-12-27 08:17:23343</p>
344</dd>
345<dt>
Junio C Hamanob6bdc742006-01-11 11:35:32346-k, --keep
347</dt>
348<dd>
349<p>
350 Keep downloaded pack.
351</p>
352</dd>
353<dt>
Junio C Hamano1a4e8412005-12-27 08:17:23354-u, --update-head-ok
355</dt>
356<dd>
357<p>
358 By default <tt>git-fetch</tt> refuses to update the head which
359 corresponds to the current branch. This flag disables the
360 check. Note that fetching into the current branch will not
361 update the index and working directory, so use it with care.
362</p>
363</dd>
364<dt>
365&lt;repository&gt;
366</dt>
367<dd>
368<p>
369 The "remote" repository that is the source of a fetch
Junio C Hamano40f2f8d2006-02-07 08:04:39370 or pull operation. See the section <a href="#URLS">GIT URLS</a> below.
Junio C Hamano1a4e8412005-12-27 08:17:23371</p>
Junio C Hamano40f2f8d2006-02-07 08:04:39372</dd>
373<dt>
374&lt;refspec&gt;
375</dt>
376<dd>
377<p>
378 The canonical format of a &lt;refspec&gt; parameter is
379 <tt>+?&lt;src&gt;:&lt;dst&gt;</tt>; that is, an optional plus <tt>+</tt>, followed
380 by the source ref, followed by a colon <tt>:</tt>, followed by
381 the destination ref.
382</p>
383<p>The remote ref that matches &lt;src&gt;
384is fetched, and if &lt;dst&gt; is not empty string, the local
385ref that matches it is fast forwarded using &lt;src&gt;.
386Again, if the optional plus <tt>+</tt> is used, the local ref
387is updated even if it does not result in a fast forward
388update.</p>
389<div class="admonitionblock">
390<table><tr>
391<td class="icon">
392<div class="title">Note</div>
393</td>
394<td class="content">If the remote branch from which you want to pull is
395modified in non-linear ways such as being rewound and
396rebased frequently, then a pull will attempt a merge with
397an older version of itself, likely conflict, and fail.
398It is under these conditions that you would want to use
399the <tt>+</tt> sign to indicate non-fast-forward updates will
400be needed. There is currently no easy way to determine
401or declare that a branch will be made available in a
402repository with this behavior; the pulling user simply
403must know this is the expected usage pattern for a branch.</td>
404</tr></table>
405</div>
406<div class="admonitionblock">
407<table><tr>
408<td class="icon">
409<div class="title">Note</div>
410</td>
411<td class="content">You never do your own development on branches that appear
412on the right hand side of a &lt;refspec&gt; colon on <tt>Pull:</tt> lines;
413they are to be updated by <tt>git-fetch</tt>. If you intend to do
414development derived from a remote branch <tt>B</tt>, have a <tt>Pull:</tt>
415line to track it (i.e. <tt>Pull: B:remote-B</tt>), and have a separate
416branch <tt>my-B</tt> to do your development on top of it. The latter
417is created by <tt>git branch my-B remote-B</tt> (or its equivalent <tt>git
418checkout -b my-B remote-B</tt>). Run <tt>git fetch</tt> to keep track of
419the progress of the remote side, and when you see something new
420on the remote branch, merge it into your development branch with
421<tt>git pull . remote-B</tt>, while you are on <tt>my-B</tt> branch.
422The common <tt>Pull: master:origin</tt> mapping of a remote <tt>master</tt>
423branch to a local <tt>origin</tt> branch, which is then merged to a
424local development branch, again typically named <tt>master</tt>, is made
425when you run <tt>git clone</tt> for you to follow this pattern.</td>
426</tr></table>
427</div>
428<div class="admonitionblock">
429<table><tr>
430<td class="icon">
431<div class="title">Note</div>
432</td>
433<td class="content">There is a difference between listing multiple &lt;refspec&gt;
434directly on <tt>git-pull</tt> command line and having multiple
435<tt>Pull:</tt> &lt;refspec&gt; lines for a &lt;repository&gt; and running
436<tt>git-pull</tt> command without any explicit &lt;refspec&gt; parameters.
437&lt;refspec&gt; listed explicitly on the command line are always
438merged into the current branch after fetching. In other words,
439if you list more than one remote refs, you would be making
440an Octopus. While <tt>git-pull</tt> run without any explicit &lt;refspec&gt;
441parameter takes default &lt;refspec&gt;s from <tt>Pull:</tt> lines, it
442merges only the first &lt;refspec&gt; found into the current branch,
443after fetching all the remote refs. This is because making an
444Octopus from remote refs is rarely done, while keeping track
445of multiple remote heads in one-go by fetching more than one
446is often useful.</td>
447</tr></table>
448</div>
449<p>Some short-cut notations are also supported.</p>
450<ul>
451<li>
452<p>
453<tt>tag &lt;tag&gt;</tt> means the same as <tt>refs/tags/&lt;tag&gt;:refs/tags/&lt;tag&gt;</tt>;
454 it requests fetching everything up to the given tag.
455</p>
456</li>
457<li>
458<p>
459A parameter &lt;ref&gt; without a colon is equivalent to
460 &lt;ref&gt;: when pulling/fetching, so it merges &lt;ref&gt; into the current
461 branch without storing the remote branch anywhere locally
462</p>
463</li>
464</ul>
465</dd>
466</dl>
467</div>
468<h2>GIT URLS<a id="URLS"></a></h2>
469<div class="sectionbody">
470<p>One of the following notations can be used
471to name the remote repository:</p>
Junio C Hamano1a4e8412005-12-27 08:17:23472<div class="exampleblock">
473<div class="exampleblock-content">
474<ul>
475<li>
476<p>
477rsync://host.xz/path/to/repo.git/
478</p>
479</li>
480<li>
481<p>
482http://host.xz/path/to/repo.git/
483</p>
484</li>
485<li>
486<p>
487https://host.xz/path/to/repo.git/
488</p>
489</li>
490<li>
491<p>
492git://host.xz/path/to/repo.git/
493</p>
494</li>
495<li>
496<p>
497git://host.xz/~user/path/to/repo.git/
498</p>
499</li>
500<li>
501<p>
502ssh://host.xz/path/to/repo.git/
503</p>
504</li>
505<li>
506<p>
507ssh://host.xz/~user/path/to/repo.git/
508</p>
509</li>
510<li>
511<p>
512ssh://host.xz/~/path/to/repo.git
513</p>
514</li>
515</ul>
516</div></div>
517<p>SSH Is the default transport protocol and also supports an
518scp-like syntax. Both syntaxes support username expansion,
519as does the native git protocol. The following three are
520identical to the last three above, respectively:</p>
521<div class="exampleblock">
522<div class="exampleblock-content">
523<ul>
524<li>
525<p>
526host.xz:/path/to/repo.git/
527</p>
528</li>
529<li>
530<p>
531host.xz:~user/path/to/repo.git/
532</p>
533</li>
534<li>
535<p>
536host.xz:path/to/repo.git
537</p>
538</li>
539</ul>
540</div></div>
541<p>To sync with a local directory, use:</p>
542<div class="exampleblock">
543<div class="exampleblock-content">
544<ul>
545<li>
546<p>
547/path/to/repo.git/
548</p>
549</li>
550</ul>
551</div></div>
Junio C Hamano40f2f8d2006-02-07 08:04:39552</div>
553<h2>REMOTES</h2>
554<div class="sectionbody">
Junio C Hamano1a4e8412005-12-27 08:17:23555<p>In addition to the above, as a short-hand, the name of a
556file in <tt>$GIT_DIR/remotes</tt> directory can be given; the
557named file should be in the following format:</p>
558<div class="literalblock">
559<div class="content">
560<pre><tt>URL: one of the above URL format
561Push: &lt;refspec&gt;
562Pull: &lt;refspec&gt;</tt></pre>
563</div></div>
Junio C Hamano40f2f8d2006-02-07 08:04:39564<p>Then such a short-hand is specified in place of
Junio C Hamano1a4e8412005-12-27 08:17:23565&lt;repository&gt; without &lt;refspec&gt; parameters on the command
566line, &lt;refspec&gt; specified on <tt>Push:</tt> lines or <tt>Pull:</tt>
567lines are used for <tt>git-push</tt> and <tt>git-fetch</tt>/<tt>git-pull</tt>,
568respectively. Multiple <tt>Push:</tt> and and <tt>Pull:</tt> lines may
569be specified for additional branch mappings.</p>
570<p>The name of a file in <tt>$GIT_DIR/branches</tt> directory can be
571specified as an older notation short-hand; the named
572file should contain a single line, a URL in one of the
573above formats, optionally followed by a hash <tt>#</tt> and the
574name of remote head (URL fragment notation).
575<tt>$GIT_DIR/branches/&lt;remote&gt;</tt> file that stores a &lt;url&gt;
576without the fragment is equivalent to have this in the
577corresponding file in the <tt>$GIT_DIR/remotes/</tt> directory.</p>
578<div class="literalblock">
579<div class="content">
580<pre><tt>URL: &lt;url&gt;
581Pull: refs/heads/master:&lt;remote&gt;</tt></pre>
582</div></div>
583<p>while having <tt>&lt;url&gt;#&lt;head&gt;</tt> is equivalent to</p>
584<div class="literalblock">
585<div class="content">
586<pre><tt>URL: &lt;url&gt;
587Pull: refs/heads/&lt;head&gt;:&lt;remote&gt;</tt></pre>
588</div></div>
Junio C Hamano1a4e8412005-12-27 08:17:23589</div>
590<h2>SEE ALSO</h2>
591<div class="sectionbody">
592<p><a href="git-pull.html">git-pull(1)</a></p>
593</div>
594<h2>Author</h2>
595<div class="sectionbody">
596<p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt; and
597Junio C Hamano &lt;junkio@cox.net&gt;</p>
598</div>
599<h2>Documentation</h2>
600<div class="sectionbody">
601<p>Documentation by David Greaves, Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p>
602</div>
603<h2>GIT</h2>
604<div class="sectionbody">
605<p>Part of the <a href="git.html">git(7)</a> suite</p>
606</div>
607<div id="footer">
608<div id="footer-text">
Junio C Hamano40f2f8d2006-02-07 08:04:39609Last updated 07-Feb-2006 08:04:30 UTC
Junio C Hamano1a4e8412005-12-27 08:17:23610</div>
611</div>
612</body>
613</html>