doc/source/en/TortoiseGit/git_doc/git-pull.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">\r
   3 \r
   4 <sect2 lang="en" id="git-pull(1)">\r
   5     <title>git-pull(1)</title>\r
   6 <indexterm>\r
   7 <primary>git-pull(1)</primary>\r
   8 </indexterm>\r
   9 <simplesect id="git-pull(1)__name">\r
  10 <title>NAME</title>\r
  11 <simpara>git-pull - Fetch from and integrate with another repository or a local branch</simpara>\r
  12 </simplesect>\r
  13 <simplesect id="git-pull(1)__synopsis">\r
  14 <title>SYNOPSIS</title>\r
  15 <blockquote>\r
  16 <literallayout><emphasis>git pull</emphasis> [options] [&lt;repository&gt; [&lt;refspec&gt;&#8230;]]</literallayout>\r
  17 </blockquote>\r
  18 </simplesect>\r
  19 <simplesect id="git-pull(1)__description">\r
  20 <title>DESCRIPTION</title>\r
  21 <simpara>Incorporates changes from a remote repository into the current\r
  22 branch.  In its default mode, <emphasis>git pull</emphasis> is shorthand for\r
  23 <emphasis>git fetch</emphasis> followed by <emphasis>git merge FETCH_HEAD</emphasis>.</simpara>\r
  24 <simpara>More precisely, <emphasis>git pull</emphasis> runs <emphasis>git fetch</emphasis> with the given\r
  25 parameters and calls <emphasis>git merge</emphasis> to merge the retrieved branch\r
  26 heads into the current branch.\r
  27 With <emphasis>--rebase</emphasis>, it runs <emphasis>git rebase</emphasis> instead of <emphasis>git merge</emphasis>.</simpara>\r
  28 <simpara>&lt;repository&gt; should be the name of a remote repository as\r
  29 passed to <xref linkend="git-fetch(1)" />.  &lt;refspec&gt; can name an\r
  30 arbitrary remote ref (for example, the name of a tag) or even\r
  31 a collection of refs with corresponding remote-tracking branches\r
  32 (e.g., refs/heads/&#42;:refs/remotes/origin/&#42;),\r
  33 but usually it is the name of a branch in the remote repository.</simpara>\r
  34 <simpara>Default values for &lt;repository&gt; and &lt;branch&gt; are read from the\r
  35 "remote" and "merge" configuration for the current branch\r
  36 as set by <xref linkend="git-branch(1)" /> <emphasis>--track</emphasis>.</simpara>\r
  37 <simpara>Assume the following history exists and the current branch is\r
  38 "<emphasis>master</emphasis>":</simpara>\r
  39 <screen>          A---B---C master on origin\r
  40          /\r
  41     D---E---F---G master\r
  42         ^\r
  43         origin/master in your repository</screen>\r
  44 <simpara>Then "<emphasis>git pull</emphasis>" will fetch and replay the changes from the remote\r
  45 <emphasis>master</emphasis> branch since it diverged from the local <emphasis>master</emphasis> (i.e., <emphasis>E</emphasis>)\r
  46 until its current commit (<emphasis>C</emphasis>) on top of <emphasis>master</emphasis> and record the\r
  47 result in a new commit along with the names of the two parent commits\r
  48 and a log message from the user describing the changes.</simpara>\r
  49 <screen>          A---B---C origin/master\r
  50          /         \\r
  51     D---E---F---G---H master</screen>\r
  52 <simpara>See <xref linkend="git-merge(1)" /> for details, including how conflicts\r
  53 are presented and handled.</simpara>\r
  54 <simpara>In Git 1.7.0 or later, to cancel a conflicting merge, use\r
  55 <emphasis>git reset --merge</emphasis>.  <emphasis role="strong">Warning</emphasis>: In older versions of Git, running <emphasis>git pull</emphasis>\r
  56 with uncommitted changes is discouraged: while possible, it leaves you\r
  57 in a state that may be hard to back out of in the case of a conflict.</simpara>\r
  58 <simpara>If any of the remote changes overlap with local uncommitted changes,\r
  59 the merge will be automatically cancelled and the work tree untouched.\r
  60 It is generally best to get any local changes in working order before\r
  61 pulling or stash them away with <xref linkend="git-stash(1)" />.</simpara>\r
  62 </simplesect>\r
  63 <simplesect id="git-pull(1)__options">\r
  64 <title>OPTIONS</title>\r
  65 <variablelist>\r
  66 <varlistentry>\r
  67 <term>\r
  68 -q\r
  69 </term>\r
  70 <term>\r
  71 --quiet\r
  72 </term>\r
  73 <listitem>\r
  74 <simpara>\r
  75         This is passed to both underlying git-fetch to squelch reporting of\r
  76         during transfer, and underlying git-merge to squelch output during\r
  77         merging.\r
  78 </simpara>\r
  79 </listitem>\r
  80 </varlistentry>\r
  81 <varlistentry>\r
  82 <term>\r
  83 -v\r
  84 </term>\r
  85 <term>\r
  86 --verbose\r
  87 </term>\r
  88 <listitem>\r
  89 <simpara>\r
  90         Pass --verbose to git-fetch and git-merge.\r
  91 </simpara>\r
  92 </listitem>\r
  93 </varlistentry>\r
  94 <varlistentry>\r
  95 <term>\r
  96 --[no-]recurse-submodules[=yes|on-demand|no]\r
  97 </term>\r
  98 <listitem>\r
  99 <simpara>\r
 100         This option controls if new commits of all populated submodules should\r
 101         be fetched too (see <xref linkend="git-config(1)" /> and <xref linkend="gitmodules(5)" />).\r
 102         That might be necessary to get the data needed for merging submodule\r
 103         commits, a feature Git learned in 1.7.3. Notice that the result of a\r
 104         merge will not be checked out in the submodule, "git submodule update"\r
 105         has to be called afterwards to bring the work tree up to date with the\r
 106         merge result.\r
 107 </simpara>\r
 108 </listitem>\r
 109 </varlistentry>\r
 110 </variablelist>\r
 111 <section id="git-pull(1)__options_related_to_merging">\r
 112 <title>Options related to merging</title>\r
 113 <variablelist>\r
 114 <varlistentry>\r
 115 <term>\r
 116 --commit\r
 117 </term>\r
 118 <term>\r
 119 --no-commit\r
 120 </term>\r
 121 <listitem>\r
 122 <simpara>\r
 123         Perform the merge and commit the result. This option can\r
 124         be used to override --no-commit.\r
 125 </simpara>\r
 126 <simpara>With --no-commit perform the merge but pretend the merge\r
 127 failed and do not autocommit, to give the user a chance to\r
 128 inspect and further tweak the merge result before committing.</simpara>\r
 129 </listitem>\r
 130 </varlistentry>\r
 131 <varlistentry>\r
 132 <term>\r
 133 --edit\r
 134 </term>\r
 135 <term>\r
 136 -e\r
 137 </term>\r
 138 <term>\r
 139 --no-edit\r
 140 </term>\r
 141 <listitem>\r
 142 <simpara>\r
 143         Invoke an editor before committing successful mechanical merge to\r
 144         further edit the auto-generated merge message, so that the user\r
 145         can explain and justify the merge. The <emphasis>--no-edit</emphasis> option can be\r
 146         used to accept the auto-generated message (this is generally\r
 147         discouraged).\r
 148 </simpara>\r
 149 <simpara>Older scripts may depend on the historical behaviour of not allowing the\r
 150 user to edit the merge log message. They will see an editor opened when\r
 151 they run <emphasis>git merge</emphasis>. To make it easier to adjust such scripts to the\r
 152 updated behaviour, the environment variable <emphasis>GIT_MERGE_AUTOEDIT</emphasis> can be\r
 153 set to <emphasis>no</emphasis> at the beginning of them.</simpara>\r
 154 </listitem>\r
 155 </varlistentry>\r
 156 <varlistentry>\r
 157 <term>\r
 158 --ff\r
 159 </term>\r
 160 <listitem>\r
 161 <simpara>\r
 162         When the merge resolves as a fast-forward, only update the branch\r
 163         pointer, without creating a merge commit.  This is the default\r
 164         behavior.\r
 165 </simpara>\r
 166 </listitem>\r
 167 </varlistentry>\r
 168 <varlistentry>\r
 169 <term>\r
 170 --no-ff\r
 171 </term>\r
 172 <listitem>\r
 173 <simpara>\r
 174         Create a merge commit even when the merge resolves as a\r
 175         fast-forward.  This is the default behaviour when merging an\r
 176         annotated (and possibly signed) tag.\r
 177 </simpara>\r
 178 </listitem>\r
 179 </varlistentry>\r
 180 <varlistentry>\r
 181 <term>\r
 182 --ff-only\r
 183 </term>\r
 184 <listitem>\r
 185 <simpara>\r
 186         Refuse to merge and exit with a non-zero status unless the\r
 187         current <emphasis>HEAD</emphasis> is already up-to-date or the merge can be\r
 188         resolved as a fast-forward.\r
 189 </simpara>\r
 190 </listitem>\r
 191 </varlistentry>\r
 192 <varlistentry>\r
 193 <term>\r
 194 --log[=&lt;n&gt;]\r
 195 </term>\r
 196 <term>\r
 197 --no-log\r
 198 </term>\r
 199 <listitem>\r
 200 <simpara>\r
 201         In addition to branch names, populate the log message with\r
 202         one-line descriptions from at most &lt;n&gt; actual commits that are being\r
 203         merged. See also <xref linkend="git-fmt-merge-msg(1)" />.\r
 204 </simpara>\r
 205 <simpara>With --no-log do not list one-line descriptions from the\r
 206 actual commits being merged.</simpara>\r
 207 </listitem>\r
 208 </varlistentry>\r
 209 <varlistentry>\r
 210 <term>\r
 211 --stat\r
 212 </term>\r
 213 <term>\r
 214 -n\r
 215 </term>\r
 216 <term>\r
 217 --no-stat\r
 218 </term>\r
 219 <listitem>\r
 220 <simpara>\r
 221         Show a diffstat at the end of the merge. The diffstat is also\r
 222         controlled by the configuration option merge.stat.\r
 223 </simpara>\r
 224 <simpara>With -n or --no-stat do not show a diffstat at the end of the\r
 225 merge.</simpara>\r
 226 </listitem>\r
 227 </varlistentry>\r
 228 <varlistentry>\r
 229 <term>\r
 230 --squash\r
 231 </term>\r
 232 <term>\r
 233 --no-squash\r
 234 </term>\r
 235 <listitem>\r
 236 <simpara>\r
 237         Produce the working tree and index state as if a real merge\r
 238         happened (except for the merge information), but do not actually\r
 239         make a commit, move the <emphasis>HEAD</emphasis>, or record <emphasis>$GIT_DIR/MERGE_HEAD</emphasis>\r
 240         (to cause the next <emphasis>git commit</emphasis> command to create a merge\r
 241         commit).  This allows you to create a single commit on top of\r
 242         the current branch whose effect is the same as merging another\r
 243         branch (or more in case of an octopus).\r
 244 </simpara>\r
 245 <simpara>With --no-squash perform the merge and commit the result. This\r
 246 option can be used to override --squash.</simpara>\r
 247 </listitem>\r
 248 </varlistentry>\r
 249 <varlistentry>\r
 250 <term>\r
 251 -s &lt;strategy&gt;\r
 252 </term>\r
 253 <term>\r
 254 --strategy=&lt;strategy&gt;\r
 255 </term>\r
 256 <listitem>\r
 257 <simpara>\r
 258         Use the given merge strategy; can be supplied more than\r
 259         once to specify them in the order they should be tried.\r
 260         If there is no <emphasis>-s</emphasis> option, a built-in list of strategies\r
 261         is used instead (<emphasis>git merge-recursive</emphasis> when merging a single\r
 262         head, <emphasis>git merge-octopus</emphasis> otherwise).\r
 263 </simpara>\r
 264 </listitem>\r
 265 </varlistentry>\r
 266 <varlistentry>\r
 267 <term>\r
 268 -X &lt;option&gt;\r
 269 </term>\r
 270 <term>\r
 271 --strategy-option=&lt;option&gt;\r
 272 </term>\r
 273 <listitem>\r
 274 <simpara>\r
 275         Pass merge strategy specific option through to the merge\r
 276         strategy.\r
 277 </simpara>\r
 278 </listitem>\r
 279 </varlistentry>\r
 280 <varlistentry>\r
 281 <term>\r
 282 --verify-signatures\r
 283 </term>\r
 284 <term>\r
 285 --no-verify-signatures\r
 286 </term>\r
 287 <listitem>\r
 288 <simpara>\r
 289         Verify that the commits being merged have good and trusted GPG signatures\r
 290         and abort the merge in case they do not.\r
 291 </simpara>\r
 292 </listitem>\r
 293 </varlistentry>\r
 294 <varlistentry>\r
 295 <term>\r
 296 --summary\r
 297 </term>\r
 298 <term>\r
 299 --no-summary\r
 300 </term>\r
 301 <listitem>\r
 302 <simpara>\r
 303         Synonyms to --stat and --no-stat; these are deprecated and will be\r
 304         removed in the future.\r
 305 </simpara>\r
 306 </listitem>\r
 307 </varlistentry>\r
 308 <varlistentry>\r
 309 <term>\r
 310 --allow-unrelated-histories\r
 311 </term>\r
 312 <listitem>\r
 313 <simpara>\r
 314         By default, <emphasis>git merge</emphasis> command refuses to merge histories\r
 315         that do not share a common ancestor.  This option can be\r
 316         used to override this safety when merging histories of two\r
 317         projects that started their lives independently. As that is\r
 318         a very rare occasion, no configuration variable to enable\r
 319         this by default exists and will not be added.\r
 320 </simpara>\r
 321 </listitem>\r
 322 </varlistentry>\r
 323 <varlistentry>\r
 324 <term>\r
 325 -r\r
 326 </term>\r
 327 <term>\r
 328 --rebase[=false|true|preserve|interactive]\r
 329 </term>\r
 330 <listitem>\r
 331 <simpara>\r
 332         When true, rebase the current branch on top of the upstream\r
 333         branch after fetching. If there is a remote-tracking branch\r
 334         corresponding to the upstream branch and the upstream branch\r
 335         was rebased since last fetched, the rebase uses that information\r
 336         to avoid rebasing non-local changes.\r
 337 </simpara>\r
 338 <simpara>When set to preserve, rebase with the <emphasis>--preserve-merges</emphasis> option passed\r
 339 to <emphasis>git rebase</emphasis> so that locally created merge commits will not be flattened.</simpara>\r
 340 <simpara>When false, merge the current branch into the upstream branch.</simpara>\r
 341 <simpara>When <emphasis>interactive</emphasis>, enable the interactive mode of rebase.</simpara>\r
 342 <simpara>See <emphasis>pull.rebase</emphasis>, <emphasis>branch.&lt;name&gt;.rebase</emphasis> and <emphasis>branch.autoSetupRebase</emphasis> in\r
 343 <xref linkend="git-config(1)" /> if you want to make <emphasis>git pull</emphasis> always use\r
 344 <emphasis>--rebase</emphasis> instead of merging.</simpara>\r
 345 <note><simpara>This is a potentially <emphasis>dangerous</emphasis> mode of operation.\r
 346 It rewrites history, which does not bode well when you\r
 347 published that history already.  Do <emphasis role="strong">not</emphasis> use this option\r
 348 unless you have read <xref linkend="git-rebase(1)" /> carefully.</simpara></note>\r
 349 </listitem>\r
 350 </varlistentry>\r
 351 <varlistentry>\r
 352 <term>\r
 353 --no-rebase\r
 354 </term>\r
 355 <listitem>\r
 356 <simpara>\r
 357         Override earlier --rebase.\r
 358 </simpara>\r
 359 </listitem>\r
 360 </varlistentry>\r
 361 <varlistentry>\r
 362 <term>\r
 363 --autostash\r
 364 </term>\r
 365 <term>\r
 366 --no-autostash\r
 367 </term>\r
 368 <listitem>\r
 369 <simpara>\r
 370         Before starting rebase, stash local modifications away (see\r
 371         <xref linkend="git-stash(1)" />) if needed, and apply the stash when\r
 372         done. <emphasis>--no-autostash</emphasis> is useful to override the <emphasis>rebase.autoStash</emphasis>\r
 373         configuration variable (see <xref linkend="git-config(1)" />).\r
 374 </simpara>\r
 375 <simpara>This option is only valid when "--rebase" is used.</simpara>\r
 376 </listitem>\r
 377 </varlistentry>\r
 378 </variablelist>\r
 379 </section>\r
 380 <section id="git-pull(1)__options_related_to_fetching">\r
 381 <title>Options related to fetching</title>\r
 382 <variablelist>\r
 383 <varlistentry>\r
 384 <term>\r
 385 --all\r
 386 </term>\r
 387 <listitem>\r
 388 <simpara>\r
 389         Fetch all remotes.\r
 390 </simpara>\r
 391 </listitem>\r
 392 </varlistentry>\r
 393 <varlistentry>\r
 394 <term>\r
 395 -a\r
 396 </term>\r
 397 <term>\r
 398 --append\r
 399 </term>\r
 400 <listitem>\r
 401 <simpara>\r
 402         Append ref names and object names of fetched refs to the\r
 403         existing contents of <emphasis>.git/FETCH_HEAD</emphasis>.  Without this\r
 404         option old data in <emphasis>.git/FETCH_HEAD</emphasis> will be overwritten.\r
 405 </simpara>\r
 406 </listitem>\r
 407 </varlistentry>\r
 408 <varlistentry>\r
 409 <term>\r
 410 --depth=&lt;depth&gt;\r
 411 </term>\r
 412 <listitem>\r
 413 <simpara>\r
 414         Limit fetching to the specified number of commits from the tip of\r
 415         each remote branch history. If fetching to a <emphasis>shallow</emphasis> repository\r
 416         created by <emphasis>git clone</emphasis> with <emphasis>--depth=&lt;depth&gt;</emphasis> option (see\r
 417         <xref linkend="git-clone(1)" />), deepen or shorten the history to the specified\r
 418         number of commits. Tags for the deepened commits are not fetched.\r
 419 </simpara>\r
 420 </listitem>\r
 421 </varlistentry>\r
 422 <varlistentry>\r
 423 <term>\r
 424 --unshallow\r
 425 </term>\r
 426 <listitem>\r
 427 <simpara>\r
 428         If the source repository is complete, convert a shallow\r
 429         repository to a complete one, removing all the limitations\r
 430         imposed by shallow repositories.\r
 431 </simpara>\r
 432 <simpara>If the source repository is shallow, fetch as much as possible so that\r
 433 the current repository has the same history as the source repository.</simpara>\r
 434 </listitem>\r
 435 </varlistentry>\r
 436 <varlistentry>\r
 437 <term>\r
 438 --update-shallow\r
 439 </term>\r
 440 <listitem>\r
 441 <simpara>\r
 442         By default when fetching from a shallow repository,\r
 443         <emphasis>git fetch</emphasis> refuses refs that require updating\r
 444         .git/shallow. This option updates .git/shallow and accept such\r
 445         refs.\r
 446 </simpara>\r
 447 </listitem>\r
 448 </varlistentry>\r
 449 <varlistentry>\r
 450 <term>\r
 451 -f\r
 452 </term>\r
 453 <term>\r
 454 --force\r
 455 </term>\r
 456 <listitem>\r
 457 <simpara>\r
 458         When <emphasis>git fetch</emphasis> is used with <emphasis>&lt;rbranch&gt;:&lt;lbranch&gt;</emphasis>\r
 459         refspec, it refuses to update the local branch\r
 460         <emphasis>&lt;lbranch&gt;</emphasis> unless the remote branch <emphasis>&lt;rbranch&gt;</emphasis> it\r
 461         fetches is a descendant of <emphasis>&lt;lbranch&gt;</emphasis>.  This option\r
 462         overrides that check.\r
 463 </simpara>\r
 464 </listitem>\r
 465 </varlistentry>\r
 466 <varlistentry>\r
 467 <term>\r
 468 -k\r
 469 </term>\r
 470 <term>\r
 471 --keep\r
 472 </term>\r
 473 <listitem>\r
 474 <simpara>\r
 475         Keep downloaded pack.\r
 476 </simpara>\r
 477 </listitem>\r
 478 </varlistentry>\r
 479 <varlistentry>\r
 480 <term>\r
 481 --no-tags\r
 482 </term>\r
 483 <listitem>\r
 484 <simpara>\r
 485         By default, tags that point at objects that are downloaded\r
 486         from the remote repository are fetched and stored locally.\r
 487         This option disables this automatic tag following. The default\r
 488         behavior for a remote may be specified with the remote.&lt;name&gt;.tagOpt\r
 489         setting. See <xref linkend="git-config(1)" />.\r
 490 </simpara>\r
 491 </listitem>\r
 492 </varlistentry>\r
 493 <varlistentry>\r
 494 <term>\r
 495 -u\r
 496 </term>\r
 497 <term>\r
 498 --update-head-ok\r
 499 </term>\r
 500 <listitem>\r
 501 <simpara>\r
 502         By default <emphasis>git fetch</emphasis> refuses to update the head which\r
 503         corresponds to the current branch.  This flag disables the\r
 504         check.  This is purely for the internal use for <emphasis>git pull</emphasis>\r
 505         to communicate with <emphasis>git fetch</emphasis>, and unless you are\r
 506         implementing your own Porcelain you are not supposed to\r
 507         use it.\r
 508 </simpara>\r
 509 </listitem>\r
 510 </varlistentry>\r
 511 <varlistentry>\r
 512 <term>\r
 513 --upload-pack &lt;upload-pack&gt;\r
 514 </term>\r
 515 <listitem>\r
 516 <simpara>\r
 517         When given, and the repository to fetch from is handled\r
 518         by <emphasis>git fetch-pack</emphasis>, <emphasis>--exec=&lt;upload-pack&gt;</emphasis> is passed to\r
 519         the command to specify non-default path for the command\r
 520         run on the other end.\r
 521 </simpara>\r
 522 </listitem>\r
 523 </varlistentry>\r
 524 <varlistentry>\r
 525 <term>\r
 526 --progress\r
 527 </term>\r
 528 <listitem>\r
 529 <simpara>\r
 530         Progress status is reported on the standard error stream\r
 531         by default when it is attached to a terminal, unless -q\r
 532         is specified. This flag forces progress status even if the\r
 533         standard error stream is not directed to a terminal.\r
 534 </simpara>\r
 535 </listitem>\r
 536 </varlistentry>\r
 537 <varlistentry>\r
 538 <term>\r
 539 -4\r
 540 </term>\r
 541 <term>\r
 542 --ipv4\r
 543 </term>\r
 544 <listitem>\r
 545 <simpara>\r
 546         Use IPv4 addresses only, ignoring IPv6 addresses.\r
 547 </simpara>\r
 548 </listitem>\r
 549 </varlistentry>\r
 550 <varlistentry>\r
 551 <term>\r
 552 -6\r
 553 </term>\r
 554 <term>\r
 555 --ipv6\r
 556 </term>\r
 557 <listitem>\r
 558 <simpara>\r
 559         Use IPv6 addresses only, ignoring IPv4 addresses.\r
 560 </simpara>\r
 561 </listitem>\r
 562 </varlistentry>\r
 563 <varlistentry>\r
 564 <term>\r
 565 &lt;repository&gt;\r
 566 </term>\r
 567 <listitem>\r
 568 <simpara>\r
 569         The "remote" repository that is the source of a fetch\r
 570         or pull operation.  This parameter can be either a URL\r
 571         (see the section <link linkend="git-pull(1)_URLS">GIT URLS</link> below) or the name\r
 572         of a remote (see the section <link linkend="git-pull(1)_REMOTES">REMOTES</link> below).\r
 573 </simpara>\r
 574 </listitem>\r
 575 </varlistentry>\r
 576 <varlistentry>\r
 577 <term>\r
 578 &lt;refspec&gt;\r
 579 </term>\r
 580 <listitem>\r
 581 <simpara>\r
 582         Specifies which refs to fetch and which local refs to update.\r
 583         When no &lt;refspec&gt;s appear on the command line, the refs to fetch\r
 584         are read from <emphasis>remote.&lt;repository&gt;.fetch</emphasis> variables instead\r
 585         (see <xref linkend="git-fetch(1)" />).\r
 586 </simpara>\r
 587 <simpara>The format of a &lt;refspec&gt; parameter is an optional plus\r
 588 <emphasis>+</emphasis>, followed by the source ref &lt;src&gt;, followed\r
 589 by a colon <emphasis>:</emphasis>, followed by the destination ref &lt;dst&gt;.\r
 590 The colon can be omitted when &lt;dst&gt; is empty.</simpara>\r
 591 <simpara><emphasis>tag &lt;tag&gt;</emphasis> means the same as <emphasis>refs/tags/&lt;tag&gt;:refs/tags/&lt;tag&gt;</emphasis>;\r
 592 it requests fetching everything up to the given tag.</simpara>\r
 593 <simpara>The remote ref that matches &lt;src&gt;\r
 594 is fetched, and if &lt;dst&gt; is not empty string, the local\r
 595 ref that matches it is fast-forwarded using &lt;src&gt;.\r
 596 If the optional plus <emphasis>+</emphasis> is used, the local ref\r
 597 is updated even if it does not result in a fast-forward\r
 598 update.</simpara>\r
 599 <note><simpara>When the remote branch you want to fetch is known to\r
 600 be rewound and rebased regularly, it is expected that\r
 601 its new tip will not be descendant of its previous tip\r
 602 (as stored in your remote-tracking branch the last time\r
 603 you fetched).  You would want\r
 604 to use the <emphasis>+</emphasis> sign to indicate non-fast-forward updates\r
 605 will be needed for such branches.  There is no way to\r
 606 determine or declare that a branch will be made available\r
 607 in a repository with this behavior; the pulling user simply\r
 608 must know this is the expected usage pattern for a branch.</simpara></note>\r
 609 <note><simpara>There is a difference between listing multiple &lt;refspec&gt;\r
 610 directly on <emphasis>git pull</emphasis> command line and having multiple\r
 611 <emphasis>remote.&lt;repository&gt;.fetch</emphasis> entries in your configuration\r
 612 for a &lt;repository&gt; and running a\r
 613 <emphasis>git pull</emphasis> command without any explicit &lt;refspec&gt; parameters.\r
 614 &lt;refspec&gt;s listed explicitly on the command line are always\r
 615 merged into the current branch after fetching.  In other words,\r
 616 if you list more than one remote ref, <emphasis>git pull</emphasis> will create\r
 617 an Octopus merge.  On the other hand, if you do not list any\r
 618 explicit &lt;refspec&gt; parameter on the command line, <emphasis>git pull</emphasis>\r
 619 will fetch all the &lt;refspec&gt;s it finds in the\r
 620 <emphasis>remote.&lt;repository&gt;.fetch</emphasis> configuration and merge\r
 621 only the first &lt;refspec&gt; found into the current branch.\r
 622 This is because making an\r
 623 Octopus from remote refs is rarely done, while keeping track\r
 624 of multiple remote heads in one-go by fetching more than one\r
 625 is often useful.</simpara></note>\r
 626 </listitem>\r
 627 </varlistentry>\r
 628 </variablelist>\r
 629 </section>\r
 630 </simplesect>\r
 631 <simplesect id="git-pull(1)__git_urls_anchor_id_git_pull_1__urls_xreflabel_urls">\r
 632 <title>GIT URLS<anchor id="git-pull(1)_URLS" xreflabel="[URLS]"/></title>\r
 633 <simpara>In general, URLs contain information about the transport protocol, the\r
 634 address of the remote server, and the path to the repository.\r
 635 Depending on the transport protocol, some of this information may be\r
 636 absent.</simpara>\r
 637 <simpara>Git supports ssh, git, http, and https protocols (in addition, ftp,\r
 638 and ftps can be used for fetching, but this is inefficient and\r
 639 deprecated; do not use it).</simpara>\r
 640 <simpara>The native transport (i.e. git:// URL) does no authentication and\r
 641 should be used with caution on unsecured networks.</simpara>\r
 642 <simpara>The following syntaxes may be used with them:</simpara>\r
 643 <itemizedlist>\r
 644 <listitem>\r
 645 <simpara>\r
 646 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/path/to/repo.git/\r
 647 </simpara>\r
 648 </listitem>\r
 649 <listitem>\r
 650 <simpara>\r
 651 git://host.xz&#91;:port&#93;/path/to/repo.git/\r
 652 </simpara>\r
 653 </listitem>\r
 654 <listitem>\r
 655 <simpara>\r
 656 http&#91;s&#93;://host.xz&#91;:port&#93;/path/to/repo.git/\r
 657 </simpara>\r
 658 </listitem>\r
 659 <listitem>\r
 660 <simpara>\r
 661 ftp&#91;s&#93;://host.xz&#91;:port&#93;/path/to/repo.git/\r
 662 </simpara>\r
 663 </listitem>\r
 664 </itemizedlist>\r
 665 <simpara>An alternative scp-like syntax may also be used with the ssh protocol:</simpara>\r
 666 <itemizedlist>\r
 667 <listitem>\r
 668 <simpara>\r
 669 &#91;user@&#93;host.xz:path/to/repo.git/\r
 670 </simpara>\r
 671 </listitem>\r
 672 </itemizedlist>\r
 673 <simpara>This syntax is only recognized if there are no slashes before the\r
 674 first colon. This helps differentiate a local path that contains a\r
 675 colon. For example the local path <emphasis>foo:bar</emphasis> could be specified as an\r
 676 absolute path or <emphasis>./foo:bar</emphasis> to avoid being misinterpreted as an ssh\r
 677 url.</simpara>\r
 678 <simpara>The ssh and git protocols additionally support ~username expansion:</simpara>\r
 679 <itemizedlist>\r
 680 <listitem>\r
 681 <simpara>\r
 682 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/~&#91;user&#93;/path/to/repo.git/\r
 683 </simpara>\r
 684 </listitem>\r
 685 <listitem>\r
 686 <simpara>\r
 687 git://host.xz&#91;:port&#93;/~&#91;user&#93;/path/to/repo.git/\r
 688 </simpara>\r
 689 </listitem>\r
 690 <listitem>\r
 691 <simpara>\r
 692 &#91;user@&#93;host.xz:/~&#91;user&#93;/path/to/repo.git/\r
 693 </simpara>\r
 694 </listitem>\r
 695 </itemizedlist>\r
 696 <simpara>For local repositories, also supported by Git natively, the following\r
 697 syntaxes may be used:</simpara>\r
 698 <itemizedlist>\r
 699 <listitem>\r
 700 <simpara>\r
 701 /path/to/repo.git/\r
 702 </simpara>\r
 703 </listitem>\r
 704 <listitem>\r
 705 <simpara>\r
 706 file:///path/to/repo.git/\r
 707 </simpara>\r
 708 </listitem>\r
 709 </itemizedlist>\r
 710 <simpara>These two syntaxes are mostly equivalent, except when cloning, when\r
 711 the former implies --local option. See <xref linkend="git-clone(1)" /> for\r
 712 details.</simpara>\r
 713 <simpara>When Git doesn't know how to handle a certain transport protocol, it\r
 714 attempts to use the <emphasis>remote-&lt;transport&gt;</emphasis> remote helper, if one\r
 715 exists. To explicitly request a remote helper, the following syntax\r
 716 may be used:</simpara>\r
 717 <itemizedlist>\r
 718 <listitem>\r
 719 <simpara>\r
 720 &lt;transport&gt;::&lt;address&gt;\r
 721 </simpara>\r
 722 </listitem>\r
 723 </itemizedlist>\r
 724 <simpara>where &lt;address&gt; may be a path, a server and path, or an arbitrary\r
 725 URL-like string recognized by the specific remote helper being\r
 726 invoked. See <xref linkend="gitremote-helpers(1)" /> for details.</simpara>\r
 727 <simpara>If there are a large number of similarly-named remote repositories and\r
 728 you want to use a different format for them (such that the URLs you\r
 729 use will be rewritten into URLs that work), you can create a\r
 730 configuration section of the form:</simpara>\r
 731 <screen>        [url "&lt;actual url base&gt;"]\r
 732                 insteadOf = &lt;other url base&gt;</screen>\r
 733 <simpara>For example, with this:</simpara>\r
 734 <screen>        [url "git://git.host.xz/"]\r
 735                 insteadOf = host.xz:/path/to/\r
 736                 insteadOf = work:</screen>\r
 737 <simpara>a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be\r
 738 rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".</simpara>\r
 739 <simpara>If you want to rewrite URLs for push only, you can create a\r
 740 configuration section of the form:</simpara>\r
 741 <screen>        [url "&lt;actual url base&gt;"]\r
 742                 pushInsteadOf = &lt;other url base&gt;</screen>\r
 743 <simpara>For example, with this:</simpara>\r
 744 <screen>        [url "ssh://example.org/"]\r
 745                 pushInsteadOf = git://example.org/</screen>\r
 746 <simpara>a URL like "git://example.org/path/to/repo.git" will be rewritten to\r
 747 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still\r
 748 use the original URL.</simpara>\r
 749 </simplesect>\r
 750 <simplesect id="git-pull(1)__remotes_anchor_id_git_pull_1__remotes_xreflabel_remotes">\r
 751 <title>REMOTES<anchor id="git-pull(1)_REMOTES" xreflabel="[REMOTES]"/></title>\r
 752 <simpara>The name of one of the following can be used instead\r
 753 of a URL as <emphasis>&lt;repository&gt;</emphasis> argument:</simpara>\r
 754 <itemizedlist>\r
 755 <listitem>\r
 756 <simpara>\r
 757 a remote in the Git configuration file: <emphasis>$GIT_DIR/config</emphasis>,\r
 758 </simpara>\r
 759 </listitem>\r
 760 <listitem>\r
 761 <simpara>\r
 762 a file in the <emphasis>$GIT_DIR/remotes</emphasis> directory, or\r
 763 </simpara>\r
 764 </listitem>\r
 765 <listitem>\r
 766 <simpara>\r
 767 a file in the <emphasis>$GIT_DIR/branches</emphasis> directory.\r
 768 </simpara>\r
 769 </listitem>\r
 770 </itemizedlist>\r
 771 <simpara>All of these also allow you to omit the refspec from the command line\r
 772 because they each contain a refspec which git will use by default.</simpara>\r
 773 <section id="git-pull(1)__named_remote_in_configuration_file">\r
 774 <title>Named remote in configuration file</title>\r
 775 <simpara>You can choose to provide the name of a remote which you had previously\r
 776 configured using <xref linkend="git-remote(1)" />, <xref linkend="git-config(1)" />\r
 777 or even by a manual edit to the <emphasis>$GIT_DIR/config</emphasis> file.  The URL of\r
 778 this remote will be used to access the repository.  The refspec\r
 779 of this remote will be used by default when you do\r
 780 not provide a refspec on the command line.  The entry in the\r
 781 config file would appear like this:</simpara>\r
 782 <screen>        [remote "&lt;name&gt;"]\r
 783                 url = &lt;url&gt;\r
 784                 pushurl = &lt;pushurl&gt;\r
 785                 push = &lt;refspec&gt;\r
 786                 fetch = &lt;refspec&gt;</screen>\r
 787 <simpara>The <emphasis>&lt;pushurl&gt;</emphasis> is used for pushes only. It is optional and defaults\r
 788 to <emphasis>&lt;url&gt;</emphasis>.</simpara>\r
 789 </section>\r
 790 <section id="git-pull(1)__named_file_in_emphasis_git_dir_remotes_emphasis">\r
 791 <title>Named file in <emphasis>$GIT_DIR/remotes</emphasis></title>\r
 792 <simpara>You can choose to provide the name of a\r
 793 file in <emphasis>$GIT_DIR/remotes</emphasis>.  The URL\r
 794 in this file will be used to access the repository.  The refspec\r
 795 in this file will be used as default when you do not\r
 796 provide a refspec on the command line.  This file should have the\r
 797 following format:</simpara>\r
 798 <screen>        URL: one of the above URL format\r
 799         Push: &lt;refspec&gt;\r
 800         Pull: &lt;refspec&gt;</screen>\r
 801 <simpara><emphasis>Push:</emphasis> lines are used by <emphasis>git push</emphasis> and\r
 802 <emphasis>Pull:</emphasis> lines are used by <emphasis>git pull</emphasis> and <emphasis>git fetch</emphasis>.\r
 803 Multiple <emphasis>Push:</emphasis> and <emphasis>Pull:</emphasis> lines may\r
 804 be specified for additional branch mappings.</simpara>\r
 805 </section>\r
 806 <section id="git-pull(1)__named_file_in_emphasis_git_dir_branches_emphasis">\r
 807 <title>Named file in <emphasis>$GIT_DIR/branches</emphasis></title>\r
 808 <simpara>You can choose to provide the name of a\r
 809 file in <emphasis>$GIT_DIR/branches</emphasis>.\r
 810 The URL in this file will be used to access the repository.\r
 811 This file should have the following format:</simpara>\r
 812 <screen>        &lt;url&gt;#&lt;head&gt;</screen>\r
 813 <simpara><emphasis>&lt;url&gt;</emphasis> is required; <emphasis>#&lt;head&gt;</emphasis> is optional.</simpara>\r
 814 <simpara>Depending on the operation, git will use one of the following\r
 815 refspecs, if you don't provide one on the command line.\r
 816 <emphasis>&lt;branch&gt;</emphasis> is the name of this file in <emphasis>$GIT_DIR/branches</emphasis> and\r
 817 <emphasis>&lt;head&gt;</emphasis> defaults to <emphasis>master</emphasis>.</simpara>\r
 818 <simpara>git fetch uses:</simpara>\r
 819 <screen>        refs/heads/&lt;head&gt;:refs/heads/&lt;branch&gt;</screen>\r
 820 <simpara>git push uses:</simpara>\r
 821 <screen>        HEAD:refs/heads/&lt;head&gt;</screen>\r
 822 </section>\r
 823 </simplesect>\r
 824 <simplesect id="git-pull(1)__merge_strategies">\r
 825 <title>MERGE STRATEGIES</title>\r
 826 <simpara>The merge mechanism (<emphasis>git merge</emphasis> and <emphasis>git pull</emphasis> commands) allows the\r
 827 backend <emphasis>merge strategies</emphasis> to be chosen with <emphasis>-s</emphasis> option.  Some strategies\r
 828 can also take their own options, which can be passed by giving <emphasis>-X&lt;option&gt;</emphasis>\r
 829 arguments to <emphasis>git merge</emphasis> and/or <emphasis>git pull</emphasis>.</simpara>\r
 830 <variablelist>\r
 831 <varlistentry>\r
 832 <term>\r
 833 resolve\r
 834 </term>\r
 835 <listitem>\r
 836 <simpara>\r
 837         This can only resolve two heads (i.e. the current branch\r
 838         and another branch you pulled from) using a 3-way merge\r
 839         algorithm.  It tries to carefully detect criss-cross\r
 840         merge ambiguities and is considered generally safe and\r
 841         fast.\r
 842 </simpara>\r
 843 </listitem>\r
 844 </varlistentry>\r
 845 <varlistentry>\r
 846 <term>\r
 847 recursive\r
 848 </term>\r
 849 <listitem>\r
 850 <simpara>\r
 851         This can only resolve two heads using a 3-way merge\r
 852         algorithm.  When there is more than one common\r
 853         ancestor that can be used for 3-way merge, it creates a\r
 854         merged tree of the common ancestors and uses that as\r
 855         the reference tree for the 3-way merge.  This has been\r
 856         reported to result in fewer merge conflicts without\r
 857         causing mismerges by tests done on actual merge commits\r
 858         taken from Linux 2.6 kernel development history.\r
 859         Additionally this can detect and handle merges involving\r
 860         renames.  This is the default merge strategy when\r
 861         pulling or merging one branch.\r
 862 </simpara>\r
 863 <simpara>The <emphasis>recursive</emphasis> strategy can take the following options:</simpara>\r
 864 <variablelist>\r
 865 <varlistentry>\r
 866 <term>\r
 867 ours\r
 868 </term>\r
 869 <listitem>\r
 870 <simpara>\r
 871         This option forces conflicting hunks to be auto-resolved cleanly by\r
 872         favoring <emphasis>our</emphasis> version.  Changes from the other tree that do not\r
 873         conflict with our side are reflected to the merge result.\r
 874         For a binary file, the entire contents are taken from our side.\r
 875 </simpara>\r
 876 <simpara>This should not be confused with the <emphasis>ours</emphasis> merge strategy, which does not\r
 877 even look at what the other tree contains at all.  It discards everything\r
 878 the other tree did, declaring <emphasis>our</emphasis> history contains all that happened in it.</simpara>\r
 879 </listitem>\r
 880 </varlistentry>\r
 881 <varlistentry>\r
 882 <term>\r
 883 theirs\r
 884 </term>\r
 885 <listitem>\r
 886 <simpara>\r
 887         This is the opposite of <emphasis>ours</emphasis>.\r
 888 </simpara>\r
 889 </listitem>\r
 890 </varlistentry>\r
 891 <varlistentry>\r
 892 <term>\r
 893 patience\r
 894 </term>\r
 895 <listitem>\r
 896 <simpara>\r
 897         With this option, <emphasis>merge-recursive</emphasis> spends a little extra time\r
 898         to avoid mismerges that sometimes occur due to unimportant\r
 899         matching lines (e.g., braces from distinct functions).  Use\r
 900         this when the branches to be merged have diverged wildly.\r
 901         See also <xref linkend="git-diff(1)" /> <emphasis>--patience</emphasis>.\r
 902 </simpara>\r
 903 </listitem>\r
 904 </varlistentry>\r
 905 <varlistentry>\r
 906 <term>\r
 907 diff-algorithm=[patience|minimal|histogram|myers]\r
 908 </term>\r
 909 <listitem>\r
 910 <simpara>\r
 911         Tells <emphasis>merge-recursive</emphasis> to use a different diff algorithm, which\r
 912         can help avoid mismerges that occur due to unimportant matching\r
 913         lines (such as braces from distinct functions).  See also\r
 914         <xref linkend="git-diff(1)" /> <emphasis>--diff-algorithm</emphasis>.\r
 915 </simpara>\r
 916 </listitem>\r
 917 </varlistentry>\r
 918 <varlistentry>\r
 919 <term>\r
 920 ignore-space-change\r
 921 </term>\r
 922 <term>\r
 923 ignore-all-space\r
 924 </term>\r
 925 <term>\r
 926 ignore-space-at-eol\r
 927 </term>\r
 928 <listitem>\r
 929 <simpara>\r
 930         Treats lines with the indicated type of whitespace change as\r
 931         unchanged for the sake of a three-way merge.  Whitespace\r
 932         changes mixed with other changes to a line are not ignored.\r
 933         See also <xref linkend="git-diff(1)" /> <emphasis>-b</emphasis>, <emphasis>-w</emphasis>, and\r
 934         <emphasis>--ignore-space-at-eol</emphasis>.\r
 935 </simpara>\r
 936 <itemizedlist>\r
 937 <listitem>\r
 938 <simpara>\r
 939 If <emphasis>their</emphasis> version only introduces whitespace changes to a line,\r
 940   <emphasis>our</emphasis> version is used;\r
 941 </simpara>\r
 942 </listitem>\r
 943 <listitem>\r
 944 <simpara>\r
 945 If <emphasis>our</emphasis> version introduces whitespace changes but <emphasis>their</emphasis>\r
 946   version includes a substantial change, <emphasis>their</emphasis> version is used;\r
 947 </simpara>\r
 948 </listitem>\r
 949 <listitem>\r
 950 <simpara>\r
 951 Otherwise, the merge proceeds in the usual way.\r
 952 </simpara>\r
 953 </listitem>\r
 954 </itemizedlist>\r
 955 </listitem>\r
 956 </varlistentry>\r
 957 <varlistentry>\r
 958 <term>\r
 959 renormalize\r
 960 </term>\r
 961 <listitem>\r
 962 <simpara>\r
 963         This runs a virtual check-out and check-in of all three stages\r
 964         of a file when resolving a three-way merge.  This option is\r
 965         meant to be used when merging branches with different clean\r
 966         filters or end-of-line normalization rules.  See "Merging\r
 967         branches with differing checkin/checkout attributes" in\r
 968         <xref linkend="gitattributes(5)" /> for details.\r
 969 </simpara>\r
 970 </listitem>\r
 971 </varlistentry>\r
 972 <varlistentry>\r
 973 <term>\r
 974 no-renormalize\r
 975 </term>\r
 976 <listitem>\r
 977 <simpara>\r
 978         Disables the <emphasis>renormalize</emphasis> option.  This overrides the\r
 979         <emphasis>merge.renormalize</emphasis> configuration variable.\r
 980 </simpara>\r
 981 </listitem>\r
 982 </varlistentry>\r
 983 <varlistentry>\r
 984 <term>\r
 985 no-renames\r
 986 </term>\r
 987 <listitem>\r
 988 <simpara>\r
 989         Turn off rename detection.\r
 990         See also <xref linkend="git-diff(1)" /> <emphasis>--no-renames</emphasis>.\r
 991 </simpara>\r
 992 </listitem>\r
 993 </varlistentry>\r
 994 <varlistentry>\r
 995 <term>\r
 996 find-renames[=&lt;n&gt;]\r
 997 </term>\r
 998 <listitem>\r
 999 <simpara>\r
1000         Turn on rename detection, optionally setting the similarity\r
1001         threshold.  This is the default.\r
1002         See also <xref linkend="git-diff(1)" /> <emphasis>--find-renames</emphasis>.\r
1003 </simpara>\r
1004 </listitem>\r
1005 </varlistentry>\r
1006 <varlistentry>\r
1007 <term>\r
1008 rename-threshold=&lt;n&gt;\r
1009 </term>\r
1010 <listitem>\r
1011 <simpara>\r
1012         Deprecated synonym for <emphasis>find-renames=&lt;n&gt;</emphasis>.\r
1013 </simpara>\r
1014 </listitem>\r
1015 </varlistentry>\r
1016 <varlistentry>\r
1017 <term>\r
1018 subtree[=&lt;path&gt;]\r
1019 </term>\r
1020 <listitem>\r
1021 <simpara>\r
1022         This option is a more advanced form of <emphasis>subtree</emphasis> strategy, where\r
1023         the strategy makes a guess on how two trees must be shifted to\r
1024         match with each other when merging.  Instead, the specified path\r
1025         is prefixed (or stripped from the beginning) to make the shape of\r
1026         two trees to match.\r
1027 </simpara>\r
1028 </listitem>\r
1029 </varlistentry>\r
1030 </variablelist>\r
1031 </listitem>\r
1032 </varlistentry>\r
1033 <varlistentry>\r
1034 <term>\r
1035 octopus\r
1036 </term>\r
1037 <listitem>\r
1038 <simpara>\r
1039         This resolves cases with more than two heads, but refuses to do\r
1040         a complex merge that needs manual resolution.  It is\r
1041         primarily meant to be used for bundling topic branch\r
1042         heads together.  This is the default merge strategy when\r
1043         pulling or merging more than one branch.\r
1044 </simpara>\r
1045 </listitem>\r
1046 </varlistentry>\r
1047 <varlistentry>\r
1048 <term>\r
1049 ours\r
1050 </term>\r
1051 <listitem>\r
1052 <simpara>\r
1053         This resolves any number of heads, but the resulting tree of the\r
1054         merge is always that of the current branch head, effectively\r
1055         ignoring all changes from all other branches.  It is meant to\r
1056         be used to supersede old development history of side\r
1057         branches.  Note that this is different from the -Xours option to\r
1058         the <emphasis>recursive</emphasis> merge strategy.\r
1059 </simpara>\r
1060 </listitem>\r
1061 </varlistentry>\r
1062 <varlistentry>\r
1063 <term>\r
1064 subtree\r
1065 </term>\r
1066 <listitem>\r
1067 <simpara>\r
1068         This is a modified recursive strategy. When merging trees A and\r
1069         B, if B corresponds to a subtree of A, B is first adjusted to\r
1070         match the tree structure of A, instead of reading the trees at\r
1071         the same level. This adjustment is also done to the common\r
1072         ancestor tree.\r
1073 </simpara>\r
1074 </listitem>\r
1075 </varlistentry>\r
1076 </variablelist>\r
1077 <simpara>With the strategies that use 3-way merge (including the default, <emphasis>recursive</emphasis>),\r
1078 if a change is made on both branches, but later reverted on one of the\r
1079 branches, that change will be present in the merged result; some people find\r
1080 this behavior confusing.  It occurs because only the heads and the merge base\r
1081 are considered when performing a merge, not the individual commits.  The merge\r
1082 algorithm therefore considers the reverted change as no change at all, and\r
1083 substitutes the changed version instead.</simpara>\r
1084 </simplesect>\r
1085 <simplesect id="git-pull(1)__default_behaviour">\r
1086 <title>DEFAULT BEHAVIOUR</title>\r
1087 <simpara>Often people use <emphasis>git pull</emphasis> without giving any parameter.\r
1088 Traditionally, this has been equivalent to saying <emphasis>git pull\r
1089 origin</emphasis>.  However, when configuration <emphasis>branch.&lt;name&gt;.remote</emphasis> is\r
1090 present while on branch <emphasis>&lt;name&gt;</emphasis>, that value is used instead of\r
1091 <emphasis>origin</emphasis>.</simpara>\r
1092 <simpara>In order to determine what URL to use to fetch from, the value\r
1093 of the configuration <emphasis>remote.&lt;origin&gt;.url</emphasis> is consulted\r
1094 and if there is not any such variable, the value on <emphasis>URL: ` line\r
1095 in `$GIT_DIR/remotes/&lt;origin&gt;</emphasis> file is used.</simpara>\r
1096 <simpara>In order to determine what remote branches to fetch (and\r
1097 optionally store in the remote-tracking branches) when the command is\r
1098 run without any refspec parameters on the command line, values\r
1099 of the configuration variable <emphasis>remote.&lt;origin&gt;.fetch</emphasis> are\r
1100 consulted, and if there aren't any, <emphasis>$GIT_DIR/remotes/&lt;origin&gt;</emphasis>\r
1101 file is consulted and its `Pull: ` lines are used.\r
1102 In addition to the refspec formats described in the OPTIONS\r
1103 section, you can have a globbing refspec that looks like this:</simpara>\r
1104 <screen>refs/heads/*:refs/remotes/origin/*</screen>\r
1105 <simpara>A globbing refspec must have a non-empty RHS (i.e. must store\r
1106 what were fetched in remote-tracking branches), and its LHS and RHS\r
1107 must end with <emphasis>/*</emphasis>.  The above specifies that all remote\r
1108 branches are tracked using remote-tracking branches in\r
1109 <emphasis>refs/remotes/origin/</emphasis> hierarchy under the same name.</simpara>\r
1110 <simpara>The rule to determine which remote branch to merge after\r
1111 fetching is a bit involved, in order not to break backward\r
1112 compatibility.</simpara>\r
1113 <simpara>If explicit refspecs were given on the command\r
1114 line of <emphasis>git pull</emphasis>, they are all merged.</simpara>\r
1115 <simpara>When no refspec was given on the command line, then <emphasis>git pull</emphasis>\r
1116 uses the refspec from the configuration or\r
1117 <emphasis>$GIT_DIR/remotes/&lt;origin&gt;</emphasis>.  In such cases, the following\r
1118 rules apply:</simpara>\r
1119 <orderedlist numeration="arabic">\r
1120 <listitem>\r
1121 <simpara>\r
1122 If <emphasis>branch.&lt;name&gt;.merge</emphasis> configuration for the current\r
1123   branch <emphasis>&lt;name&gt;</emphasis> exists, that is the name of the branch at the\r
1124   remote site that is merged.\r
1125 </simpara>\r
1126 </listitem>\r
1127 <listitem>\r
1128 <simpara>\r
1129 If the refspec is a globbing one, nothing is merged.\r
1130 </simpara>\r
1131 </listitem>\r
1132 <listitem>\r
1133 <simpara>\r
1134 Otherwise the remote branch of the first refspec is merged.\r
1135 </simpara>\r
1136 </listitem>\r
1137 </orderedlist>\r
1138 </simplesect>\r
1139 <simplesect id="git-pull(1)__examples">\r
1140 <title>EXAMPLES</title>\r
1141 <itemizedlist>\r
1142 <listitem>\r
1143 <simpara>\r
1144 Update the remote-tracking branches for the repository\r
1145   you cloned from, then merge one of them into your\r
1146   current branch:\r
1147 </simpara>\r
1148 <screen>$ git pull, git pull origin</screen>\r
1149 <simpara>Normally the branch merged in is the HEAD of the remote repository,\r
1150 but the choice is determined by the branch.&lt;name&gt;.remote and\r
1151 branch.&lt;name&gt;.merge options; see <xref linkend="git-config(1)" /> for details.</simpara>\r
1152 </listitem>\r
1153 <listitem>\r
1154 <simpara>\r
1155 Merge into the current branch the remote branch <emphasis>next</emphasis>:\r
1156 </simpara>\r
1157 <screen>$ git pull origin next</screen>\r
1158 <simpara>This leaves a copy of <emphasis>next</emphasis> temporarily in FETCH_HEAD, but\r
1159 does not update any remote-tracking branches. Using remote-tracking\r
1160 branches, the same can be done by invoking fetch and merge:</simpara>\r
1161 <screen>$ git fetch origin\r
1162 $ git merge origin/next</screen>\r
1163 </listitem>\r
1164 </itemizedlist>\r
1165 <simpara>If you tried a pull which resulted in complex conflicts and\r
1166 would want to start over, you can recover with <emphasis>git reset</emphasis>.</simpara>\r
1167 </simplesect>\r
1168 <simplesect id="git-pull(1)__bugs">\r
1169 <title>BUGS</title>\r
1170 <simpara>Using --recurse-submodules can only fetch new commits in already checked\r
1171 out submodules right now. When e.g. upstream added a new submodule in the\r
1172 just fetched commits of the superproject the submodule itself can not be\r
1173 fetched, making it impossible to check out that submodule later without\r
1174 having to do a fetch again. This is expected to be fixed in a future Git\r
1175 version.</simpara>\r
1176 </simplesect>\r
1177 <simplesect id="git-pull(1)__see_also">\r
1178 <title>SEE ALSO</title>\r
1179 <simpara><xref linkend="git-fetch(1)" />, <xref linkend="git-merge(1)" />, <xref linkend="git-config(1)" /></simpara>\r
1180 </simplesect>\r
1181 <simplesect id="git-pull(1)__git">\r
1182 <title>GIT</title>\r
1183 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
1184 </simplesect>\r
1185 </sect2>\r