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

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE sect2 SYSTEM "../../../dtd/dblite.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> [&lt;options&gt;] [&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 canceled 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 populated submodules should\r
 101         be fetched, and if the working trees of active submodules should be\r
 102         updated, too (see <xref linkend="git-fetch(1)" />, <xref linkend="git-config(1)" /> and\r
 103         <xref linkend="gitmodules(5)" />).\r
 104 </simpara>\r
 105 <simpara>If the checkout is done via rebase, local submodule commits are rebased as well.</simpara>\r
 106 <simpara>If the update is done via merge, the submodule conflicts are resolved and checked out.</simpara>\r
 107 </listitem>\r
 108 </varlistentry>\r
 109 </variablelist>\r
 110 <section id="git-pull(1)__options_related_to_merging">\r
 111 <title>Options related to merging</title>\r
 112 <variablelist>\r
 113 <varlistentry>\r
 114 <term>\r
 115 --commit\r
 116 </term>\r
 117 <term>\r
 118 --no-commit\r
 119 </term>\r
 120 <listitem>\r
 121 <simpara>\r
 122         Perform the merge and commit the result. This option can\r
 123         be used to override --no-commit.\r
 124 </simpara>\r
 125 <simpara>With --no-commit perform the merge and stop just before creating\r
 126 a merge commit, to give the user a chance to inspect and further\r
 127 tweak the merge result before committing.</simpara>\r
 128 <simpara>Note that fast-forward updates do not create a merge commit and\r
 129 therefore there is no way to stop those merges with --no-commit.\r
 130 Thus, if you want to ensure your branch is not changed or updated\r
 131 by the merge command, use --no-ff with --no-commit.</simpara>\r
 132 </listitem>\r
 133 </varlistentry>\r
 134 <varlistentry>\r
 135 <term>\r
 136 --edit\r
 137 </term>\r
 138 <term>\r
 139 -e\r
 140 </term>\r
 141 <term>\r
 142 --no-edit\r
 143 </term>\r
 144 <listitem>\r
 145 <simpara>\r
 146         Invoke an editor before committing successful mechanical merge to\r
 147         further edit the auto-generated merge message, so that the user\r
 148         can explain and justify the merge. The <emphasis>--no-edit</emphasis> option can be\r
 149         used to accept the auto-generated message (this is generally\r
 150         discouraged).\r
 151 </simpara>\r
 152 <simpara>Older scripts may depend on the historical behaviour of not allowing the\r
 153 user to edit the merge log message. They will see an editor opened when\r
 154 they run <emphasis>git merge</emphasis>. To make it easier to adjust such scripts to the\r
 155 updated behaviour, the environment variable <emphasis>GIT_MERGE_AUTOEDIT</emphasis> can be\r
 156 set to <emphasis>no</emphasis> at the beginning of them.</simpara>\r
 157 </listitem>\r
 158 </varlistentry>\r
 159 <varlistentry>\r
 160 <term>\r
 161 --cleanup=&lt;mode&gt;\r
 162 </term>\r
 163 <listitem>\r
 164 <simpara>\r
 165         This option determines how the merge message will be cleaned up before\r
 166         committing. See <xref linkend="git-commit(1)" /> for more details. In addition, if\r
 167         the <emphasis>&lt;mode&gt;</emphasis> is given a value of <emphasis>scissors</emphasis>, scissors will be appended\r
 168         to <emphasis>MERGE_MSG</emphasis> before being passed on to the commit machinery in the\r
 169         case of a merge conflict.\r
 170 </simpara>\r
 171 </listitem>\r
 172 </varlistentry>\r
 173 <varlistentry>\r
 174 <term>\r
 175 --ff\r
 176 </term>\r
 177 <term>\r
 178 --no-ff\r
 179 </term>\r
 180 <term>\r
 181 --ff-only\r
 182 </term>\r
 183 <listitem>\r
 184 <simpara>\r
 185         Specifies how a merge is handled when the merged-in history is\r
 186         already a descendant of the current history.  <emphasis>--ff</emphasis> is the\r
 187         default unless merging an annotated (and possibly signed) tag\r
 188         that is not stored in its natural place in the <emphasis>refs/tags/</emphasis>\r
 189         hierarchy, in which case <emphasis>--no-ff</emphasis> is assumed.\r
 190 </simpara>\r
 191 <simpara>With <emphasis>--ff</emphasis>, when possible resolve the merge as a fast-forward (only\r
 192 update the branch pointer to match the merged branch; do not create a\r
 193 merge commit).  When not possible (when the merged-in history is not a\r
 194 descendant of the current history), create a merge commit.</simpara>\r
 195 <simpara>With <emphasis>--no-ff</emphasis>, create a merge commit in all cases, even when the merge\r
 196 could instead be resolved as a fast-forward.</simpara>\r
 197 <simpara>With <emphasis>--ff-only</emphasis>, resolve the merge as a fast-forward when possible.\r
 198 When not possible, refuse to merge and exit with a non-zero status.</simpara>\r
 199 </listitem>\r
 200 </varlistentry>\r
 201 <varlistentry>\r
 202 <term>\r
 203 -S[&lt;keyid&gt;]\r
 204 </term>\r
 205 <term>\r
 206 --gpg-sign[=&lt;keyid&gt;]\r
 207 </term>\r
 208 <term>\r
 209 --no-gpg-sign\r
 210 </term>\r
 211 <listitem>\r
 212 <simpara>\r
 213         GPG-sign the resulting merge commit. The <emphasis>keyid</emphasis> argument is\r
 214         optional and defaults to the committer identity; if specified,\r
 215         it must be stuck to the option without a space. <emphasis>--no-gpg-sign</emphasis>\r
 216         is useful to countermand both <emphasis>commit.gpgSign</emphasis> configuration variable,\r
 217         and earlier <emphasis>--gpg-sign</emphasis>.\r
 218 </simpara>\r
 219 </listitem>\r
 220 </varlistentry>\r
 221 <varlistentry>\r
 222 <term>\r
 223 --log[=&lt;n&gt;]\r
 224 </term>\r
 225 <term>\r
 226 --no-log\r
 227 </term>\r
 228 <listitem>\r
 229 <simpara>\r
 230         In addition to branch names, populate the log message with\r
 231         one-line descriptions from at most &lt;n&gt; actual commits that are being\r
 232         merged. See also <xref linkend="git-fmt-merge-msg(1)" />.\r
 233 </simpara>\r
 234 <simpara>With --no-log do not list one-line descriptions from the\r
 235 actual commits being merged.</simpara>\r
 236 </listitem>\r
 237 </varlistentry>\r
 238 <varlistentry>\r
 239 <term>\r
 240 --signoff\r
 241 </term>\r
 242 <term>\r
 243 --no-signoff\r
 244 </term>\r
 245 <listitem>\r
 246 <simpara>\r
 247         Add Signed-off-by line by the committer at the end of the commit\r
 248         log message.  The meaning of a signoff depends on the project,\r
 249         but it typically certifies that committer has\r
 250         the rights to submit this work under the same license and\r
 251         agrees to a Developer Certificate of Origin\r
 252         (see <ulink url="http://developercertificate.org/">http://developercertificate.org/</ulink> for more information).\r
 253 </simpara>\r
 254 <simpara>With --no-signoff do not add a Signed-off-by line.</simpara>\r
 255 </listitem>\r
 256 </varlistentry>\r
 257 <varlistentry>\r
 258 <term>\r
 259 --stat\r
 260 </term>\r
 261 <term>\r
 262 -n\r
 263 </term>\r
 264 <term>\r
 265 --no-stat\r
 266 </term>\r
 267 <listitem>\r
 268 <simpara>\r
 269         Show a diffstat at the end of the merge. The diffstat is also\r
 270         controlled by the configuration option merge.stat.\r
 271 </simpara>\r
 272 <simpara>With -n or --no-stat do not show a diffstat at the end of the\r
 273 merge.</simpara>\r
 274 </listitem>\r
 275 </varlistentry>\r
 276 <varlistentry>\r
 277 <term>\r
 278 --squash\r
 279 </term>\r
 280 <term>\r
 281 --no-squash\r
 282 </term>\r
 283 <listitem>\r
 284 <simpara>\r
 285         Produce the working tree and index state as if a real merge\r
 286         happened (except for the merge information), but do not actually\r
 287         make a commit, move the <emphasis>HEAD</emphasis>, or record <emphasis>$GIT_DIR/MERGE_HEAD</emphasis>\r
 288         (to cause the next <emphasis>git commit</emphasis> command to create a merge\r
 289         commit).  This allows you to create a single commit on top of\r
 290         the current branch whose effect is the same as merging another\r
 291         branch (or more in case of an octopus).\r
 292 </simpara>\r
 293 <simpara>With --no-squash perform the merge and commit the result. This\r
 294 option can be used to override --squash.</simpara>\r
 295 <simpara>With --squash, --commit is not allowed, and will fail.</simpara>\r
 296 </listitem>\r
 297 </varlistentry>\r
 298 <varlistentry>\r
 299 <term>\r
 300 --no-verify\r
 301 </term>\r
 302 <listitem>\r
 303 <simpara>\r
 304         This option bypasses the pre-merge and commit-msg hooks.\r
 305         See also <xref linkend="githooks(5)" />.\r
 306 </simpara>\r
 307 </listitem>\r
 308 </varlistentry>\r
 309 <varlistentry>\r
 310 <term>\r
 311 -s &lt;strategy&gt;\r
 312 </term>\r
 313 <term>\r
 314 --strategy=&lt;strategy&gt;\r
 315 </term>\r
 316 <listitem>\r
 317 <simpara>\r
 318         Use the given merge strategy; can be supplied more than\r
 319         once to specify them in the order they should be tried.\r
 320         If there is no <emphasis>-s</emphasis> option, a built-in list of strategies\r
 321         is used instead (<emphasis>git merge-recursive</emphasis> when merging a single\r
 322         head, <emphasis>git merge-octopus</emphasis> otherwise).\r
 323 </simpara>\r
 324 </listitem>\r
 325 </varlistentry>\r
 326 <varlistentry>\r
 327 <term>\r
 328 -X &lt;option&gt;\r
 329 </term>\r
 330 <term>\r
 331 --strategy-option=&lt;option&gt;\r
 332 </term>\r
 333 <listitem>\r
 334 <simpara>\r
 335         Pass merge strategy specific option through to the merge\r
 336         strategy.\r
 337 </simpara>\r
 338 </listitem>\r
 339 </varlistentry>\r
 340 <varlistentry>\r
 341 <term>\r
 342 --verify-signatures\r
 343 </term>\r
 344 <term>\r
 345 --no-verify-signatures\r
 346 </term>\r
 347 <listitem>\r
 348 <simpara>\r
 349         Verify that the tip commit of the side branch being merged is\r
 350         signed with a valid key, i.e. a key that has a valid uid: in the\r
 351         default trust model, this means the signing key has been signed by\r
 352         a trusted key.  If the tip commit of the side branch is not signed\r
 353         with a valid key, the merge is aborted.\r
 354 </simpara>\r
 355 </listitem>\r
 356 </varlistentry>\r
 357 <varlistentry>\r
 358 <term>\r
 359 --summary\r
 360 </term>\r
 361 <term>\r
 362 --no-summary\r
 363 </term>\r
 364 <listitem>\r
 365 <simpara>\r
 366         Synonyms to --stat and --no-stat; these are deprecated and will be\r
 367         removed in the future.\r
 368 </simpara>\r
 369 </listitem>\r
 370 </varlistentry>\r
 371 <varlistentry>\r
 372 <term>\r
 373 --autostash\r
 374 </term>\r
 375 <term>\r
 376 --no-autostash\r
 377 </term>\r
 378 <listitem>\r
 379 <simpara>\r
 380         Automatically create a temporary stash entry before the operation\r
 381         begins, and apply it after the operation ends.  This means\r
 382         that you can run the operation on a dirty worktree.  However, use\r
 383         with care: the final stash application after a successful\r
 384         merge might result in non-trivial conflicts.\r
 385 </simpara>\r
 386 </listitem>\r
 387 </varlistentry>\r
 388 <varlistentry>\r
 389 <term>\r
 390 --allow-unrelated-histories\r
 391 </term>\r
 392 <listitem>\r
 393 <simpara>\r
 394         By default, <emphasis>git merge</emphasis> command refuses to merge histories\r
 395         that do not share a common ancestor.  This option can be\r
 396         used to override this safety when merging histories of two\r
 397         projects that started their lives independently. As that is\r
 398         a very rare occasion, no configuration variable to enable\r
 399         this by default exists and will not be added.\r
 400 </simpara>\r
 401 </listitem>\r
 402 </varlistentry>\r
 403 <varlistentry>\r
 404 <term>\r
 405 -r\r
 406 </term>\r
 407 <term>\r
 408 --rebase[=false|true|merges|preserve|interactive]\r
 409 </term>\r
 410 <listitem>\r
 411 <simpara>\r
 412         When true, rebase the current branch on top of the upstream\r
 413         branch after fetching. If there is a remote-tracking branch\r
 414         corresponding to the upstream branch and the upstream branch\r
 415         was rebased since last fetched, the rebase uses that information\r
 416         to avoid rebasing non-local changes.\r
 417 </simpara>\r
 418 <simpara>When set to <emphasis>merges</emphasis>, rebase using <emphasis>git rebase --rebase-merges</emphasis> so that\r
 419 the local merge commits are included in the rebase (see\r
 420 <xref linkend="git-rebase(1)" /> for details).</simpara>\r
 421 <simpara>When set to <emphasis>preserve</emphasis> (deprecated in favor of <emphasis>merges</emphasis>), rebase with the\r
 422 <emphasis>--preserve-merges</emphasis> option passed to <emphasis>git rebase</emphasis> so that locally created\r
 423 merge commits will not be flattened.</simpara>\r
 424 <simpara>When false, merge the current branch into the upstream branch.</simpara>\r
 425 <simpara>When <emphasis>interactive</emphasis>, enable the interactive mode of rebase.</simpara>\r
 426 <simpara>See <emphasis>pull.rebase</emphasis>, <emphasis>branch.&lt;name&gt;.rebase</emphasis> and <emphasis>branch.autoSetupRebase</emphasis> in\r
 427 <xref linkend="git-config(1)" /> if you want to make <emphasis>git pull</emphasis> always use\r
 428 <emphasis>--rebase</emphasis> instead of merging.</simpara>\r
 429 <note><simpara>This is a potentially <emphasis>dangerous</emphasis> mode of operation.\r
 430 It rewrites history, which does not bode well when you\r
 431 published that history already.  Do <emphasis role="strong">not</emphasis> use this option\r
 432 unless you have read <xref linkend="git-rebase(1)" /> carefully.</simpara></note>\r
 433 </listitem>\r
 434 </varlistentry>\r
 435 <varlistentry>\r
 436 <term>\r
 437 --no-rebase\r
 438 </term>\r
 439 <listitem>\r
 440 <simpara>\r
 441         Override earlier --rebase.\r
 442 </simpara>\r
 443 </listitem>\r
 444 </varlistentry>\r
 445 </variablelist>\r
 446 </section>\r
 447 <section id="git-pull(1)__options_related_to_fetching">\r
 448 <title>Options related to fetching</title>\r
 449 <variablelist>\r
 450 <varlistentry>\r
 451 <term>\r
 452 --all\r
 453 </term>\r
 454 <listitem>\r
 455 <simpara>\r
 456         Fetch all remotes.\r
 457 </simpara>\r
 458 </listitem>\r
 459 </varlistentry>\r
 460 <varlistentry>\r
 461 <term>\r
 462 -a\r
 463 </term>\r
 464 <term>\r
 465 --append\r
 466 </term>\r
 467 <listitem>\r
 468 <simpara>\r
 469         Append ref names and object names of fetched refs to the\r
 470         existing contents of <emphasis>.git/FETCH_HEAD</emphasis>.  Without this\r
 471         option old data in <emphasis>.git/FETCH_HEAD</emphasis> will be overwritten.\r
 472 </simpara>\r
 473 </listitem>\r
 474 </varlistentry>\r
 475 <varlistentry>\r
 476 <term>\r
 477 --depth=&lt;depth&gt;\r
 478 </term>\r
 479 <listitem>\r
 480 <simpara>\r
 481         Limit fetching to the specified number of commits from the tip of\r
 482         each remote branch history. If fetching to a <emphasis>shallow</emphasis> repository\r
 483         created by <emphasis>git clone</emphasis> with <emphasis>--depth=&lt;depth&gt;</emphasis> option (see\r
 484         <xref linkend="git-clone(1)" />), deepen or shorten the history to the specified\r
 485         number of commits. Tags for the deepened commits are not fetched.\r
 486 </simpara>\r
 487 </listitem>\r
 488 </varlistentry>\r
 489 <varlistentry>\r
 490 <term>\r
 491 --deepen=&lt;depth&gt;\r
 492 </term>\r
 493 <listitem>\r
 494 <simpara>\r
 495         Similar to --depth, except it specifies the number of commits\r
 496         from the current shallow boundary instead of from the tip of\r
 497         each remote branch history.\r
 498 </simpara>\r
 499 </listitem>\r
 500 </varlistentry>\r
 501 <varlistentry>\r
 502 <term>\r
 503 --shallow-since=&lt;date&gt;\r
 504 </term>\r
 505 <listitem>\r
 506 <simpara>\r
 507         Deepen or shorten the history of a shallow repository to\r
 508         include all reachable commits after &lt;date&gt;.\r
 509 </simpara>\r
 510 </listitem>\r
 511 </varlistentry>\r
 512 <varlistentry>\r
 513 <term>\r
 514 --shallow-exclude=&lt;revision&gt;\r
 515 </term>\r
 516 <listitem>\r
 517 <simpara>\r
 518         Deepen or shorten the history of a shallow repository to\r
 519         exclude commits reachable from a specified remote branch or tag.\r
 520         This option can be specified multiple times.\r
 521 </simpara>\r
 522 </listitem>\r
 523 </varlistentry>\r
 524 <varlistentry>\r
 525 <term>\r
 526 --unshallow\r
 527 </term>\r
 528 <listitem>\r
 529 <simpara>\r
 530         If the source repository is complete, convert a shallow\r
 531         repository to a complete one, removing all the limitations\r
 532         imposed by shallow repositories.\r
 533 </simpara>\r
 534 <simpara>If the source repository is shallow, fetch as much as possible so that\r
 535 the current repository has the same history as the source repository.</simpara>\r
 536 </listitem>\r
 537 </varlistentry>\r
 538 <varlistentry>\r
 539 <term>\r
 540 --update-shallow\r
 541 </term>\r
 542 <listitem>\r
 543 <simpara>\r
 544         By default when fetching from a shallow repository,\r
 545         <emphasis>git fetch</emphasis> refuses refs that require updating\r
 546         .git/shallow. This option updates .git/shallow and accept such\r
 547         refs.\r
 548 </simpara>\r
 549 </listitem>\r
 550 </varlistentry>\r
 551 <varlistentry>\r
 552 <term>\r
 553 --negotiation-tip=&lt;commit|glob&gt;\r
 554 </term>\r
 555 <listitem>\r
 556 <simpara>\r
 557         By default, Git will report, to the server, commits reachable\r
 558         from all local refs to find common commits in an attempt to\r
 559         reduce the size of the to-be-received packfile. If specified,\r
 560         Git will only report commits reachable from the given tips.\r
 561         This is useful to speed up fetches when the user knows which\r
 562         local ref is likely to have commits in common with the\r
 563         upstream ref being fetched.\r
 564 </simpara>\r
 565 <simpara>This option may be specified more than once; if so, Git will report\r
 566 commits reachable from any of the given commits.</simpara>\r
 567 <simpara>The argument to this option may be a glob on ref names, a ref, or the (possibly\r
 568 abbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifying\r
 569 this option multiple times, one for each matching ref name.</simpara>\r
 570 <simpara>See also the <emphasis>fetch.negotiationAlgorithm</emphasis> configuration variable\r
 571 documented in <xref linkend="git-config(1)" />.</simpara>\r
 572 </listitem>\r
 573 </varlistentry>\r
 574 <varlistentry>\r
 575 <term>\r
 576 --dry-run\r
 577 </term>\r
 578 <listitem>\r
 579 <simpara>\r
 580         Show what would be done, without making any changes.\r
 581 </simpara>\r
 582 </listitem>\r
 583 </varlistentry>\r
 584 <varlistentry>\r
 585 <term>\r
 586 -f\r
 587 </term>\r
 588 <term>\r
 589 --force\r
 590 </term>\r
 591 <listitem>\r
 592 <simpara>\r
 593         When <emphasis>git fetch</emphasis> is used with <emphasis>&lt;src&gt;:&lt;dst&gt;</emphasis> refspec it may\r
 594         refuse to update the local branch as discussed\r
 595         in the <emphasis>&lt;refspec&gt;</emphasis> part of the <xref linkend="git-fetch(1)" />\r
 596         documentation.\r
 597         This option overrides that check.\r
 598 </simpara>\r
 599 </listitem>\r
 600 </varlistentry>\r
 601 <varlistentry>\r
 602 <term>\r
 603 -k\r
 604 </term>\r
 605 <term>\r
 606 --keep\r
 607 </term>\r
 608 <listitem>\r
 609 <simpara>\r
 610         Keep downloaded pack.\r
 611 </simpara>\r
 612 </listitem>\r
 613 </varlistentry>\r
 614 <varlistentry>\r
 615 <term>\r
 616 -p\r
 617 </term>\r
 618 <term>\r
 619 --prune\r
 620 </term>\r
 621 <listitem>\r
 622 <simpara>\r
 623         Before fetching, remove any remote-tracking references that no\r
 624         longer exist on the remote.  Tags are not subject to pruning\r
 625         if they are fetched only because of the default tag\r
 626         auto-following or due to a --tags option.  However, if tags\r
 627         are fetched due to an explicit refspec (either on the command\r
 628         line or in the remote configuration, for example if the remote\r
 629         was cloned with the --mirror option), then they are also\r
 630         subject to pruning. Supplying <emphasis>--prune-tags</emphasis> is a shorthand for\r
 631         providing the tag refspec.\r
 632 </simpara>\r
 633 </listitem>\r
 634 </varlistentry>\r
 635 <varlistentry>\r
 636 <term>\r
 637 --no-tags\r
 638 </term>\r
 639 <listitem>\r
 640 <simpara>\r
 641         By default, tags that point at objects that are downloaded\r
 642         from the remote repository are fetched and stored locally.\r
 643         This option disables this automatic tag following. The default\r
 644         behavior for a remote may be specified with the remote.&lt;name&gt;.tagOpt\r
 645         setting. See <xref linkend="git-config(1)" />.\r
 646 </simpara>\r
 647 </listitem>\r
 648 </varlistentry>\r
 649 <varlistentry>\r
 650 <term>\r
 651 --refmap=&lt;refspec&gt;\r
 652 </term>\r
 653 <listitem>\r
 654 <simpara>\r
 655         When fetching refs listed on the command line, use the\r
 656         specified refspec (can be given more than once) to map the\r
 657         refs to remote-tracking branches, instead of the values of\r
 658         <emphasis>remote.*.fetch</emphasis> configuration variables for the remote\r
 659         repository.  Providing an empty <emphasis>&lt;refspec&gt;</emphasis> to the\r
 660         <emphasis>--refmap</emphasis> option causes Git to ignore the configured\r
 661         refspecs and rely entirely on the refspecs supplied as\r
 662         command-line arguments. See section on "Configured Remote-tracking\r
 663         Branches" for details.\r
 664 </simpara>\r
 665 </listitem>\r
 666 </varlistentry>\r
 667 <varlistentry>\r
 668 <term>\r
 669 -t\r
 670 </term>\r
 671 <term>\r
 672 --tags\r
 673 </term>\r
 674 <listitem>\r
 675 <simpara>\r
 676         Fetch all tags from the remote (i.e., fetch remote tags\r
 677         <emphasis>refs/tags/*</emphasis> into local tags with the same name), in addition\r
 678         to whatever else would otherwise be fetched.  Using this\r
 679         option alone does not subject tags to pruning, even if --prune\r
 680         is used (though tags may be pruned anyway if they are also the\r
 681         destination of an explicit refspec; see <emphasis>--prune</emphasis>).\r
 682 </simpara>\r
 683 </listitem>\r
 684 </varlistentry>\r
 685 <varlistentry>\r
 686 <term>\r
 687 -j\r
 688 </term>\r
 689 <term>\r
 690 --jobs=&lt;n&gt;\r
 691 </term>\r
 692 <listitem>\r
 693 <simpara>\r
 694         Number of parallel children to be used for all forms of fetching.\r
 695 </simpara>\r
 696 <simpara>If the <emphasis>--multiple</emphasis> option was specified, the different remotes will be fetched\r
 697 in parallel. If multiple submodules are fetched, they will be fetched in\r
 698 parallel. To control them independently, use the config settings\r
 699 <emphasis>fetch.parallel</emphasis> and <emphasis>submodule.fetchJobs</emphasis> (see <xref linkend="git-config(1)" />).</simpara>\r
 700 <simpara>Typically, parallel recursive and multi-remote fetches will be faster. By\r
 701 default fetches are performed sequentially, not in parallel.</simpara>\r
 702 </listitem>\r
 703 </varlistentry>\r
 704 <varlistentry>\r
 705 <term>\r
 706 --set-upstream\r
 707 </term>\r
 708 <listitem>\r
 709 <simpara>\r
 710         If the remote is fetched successfully, pull and add upstream\r
 711         (tracking) reference, used by argument-less\r
 712         <xref linkend="git-pull(1)" /> and other commands. For more information,\r
 713         see <emphasis>branch.&lt;name&gt;.merge</emphasis> and <emphasis>branch.&lt;name&gt;.remote</emphasis> in\r
 714         <xref linkend="git-config(1)" />.\r
 715 </simpara>\r
 716 </listitem>\r
 717 </varlistentry>\r
 718 <varlistentry>\r
 719 <term>\r
 720 --upload-pack &lt;upload-pack&gt;\r
 721 </term>\r
 722 <listitem>\r
 723 <simpara>\r
 724         When given, and the repository to fetch from is handled\r
 725         by <emphasis>git fetch-pack</emphasis>, <emphasis>--exec=&lt;upload-pack&gt;</emphasis> is passed to\r
 726         the command to specify non-default path for the command\r
 727         run on the other end.\r
 728 </simpara>\r
 729 </listitem>\r
 730 </varlistentry>\r
 731 <varlistentry>\r
 732 <term>\r
 733 --progress\r
 734 </term>\r
 735 <listitem>\r
 736 <simpara>\r
 737         Progress status is reported on the standard error stream\r
 738         by default when it is attached to a terminal, unless -q\r
 739         is specified. This flag forces progress status even if the\r
 740         standard error stream is not directed to a terminal.\r
 741 </simpara>\r
 742 </listitem>\r
 743 </varlistentry>\r
 744 <varlistentry>\r
 745 <term>\r
 746 -o &lt;option&gt;\r
 747 </term>\r
 748 <term>\r
 749 --server-option=&lt;option&gt;\r
 750 </term>\r
 751 <listitem>\r
 752 <simpara>\r
 753         Transmit the given string to the server when communicating using\r
 754         protocol version 2.  The given string must not contain a NUL or LF\r
 755         character.  The server's handling of server options, including\r
 756         unknown ones, is server-specific.\r
 757         When multiple <emphasis>--server-option=&lt;option&gt;</emphasis> are given, they are all\r
 758         sent to the other side in the order listed on the command line.\r
 759 </simpara>\r
 760 </listitem>\r
 761 </varlistentry>\r
 762 <varlistentry>\r
 763 <term>\r
 764 --show-forced-updates\r
 765 </term>\r
 766 <listitem>\r
 767 <simpara>\r
 768         By default, git checks if a branch is force-updated during\r
 769         fetch. This can be disabled through fetch.showForcedUpdates, but\r
 770         the --show-forced-updates option guarantees this check occurs.\r
 771         See <xref linkend="git-config(1)" />.\r
 772 </simpara>\r
 773 </listitem>\r
 774 </varlistentry>\r
 775 <varlistentry>\r
 776 <term>\r
 777 --no-show-forced-updates\r
 778 </term>\r
 779 <listitem>\r
 780 <simpara>\r
 781         By default, git checks if a branch is force-updated during\r
 782         fetch. Pass --no-show-forced-updates or set fetch.showForcedUpdates\r
 783         to false to skip this check for performance reasons. If used during\r
 784         <emphasis>git-pull</emphasis> the --ff-only option will still check for forced updates\r
 785         before attempting a fast-forward update. See <xref linkend="git-config(1)" />.\r
 786 </simpara>\r
 787 </listitem>\r
 788 </varlistentry>\r
 789 <varlistentry>\r
 790 <term>\r
 791 -4\r
 792 </term>\r
 793 <term>\r
 794 --ipv4\r
 795 </term>\r
 796 <listitem>\r
 797 <simpara>\r
 798         Use IPv4 addresses only, ignoring IPv6 addresses.\r
 799 </simpara>\r
 800 </listitem>\r
 801 </varlistentry>\r
 802 <varlistentry>\r
 803 <term>\r
 804 -6\r
 805 </term>\r
 806 <term>\r
 807 --ipv6\r
 808 </term>\r
 809 <listitem>\r
 810 <simpara>\r
 811         Use IPv6 addresses only, ignoring IPv4 addresses.\r
 812 </simpara>\r
 813 </listitem>\r
 814 </varlistentry>\r
 815 <varlistentry>\r
 816 <term>\r
 817 &lt;repository&gt;\r
 818 </term>\r
 819 <listitem>\r
 820 <simpara>\r
 821         The "remote" repository that is the source of a fetch\r
 822         or pull operation.  This parameter can be either a URL\r
 823         (see the section <link linkend="git-pull(1)_URLS">GIT URLS</link> below) or the name\r
 824         of a remote (see the section <link linkend="git-pull(1)_REMOTES">REMOTES</link> below).\r
 825 </simpara>\r
 826 </listitem>\r
 827 </varlistentry>\r
 828 <varlistentry>\r
 829 <term>\r
 830 &lt;refspec&gt;\r
 831 </term>\r
 832 <listitem>\r
 833 <simpara>\r
 834         Specifies which refs to fetch and which local refs to update.\r
 835         When no &lt;refspec&gt;s appear on the command line, the refs to fetch\r
 836         are read from <emphasis>remote.&lt;repository&gt;.fetch</emphasis> variables instead\r
 837         (see the section "CONFIGURED REMOTE-TRACKING BRANCHES"\r
 838         in <xref linkend="git-fetch(1)" />).\r
 839 </simpara>\r
 840 <simpara>The format of a &lt;refspec&gt; parameter is an optional plus\r
 841 <emphasis>+</emphasis>, followed by the source &lt;src&gt;, followed\r
 842 by a colon <emphasis>:</emphasis>, followed by the destination ref &lt;dst&gt;.\r
 843 The colon can be omitted when &lt;dst&gt; is empty.  &lt;src&gt; is\r
 844 typically a ref, but it can also be a fully spelled hex object\r
 845 name.</simpara>\r
 846 <simpara><emphasis>tag &lt;tag&gt;</emphasis> means the same as <emphasis>refs/tags/&lt;tag&gt;:refs/tags/&lt;tag&gt;</emphasis>;\r
 847 it requests fetching everything up to the given tag.</simpara>\r
 848 <simpara>The remote ref that matches &lt;src&gt;\r
 849 is fetched, and if &lt;dst&gt; is not an empty string, an attempt\r
 850 is made to update the local ref that matches it.</simpara>\r
 851 <simpara>Whether that update is allowed without <emphasis>--force</emphasis> depends on the ref\r
 852 namespace it's being fetched to, the type of object being fetched, and\r
 853 whether the update is considered to be a fast-forward. Generally, the\r
 854 same rules apply for fetching as when pushing, see the <emphasis>&lt;refspec&gt;...</emphasis>\r
 855 section of <xref linkend="git-push(1)" /> for what those are. Exceptions to those\r
 856 rules particular to <emphasis>git fetch</emphasis> are noted below.</simpara>\r
 857 <simpara>Until Git version 2.20, and unlike when pushing with\r
 858 <xref linkend="git-push(1)" />, any updates to <emphasis>refs/tags/*</emphasis> would be accepted\r
 859 without <emphasis>+</emphasis> in the refspec (or <emphasis>--force</emphasis>). When fetching, we promiscuously\r
 860 considered all tag updates from a remote to be forced fetches.  Since\r
 861 Git version 2.20, fetching to update <emphasis>refs/tags/*</emphasis> works the same way\r
 862 as when pushing. I.e. any updates will be rejected without <emphasis>+</emphasis> in the\r
 863 refspec (or <emphasis>--force</emphasis>).</simpara>\r
 864 <simpara>Unlike when pushing with <xref linkend="git-push(1)" />, any updates outside of\r
 865 <emphasis>refs/{tags,heads}/*</emphasis> will be accepted without <emphasis>+</emphasis> in the refspec (or\r
 866 <emphasis>--force</emphasis>), whether that's swapping e.g. a tree object for a blob, or\r
 867 a commit for another commit that's doesn't have the previous commit as\r
 868 an ancestor etc.</simpara>\r
 869 <simpara>Unlike when pushing with <xref linkend="git-push(1)" />, there is no\r
 870 configuration which'll amend these rules, and nothing like a\r
 871 <emphasis>pre-fetch</emphasis> hook analogous to the <emphasis>pre-receive</emphasis> hook.</simpara>\r
 872 <simpara>As with pushing with <xref linkend="git-push(1)" />, all of the rules described\r
 873 above about what's not allowed as an update can be overridden by\r
 874 adding an the optional leading <emphasis>+</emphasis> to a refspec (or using <emphasis>--force</emphasis>\r
 875 command line option). The only exception to this is that no amount of\r
 876 forcing will make the <emphasis>refs/heads/*</emphasis> namespace accept a non-commit\r
 877 object.</simpara>\r
 878 <note><simpara>When the remote branch you want to fetch is known to\r
 879 be rewound and rebased regularly, it is expected that\r
 880 its new tip will not be descendant of its previous tip\r
 881 (as stored in your remote-tracking branch the last time\r
 882 you fetched).  You would want\r
 883 to use the <emphasis>+</emphasis> sign to indicate non-fast-forward updates\r
 884 will be needed for such branches.  There is no way to\r
 885 determine or declare that a branch will be made available\r
 886 in a repository with this behavior; the pulling user simply\r
 887 must know this is the expected usage pattern for a branch.</simpara></note>\r
 888 <note><simpara>There is a difference between listing multiple &lt;refspec&gt;\r
 889 directly on <emphasis>git pull</emphasis> command line and having multiple\r
 890 <emphasis>remote.&lt;repository&gt;.fetch</emphasis> entries in your configuration\r
 891 for a &lt;repository&gt; and running a\r
 892 <emphasis>git pull</emphasis> command without any explicit &lt;refspec&gt; parameters.\r
 893 &lt;refspec&gt;s listed explicitly on the command line are always\r
 894 merged into the current branch after fetching.  In other words,\r
 895 if you list more than one remote ref, <emphasis>git pull</emphasis> will create\r
 896 an Octopus merge.  On the other hand, if you do not list any\r
 897 explicit &lt;refspec&gt; parameter on the command line, <emphasis>git pull</emphasis>\r
 898 will fetch all the &lt;refspec&gt;s it finds in the\r
 899 <emphasis>remote.&lt;repository&gt;.fetch</emphasis> configuration and merge\r
 900 only the first &lt;refspec&gt; found into the current branch.\r
 901 This is because making an\r
 902 Octopus from remote refs is rarely done, while keeping track\r
 903 of multiple remote heads in one-go by fetching more than one\r
 904 is often useful.</simpara></note>\r
 905 </listitem>\r
 906 </varlistentry>\r
 907 </variablelist>\r
 908 </section>\r
 909 </simplesect>\r
 910 <simplesect id="git-pull(1)__git_urls_anchor_id_git_pull_1__urls_xreflabel_urls">\r
 911 <title>GIT URLS<anchor id="git-pull(1)_URLS" xreflabel="[URLS]"/></title>\r
 912 <simpara>In general, URLs contain information about the transport protocol, the\r
 913 address of the remote server, and the path to the repository.\r
 914 Depending on the transport protocol, some of this information may be\r
 915 absent.</simpara>\r
 916 <simpara>Git supports ssh, git, http, and https protocols (in addition, ftp,\r
 917 and ftps can be used for fetching, but this is inefficient and\r
 918 deprecated; do not use it).</simpara>\r
 919 <simpara>The native transport (i.e. git:// URL) does no authentication and\r
 920 should be used with caution on unsecured networks.</simpara>\r
 921 <simpara>The following syntaxes may be used with them:</simpara>\r
 922 <itemizedlist>\r
 923 <listitem>\r
 924 <simpara>\r
 925 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/path/to/repo.git/\r
 926 </simpara>\r
 927 </listitem>\r
 928 <listitem>\r
 929 <simpara>\r
 930 git://host.xz&#91;:port&#93;/path/to/repo.git/\r
 931 </simpara>\r
 932 </listitem>\r
 933 <listitem>\r
 934 <simpara>\r
 935 http&#91;s&#93;://host.xz&#91;:port&#93;/path/to/repo.git/\r
 936 </simpara>\r
 937 </listitem>\r
 938 <listitem>\r
 939 <simpara>\r
 940 ftp&#91;s&#93;://host.xz&#91;:port&#93;/path/to/repo.git/\r
 941 </simpara>\r
 942 </listitem>\r
 943 </itemizedlist>\r
 944 <simpara>An alternative scp-like syntax may also be used with the ssh protocol:</simpara>\r
 945 <itemizedlist>\r
 946 <listitem>\r
 947 <simpara>\r
 948 &#91;user@&#93;host.xz:path/to/repo.git/\r
 949 </simpara>\r
 950 </listitem>\r
 951 </itemizedlist>\r
 952 <simpara>This syntax is only recognized if there are no slashes before the\r
 953 first colon. This helps differentiate a local path that contains a\r
 954 colon. For example the local path <emphasis>foo:bar</emphasis> could be specified as an\r
 955 absolute path or <emphasis>./foo:bar</emphasis> to avoid being misinterpreted as an ssh\r
 956 url.</simpara>\r
 957 <simpara>The ssh and git protocols additionally support ~username expansion:</simpara>\r
 958 <itemizedlist>\r
 959 <listitem>\r
 960 <simpara>\r
 961 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/~&#91;user&#93;/path/to/repo.git/\r
 962 </simpara>\r
 963 </listitem>\r
 964 <listitem>\r
 965 <simpara>\r
 966 git://host.xz&#91;:port&#93;/~&#91;user&#93;/path/to/repo.git/\r
 967 </simpara>\r
 968 </listitem>\r
 969 <listitem>\r
 970 <simpara>\r
 971 &#91;user@&#93;host.xz:/~&#91;user&#93;/path/to/repo.git/\r
 972 </simpara>\r
 973 </listitem>\r
 974 </itemizedlist>\r
 975 <simpara>For local repositories, also supported by Git natively, the following\r
 976 syntaxes may be used:</simpara>\r
 977 <itemizedlist>\r
 978 <listitem>\r
 979 <simpara>\r
 980 /path/to/repo.git/\r
 981 </simpara>\r
 982 </listitem>\r
 983 <listitem>\r
 984 <simpara>\r
 985 file:///path/to/repo.git/\r
 986 </simpara>\r
 987 </listitem>\r
 988 </itemizedlist>\r
 989 <simpara>These two syntaxes are mostly equivalent, except when cloning, when\r
 990 the former implies --local option. See <xref linkend="git-clone(1)" /> for\r
 991 details.</simpara>\r
 992 <simpara><emphasis>git clone</emphasis>, <emphasis>git fetch</emphasis> and <emphasis>git pull</emphasis>, but not <emphasis>git push</emphasis>, will also\r
 993 accept a suitable bundle file. See <xref linkend="git-bundle(1)" />.</simpara>\r
 994 <simpara>When Git doesn't know how to handle a certain transport protocol, it\r
 995 attempts to use the <emphasis>remote-&lt;transport&gt;</emphasis> remote helper, if one\r
 996 exists. To explicitly request a remote helper, the following syntax\r
 997 may be used:</simpara>\r
 998 <itemizedlist>\r
 999 <listitem>\r
1000 <simpara>\r
1001 &lt;transport&gt;::&lt;address&gt;\r
1002 </simpara>\r
1003 </listitem>\r
1004 </itemizedlist>\r
1005 <simpara>where &lt;address&gt; may be a path, a server and path, or an arbitrary\r
1006 URL-like string recognized by the specific remote helper being\r
1007 invoked. See <xref linkend="gitremote-helpers(7)" /> for details.</simpara>\r
1008 <simpara>If there are a large number of similarly-named remote repositories and\r
1009 you want to use a different format for them (such that the URLs you\r
1010 use will be rewritten into URLs that work), you can create a\r
1011 configuration section of the form:</simpara>\r
1012 <screen>        [url "&lt;actual url base&gt;"]\r
1013                 insteadOf = &lt;other url base&gt;</screen>\r
1014 <simpara>For example, with this:</simpara>\r
1015 <screen>        [url "git://git.host.xz/"]\r
1016                 insteadOf = host.xz:/path/to/\r
1017                 insteadOf = work:</screen>\r
1018 <simpara>a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be\r
1019 rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".</simpara>\r
1020 <simpara>If you want to rewrite URLs for push only, you can create a\r
1021 configuration section of the form:</simpara>\r
1022 <screen>        [url "&lt;actual url base&gt;"]\r
1023                 pushInsteadOf = &lt;other url base&gt;</screen>\r
1024 <simpara>For example, with this:</simpara>\r
1025 <screen>        [url "ssh://example.org/"]\r
1026                 pushInsteadOf = git://example.org/</screen>\r
1027 <simpara>a URL like "git://example.org/path/to/repo.git" will be rewritten to\r
1028 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still\r
1029 use the original URL.</simpara>\r
1030 </simplesect>\r
1031 <simplesect id="git-pull(1)__remotes_anchor_id_git_pull_1__remotes_xreflabel_remotes">\r
1032 <title>REMOTES<anchor id="git-pull(1)_REMOTES" xreflabel="[REMOTES]"/></title>\r
1033 <simpara>The name of one of the following can be used instead\r
1034 of a URL as <emphasis>&lt;repository&gt;</emphasis> argument:</simpara>\r
1035 <itemizedlist>\r
1036 <listitem>\r
1037 <simpara>\r
1038 a remote in the Git configuration file: <emphasis>$GIT_DIR/config</emphasis>,\r
1039 </simpara>\r
1040 </listitem>\r
1041 <listitem>\r
1042 <simpara>\r
1043 a file in the <emphasis>$GIT_DIR/remotes</emphasis> directory, or\r
1044 </simpara>\r
1045 </listitem>\r
1046 <listitem>\r
1047 <simpara>\r
1048 a file in the <emphasis>$GIT_DIR/branches</emphasis> directory.\r
1049 </simpara>\r
1050 </listitem>\r
1051 </itemizedlist>\r
1052 <simpara>All of these also allow you to omit the refspec from the command line\r
1053 because they each contain a refspec which git will use by default.</simpara>\r
1054 <section id="git-pull(1)__named_remote_in_configuration_file">\r
1055 <title>Named remote in configuration file</title>\r
1056 <simpara>You can choose to provide the name of a remote which you had previously\r
1057 configured using <xref linkend="git-remote(1)" />, <xref linkend="git-config(1)" />\r
1058 or even by a manual edit to the <emphasis>$GIT_DIR/config</emphasis> file.  The URL of\r
1059 this remote will be used to access the repository.  The refspec\r
1060 of this remote will be used by default when you do\r
1061 not provide a refspec on the command line.  The entry in the\r
1062 config file would appear like this:</simpara>\r
1063 <screen>        [remote "&lt;name&gt;"]\r
1064                 url = &lt;url&gt;\r
1065                 pushurl = &lt;pushurl&gt;\r
1066                 push = &lt;refspec&gt;\r
1067                 fetch = &lt;refspec&gt;</screen>\r
1068 <simpara>The <emphasis>&lt;pushurl&gt;</emphasis> is used for pushes only. It is optional and defaults\r
1069 to <emphasis>&lt;url&gt;</emphasis>.</simpara>\r
1070 </section>\r
1071 <section id="git-pull(1)__named_file_in_emphasis_git_dir_remotes_emphasis">\r
1072 <title>Named file in <emphasis>$GIT_DIR/remotes</emphasis></title>\r
1073 <simpara>You can choose to provide the name of a\r
1074 file in <emphasis>$GIT_DIR/remotes</emphasis>.  The URL\r
1075 in this file will be used to access the repository.  The refspec\r
1076 in this file will be used as default when you do not\r
1077 provide a refspec on the command line.  This file should have the\r
1078 following format:</simpara>\r
1079 <screen>        URL: one of the above URL format\r
1080         Push: &lt;refspec&gt;\r
1081         Pull: &lt;refspec&gt;</screen>\r
1082 <simpara><emphasis>Push:</emphasis> lines are used by <emphasis>git push</emphasis> and\r
1083 <emphasis>Pull:</emphasis> lines are used by <emphasis>git pull</emphasis> and <emphasis>git fetch</emphasis>.\r
1084 Multiple <emphasis>Push:</emphasis> and <emphasis>Pull:</emphasis> lines may\r
1085 be specified for additional branch mappings.</simpara>\r
1086 </section>\r
1087 <section id="git-pull(1)__named_file_in_emphasis_git_dir_branches_emphasis">\r
1088 <title>Named file in <emphasis>$GIT_DIR/branches</emphasis></title>\r
1089 <simpara>You can choose to provide the name of a\r
1090 file in <emphasis>$GIT_DIR/branches</emphasis>.\r
1091 The URL in this file will be used to access the repository.\r
1092 This file should have the following format:</simpara>\r
1093 <screen>        &lt;url&gt;#&lt;head&gt;</screen>\r
1094 <simpara><emphasis>&lt;url&gt;</emphasis> is required; <emphasis>#&lt;head&gt;</emphasis> is optional.</simpara>\r
1095 <simpara>Depending on the operation, git will use one of the following\r
1096 refspecs, if you don't provide one on the command line.\r
1097 <emphasis>&lt;branch&gt;</emphasis> is the name of this file in <emphasis>$GIT_DIR/branches</emphasis> and\r
1098 <emphasis>&lt;head&gt;</emphasis> defaults to <emphasis>master</emphasis>.</simpara>\r
1099 <simpara>git fetch uses:</simpara>\r
1100 <screen>        refs/heads/&lt;head&gt;:refs/heads/&lt;branch&gt;</screen>\r
1101 <simpara>git push uses:</simpara>\r
1102 <screen>        HEAD:refs/heads/&lt;head&gt;</screen>\r
1103 </section>\r
1104 </simplesect>\r
1105 <simplesect id="git-pull(1)__merge_strategies">\r
1106 <title>MERGE STRATEGIES</title>\r
1107 <simpara>The merge mechanism (<emphasis>git merge</emphasis> and <emphasis>git pull</emphasis> commands) allows the\r
1108 backend <emphasis>merge strategies</emphasis> to be chosen with <emphasis>-s</emphasis> option.  Some strategies\r
1109 can also take their own options, which can be passed by giving <emphasis>-X&lt;option&gt;</emphasis>\r
1110 arguments to <emphasis>git merge</emphasis> and/or <emphasis>git pull</emphasis>.</simpara>\r
1111 <variablelist>\r
1112 <varlistentry>\r
1113 <term>\r
1114 resolve\r
1115 </term>\r
1116 <listitem>\r
1117 <simpara>\r
1118         This can only resolve two heads (i.e. the current branch\r
1119         and another branch you pulled from) using a 3-way merge\r
1120         algorithm.  It tries to carefully detect criss-cross\r
1121         merge ambiguities and is considered generally safe and\r
1122         fast.\r
1123 </simpara>\r
1124 </listitem>\r
1125 </varlistentry>\r
1126 <varlistentry>\r
1127 <term>\r
1128 recursive\r
1129 </term>\r
1130 <listitem>\r
1131 <simpara>\r
1132         This can only resolve two heads using a 3-way merge\r
1133         algorithm.  When there is more than one common\r
1134         ancestor that can be used for 3-way merge, it creates a\r
1135         merged tree of the common ancestors and uses that as\r
1136         the reference tree for the 3-way merge.  This has been\r
1137         reported to result in fewer merge conflicts without\r
1138         causing mismerges by tests done on actual merge commits\r
1139         taken from Linux 2.6 kernel development history.\r
1140         Additionally this can detect and handle merges involving\r
1141         renames, but currently cannot make use of detected\r
1142         copies.  This is the default merge strategy when pulling\r
1143         or merging one branch.\r
1144 </simpara>\r
1145 <simpara>The <emphasis>recursive</emphasis> strategy can take the following options:</simpara>\r
1146 <variablelist>\r
1147 <varlistentry>\r
1148 <term>\r
1149 ours\r
1150 </term>\r
1151 <listitem>\r
1152 <simpara>\r
1153         This option forces conflicting hunks to be auto-resolved cleanly by\r
1154         favoring <emphasis>our</emphasis> version.  Changes from the other tree that do not\r
1155         conflict with our side are reflected in the merge result.\r
1156         For a binary file, the entire contents are taken from our side.\r
1157 </simpara>\r
1158 <simpara>This should not be confused with the <emphasis>ours</emphasis> merge strategy, which does not\r
1159 even look at what the other tree contains at all.  It discards everything\r
1160 the other tree did, declaring <emphasis>our</emphasis> history contains all that happened in it.</simpara>\r
1161 </listitem>\r
1162 </varlistentry>\r
1163 <varlistentry>\r
1164 <term>\r
1165 theirs\r
1166 </term>\r
1167 <listitem>\r
1168 <simpara>\r
1169         This is the opposite of <emphasis>ours</emphasis>; note that, unlike <emphasis>ours</emphasis>, there is\r
1170         no <emphasis>theirs</emphasis> merge strategy to confuse this merge option with.\r
1171 </simpara>\r
1172 </listitem>\r
1173 </varlistentry>\r
1174 <varlistentry>\r
1175 <term>\r
1176 patience\r
1177 </term>\r
1178 <listitem>\r
1179 <simpara>\r
1180         With this option, <emphasis>merge-recursive</emphasis> spends a little extra time\r
1181         to avoid mismerges that sometimes occur due to unimportant\r
1182         matching lines (e.g., braces from distinct functions).  Use\r
1183         this when the branches to be merged have diverged wildly.\r
1184         See also <xref linkend="git-diff(1)" /> <emphasis>--patience</emphasis>.\r
1185 </simpara>\r
1186 </listitem>\r
1187 </varlistentry>\r
1188 <varlistentry>\r
1189 <term>\r
1190 diff-algorithm=[patience|minimal|histogram|myers]\r
1191 </term>\r
1192 <listitem>\r
1193 <simpara>\r
1194         Tells <emphasis>merge-recursive</emphasis> to use a different diff algorithm, which\r
1195         can help avoid mismerges that occur due to unimportant matching\r
1196         lines (such as braces from distinct functions).  See also\r
1197         <xref linkend="git-diff(1)" /> <emphasis>--diff-algorithm</emphasis>.\r
1198 </simpara>\r
1199 </listitem>\r
1200 </varlistentry>\r
1201 <varlistentry>\r
1202 <term>\r
1203 ignore-space-change\r
1204 </term>\r
1205 <term>\r
1206 ignore-all-space\r
1207 </term>\r
1208 <term>\r
1209 ignore-space-at-eol\r
1210 </term>\r
1211 <term>\r
1212 ignore-cr-at-eol\r
1213 </term>\r
1214 <listitem>\r
1215 <simpara>\r
1216         Treats lines with the indicated type of whitespace change as\r
1217         unchanged for the sake of a three-way merge.  Whitespace\r
1218         changes mixed with other changes to a line are not ignored.\r
1219         See also <xref linkend="git-diff(1)" /> <emphasis>-b</emphasis>, <emphasis>-w</emphasis>,\r
1220         <emphasis>--ignore-space-at-eol</emphasis>, and <emphasis>--ignore-cr-at-eol</emphasis>.\r
1221 </simpara>\r
1222 <itemizedlist>\r
1223 <listitem>\r
1224 <simpara>\r
1225 If <emphasis>their</emphasis> version only introduces whitespace changes to a line,\r
1226   <emphasis>our</emphasis> version is used;\r
1227 </simpara>\r
1228 </listitem>\r
1229 <listitem>\r
1230 <simpara>\r
1231 If <emphasis>our</emphasis> version introduces whitespace changes but <emphasis>their</emphasis>\r
1232   version includes a substantial change, <emphasis>their</emphasis> version is used;\r
1233 </simpara>\r
1234 </listitem>\r
1235 <listitem>\r
1236 <simpara>\r
1237 Otherwise, the merge proceeds in the usual way.\r
1238 </simpara>\r
1239 </listitem>\r
1240 </itemizedlist>\r
1241 </listitem>\r
1242 </varlistentry>\r
1243 <varlistentry>\r
1244 <term>\r
1245 renormalize\r
1246 </term>\r
1247 <listitem>\r
1248 <simpara>\r
1249         This runs a virtual check-out and check-in of all three stages\r
1250         of a file when resolving a three-way merge.  This option is\r
1251         meant to be used when merging branches with different clean\r
1252         filters or end-of-line normalization rules.  See "Merging\r
1253         branches with differing checkin/checkout attributes" in\r
1254         <xref linkend="gitattributes(5)" /> for details.\r
1255 </simpara>\r
1256 </listitem>\r
1257 </varlistentry>\r
1258 <varlistentry>\r
1259 <term>\r
1260 no-renormalize\r
1261 </term>\r
1262 <listitem>\r
1263 <simpara>\r
1264         Disables the <emphasis>renormalize</emphasis> option.  This overrides the\r
1265         <emphasis>merge.renormalize</emphasis> configuration variable.\r
1266 </simpara>\r
1267 </listitem>\r
1268 </varlistentry>\r
1269 <varlistentry>\r
1270 <term>\r
1271 no-renames\r
1272 </term>\r
1273 <listitem>\r
1274 <simpara>\r
1275         Turn off rename detection. This overrides the <emphasis>merge.renames</emphasis>\r
1276         configuration variable.\r
1277         See also <xref linkend="git-diff(1)" /> <emphasis>--no-renames</emphasis>.\r
1278 </simpara>\r
1279 </listitem>\r
1280 </varlistentry>\r
1281 <varlistentry>\r
1282 <term>\r
1283 find-renames[=&lt;n&gt;]\r
1284 </term>\r
1285 <listitem>\r
1286 <simpara>\r
1287         Turn on rename detection, optionally setting the similarity\r
1288         threshold.  This is the default. This overrides the\r
1289         <emphasis>merge.renames</emphasis> configuration variable.\r
1290         See also <xref linkend="git-diff(1)" /> <emphasis>--find-renames</emphasis>.\r
1291 </simpara>\r
1292 </listitem>\r
1293 </varlistentry>\r
1294 <varlistentry>\r
1295 <term>\r
1296 rename-threshold=&lt;n&gt;\r
1297 </term>\r
1298 <listitem>\r
1299 <simpara>\r
1300         Deprecated synonym for <emphasis>find-renames=&lt;n&gt;</emphasis>.\r
1301 </simpara>\r
1302 </listitem>\r
1303 </varlistentry>\r
1304 <varlistentry>\r
1305 <term>\r
1306 subtree[=&lt;path&gt;]\r
1307 </term>\r
1308 <listitem>\r
1309 <simpara>\r
1310         This option is a more advanced form of <emphasis>subtree</emphasis> strategy, where\r
1311         the strategy makes a guess on how two trees must be shifted to\r
1312         match with each other when merging.  Instead, the specified path\r
1313         is prefixed (or stripped from the beginning) to make the shape of\r
1314         two trees to match.\r
1315 </simpara>\r
1316 </listitem>\r
1317 </varlistentry>\r
1318 </variablelist>\r
1319 </listitem>\r
1320 </varlistentry>\r
1321 <varlistentry>\r
1322 <term>\r
1323 octopus\r
1324 </term>\r
1325 <listitem>\r
1326 <simpara>\r
1327         This resolves cases with more than two heads, but refuses to do\r
1328         a complex merge that needs manual resolution.  It is\r
1329         primarily meant to be used for bundling topic branch\r
1330         heads together.  This is the default merge strategy when\r
1331         pulling or merging more than one branch.\r
1332 </simpara>\r
1333 </listitem>\r
1334 </varlistentry>\r
1335 <varlistentry>\r
1336 <term>\r
1337 ours\r
1338 </term>\r
1339 <listitem>\r
1340 <simpara>\r
1341         This resolves any number of heads, but the resulting tree of the\r
1342         merge is always that of the current branch head, effectively\r
1343         ignoring all changes from all other branches.  It is meant to\r
1344         be used to supersede old development history of side\r
1345         branches.  Note that this is different from the -Xours option to\r
1346         the <emphasis>recursive</emphasis> merge strategy.\r
1347 </simpara>\r
1348 </listitem>\r
1349 </varlistentry>\r
1350 <varlistentry>\r
1351 <term>\r
1352 subtree\r
1353 </term>\r
1354 <listitem>\r
1355 <simpara>\r
1356         This is a modified recursive strategy. When merging trees A and\r
1357         B, if B corresponds to a subtree of A, B is first adjusted to\r
1358         match the tree structure of A, instead of reading the trees at\r
1359         the same level. This adjustment is also done to the common\r
1360         ancestor tree.\r
1361 </simpara>\r
1362 </listitem>\r
1363 </varlistentry>\r
1364 </variablelist>\r
1365 <simpara>With the strategies that use 3-way merge (including the default, <emphasis>recursive</emphasis>),\r
1366 if a change is made on both branches, but later reverted on one of the\r
1367 branches, that change will be present in the merged result; some people find\r
1368 this behavior confusing.  It occurs because only the heads and the merge base\r
1369 are considered when performing a merge, not the individual commits.  The merge\r
1370 algorithm therefore considers the reverted change as no change at all, and\r
1371 substitutes the changed version instead.</simpara>\r
1372 </simplesect>\r
1373 <simplesect id="git-pull(1)__default_behaviour">\r
1374 <title>DEFAULT BEHAVIOUR</title>\r
1375 <simpara>Often people use <emphasis>git pull</emphasis> without giving any parameter.\r
1376 Traditionally, this has been equivalent to saying <emphasis>git pull\r
1377 origin</emphasis>.  However, when configuration <emphasis>branch.&lt;name&gt;.remote</emphasis> is\r
1378 present while on branch <emphasis>&lt;name&gt;</emphasis>, that value is used instead of\r
1379 <emphasis>origin</emphasis>.</simpara>\r
1380 <simpara>In order to determine what URL to use to fetch from, the value\r
1381 of the configuration <emphasis>remote.&lt;origin&gt;.url</emphasis> is consulted\r
1382 and if there is not any such variable, the value on the <emphasis>URL:</emphasis> line\r
1383 in <emphasis>$GIT_DIR/remotes/&lt;origin&gt;</emphasis> is used.</simpara>\r
1384 <simpara>In order to determine what remote branches to fetch (and\r
1385 optionally store in the remote-tracking branches) when the command is\r
1386 run without any refspec parameters on the command line, values\r
1387 of the configuration variable <emphasis>remote.&lt;origin&gt;.fetch</emphasis> are\r
1388 consulted, and if there aren't any, <emphasis>$GIT_DIR/remotes/&lt;origin&gt;</emphasis>\r
1389 is consulted and its <emphasis>Pull:</emphasis> lines are used.\r
1390 In addition to the refspec formats described in the OPTIONS\r
1391 section, you can have a globbing refspec that looks like this:</simpara>\r
1392 <screen>refs/heads/*:refs/remotes/origin/*</screen>\r
1393 <simpara>A globbing refspec must have a non-empty RHS (i.e. must store\r
1394 what were fetched in remote-tracking branches), and its LHS and RHS\r
1395 must end with <emphasis>/*</emphasis>.  The above specifies that all remote\r
1396 branches are tracked using remote-tracking branches in\r
1397 <emphasis>refs/remotes/origin/</emphasis> hierarchy under the same name.</simpara>\r
1398 <simpara>The rule to determine which remote branch to merge after\r
1399 fetching is a bit involved, in order not to break backward\r
1400 compatibility.</simpara>\r
1401 <simpara>If explicit refspecs were given on the command\r
1402 line of <emphasis>git pull</emphasis>, they are all merged.</simpara>\r
1403 <simpara>When no refspec was given on the command line, then <emphasis>git pull</emphasis>\r
1404 uses the refspec from the configuration or\r
1405 <emphasis>$GIT_DIR/remotes/&lt;origin&gt;</emphasis>.  In such cases, the following\r
1406 rules apply:</simpara>\r
1407 <orderedlist numeration="arabic">\r
1408 <listitem>\r
1409 <simpara>\r
1410 If <emphasis>branch.&lt;name&gt;.merge</emphasis> configuration for the current\r
1411   branch <emphasis>&lt;name&gt;</emphasis> exists, that is the name of the branch at the\r
1412   remote site that is merged.\r
1413 </simpara>\r
1414 </listitem>\r
1415 <listitem>\r
1416 <simpara>\r
1417 If the refspec is a globbing one, nothing is merged.\r
1418 </simpara>\r
1419 </listitem>\r
1420 <listitem>\r
1421 <simpara>\r
1422 Otherwise the remote branch of the first refspec is merged.\r
1423 </simpara>\r
1424 </listitem>\r
1425 </orderedlist>\r
1426 </simplesect>\r
1427 <simplesect id="git-pull(1)__examples">\r
1428 <title>EXAMPLES</title>\r
1429 <itemizedlist>\r
1430 <listitem>\r
1431 <simpara>\r
1432 Update the remote-tracking branches for the repository\r
1433   you cloned from, then merge one of them into your\r
1434   current branch:\r
1435 </simpara>\r
1436 <screen>$ git pull\r
1437 $ git pull origin</screen>\r
1438 <simpara>Normally the branch merged in is the HEAD of the remote repository,\r
1439 but the choice is determined by the branch.&lt;name&gt;.remote and\r
1440 branch.&lt;name&gt;.merge options; see <xref linkend="git-config(1)" /> for details.</simpara>\r
1441 </listitem>\r
1442 <listitem>\r
1443 <simpara>\r
1444 Merge into the current branch the remote branch <emphasis>next</emphasis>:\r
1445 </simpara>\r
1446 <screen>$ git pull origin next</screen>\r
1447 <simpara>This leaves a copy of <emphasis>next</emphasis> temporarily in FETCH_HEAD, and\r
1448 updates the remote-tracking branch <emphasis>origin/next</emphasis>.\r
1449 The same can be done by invoking fetch and merge:</simpara>\r
1450 <screen>$ git fetch origin\r
1451 $ git merge origin/next</screen>\r
1452 </listitem>\r
1453 </itemizedlist>\r
1454 <simpara>If you tried a pull which resulted in complex conflicts and\r
1455 would want to start over, you can recover with <emphasis>git reset</emphasis>.</simpara>\r
1456 </simplesect>\r
1457 <simplesect id="git-pull(1)__security">\r
1458 <title>SECURITY</title>\r
1459 <simpara>The fetch and push protocols are not designed to prevent one side from\r
1460 stealing data from the other repository that was not intended to be\r
1461 shared. If you have private data that you need to protect from a malicious\r
1462 peer, your best option is to store it in another repository. This applies\r
1463 to both clients and servers. In particular, namespaces on a server are not\r
1464 effective for read access control; you should only grant read access to a\r
1465 namespace to clients that you would trust with read access to the entire\r
1466 repository.</simpara>\r
1467 <simpara>The known attack vectors are as follows:</simpara>\r
1468 <orderedlist numeration="arabic">\r
1469 <listitem>\r
1470 <simpara>\r
1471 The victim sends "have" lines advertising the IDs of objects it has that\r
1472   are not explicitly intended to be shared but can be used to optimize the\r
1473   transfer if the peer also has them. The attacker chooses an object ID X\r
1474   to steal and sends a ref to X, but isn't required to send the content of\r
1475   X because the victim already has it. Now the victim believes that the\r
1476   attacker has X, and it sends the content of X back to the attacker\r
1477   later. (This attack is most straightforward for a client to perform on a\r
1478   server, by creating a ref to X in the namespace the client has access\r
1479   to and then fetching it. The most likely way for a server to perform it\r
1480   on a client is to "merge" X into a public branch and hope that the user\r
1481   does additional work on this branch and pushes it back to the server\r
1482   without noticing the merge.)\r
1483 </simpara>\r
1484 </listitem>\r
1485 <listitem>\r
1486 <simpara>\r
1487 As in #1, the attacker chooses an object ID X to steal. The victim sends\r
1488   an object Y that the attacker already has, and the attacker falsely\r
1489   claims to have X and not Y, so the victim sends Y as a delta against X.\r
1490   The delta reveals regions of X that are similar to Y to the attacker.\r
1491 </simpara>\r
1492 </listitem>\r
1493 </orderedlist>\r
1494 </simplesect>\r
1495 <simplesect id="git-pull(1)__bugs">\r
1496 <title>BUGS</title>\r
1497 <simpara>Using --recurse-submodules can only fetch new commits in already checked\r
1498 out submodules right now. When e.g. upstream added a new submodule in the\r
1499 just fetched commits of the superproject the submodule itself cannot be\r
1500 fetched, making it impossible to check out that submodule later without\r
1501 having to do a fetch again. This is expected to be fixed in a future Git\r
1502 version.</simpara>\r
1503 </simplesect>\r
1504 <simplesect id="git-pull(1)__see_also">\r
1505 <title>SEE ALSO</title>\r
1506 <simpara><xref linkend="git-fetch(1)" />, <xref linkend="git-merge(1)" />, <xref linkend="git-config(1)" /></simpara>\r
1507 </simplesect>\r
1508 <simplesect id="git-pull(1)__git">\r
1509 <title>GIT</title>\r
1510 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
1511 </simplesect>\r
1512 </sect2>\r