git-pull.html

   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 {
  10 /*
  11   border: 1px solid red;
  12 */
  13 }
  14
  15 body {
  16   margin: 1em 5% 1em 5%;
  17 }
  18
  19 a {
  20   color: blue;
  21   text-decoration: underline;
  22 }
  23 a:visited {
  24   color: fuchsia;
  25 }
  26
  27 em {
  28   font-style: italic;
  29 }
  30
  31 strong {
  32   font-weight: bold;
  33 }
  34
  35 tt {
  36   color: navy;
  37 }
  38
  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;
  45 }
  46
  47 h1, h2, h3 {
  48   border-bottom: 2px solid silver;
  49 }
  50 h2 {
  51   padding-top: 0.5em;
  52 }
  53 h3 {
  54   float: left;
  55 }
  56 h3 + * {
  57   clear: left;
  58 }
  59
  60 div.sectionbody {
  61   font-family: serif;
  62   margin-left: 0;
  63 }
  64
  65 hr {
  66   border: 1px solid silver;
  67 }
  68
  69 p {
  70   margin-top: 0.5em;
  71   margin-bottom: 0.5em;
  72 }
  73
  74 pre {
  75   padding: 0;
  76   margin: 0;
  77 }
  78
  79 span#author {
  80   color: #527bbd;
  81   font-family: sans-serif;
  82   font-weight: bold;
  83   font-size: 1.1em;
  84 }
  85 span#email {
  86 }
  87 span#revision {
  88   font-family: sans-serif;
  89 }
  90
  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;
  97 }
  98 div#footer-text {
  99   float: left;
 100   padding-bottom: 0.5em;
 101 }
 102 div#footer-badges {
 103   float: right;
 104   padding-bottom: 0.5em;
 105 }
 106
 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;
 114 }
 115 div.admonitionblock {
 116   margin-top: 2.5em;
 117   margin-bottom: 2.5em;
 118 }
 119
 120 div.content { /* Block element content. */
 121   padding: 0;
 122 }
 123
 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;
 131 }
 132 div.title + * {
 133   margin-top: 0;
 134 }
 135
 136 td div.title:first-child {
 137   margin-top: 0.0em;
 138 }
 139 div.content div.title:first-child {
 140   margin-top: 0.0em;
 141 }
 142 div.content + div.title {
 143   margin-top: 0.0em;
 144 }
 145
 146 div.sidebarblock > div.content {
 147   background: #ffffee;
 148   border: 1px solid silver;
 149   padding: 0.5em;
 150 }
 151
 152 div.listingblock {
 153   margin-right: 0%;
 154 }
 155 div.listingblock > div.content {
 156   border: 1px solid silver;
 157   background: #f4f4f4;
 158   padding: 0.5em;
 159 }
 160
 161 div.quoteblock > div.content {
 162   padding-left: 2.0em;
 163 }
 164
 165 div.attribution {
 166   text-align: right;
 167 }
 168 div.verseblock + div.attribution {
 169   text-align: left;
 170 }
 171
 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;
 179 }
 180 div.admonitionblock td.content {
 181   padding-left: 0.5em;
 182   border-left: 2px solid silver;
 183 }
 184
 185 div.exampleblock > div.content {
 186   border-left: 2px solid silver;
 187   padding: 0.5em;
 188 }
 189
 190 div.verseblock div.content {
 191   white-space: pre;
 192 }
 193
 194 div.imageblock div.content { padding-left: 0; }
 195 div.imageblock img { border: 1px solid silver; }
 196 span.image img { border-style: none; }
 197
 198 dl {
 199   margin-top: 0.8em;
 200   margin-bottom: 0.8em;
 201 }
 202 dt {
 203   margin-top: 0.5em;
 204   margin-bottom: 0;
 205   font-style: italic;
 206 }
 207 dd > *:first-child {
 208   margin-top: 0;
 209 }
 210
 211 ul, ol {
 212     list-style-position: outside;
 213 }
 214 div.olist2 ol {
 215   list-style-type: lower-alpha;
 216 }
 217
 218 div.tableblock > table {
 219   border: 3px solid #527bbd;
 220 }
 221 thead {
 222   font-family: sans-serif;
 223   font-weight: bold;
 224 }
 225 tfoot {
 226   font-weight: bold;
 227 }
 228
 229 div.hlist {
 230   margin-top: 0.8em;
 231   margin-bottom: 0.8em;
 232 }
 233 div.hlist td {
 234   padding-bottom: 5px;
 235 }
 236 td.hlist1 {
 237   vertical-align: top;
 238   font-style: italic;
 239   padding-right: 0.8em;
 240 }
 241 td.hlist2 {
 242   vertical-align: top;
 243 }
 244
 245 @media print {
 246   div#footer-badges { display: none; }
 247 }
 248
 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;
 256 }
 257
 258 div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 259   margin-top: 0;
 260   margin-bottom: 0;
 261 }
 262 div.toclevel2 {
 263   margin-left: 2em;
 264   font-size: 0.9em;
 265 }
 266 div.toclevel3 {
 267   margin-left: 4em;
 268   font-size: 0.9em;
 269 }
 270 div.toclevel4 {
 271   margin-left: 6em;
 272   font-size: 0.9em;
 273 }
 274 include1::./stylesheets/xhtml11-manpage.css[]
 275 /* Workarounds for IE6's broken and incomplete CSS2. */
 276
 277 div.sidebar-content {
 278   background: #ffffee;
 279   border: 1px solid silver;
 280   padding: 0.5em;
 281 }
 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;
 287 }
 288
 289 div.listingblock div.content {
 290   border: 1px solid silver;
 291   background: #f4f4f4;
 292   padding: 0.5em;
 293 }
 294
 295 div.quoteblock-content {
 296   padding-left: 2.0em;
 297 }
 298
 299 div.exampleblock-content {
 300   border-left: 2px solid silver;
 301   padding-left: 0.5em;
 302 }
 303
 304 /* IE6 sets dynamically generated links as visited. */
 305 div#toc a:visited { color: blue; }
 306 </style>
 307 <title>git-pull(1)</title>
 308 </head>
 309 <body>
 310 <div id="header">
 311 <h1>
 312 git-pull(1) Manual Page
 313 </h1>
 314 <h2>NAME</h2>
 315 <div class="sectionbody">
 316 <p>git-pull -
 317    Fetch from and merge with another repository or a local branch
 318 </p>
 319 </div>
 320 </div>
 321 <h2>SYNOPSIS</h2>
 322 <div class="sectionbody">
 323 <div class="para"><p><em>git pull</em> &lt;options&gt; &lt;repository&gt; &lt;refspec&gt;&#8230;</p></div>
 324 </div>
 325 <h2 id="_description">DESCRIPTION</h2>
 326 <div class="sectionbody">
 327 <div class="para"><p>Runs <em>git fetch</em> with the given parameters, and calls <em>git merge</em>
 328 to merge the retrieved head(s) into the current branch.
 329 With <tt>--rebase</tt>, calls <em>git rebase</em> instead of <em>git merge</em>.</p></div>
 330 <div class="para"><p>Note that you can use <tt>.</tt> (current directory) as the
 331 &lt;repository&gt; to pull from the local repository &#8212; this is useful
 332 when merging local branches into the current branch.</p></div>
 333 <div class="para"><p>Also note that options meant for <em>git pull</em> itself and underlying
 334 <em>git merge</em> must be given before the options meant for <em>git fetch</em>.</p></div>
 335 <div class="para"><p><strong>Warning</strong>: Running <em>git pull</em> (actually, the underlying <em>git merge</em>)
 336 with uncommitted changes is discouraged: while possible, it leaves you
 337 in a state that is hard to back out of in the case of a conflict.</p></div>
 338 </div>
 339 <h2 id="_options">OPTIONS</h2>
 340 <div class="sectionbody">
 341 <div class="vlist"><dl>
 342 <dt>
 343 -q
 344 </dt>
 345 <dt>
 346 --quiet
 347 </dt>
 348 <dd>
 349 <p>
 350         This is passed to both underlying git-fetch to squelch reporting of
 351         during transfer, and underlying git-merge to squelch output during
 352         merging.
 353 </p>
 354 </dd>
 355 <dt>
 356 -v
 357 </dt>
 358 <dt>
 359 --verbose
 360 </dt>
 361 <dd>
 362 <p>
 363         Pass --verbose to git-fetch and git-merge.
 364 </p>
 365 </dd>
 366 </dl></div>
 367 <h3 id="_options_related_to_merging">Options related to merging</h3><div style="clear:left"></div>
 368 <div class="vlist"><dl>
 369 <dt>
 370 --commit
 371 </dt>
 372 <dt>
 373 --no-commit
 374 </dt>
 375 <dd>
 376 <p>
 377         Perform the merge and commit the result. This option can
 378         be used to override --no-commit.
 379 </p>
 380 <div class="para"><p>With --no-commit perform the merge but pretend the merge
 381 failed and do not autocommit, to give the user a chance to
 382 inspect and further tweak the merge result before committing.</p></div>
 383 </dd>
 384 <dt>
 385 --ff
 386 </dt>
 387 <dt>
 388 --no-ff
 389 </dt>
 390 <dd>
 391 <p>
 392         Do not generate a merge commit if the merge resolved as
 393         a fast-forward, only update the branch pointer. This is
 394         the default behavior of git-merge.
 395 </p>
 396 <div class="para"><p>With --no-ff Generate a merge commit even if the merge
 397 resolved as a fast-forward.</p></div>
 398 </dd>
 399 <dt>
 400 --log
 401 </dt>
 402 <dt>
 403 --no-log
 404 </dt>
 405 <dd>
 406 <p>
 407         In addition to branch names, populate the log message with
 408         one-line descriptions from the actual commits that are being
 409         merged.
 410 </p>
 411 <div class="para"><p>With --no-log do not list one-line descriptions from the
 412 actual commits being merged.</p></div>
 413 </dd>
 414 <dt>
 415 --stat
 416 </dt>
 417 <dt>
 418 -n
 419 </dt>
 420 <dt>
 421 --no-stat
 422 </dt>
 423 <dd>
 424 <p>
 425         Show a diffstat at the end of the merge. The diffstat is also
 426         controlled by the configuration option merge.stat.
 427 </p>
 428 <div class="para"><p>With -n or --no-stat do not show a diffstat at the end of the
 429 merge.</p></div>
 430 </dd>
 431 <dt>
 432 --squash
 433 </dt>
 434 <dt>
 435 --no-squash
 436 </dt>
 437 <dd>
 438 <p>
 439         Produce the working tree and index state as if a real
 440         merge happened (except for the merge information),
 441         but do not actually make a commit or
 442         move the <tt>HEAD</tt>, nor record <tt>$GIT_DIR/MERGE_HEAD</tt> to
 443         cause the next <tt>git commit</tt> command to create a merge
 444         commit.  This allows you to create a single commit on
 445         top of the current branch whose effect is the same as
 446         merging another branch (or more in case of an octopus).
 447 </p>
 448 <div class="para"><p>With --no-squash perform the merge and commit the result. This
 449 option can be used to override --squash.</p></div>
 450 </dd>
 451 <dt>
 452 --ff-only
 453 </dt>
 454 <dd>
 455 <p>
 456         Refuse to merge and exit with a non-zero status unless the
 457         current <tt>HEAD</tt> is already up-to-date or the merge can be
 458         resolved as a fast-forward.
 459 </p>
 460 </dd>
 461 <dt>
 462 -s &lt;strategy&gt;
 463 </dt>
 464 <dt>
 465 --strategy=&lt;strategy&gt;
 466 </dt>
 467 <dd>
 468 <p>
 469         Use the given merge strategy; can be supplied more than
 470         once to specify them in the order they should be tried.
 471         If there is no <tt>-s</tt> option, a built-in list of strategies
 472         is used instead (<em>git merge-recursive</em> when merging a single
 473         head, <em>git merge-octopus</em> otherwise).
 474 </p>
 475 </dd>
 476 <dt>
 477 -X &lt;option&gt;
 478 </dt>
 479 <dt>
 480 --strategy-option=&lt;option&gt;
 481 </dt>
 482 <dd>
 483 <p>
 484         Pass merge strategy specific option through to the merge
 485         strategy.
 486 </p>
 487 </dd>
 488 <dt>
 489 --summary
 490 </dt>
 491 <dt>
 492 --no-summary
 493 </dt>
 494 <dd>
 495 <p>
 496         Synonyms to --stat and --no-stat; these are deprecated and will be
 497         removed in the future.
 498 </p>
 499 </dd>
 500 <dt>
 501 -q
 502 </dt>
 503 <dt>
 504 --quiet
 505 </dt>
 506 <dd>
 507 <p>
 508         Operate quietly.
 509 </p>
 510 </dd>
 511 <dt>
 512 -v
 513 </dt>
 514 <dt>
 515 --verbose
 516 </dt>
 517 <dd>
 518 <p>
 519         Be verbose.
 520 </p>
 521 </dd>
 522 </dl></div>
 523 <div class="vlist"><dl>
 524 <dt>
 525 --rebase
 526 </dt>
 527 <dd>
 528 <p>
 529         Instead of a merge, perform a rebase after fetching.  If
 530         there is a remote ref for the upstream branch, and this branch
 531         was rebased since last fetched, the rebase uses that information
 532         to avoid rebasing non-local changes. To make this the default
 533         for branch <tt>&lt;name&gt;</tt>, set configuration <tt>branch.&lt;name&gt;.rebase</tt>
 534         to <tt>true</tt>.
 535 </p>
 536 <div class="admonitionblock">
 537 <table><tr>
 538 <td class="icon">
 539 <div class="title">Note</div>
 540 </td>
 541 <td class="content">This is a potentially _dangerous_ mode of operation.
 542 It rewrites history, which does not bode well when you
 543 published that history already.  Do <strong>not</strong> use this option
 544 unless you have read <a href="git-rebase.html">git-rebase(1)</a> carefully.</td>
 545 </tr></table>
 546 </div>
 547 </dd>
 548 <dt>
 549 --no-rebase
 550 </dt>
 551 <dd>
 552 <p>
 553         Override earlier --rebase.
 554 </p>
 555 </dd>
 556 </dl></div>
 557 <h3 id="_options_related_to_fetching">Options related to fetching</h3><div style="clear:left"></div>
 558 <div class="vlist"><dl>
 559 <dt>
 560 --all
 561 </dt>
 562 <dd>
 563 <p>
 564         Fetch all remotes.
 565 </p>
 566 </dd>
 567 <dt>
 568 -a
 569 </dt>
 570 <dt>
 571 --append
 572 </dt>
 573 <dd>
 574 <p>
 575         Append ref names and object names of fetched refs to the
 576         existing contents of <tt>.git/FETCH_HEAD</tt>.  Without this
 577         option old data in <tt>.git/FETCH_HEAD</tt> will be overwritten.
 578 </p>
 579 </dd>
 580 <dt>
 581 --depth=&lt;depth&gt;
 582 </dt>
 583 <dd>
 584 <p>
 585         Deepen the history of a <em>shallow</em> repository created by
 586         <tt>git clone</tt> with <tt>--depth=&lt;depth&gt;</tt> option (see <a href="git-clone.html">git-clone(1)</a>)
 587         by the specified number of commits.
 588 </p>
 589 </dd>
 590 <dt>
 591 -f
 592 </dt>
 593 <dt>
 594 --force
 595 </dt>
 596 <dd>
 597 <p>
 598         When <em>git fetch</em> is used with <tt>&lt;rbranch&gt;:&lt;lbranch&gt;</tt>
 599         refspec, it refuses to update the local branch
 600         <tt>&lt;lbranch&gt;</tt> unless the remote branch <tt>&lt;rbranch&gt;</tt> it
 601         fetches is a descendant of <tt>&lt;lbranch&gt;</tt>.  This option
 602         overrides that check.
 603 </p>
 604 </dd>
 605 <dt>
 606 -k
 607 </dt>
 608 <dt>
 609 --keep
 610 </dt>
 611 <dd>
 612 <p>
 613         Keep downloaded pack.
 614 </p>
 615 </dd>
 616 <dt>
 617 --no-tags
 618 </dt>
 619 <dd>
 620 <p>
 621         By default, tags that point at objects that are downloaded
 622         from the remote repository are fetched and stored locally.
 623         This option disables this automatic tag following.
 624 </p>
 625 </dd>
 626 <dt>
 627 -t
 628 </dt>
 629 <dt>
 630 --tags
 631 </dt>
 632 <dd>
 633 <p>
 634         Most of the tags are fetched automatically as branch
 635         heads are downloaded, but tags that do not point at
 636         objects reachable from the branch heads that are being
 637         tracked will not be fetched by this mechanism.  This
 638         flag lets all tags and their associated objects be
 639         downloaded.
 640 </p>
 641 </dd>
 642 <dt>
 643 -u
 644 </dt>
 645 <dt>
 646 --update-head-ok
 647 </dt>
 648 <dd>
 649 <p>
 650         By default <em>git fetch</em> refuses to update the head which
 651         corresponds to the current branch.  This flag disables the
 652         check.  This is purely for the internal use for <em>git pull</em>
 653         to communicate with <em>git fetch</em>, and unless you are
 654         implementing your own Porcelain you are not supposed to
 655         use it.
 656 </p>
 657 </dd>
 658 <dt>
 659 --upload-pack &lt;upload-pack&gt;
 660 </dt>
 661 <dd>
 662 <p>
 663         When given, and the repository to fetch from is handled
 664         by <em>git fetch-pack</em>, <em>--exec=&lt;upload-pack&gt;</em> is passed to
 665         the command to specify non-default path for the command
 666         run on the other end.
 667 </p>
 668 </dd>
 669 <dt>
 670 --progress
 671 </dt>
 672 <dd>
 673 <p>
 674         Progress status is reported on the standard error stream
 675         by default when it is attached to a terminal, unless -q
 676         is specified. This flag forces progress status even if the
 677         standard error stream is not directed to a terminal.
 678 </p>
 679 </dd>
 680 <dt>
 681 &lt;repository&gt;
 682 </dt>
 683 <dd>
 684 <p>
 685         The "remote" repository that is the source of a fetch
 686         or pull operation.  This parameter can be either a URL
 687         (see the section <a href="#URLS">GIT URLS</a> below) or the name
 688         of a remote (see the section <a href="#REMOTES">REMOTES</a> below).
 689 </p>
 690 </dd>
 691 <dt>
 692 &lt;refspec&gt;
 693 </dt>
 694 <dd>
 695 <p>
 696         The format of a &lt;refspec&gt; parameter is an optional plus
 697         <tt>&#43;</tt>, followed by the source ref &lt;src&gt;, followed
 698         by a colon <tt>:</tt>, followed by the destination ref &lt;dst&gt;.
 699 </p>
 700 <div class="para"><p>The remote ref that matches &lt;src&gt;
 701 is fetched, and if &lt;dst&gt; is not empty string, the local
 702 ref that matches it is fast-forwarded using &lt;src&gt;.
 703 If the optional plus <tt>+</tt> is used, the local ref
 704 is updated even if it does not result in a fast-forward
 705 update.</p></div>
 706 <div class="admonitionblock">
 707 <table><tr>
 708 <td class="icon">
 709 <div class="title">Note</div>
 710 </td>
 711 <td class="content">If the remote branch from which you want to pull is
 712 modified in non-linear ways such as being rewound and
 713 rebased frequently, then a pull will attempt a merge with
 714 an older version of itself, likely conflict, and fail.
 715 It is under these conditions that you would want to use
 716 the <tt>+</tt> sign to indicate non-fast-forward updates will
 717 be needed.  There is currently no easy way to determine
 718 or declare that a branch will be made available in a
 719 repository with this behavior; the pulling user simply
 720 must know this is the expected usage pattern for a branch.</td>
 721 </tr></table>
 722 </div>
 723 <div class="admonitionblock">
 724 <table><tr>
 725 <td class="icon">
 726 <div class="title">Note</div>
 727 </td>
 728 <td class="content">You never do your own development on branches that appear
 729 on the right hand side of a &lt;refspec&gt; colon on <tt>Pull:</tt> lines;
 730 they are to be updated by <em>git fetch</em>.  If you intend to do
 731 development derived from a remote branch <tt>B</tt>, have a <tt>Pull:</tt>
 732 line to track it (i.e. <tt>Pull: B:remote-B</tt>), and have a separate
 733 branch <tt>my-B</tt> to do your development on top of it.  The latter
 734 is created by <tt>git branch my-B remote-B</tt> (or its equivalent <tt>git
 735 checkout -b my-B remote-B</tt>).  Run <tt>git fetch</tt> to keep track of
 736 the progress of the remote side, and when you see something new
 737 on the remote branch, merge it into your development branch with
 738 <tt>git pull . remote-B</tt>, while you are on <tt>my-B</tt> branch.</td>
 739 </tr></table>
 740 </div>
 741 <div class="admonitionblock">
 742 <table><tr>
 743 <td class="icon">
 744 <div class="title">Note</div>
 745 </td>
 746 <td class="content">There is a difference between listing multiple &lt;refspec&gt;
 747 directly on <em>git pull</em> command line and having multiple
 748 <tt>Pull:</tt> &lt;refspec&gt; lines for a &lt;repository&gt; and running
 749 <em>git pull</em> command without any explicit &lt;refspec&gt; parameters.
 750 &lt;refspec&gt; listed explicitly on the command line are always
 751 merged into the current branch after fetching.  In other words,
 752 if you list more than one remote refs, you would be making
 753 an Octopus.  While <em>git pull</em> run without any explicit &lt;refspec&gt;
 754 parameter takes default &lt;refspec&gt;s from <tt>Pull:</tt> lines, it
 755 merges only the first &lt;refspec&gt; found into the current branch,
 756 after fetching all the remote refs.  This is because making an
 757 Octopus from remote refs is rarely done, while keeping track
 758 of multiple remote heads in one-go by fetching more than one
 759 is often useful.</td>
 760 </tr></table>
 761 </div>
 762 <div class="para"><p>Some short-cut notations are also supported.</p></div>
 763 <div class="ilist"><ul>
 764 <li>
 765 <p>
 766 <tt>tag &lt;tag&gt;</tt> means the same as <tt>refs/tags/&lt;tag&gt;:refs/tags/&lt;tag&gt;</tt>;
 767   it requests fetching everything up to the given tag.
 768 </p>
 769 </li>
 770 <li>
 771 <p>
 772 A parameter &lt;ref&gt; without a colon is equivalent to
 773   &lt;ref&gt;: when pulling/fetching, so it merges &lt;ref&gt; into the current
 774   branch without storing the remote branch anywhere locally
 775 </p>
 776 </li>
 777 </ul></div>
 778 </dd>
 779 </dl></div>
 780 </div>
 781 <h2 id="_git_urls_a_id_urls_a">GIT URLS<a id="URLS"></a></h2>
 782 <div class="sectionbody">
 783 <div class="para"><p>In general, URLs contain information about the transport protocol, the
 784 address of the remote server, and the path to the repository.
 785 Depending on the transport protocol, some of this information may be
 786 absent.</p></div>
 787 <div class="para"><p>Git natively supports ssh, git, http, https, ftp, ftps, and rsync
 788 protocols. The following syntaxes may be used with them:</p></div>
 789 <div class="ilist"><ul>
 790 <li>
 791 <p>
 792 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/path/to/repo.git/
 793 </p>
 794 </li>
 795 <li>
 796 <p>
 797 git://host.xz&#91;:port&#93;/path/to/repo.git/
 798 </p>
 799 </li>
 800 <li>
 801 <p>
 802 http&#91;s&#93;://host.xz&#91;:port&#93;/path/to/repo.git/
 803 </p>
 804 </li>
 805 <li>
 806 <p>
 807 ftp&#91;s&#93;://host.xz&#91;:port&#93;/path/to/repo.git/
 808 </p>
 809 </li>
 810 <li>
 811 <p>
 812 rsync://host.xz/path/to/repo.git/
 813 </p>
 814 </li>
 815 </ul></div>
 816 <div class="para"><p>An alternative scp-like syntax may also be used with the ssh protocol:</p></div>
 817 <div class="ilist"><ul>
 818 <li>
 819 <p>
 820 &#91;user@&#93;host.xz:path/to/repo.git/
 821 </p>
 822 </li>
 823 </ul></div>
 824 <div class="para"><p>The ssh and git protocols additionally support ~username expansion:</p></div>
 825 <div class="ilist"><ul>
 826 <li>
 827 <p>
 828 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/~&#91;user&#93;/path/to/repo.git/
 829 </p>
 830 </li>
 831 <li>
 832 <p>
 833 git://host.xz&#91;:port&#93;/~&#91;user&#93;/path/to/repo.git/
 834 </p>
 835 </li>
 836 <li>
 837 <p>
 838 &#91;user@&#93;host.xz:/~&#91;user&#93;/path/to/repo.git/
 839 </p>
 840 </li>
 841 </ul></div>
 842 <div class="para"><p>For local respositories, also supported by git natively, the following
 843 syntaxes may be used:</p></div>
 844 <div class="ilist"><ul>
 845 <li>
 846 <p>
 847 /path/to/repo.git/
 848 </p>
 849 </li>
 850 <li>
 851 <p>
 852 file:///path/to/repo.git/
 853 </p>
 854 </li>
 855 </ul></div>
 856 <div class="para"><p>These two syntaxes are mostly equivalent, except when cloning, when
 857 the former implies --local option. See <a href="git-clone.html">git-clone(1)</a> for
 858 details.</p></div>
 859 <div class="para"><p>When git doesn't know how to handle a certain transport protocol, it
 860 attempts to use the <em>remote-&lt;transport&gt;</em> remote helper, if one
 861 exists. To explicitly request a remote helper, the following syntax
 862 may be used:</p></div>
 863 <div class="ilist"><ul>
 864 <li>
 865 <p>
 866 &lt;transport&gt;::&lt;address&gt;
 867 </p>
 868 </li>
 869 </ul></div>
 870 <div class="para"><p>where &lt;address&gt; may be a path, a server and path, or an arbitrary
 871 URL-like string recognized by the specific remote helper being
 872 invoked. See <a href="git-remote-helpers.html">git-remote-helpers(1)</a> for details.</p></div>
 873 <div class="para"><p>If there are a large number of similarly-named remote repositories and
 874 you want to use a different format for them (such that the URLs you
 875 use will be rewritten into URLs that work), you can create a
 876 configuration section of the form:</p></div>
 877 <div class="listingblock">
 878 <div class="content">
 879 <pre><tt>        [url "&lt;actual url base&gt;"]
 880                 insteadOf = &lt;other url base&gt;</tt></pre>
 881 </div></div>
 882 <div class="para"><p>For example, with this:</p></div>
 883 <div class="listingblock">
 884 <div class="content">
 885 <pre><tt>        [url "git://git.host.xz/"]
 886                 insteadOf = host.xz:/path/to/
 887                 insteadOf = work:</tt></pre>
 888 </div></div>
 889 <div class="para"><p>a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be
 890 rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".</p></div>
 891 <div class="para"><p>If you want to rewrite URLs for push only, you can create a
 892 configuration section of the form:</p></div>
 893 <div class="listingblock">
 894 <div class="content">
 895 <pre><tt>        [url "&lt;actual url base&gt;"]
 896                 pushInsteadOf = &lt;other url base&gt;</tt></pre>
 897 </div></div>
 898 <div class="para"><p>For example, with this:</p></div>
 899 <div class="listingblock">
 900 <div class="content">
 901 <pre><tt>        [url "ssh://example.org/"]
 902                 pushInsteadOf = git://example.org/</tt></pre>
 903 </div></div>
 904 <div class="para"><p>a URL like "git://example.org/path/to/repo.git" will be rewritten to
 905 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still
 906 use the original URL.</p></div>
 907 </div>
 908 <h2 id="_remotes_a_id_remotes_a">REMOTES<a id="REMOTES"></a></h2>
 909 <div class="sectionbody">
 910 <div class="para"><p>The name of one of the following can be used instead
 911 of a URL as <tt>&lt;repository&gt;</tt> argument:</p></div>
 912 <div class="ilist"><ul>
 913 <li>
 914 <p>
 915 a remote in the git configuration file: <tt>$GIT_DIR/config</tt>,
 916 </p>
 917 </li>
 918 <li>
 919 <p>
 920 a file in the <tt>$GIT_DIR/remotes</tt> directory, or
 921 </p>
 922 </li>
 923 <li>
 924 <p>
 925 a file in the <tt>$GIT_DIR/branches</tt> directory.
 926 </p>
 927 </li>
 928 </ul></div>
 929 <div class="para"><p>All of these also allow you to omit the refspec from the command line
 930 because they each contain a refspec which git will use by default.</p></div>
 931 <h3 id="_named_remote_in_configuration_file">Named remote in configuration file</h3><div style="clear:left"></div>
 932 <div class="para"><p>You can choose to provide the name of a remote which you had previously
 933 configured using <a href="git-remote.html">git-remote(1)</a>, <a href="git-config.html">git-config(1)</a>
 934 or even by a manual edit to the <tt>$GIT_DIR/config</tt> file.  The URL of
 935 this remote will be used to access the repository.  The refspec
 936 of this remote will be used by default when you do
 937 not provide a refspec on the command line.  The entry in the
 938 config file would appear like this:</p></div>
 939 <div class="listingblock">
 940 <div class="content">
 941 <pre><tt>        [remote "&lt;name&gt;"]
 942                 url = &lt;url&gt;
 943                 pushurl = &lt;pushurl&gt;
 944                 push = &lt;refspec&gt;
 945                 fetch = &lt;refspec&gt;</tt></pre>
 946 </div></div>
 947 <div class="para"><p>The <tt>&lt;pushurl&gt;</tt> is used for pushes only. It is optional and defaults
 948 to <tt>&lt;url&gt;</tt>.</p></div>
 949 <h3 id="_named_file_in_tt_git_dir_remotes_tt">Named file in <tt>$GIT_DIR/remotes</tt></h3><div style="clear:left"></div>
 950 <div class="para"><p>You can choose to provide the name of a
 951 file in <tt>$GIT_DIR/remotes</tt>.  The URL
 952 in this file will be used to access the repository.  The refspec
 953 in this file will be used as default when you do not
 954 provide a refspec on the command line.  This file should have the
 955 following format:</p></div>
 956 <div class="listingblock">
 957 <div class="content">
 958 <pre><tt>        URL: one of the above URL format
 959         Push: &lt;refspec&gt;
 960         Pull: &lt;refspec&gt;
 961 </tt></pre>
 962 </div></div>
 963 <div class="para"><p><tt>Push:</tt> lines are used by <em>git push</em> and
 964 <tt>Pull:</tt> lines are used by <em>git pull</em> and <em>git fetch</em>.
 965 Multiple <tt>Push:</tt> and <tt>Pull:</tt> lines may
 966 be specified for additional branch mappings.</p></div>
 967 <h3 id="_named_file_in_tt_git_dir_branches_tt">Named file in <tt>$GIT_DIR/branches</tt></h3><div style="clear:left"></div>
 968 <div class="para"><p>You can choose to provide the name of a
 969 file in <tt>$GIT_DIR/branches</tt>.
 970 The URL in this file will be used to access the repository.
 971 This file should have the following format:</p></div>
 972 <div class="listingblock">
 973 <div class="content">
 974 <pre><tt>        &lt;url&gt;#&lt;head&gt;</tt></pre>
 975 </div></div>
 976 <div class="para"><p><tt>&lt;url&gt;</tt> is required; <tt>#&lt;head&gt;</tt> is optional.</p></div>
 977 <div class="para"><p>Depending on the operation, git will use one of the following
 978 refspecs, if you don't provide one on the command line.
 979 <tt>&lt;branch&gt;</tt> is the name of this file in <tt>$GIT_DIR/branches</tt> and
 980 <tt>&lt;head&gt;</tt> defaults to <tt>master</tt>.</p></div>
 981 <div class="para"><p>git fetch uses:</p></div>
 982 <div class="listingblock">
 983 <div class="content">
 984 <pre><tt>        refs/heads/&lt;head&gt;:refs/heads/&lt;branch&gt;</tt></pre>
 985 </div></div>
 986 <div class="para"><p>git push uses:</p></div>
 987 <div class="listingblock">
 988 <div class="content">
 989 <pre><tt>        HEAD:refs/heads/&lt;head&gt;</tt></pre>
 990 </div></div>
 991 </div>
 992 <h2 id="_merge_strategies">MERGE STRATEGIES</h2>
 993 <div class="sectionbody">
 994 <div class="para"><p>The merge mechanism (<em>git-merge</em> and <em>git-pull</em> commands) allows the
 995 backend <em>merge strategies</em> to be chosen with <tt>-s</tt> option.  Some strategies
 996 can also take their own options, which can be passed by giving <tt>-X&lt;option&gt;</tt>
 997 arguments to <em>git-merge</em> and/or <em>git-pull</em>.</p></div>
 998 <div class="vlist"><dl>
 999 <dt>
1000 resolve
1001 </dt>
1002 <dd>
1003 <p>
1004         This can only resolve two heads (i.e. the current branch
1005         and another branch you pulled from) using a 3-way merge
1006         algorithm.  It tries to carefully detect criss-cross
1007         merge ambiguities and is considered generally safe and
1008         fast.
1009 </p>
1010 </dd>
1011 <dt>
1012 recursive
1013 </dt>
1014 <dd>
1015 <p>
1016         This can only resolve two heads using a 3-way merge
1017         algorithm.  When there is more than one common
1018         ancestor that can be used for 3-way merge, it creates a
1019         merged tree of the common ancestors and uses that as
1020         the reference tree for the 3-way merge.  This has been
1021         reported to result in fewer merge conflicts without
1022         causing mis-merges by tests done on actual merge commits
1023         taken from Linux 2.6 kernel development history.
1024         Additionally this can detect and handle merges involving
1025         renames.  This is the default merge strategy when
1026         pulling or merging one branch.
1027 </p>
1028 <div class="para"><p>The <em>recursive</em> strategy can take the following options:</p></div>
1029 <div class="vlist"><dl>
1030 <dt>
1031 ours
1032 </dt>
1033 <dd>
1034 <p>
1035         This option forces conflicting hunks to be auto-resolved cleanly by
1036         favoring <em>our</em> version.  Changes from the other tree that do not
1037         conflict with our side are reflected to the merge result.
1038 </p>
1039 <div class="para"><p>This should not be confused with the <em>ours</em> merge strategy, which does not
1040 even look at what the other tree contains at all.  It discards everything
1041 the other tree did, declaring <em>our</em> history contains all that happened in it.</p></div>
1042 </dd>
1043 <dt>
1044 theirs
1045 </dt>
1046 <dd>
1047 <p>
1048         This is opposite of <em>ours</em>.
1049 </p>
1050 </dd>
1051 <dt>
1052 subtree[=path]
1053 </dt>
1054 <dd>
1055 <p>
1056         This option is a more advanced form of <em>subtree</em> strategy, where
1057         the strategy makes a guess on how two trees must be shifted to
1058         match with each other when merging.  Instead, the specified path
1059         is prefixed (or stripped from the beginning) to make the shape of
1060         two trees to match.
1061 </p>
1062 </dd>
1063 </dl></div>
1064 </dd>
1065 <dt>
1066 octopus
1067 </dt>
1068 <dd>
1069 <p>
1070         This resolves cases with more than two heads, but refuses to do
1071         a complex merge that needs manual resolution.  It is
1072         primarily meant to be used for bundling topic branch
1073         heads together.  This is the default merge strategy when
1074         pulling or merging more than one branch.
1075 </p>
1076 </dd>
1077 <dt>
1078 ours
1079 </dt>
1080 <dd>
1081 <p>
1082         This resolves any number of heads, but the resulting tree of the
1083         merge is always that of the current branch head, effectively
1084         ignoring all changes from all other branches.  It is meant to
1085         be used to supersede old development history of side
1086         branches.  Note that this is different from the -Xours option to
1087         the <em>recursive</em> merge strategy.
1088 </p>
1089 </dd>
1090 <dt>
1091 subtree
1092 </dt>
1093 <dd>
1094 <p>
1095         This is a modified recursive strategy. When merging trees A and
1096         B, if B corresponds to a subtree of A, B is first adjusted to
1097         match the tree structure of A, instead of reading the trees at
1098         the same level. This adjustment is also done to the common
1099         ancestor tree.
1100 </p>
1101 </dd>
1102 </dl></div>
1103 </div>
1104 <h2 id="_default_behaviour">DEFAULT BEHAVIOUR</h2>
1105 <div class="sectionbody">
1106 <div class="para"><p>Often people use <tt>git pull</tt> without giving any parameter.
1107 Traditionally, this has been equivalent to saying <tt>git pull
1108 origin</tt>.  However, when configuration <tt>branch.&lt;name&gt;.remote</tt> is
1109 present while on branch <tt>&lt;name&gt;</tt>, that value is used instead of
1110 <tt>origin</tt>.</p></div>
1111 <div class="para"><p>In order to determine what URL to use to fetch from, the value
1112 of the configuration <tt>remote.&lt;origin&gt;.url</tt> is consulted
1113 and if there is not any such variable, the value on <tt>URL: </tt> line
1114 in <tt>$GIT_DIR/remotes/&lt;origin&gt;</tt> file is used.</p></div>
1115 <div class="para"><p>In order to determine what remote branches to fetch (and
1116 optionally store in the tracking branches) when the command is
1117 run without any refspec parameters on the command line, values
1118 of the configuration variable <tt>remote.&lt;origin&gt;.fetch</tt> are
1119 consulted, and if there aren't any, <tt>$GIT_DIR/remotes/&lt;origin&gt;</tt>
1120 file is consulted and its <tt>Pull: </tt> lines are used.
1121 In addition to the refspec formats described in the OPTIONS
1122 section, you can have a globbing refspec that looks like this:</p></div>
1123 <div class="listingblock">
1124 <div class="content">
1125 <pre><tt>refs/heads/*:refs/remotes/origin/*</tt></pre>
1126 </div></div>
1127 <div class="para"><p>A globbing refspec must have a non-empty RHS (i.e. must store
1128 what were fetched in tracking branches), and its LHS and RHS
1129 must end with <tt>/*</tt>.  The above specifies that all remote
1130 branches are tracked using tracking branches in
1131 <tt>refs/remotes/origin/</tt> hierarchy under the same name.</p></div>
1132 <div class="para"><p>The rule to determine which remote branch to merge after
1133 fetching is a bit involved, in order not to break backward
1134 compatibility.</p></div>
1135 <div class="para"><p>If explicit refspecs were given on the command
1136 line of <tt>git pull</tt>, they are all merged.</p></div>
1137 <div class="para"><p>When no refspec was given on the command line, then <tt>git pull</tt>
1138 uses the refspec from the configuration or
1139 <tt>$GIT_DIR/remotes/&lt;origin&gt;</tt>.  In such cases, the following
1140 rules apply:</p></div>
1141 <div class="olist"><ol>
1142 <li>
1143 <p>
1144 If <tt>branch.&lt;name&gt;.merge</tt> configuration for the current
1145   branch <tt>&lt;name&gt;</tt> exists, that is the name of the branch at the
1146   remote site that is merged.
1147 </p>
1148 </li>
1149 <li>
1150 <p>
1151 If the refspec is a globbing one, nothing is merged.
1152 </p>
1153 </li>
1154 <li>
1155 <p>
1156 Otherwise the remote branch of the first refspec is merged.
1157 </p>
1158 </li>
1159 </ol></div>
1160 </div>
1161 <h2 id="_examples">EXAMPLES</h2>
1162 <div class="sectionbody">
1163 <div class="ilist"><ul>
1164 <li>
1165 <p>
1166 Update the remote-tracking branches for the repository
1167   you cloned from, then merge one of them into your
1168   current branch:
1169 </p>
1170 <div class="listingblock">
1171 <div class="content">
1172 <pre><tt>$ git pull, git pull origin</tt></pre>
1173 </div></div>
1174 <div class="para"><p>Normally the branch merged in is the HEAD of the remote repository,
1175 but the choice is determined by the branch.&lt;name&gt;.remote and
1176 branch.&lt;name&gt;.merge options; see <a href="git-config.html">git-config(1)</a> for details.</p></div>
1177 </li>
1178 <li>
1179 <p>
1180 Merge into the current branch the remote branch <tt>next</tt>:
1181 </p>
1182 <div class="listingblock">
1183 <div class="content">
1184 <pre><tt>$ git pull origin next</tt></pre>
1185 </div></div>
1186 <div class="para"><p>This leaves a copy of <tt>next</tt> temporarily in FETCH_HEAD, but
1187 does not update any remote-tracking branches. Using remote-tracking
1188 branches, the same can be done by invoking fetch and merge:</p></div>
1189 <div class="listingblock">
1190 <div class="content">
1191 <pre><tt>$ git fetch origin
1192 $ git merge origin/next</tt></pre>
1193 </div></div>
1194 </li>
1195 </ul></div>
1196 <div class="para"><p>If you tried a pull which resulted in a complex conflicts and
1197 would want to start over, you can recover with <em>git reset</em>.</p></div>
1198 </div>
1199 <h2 id="_see_also">SEE ALSO</h2>
1200 <div class="sectionbody">
1201 <div class="para"><p><a href="git-fetch.html">git-fetch(1)</a>, <a href="git-merge.html">git-merge(1)</a>, <a href="git-config.html">git-config(1)</a></p></div>
1202 </div>
1203 <h2 id="_author">Author</h2>
1204 <div class="sectionbody">
1205 <div class="para"><p>Written by Linus Torvalds &lt;torvalds@osdl.org&gt;
1206 and Junio C Hamano &lt;gitster@pobox.com&gt;</p></div>
1207 </div>
1208 <h2 id="_documentation">Documentation</h2>
1209 <div class="sectionbody">
1210 <div class="para"><p>Documentation by Jon Loeliger,
1211 David Greaves,
1212 Junio C Hamano and the git-list &lt;git@vger.kernel.org&gt;.</p></div>
1213 </div>
1214 <h2 id="_git">GIT</h2>
1215 <div class="sectionbody">
1216 <div class="para"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1217 </div>
1218 <div id="footer">
1219 <div id="footer-text">
1220 Last updated 2010-04-24 02:56:03 UTC
1221 </div>
1222 </div>
1223 </body>
1224 </html>