doc/source/en/TortoiseGit/git_doc/git-fetch.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-fetch(1)">\r
   5     <title>git-fetch(1)</title>\r
   6 <indexterm>\r
   7 <primary>git-fetch(1)</primary>\r
   8 </indexterm>\r
   9 <simplesect id="git-fetch(1)__name">\r
  10 <title>NAME</title>\r
  11 <simpara>git-fetch - Download objects and refs from another repository</simpara>\r
  12 </simplesect>\r
  13 <simplesect id="git-fetch(1)__synopsis">\r
  14 <title>SYNOPSIS</title>\r
  15 <blockquote>\r
  16 <literallayout><emphasis>git fetch</emphasis> [&lt;options&gt;] [&lt;repository&gt; [&lt;refspec&gt;&#8230;]]\r
  17 <emphasis>git fetch</emphasis> [&lt;options&gt;] &lt;group&gt;\r
  18 <emphasis>git fetch</emphasis> --multiple [&lt;options&gt;] [(&lt;repository&gt; | &lt;group&gt;)&#8230;]\r
  19 <emphasis>git fetch</emphasis> --all [&lt;options&gt;]</literallayout>\r
  20 </blockquote>\r
  21 </simplesect>\r
  22 <simplesect id="git-fetch(1)__description">\r
  23 <title>DESCRIPTION</title>\r
  24 <simpara>Fetch branches and/or tags (collectively, "refs") from one or more\r
  25 other repositories, along with the objects necessary to complete their\r
  26 histories.  Remote-tracking branches are updated (see the description\r
  27 of &lt;refspec&gt; below for ways to control this behavior).</simpara>\r
  28 <simpara>By default, any tag that points into the histories being fetched is\r
  29 also fetched; the effect is to fetch tags that\r
  30 point at branches that you are interested in.  This default behavior\r
  31 can be changed by using the --tags or --no-tags options or by\r
  32 configuring remote.&lt;name&gt;.tagOpt.  By using a refspec that fetches tags\r
  33 explicitly, you can fetch tags that do not point into branches you\r
  34 are interested in as well.</simpara>\r
  35 <simpara><emphasis>git fetch</emphasis> can fetch from either a single named repository or URL,\r
  36 or from several repositories at once if &lt;group&gt; is given and\r
  37 there is a remotes.&lt;group&gt; entry in the configuration file.\r
  38 (See <xref linkend="git-config(1)" />).</simpara>\r
  39 <simpara>When no remote is specified, by default the <emphasis>origin</emphasis> remote will be used,\r
  40 unless there's an upstream branch configured for the current branch.</simpara>\r
  41 <simpara>The names of refs that are fetched, together with the object names\r
  42 they point at, are written to <emphasis>.git/FETCH_HEAD</emphasis>.  This information\r
  43 may be used by scripts or other git commands, such as <xref linkend="git-pull(1)" />.</simpara>\r
  44 </simplesect>\r
  45 <simplesect id="git-fetch(1)__options">\r
  46 <title>OPTIONS</title>\r
  47 <variablelist>\r
  48 <varlistentry>\r
  49 <term>\r
  50 --all\r
  51 </term>\r
  52 <listitem>\r
  53 <simpara>\r
  54         Fetch all remotes.\r
  55 </simpara>\r
  56 </listitem>\r
  57 </varlistentry>\r
  58 <varlistentry>\r
  59 <term>\r
  60 -a\r
  61 </term>\r
  62 <term>\r
  63 --append\r
  64 </term>\r
  65 <listitem>\r
  66 <simpara>\r
  67         Append ref names and object names of fetched refs to the\r
  68         existing contents of <emphasis>.git/FETCH_HEAD</emphasis>.  Without this\r
  69         option old data in <emphasis>.git/FETCH_HEAD</emphasis> will be overwritten.\r
  70 </simpara>\r
  71 </listitem>\r
  72 </varlistentry>\r
  73 <varlistentry>\r
  74 <term>\r
  75 --depth=&lt;depth&gt;\r
  76 </term>\r
  77 <listitem>\r
  78 <simpara>\r
  79         Limit fetching to the specified number of commits from the tip of\r
  80         each remote branch history. If fetching to a <emphasis>shallow</emphasis> repository\r
  81         created by <emphasis>git clone</emphasis> with <emphasis>--depth=&lt;depth&gt;</emphasis> option (see\r
  82         <xref linkend="git-clone(1)" />), deepen or shorten the history to the specified\r
  83         number of commits. Tags for the deepened commits are not fetched.\r
  84 </simpara>\r
  85 </listitem>\r
  86 </varlistentry>\r
  87 <varlistentry>\r
  88 <term>\r
  89 --deepen=&lt;depth&gt;\r
  90 </term>\r
  91 <listitem>\r
  92 <simpara>\r
  93         Similar to --depth, except it specifies the number of commits\r
  94         from the current shallow boundary instead of from the tip of\r
  95         each remote branch history.\r
  96 </simpara>\r
  97 </listitem>\r
  98 </varlistentry>\r
  99 <varlistentry>\r
 100 <term>\r
 101 --shallow-since=&lt;date&gt;\r
 102 </term>\r
 103 <listitem>\r
 104 <simpara>\r
 105         Deepen or shorten the history of a shallow repository to\r
 106         include all reachable commits after &lt;date&gt;.\r
 107 </simpara>\r
 108 </listitem>\r
 109 </varlistentry>\r
 110 <varlistentry>\r
 111 <term>\r
 112 --shallow-exclude=&lt;revision&gt;\r
 113 </term>\r
 114 <listitem>\r
 115 <simpara>\r
 116         Deepen or shorten the history of a shallow repository to\r
 117         exclude commits reachable from a specified remote branch or tag.\r
 118         This option can be specified multiple times.\r
 119 </simpara>\r
 120 </listitem>\r
 121 </varlistentry>\r
 122 <varlistentry>\r
 123 <term>\r
 124 --unshallow\r
 125 </term>\r
 126 <listitem>\r
 127 <simpara>\r
 128         If the source repository is complete, convert a shallow\r
 129         repository to a complete one, removing all the limitations\r
 130         imposed by shallow repositories.\r
 131 </simpara>\r
 132 <simpara>If the source repository is shallow, fetch as much as possible so that\r
 133 the current repository has the same history as the source repository.</simpara>\r
 134 </listitem>\r
 135 </varlistentry>\r
 136 <varlistentry>\r
 137 <term>\r
 138 --update-shallow\r
 139 </term>\r
 140 <listitem>\r
 141 <simpara>\r
 142         By default when fetching from a shallow repository,\r
 143         <emphasis>git fetch</emphasis> refuses refs that require updating\r
 144         .git/shallow. This option updates .git/shallow and accept such\r
 145         refs.\r
 146 </simpara>\r
 147 </listitem>\r
 148 </varlistentry>\r
 149 <varlistentry>\r
 150 <term>\r
 151 --negotiation-tip=&lt;commit|glob&gt;\r
 152 </term>\r
 153 <listitem>\r
 154 <simpara>\r
 155         By default, Git will report, to the server, commits reachable\r
 156         from all local refs to find common commits in an attempt to\r
 157         reduce the size of the to-be-received packfile. If specified,\r
 158         Git will only report commits reachable from the given tips.\r
 159         This is useful to speed up fetches when the user knows which\r
 160         local ref is likely to have commits in common with the\r
 161         upstream ref being fetched.\r
 162 </simpara>\r
 163 <simpara>This option may be specified more than once; if so, Git will report\r
 164 commits reachable from any of the given commits.</simpara>\r
 165 <simpara>The argument to this option may be a glob on ref names, a ref, or the (possibly\r
 166 abbreviated) SHA-1 of a commit. Specifying a glob is equivalent to specifying\r
 167 this option multiple times, one for each matching ref name.</simpara>\r
 168 <simpara>See also the <emphasis>fetch.negotiationAlgorithm</emphasis> configuration variable\r
 169 documented in <xref linkend="git-config(1)" />.</simpara>\r
 170 </listitem>\r
 171 </varlistentry>\r
 172 <varlistentry>\r
 173 <term>\r
 174 --dry-run\r
 175 </term>\r
 176 <listitem>\r
 177 <simpara>\r
 178         Show what would be done, without making any changes.\r
 179 </simpara>\r
 180 </listitem>\r
 181 </varlistentry>\r
 182 <varlistentry>\r
 183 <term>\r
 184 -f\r
 185 </term>\r
 186 <term>\r
 187 --force\r
 188 </term>\r
 189 <listitem>\r
 190 <simpara>\r
 191         When <emphasis>git fetch</emphasis> is used with <emphasis>&lt;src&gt;:&lt;dst&gt;</emphasis> refspec it may\r
 192         refuse to update the local branch as discussed\r
 193         in the <emphasis>&lt;refspec&gt;</emphasis> part below.\r
 194         This option overrides that check.\r
 195 </simpara>\r
 196 </listitem>\r
 197 </varlistentry>\r
 198 <varlistentry>\r
 199 <term>\r
 200 -k\r
 201 </term>\r
 202 <term>\r
 203 --keep\r
 204 </term>\r
 205 <listitem>\r
 206 <simpara>\r
 207         Keep downloaded pack.\r
 208 </simpara>\r
 209 </listitem>\r
 210 </varlistentry>\r
 211 <varlistentry>\r
 212 <term>\r
 213 --multiple\r
 214 </term>\r
 215 <listitem>\r
 216 <simpara>\r
 217         Allow several &lt;repository&gt; and &lt;group&gt; arguments to be\r
 218         specified. No &lt;refspec&gt;s may be specified.\r
 219 </simpara>\r
 220 </listitem>\r
 221 </varlistentry>\r
 222 <varlistentry>\r
 223 <term>\r
 224 --[no-]auto-gc\r
 225 </term>\r
 226 <listitem>\r
 227 <simpara>\r
 228         Run <emphasis>git gc --auto</emphasis> at the end to perform garbage collection\r
 229         if needed. This is enabled by default.\r
 230 </simpara>\r
 231 </listitem>\r
 232 </varlistentry>\r
 233 <varlistentry>\r
 234 <term>\r
 235 --[no-]write-commit-graph\r
 236 </term>\r
 237 <listitem>\r
 238 <simpara>\r
 239         Write a commit-graph after fetching. This overrides the config\r
 240         setting <emphasis>fetch.writeCommitGraph</emphasis>.\r
 241 </simpara>\r
 242 </listitem>\r
 243 </varlistentry>\r
 244 <varlistentry>\r
 245 <term>\r
 246 -p\r
 247 </term>\r
 248 <term>\r
 249 --prune\r
 250 </term>\r
 251 <listitem>\r
 252 <simpara>\r
 253         Before fetching, remove any remote-tracking references that no\r
 254         longer exist on the remote.  Tags are not subject to pruning\r
 255         if they are fetched only because of the default tag\r
 256         auto-following or due to a --tags option.  However, if tags\r
 257         are fetched due to an explicit refspec (either on the command\r
 258         line or in the remote configuration, for example if the remote\r
 259         was cloned with the --mirror option), then they are also\r
 260         subject to pruning. Supplying <emphasis>--prune-tags</emphasis> is a shorthand for\r
 261         providing the tag refspec.\r
 262 </simpara>\r
 263 <simpara>See the PRUNING section below for more details.</simpara>\r
 264 </listitem>\r
 265 </varlistentry>\r
 266 <varlistentry>\r
 267 <term>\r
 268 -P\r
 269 </term>\r
 270 <term>\r
 271 --prune-tags\r
 272 </term>\r
 273 <listitem>\r
 274 <simpara>\r
 275         Before fetching, remove any local tags that no longer exist on\r
 276         the remote if <emphasis>--prune</emphasis> is enabled. This option should be used\r
 277         more carefully, unlike <emphasis>--prune</emphasis> it will remove any local\r
 278         references (local tags) that have been created. This option is\r
 279         a shorthand for providing the explicit tag refspec along with\r
 280         <emphasis>--prune</emphasis>, see the discussion about that in its documentation.\r
 281 </simpara>\r
 282 <simpara>See the PRUNING section below for more details.</simpara>\r
 283 </listitem>\r
 284 </varlistentry>\r
 285 <varlistentry>\r
 286 <term>\r
 287 -n\r
 288 </term>\r
 289 <term>\r
 290 --no-tags\r
 291 </term>\r
 292 <listitem>\r
 293 <simpara>\r
 294         By default, tags that point at objects that are downloaded\r
 295         from the remote repository are fetched and stored locally.\r
 296         This option disables this automatic tag following. The default\r
 297         behavior for a remote may be specified with the remote.&lt;name&gt;.tagOpt\r
 298         setting. See <xref linkend="git-config(1)" />.\r
 299 </simpara>\r
 300 </listitem>\r
 301 </varlistentry>\r
 302 <varlistentry>\r
 303 <term>\r
 304 --refmap=&lt;refspec&gt;\r
 305 </term>\r
 306 <listitem>\r
 307 <simpara>\r
 308         When fetching refs listed on the command line, use the\r
 309         specified refspec (can be given more than once) to map the\r
 310         refs to remote-tracking branches, instead of the values of\r
 311         <emphasis>remote.*.fetch</emphasis> configuration variables for the remote\r
 312         repository.  Providing an empty <emphasis>&lt;refspec&gt;</emphasis> to the\r
 313         <emphasis>--refmap</emphasis> option causes Git to ignore the configured\r
 314         refspecs and rely entirely on the refspecs supplied as\r
 315         command-line arguments. See section on "Configured Remote-tracking\r
 316         Branches" for details.\r
 317 </simpara>\r
 318 </listitem>\r
 319 </varlistentry>\r
 320 <varlistentry>\r
 321 <term>\r
 322 -t\r
 323 </term>\r
 324 <term>\r
 325 --tags\r
 326 </term>\r
 327 <listitem>\r
 328 <simpara>\r
 329         Fetch all tags from the remote (i.e., fetch remote tags\r
 330         <emphasis>refs/tags/*</emphasis> into local tags with the same name), in addition\r
 331         to whatever else would otherwise be fetched.  Using this\r
 332         option alone does not subject tags to pruning, even if --prune\r
 333         is used (though tags may be pruned anyway if they are also the\r
 334         destination of an explicit refspec; see <emphasis>--prune</emphasis>).\r
 335 </simpara>\r
 336 </listitem>\r
 337 </varlistentry>\r
 338 <varlistentry>\r
 339 <term>\r
 340 --recurse-submodules[=yes|on-demand|no]\r
 341 </term>\r
 342 <listitem>\r
 343 <simpara>\r
 344         This option controls if and under what conditions new commits of\r
 345         populated submodules should be fetched too. It can be used as a\r
 346         boolean option to completely disable recursion when set to <emphasis>no</emphasis> or to\r
 347         unconditionally recurse into all populated submodules when set to\r
 348         <emphasis>yes</emphasis>, which is the default when this option is used without any\r
 349         value. Use <emphasis>on-demand</emphasis> to only recurse into a populated submodule\r
 350         when the superproject retrieves a commit that updates the submodule's\r
 351         reference to a commit that isn't already in the local submodule\r
 352         clone. By default, <emphasis>on-demand</emphasis> is used, unless\r
 353         <emphasis>fetch.recurseSubmodules</emphasis> is set (see <xref linkend="git-config(1)" />).\r
 354 </simpara>\r
 355 </listitem>\r
 356 </varlistentry>\r
 357 <varlistentry>\r
 358 <term>\r
 359 -j\r
 360 </term>\r
 361 <term>\r
 362 --jobs=&lt;n&gt;\r
 363 </term>\r
 364 <listitem>\r
 365 <simpara>\r
 366         Number of parallel children to be used for all forms of fetching.\r
 367 </simpara>\r
 368 <simpara>If the <emphasis>--multiple</emphasis> option was specified, the different remotes will be fetched\r
 369 in parallel. If multiple submodules are fetched, they will be fetched in\r
 370 parallel. To control them independently, use the config settings\r
 371 <emphasis>fetch.parallel</emphasis> and <emphasis>submodule.fetchJobs</emphasis> (see <xref linkend="git-config(1)" />).</simpara>\r
 372 <simpara>Typically, parallel recursive and multi-remote fetches will be faster. By\r
 373 default fetches are performed sequentially, not in parallel.</simpara>\r
 374 </listitem>\r
 375 </varlistentry>\r
 376 <varlistentry>\r
 377 <term>\r
 378 --no-recurse-submodules\r
 379 </term>\r
 380 <listitem>\r
 381 <simpara>\r
 382         Disable recursive fetching of submodules (this has the same effect as\r
 383         using the <emphasis>--recurse-submodules=no</emphasis> option).\r
 384 </simpara>\r
 385 </listitem>\r
 386 </varlistentry>\r
 387 <varlistentry>\r
 388 <term>\r
 389 --set-upstream\r
 390 </term>\r
 391 <listitem>\r
 392 <simpara>\r
 393         If the remote is fetched successfully, pull and add upstream\r
 394         (tracking) reference, used by argument-less\r
 395         <xref linkend="git-pull(1)" /> and other commands. For more information,\r
 396         see <emphasis>branch.&lt;name&gt;.merge</emphasis> and <emphasis>branch.&lt;name&gt;.remote</emphasis> in\r
 397         <xref linkend="git-config(1)" />.\r
 398 </simpara>\r
 399 </listitem>\r
 400 </varlistentry>\r
 401 <varlistentry>\r
 402 <term>\r
 403 --submodule-prefix=&lt;path&gt;\r
 404 </term>\r
 405 <listitem>\r
 406 <simpara>\r
 407         Prepend &lt;path&gt; to paths printed in informative messages\r
 408         such as "Fetching submodule foo".  This option is used\r
 409         internally when recursing over submodules.\r
 410 </simpara>\r
 411 </listitem>\r
 412 </varlistentry>\r
 413 <varlistentry>\r
 414 <term>\r
 415 --recurse-submodules-default=[yes|on-demand]\r
 416 </term>\r
 417 <listitem>\r
 418 <simpara>\r
 419         This option is used internally to temporarily provide a\r
 420         non-negative default value for the --recurse-submodules\r
 421         option.  All other methods of configuring fetch's submodule\r
 422         recursion (such as settings in <xref linkend="gitmodules(5)" /> and\r
 423         <xref linkend="git-config(1)" />) override this option, as does\r
 424         specifying --[no-]recurse-submodules directly.\r
 425 </simpara>\r
 426 </listitem>\r
 427 </varlistentry>\r
 428 <varlistentry>\r
 429 <term>\r
 430 -u\r
 431 </term>\r
 432 <term>\r
 433 --update-head-ok\r
 434 </term>\r
 435 <listitem>\r
 436 <simpara>\r
 437         By default <emphasis>git fetch</emphasis> refuses to update the head which\r
 438         corresponds to the current branch.  This flag disables the\r
 439         check.  This is purely for the internal use for <emphasis>git pull</emphasis>\r
 440         to communicate with <emphasis>git fetch</emphasis>, and unless you are\r
 441         implementing your own Porcelain you are not supposed to\r
 442         use it.\r
 443 </simpara>\r
 444 </listitem>\r
 445 </varlistentry>\r
 446 <varlistentry>\r
 447 <term>\r
 448 --upload-pack &lt;upload-pack&gt;\r
 449 </term>\r
 450 <listitem>\r
 451 <simpara>\r
 452         When given, and the repository to fetch from is handled\r
 453         by <emphasis>git fetch-pack</emphasis>, <emphasis>--exec=&lt;upload-pack&gt;</emphasis> is passed to\r
 454         the command to specify non-default path for the command\r
 455         run on the other end.\r
 456 </simpara>\r
 457 </listitem>\r
 458 </varlistentry>\r
 459 <varlistentry>\r
 460 <term>\r
 461 -q\r
 462 </term>\r
 463 <term>\r
 464 --quiet\r
 465 </term>\r
 466 <listitem>\r
 467 <simpara>\r
 468         Pass --quiet to git-fetch-pack and silence any other internally\r
 469         used git commands. Progress is not reported to the standard error\r
 470         stream.\r
 471 </simpara>\r
 472 </listitem>\r
 473 </varlistentry>\r
 474 <varlistentry>\r
 475 <term>\r
 476 -v\r
 477 </term>\r
 478 <term>\r
 479 --verbose\r
 480 </term>\r
 481 <listitem>\r
 482 <simpara>\r
 483         Be verbose.\r
 484 </simpara>\r
 485 </listitem>\r
 486 </varlistentry>\r
 487 <varlistentry>\r
 488 <term>\r
 489 --progress\r
 490 </term>\r
 491 <listitem>\r
 492 <simpara>\r
 493         Progress status is reported on the standard error stream\r
 494         by default when it is attached to a terminal, unless -q\r
 495         is specified. This flag forces progress status even if the\r
 496         standard error stream is not directed to a terminal.\r
 497 </simpara>\r
 498 </listitem>\r
 499 </varlistentry>\r
 500 <varlistentry>\r
 501 <term>\r
 502 -o &lt;option&gt;\r
 503 </term>\r
 504 <term>\r
 505 --server-option=&lt;option&gt;\r
 506 </term>\r
 507 <listitem>\r
 508 <simpara>\r
 509         Transmit the given string to the server when communicating using\r
 510         protocol version 2.  The given string must not contain a NUL or LF\r
 511         character.  The server's handling of server options, including\r
 512         unknown ones, is server-specific.\r
 513         When multiple <emphasis>--server-option=&lt;option&gt;</emphasis> are given, they are all\r
 514         sent to the other side in the order listed on the command line.\r
 515 </simpara>\r
 516 </listitem>\r
 517 </varlistentry>\r
 518 <varlistentry>\r
 519 <term>\r
 520 --show-forced-updates\r
 521 </term>\r
 522 <listitem>\r
 523 <simpara>\r
 524         By default, git checks if a branch is force-updated during\r
 525         fetch. This can be disabled through fetch.showForcedUpdates, but\r
 526         the --show-forced-updates option guarantees this check occurs.\r
 527         See <xref linkend="git-config(1)" />.\r
 528 </simpara>\r
 529 </listitem>\r
 530 </varlistentry>\r
 531 <varlistentry>\r
 532 <term>\r
 533 --no-show-forced-updates\r
 534 </term>\r
 535 <listitem>\r
 536 <simpara>\r
 537         By default, git checks if a branch is force-updated during\r
 538         fetch. Pass --no-show-forced-updates or set fetch.showForcedUpdates\r
 539         to false to skip this check for performance reasons. If used during\r
 540         <emphasis>git-pull</emphasis> the --ff-only option will still check for forced updates\r
 541         before attempting a fast-forward update. See <xref linkend="git-config(1)" />.\r
 542 </simpara>\r
 543 </listitem>\r
 544 </varlistentry>\r
 545 <varlistentry>\r
 546 <term>\r
 547 -4\r
 548 </term>\r
 549 <term>\r
 550 --ipv4\r
 551 </term>\r
 552 <listitem>\r
 553 <simpara>\r
 554         Use IPv4 addresses only, ignoring IPv6 addresses.\r
 555 </simpara>\r
 556 </listitem>\r
 557 </varlistentry>\r
 558 <varlistentry>\r
 559 <term>\r
 560 -6\r
 561 </term>\r
 562 <term>\r
 563 --ipv6\r
 564 </term>\r
 565 <listitem>\r
 566 <simpara>\r
 567         Use IPv6 addresses only, ignoring IPv4 addresses.\r
 568 </simpara>\r
 569 </listitem>\r
 570 </varlistentry>\r
 571 <varlistentry>\r
 572 <term>\r
 573 &lt;repository&gt;\r
 574 </term>\r
 575 <listitem>\r
 576 <simpara>\r
 577         The "remote" repository that is the source of a fetch\r
 578         or pull operation.  This parameter can be either a URL\r
 579         (see the section <link linkend="git-fetch(1)_URLS">GIT URLS</link> below) or the name\r
 580         of a remote (see the section <link linkend="git-fetch(1)_REMOTES">REMOTES</link> below).\r
 581 </simpara>\r
 582 </listitem>\r
 583 </varlistentry>\r
 584 <varlistentry>\r
 585 <term>\r
 586 &lt;group&gt;\r
 587 </term>\r
 588 <listitem>\r
 589 <simpara>\r
 590         A name referring to a list of repositories as the value\r
 591         of remotes.&lt;group&gt; in the configuration file.\r
 592         (See <xref linkend="git-config(1)" />).\r
 593 </simpara>\r
 594 </listitem>\r
 595 </varlistentry>\r
 596 <varlistentry>\r
 597 <term>\r
 598 &lt;refspec&gt;\r
 599 </term>\r
 600 <listitem>\r
 601 <simpara>\r
 602         Specifies which refs to fetch and which local refs to update.\r
 603         When no &lt;refspec&gt;s appear on the command line, the refs to fetch\r
 604         are read from <emphasis>remote.&lt;repository&gt;.fetch</emphasis> variables instead\r
 605         (see <link linkend="git-fetch(1)_CRTB">CONFIGURED REMOTE-TRACKING BRANCHES</link> below).\r
 606 </simpara>\r
 607 <simpara>The format of a &lt;refspec&gt; parameter is an optional plus\r
 608 <emphasis>+</emphasis>, followed by the source &lt;src&gt;, followed\r
 609 by a colon <emphasis>:</emphasis>, followed by the destination ref &lt;dst&gt;.\r
 610 The colon can be omitted when &lt;dst&gt; is empty.  &lt;src&gt; is\r
 611 typically a ref, but it can also be a fully spelled hex object\r
 612 name.</simpara>\r
 613 <simpara><emphasis>tag &lt;tag&gt;</emphasis> means the same as <emphasis>refs/tags/&lt;tag&gt;:refs/tags/&lt;tag&gt;</emphasis>;\r
 614 it requests fetching everything up to the given tag.</simpara>\r
 615 <simpara>The remote ref that matches &lt;src&gt;\r
 616 is fetched, and if &lt;dst&gt; is not an empty string, an attempt\r
 617 is made to update the local ref that matches it.</simpara>\r
 618 <simpara>Whether that update is allowed without <emphasis>--force</emphasis> depends on the ref\r
 619 namespace it's being fetched to, the type of object being fetched, and\r
 620 whether the update is considered to be a fast-forward. Generally, the\r
 621 same rules apply for fetching as when pushing, see the <emphasis>&lt;refspec&gt;...</emphasis>\r
 622 section of <xref linkend="git-push(1)" /> for what those are. Exceptions to those\r
 623 rules particular to <emphasis>git fetch</emphasis> are noted below.</simpara>\r
 624 <simpara>Until Git version 2.20, and unlike when pushing with\r
 625 <xref linkend="git-push(1)" />, any updates to <emphasis>refs/tags/*</emphasis> would be accepted\r
 626 without <emphasis>+</emphasis> in the refspec (or <emphasis>--force</emphasis>). When fetching, we promiscuously\r
 627 considered all tag updates from a remote to be forced fetches.  Since\r
 628 Git version 2.20, fetching to update <emphasis>refs/tags/*</emphasis> works the same way\r
 629 as when pushing. I.e. any updates will be rejected without <emphasis>+</emphasis> in the\r
 630 refspec (or <emphasis>--force</emphasis>).</simpara>\r
 631 <simpara>Unlike when pushing with <xref linkend="git-push(1)" />, any updates outside of\r
 632 <emphasis>refs/{tags,heads}/*</emphasis> will be accepted without <emphasis>+</emphasis> in the refspec (or\r
 633 <emphasis>--force</emphasis>), whether that's swapping e.g. a tree object for a blob, or\r
 634 a commit for another commit that's doesn't have the previous commit as\r
 635 an ancestor etc.</simpara>\r
 636 <simpara>Unlike when pushing with <xref linkend="git-push(1)" />, there is no\r
 637 configuration which'll amend these rules, and nothing like a\r
 638 <emphasis>pre-fetch</emphasis> hook analogous to the <emphasis>pre-receive</emphasis> hook.</simpara>\r
 639 <simpara>As with pushing with <xref linkend="git-push(1)" />, all of the rules described\r
 640 above about what's not allowed as an update can be overridden by\r
 641 adding an the optional leading <emphasis>+</emphasis> to a refspec (or using <emphasis>--force</emphasis>\r
 642 command line option). The only exception to this is that no amount of\r
 643 forcing will make the <emphasis>refs/heads/*</emphasis> namespace accept a non-commit\r
 644 object.</simpara>\r
 645 <note><simpara>When the remote branch you want to fetch is known to\r
 646 be rewound and rebased regularly, it is expected that\r
 647 its new tip will not be descendant of its previous tip\r
 648 (as stored in your remote-tracking branch the last time\r
 649 you fetched).  You would want\r
 650 to use the <emphasis>+</emphasis> sign to indicate non-fast-forward updates\r
 651 will be needed for such branches.  There is no way to\r
 652 determine or declare that a branch will be made available\r
 653 in a repository with this behavior; the pulling user simply\r
 654 must know this is the expected usage pattern for a branch.</simpara></note>\r
 655 </listitem>\r
 656 </varlistentry>\r
 657 </variablelist>\r
 658 </simplesect>\r
 659 <simplesect id="git-fetch(1)__git_urls_anchor_id_git_fetch_1__urls_xreflabel_urls">\r
 660 <title>GIT URLS<anchor id="git-fetch(1)_URLS" xreflabel="[URLS]"/></title>\r
 661 <simpara>In general, URLs contain information about the transport protocol, the\r
 662 address of the remote server, and the path to the repository.\r
 663 Depending on the transport protocol, some of this information may be\r
 664 absent.</simpara>\r
 665 <simpara>Git supports ssh, git, http, and https protocols (in addition, ftp,\r
 666 and ftps can be used for fetching, but this is inefficient and\r
 667 deprecated; do not use it).</simpara>\r
 668 <simpara>The native transport (i.e. git:// URL) does no authentication and\r
 669 should be used with caution on unsecured networks.</simpara>\r
 670 <simpara>The following syntaxes may be used with them:</simpara>\r
 671 <itemizedlist>\r
 672 <listitem>\r
 673 <simpara>\r
 674 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/path/to/repo.git/\r
 675 </simpara>\r
 676 </listitem>\r
 677 <listitem>\r
 678 <simpara>\r
 679 git://host.xz&#91;:port&#93;/path/to/repo.git/\r
 680 </simpara>\r
 681 </listitem>\r
 682 <listitem>\r
 683 <simpara>\r
 684 http&#91;s&#93;://host.xz&#91;:port&#93;/path/to/repo.git/\r
 685 </simpara>\r
 686 </listitem>\r
 687 <listitem>\r
 688 <simpara>\r
 689 ftp&#91;s&#93;://host.xz&#91;:port&#93;/path/to/repo.git/\r
 690 </simpara>\r
 691 </listitem>\r
 692 </itemizedlist>\r
 693 <simpara>An alternative scp-like syntax may also be used with the ssh protocol:</simpara>\r
 694 <itemizedlist>\r
 695 <listitem>\r
 696 <simpara>\r
 697 &#91;user@&#93;host.xz:path/to/repo.git/\r
 698 </simpara>\r
 699 </listitem>\r
 700 </itemizedlist>\r
 701 <simpara>This syntax is only recognized if there are no slashes before the\r
 702 first colon. This helps differentiate a local path that contains a\r
 703 colon. For example the local path <emphasis>foo:bar</emphasis> could be specified as an\r
 704 absolute path or <emphasis>./foo:bar</emphasis> to avoid being misinterpreted as an ssh\r
 705 url.</simpara>\r
 706 <simpara>The ssh and git protocols additionally support ~username expansion:</simpara>\r
 707 <itemizedlist>\r
 708 <listitem>\r
 709 <simpara>\r
 710 ssh://&#91;user@&#93;host.xz&#91;:port&#93;/~&#91;user&#93;/path/to/repo.git/\r
 711 </simpara>\r
 712 </listitem>\r
 713 <listitem>\r
 714 <simpara>\r
 715 git://host.xz&#91;:port&#93;/~&#91;user&#93;/path/to/repo.git/\r
 716 </simpara>\r
 717 </listitem>\r
 718 <listitem>\r
 719 <simpara>\r
 720 &#91;user@&#93;host.xz:/~&#91;user&#93;/path/to/repo.git/\r
 721 </simpara>\r
 722 </listitem>\r
 723 </itemizedlist>\r
 724 <simpara>For local repositories, also supported by Git natively, the following\r
 725 syntaxes may be used:</simpara>\r
 726 <itemizedlist>\r
 727 <listitem>\r
 728 <simpara>\r
 729 /path/to/repo.git/\r
 730 </simpara>\r
 731 </listitem>\r
 732 <listitem>\r
 733 <simpara>\r
 734 file:///path/to/repo.git/\r
 735 </simpara>\r
 736 </listitem>\r
 737 </itemizedlist>\r
 738 <simpara>These two syntaxes are mostly equivalent, except when cloning, when\r
 739 the former implies --local option. See <xref linkend="git-clone(1)" /> for\r
 740 details.</simpara>\r
 741 <simpara><emphasis>git clone</emphasis>, <emphasis>git fetch</emphasis> and <emphasis>git pull</emphasis>, but not <emphasis>git push</emphasis>, will also\r
 742 accept a suitable bundle file. See <xref linkend="git-bundle(1)" />.</simpara>\r
 743 <simpara>When Git doesn't know how to handle a certain transport protocol, it\r
 744 attempts to use the <emphasis>remote-&lt;transport&gt;</emphasis> remote helper, if one\r
 745 exists. To explicitly request a remote helper, the following syntax\r
 746 may be used:</simpara>\r
 747 <itemizedlist>\r
 748 <listitem>\r
 749 <simpara>\r
 750 &lt;transport&gt;::&lt;address&gt;\r
 751 </simpara>\r
 752 </listitem>\r
 753 </itemizedlist>\r
 754 <simpara>where &lt;address&gt; may be a path, a server and path, or an arbitrary\r
 755 URL-like string recognized by the specific remote helper being\r
 756 invoked. See <xref linkend="gitremote-helpers(7)" /> for details.</simpara>\r
 757 <simpara>If there are a large number of similarly-named remote repositories and\r
 758 you want to use a different format for them (such that the URLs you\r
 759 use will be rewritten into URLs that work), you can create a\r
 760 configuration section of the form:</simpara>\r
 761 <screen>        [url "&lt;actual url base&gt;"]\r
 762                 insteadOf = &lt;other url base&gt;</screen>\r
 763 <simpara>For example, with this:</simpara>\r
 764 <screen>        [url "git://git.host.xz/"]\r
 765                 insteadOf = host.xz:/path/to/\r
 766                 insteadOf = work:</screen>\r
 767 <simpara>a URL like "work:repo.git" or like "host.xz:/path/to/repo.git" will be\r
 768 rewritten in any context that takes a URL to be "git://git.host.xz/repo.git".</simpara>\r
 769 <simpara>If you want to rewrite URLs for push only, you can create a\r
 770 configuration section of the form:</simpara>\r
 771 <screen>        [url "&lt;actual url base&gt;"]\r
 772                 pushInsteadOf = &lt;other url base&gt;</screen>\r
 773 <simpara>For example, with this:</simpara>\r
 774 <screen>        [url "ssh://example.org/"]\r
 775                 pushInsteadOf = git://example.org/</screen>\r
 776 <simpara>a URL like "git://example.org/path/to/repo.git" will be rewritten to\r
 777 "ssh://example.org/path/to/repo.git" for pushes, but pulls will still\r
 778 use the original URL.</simpara>\r
 779 </simplesect>\r
 780 <simplesect id="git-fetch(1)__remotes_anchor_id_git_fetch_1__remotes_xreflabel_remotes">\r
 781 <title>REMOTES<anchor id="git-fetch(1)_REMOTES" xreflabel="[REMOTES]"/></title>\r
 782 <simpara>The name of one of the following can be used instead\r
 783 of a URL as <emphasis>&lt;repository&gt;</emphasis> argument:</simpara>\r
 784 <itemizedlist>\r
 785 <listitem>\r
 786 <simpara>\r
 787 a remote in the Git configuration file: <emphasis>$GIT_DIR/config</emphasis>,\r
 788 </simpara>\r
 789 </listitem>\r
 790 <listitem>\r
 791 <simpara>\r
 792 a file in the <emphasis>$GIT_DIR/remotes</emphasis> directory, or\r
 793 </simpara>\r
 794 </listitem>\r
 795 <listitem>\r
 796 <simpara>\r
 797 a file in the <emphasis>$GIT_DIR/branches</emphasis> directory.\r
 798 </simpara>\r
 799 </listitem>\r
 800 </itemizedlist>\r
 801 <simpara>All of these also allow you to omit the refspec from the command line\r
 802 because they each contain a refspec which git will use by default.</simpara>\r
 803 <section id="git-fetch(1)__named_remote_in_configuration_file">\r
 804 <title>Named remote in configuration file</title>\r
 805 <simpara>You can choose to provide the name of a remote which you had previously\r
 806 configured using <xref linkend="git-remote(1)" />, <xref linkend="git-config(1)" />\r
 807 or even by a manual edit to the <emphasis>$GIT_DIR/config</emphasis> file.  The URL of\r
 808 this remote will be used to access the repository.  The refspec\r
 809 of this remote will be used by default when you do\r
 810 not provide a refspec on the command line.  The entry in the\r
 811 config file would appear like this:</simpara>\r
 812 <screen>        [remote "&lt;name&gt;"]\r
 813                 url = &lt;url&gt;\r
 814                 pushurl = &lt;pushurl&gt;\r
 815                 push = &lt;refspec&gt;\r
 816                 fetch = &lt;refspec&gt;</screen>\r
 817 <simpara>The <emphasis>&lt;pushurl&gt;</emphasis> is used for pushes only. It is optional and defaults\r
 818 to <emphasis>&lt;url&gt;</emphasis>.</simpara>\r
 819 </section>\r
 820 <section id="git-fetch(1)__named_file_in_emphasis_git_dir_remotes_emphasis">\r
 821 <title>Named file in <emphasis>$GIT_DIR/remotes</emphasis></title>\r
 822 <simpara>You can choose to provide the name of a\r
 823 file in <emphasis>$GIT_DIR/remotes</emphasis>.  The URL\r
 824 in this file will be used to access the repository.  The refspec\r
 825 in this file will be used as default when you do not\r
 826 provide a refspec on the command line.  This file should have the\r
 827 following format:</simpara>\r
 828 <screen>        URL: one of the above URL format\r
 829         Push: &lt;refspec&gt;\r
 830         Pull: &lt;refspec&gt;</screen>\r
 831 <simpara><emphasis>Push:</emphasis> lines are used by <emphasis>git push</emphasis> and\r
 832 <emphasis>Pull:</emphasis> lines are used by <emphasis>git pull</emphasis> and <emphasis>git fetch</emphasis>.\r
 833 Multiple <emphasis>Push:</emphasis> and <emphasis>Pull:</emphasis> lines may\r
 834 be specified for additional branch mappings.</simpara>\r
 835 </section>\r
 836 <section id="git-fetch(1)__named_file_in_emphasis_git_dir_branches_emphasis">\r
 837 <title>Named file in <emphasis>$GIT_DIR/branches</emphasis></title>\r
 838 <simpara>You can choose to provide the name of a\r
 839 file in <emphasis>$GIT_DIR/branches</emphasis>.\r
 840 The URL in this file will be used to access the repository.\r
 841 This file should have the following format:</simpara>\r
 842 <screen>        &lt;url&gt;#&lt;head&gt;</screen>\r
 843 <simpara><emphasis>&lt;url&gt;</emphasis> is required; <emphasis>#&lt;head&gt;</emphasis> is optional.</simpara>\r
 844 <simpara>Depending on the operation, git will use one of the following\r
 845 refspecs, if you don't provide one on the command line.\r
 846 <emphasis>&lt;branch&gt;</emphasis> is the name of this file in <emphasis>$GIT_DIR/branches</emphasis> and\r
 847 <emphasis>&lt;head&gt;</emphasis> defaults to <emphasis>master</emphasis>.</simpara>\r
 848 <simpara>git fetch uses:</simpara>\r
 849 <screen>        refs/heads/&lt;head&gt;:refs/heads/&lt;branch&gt;</screen>\r
 850 <simpara>git push uses:</simpara>\r
 851 <screen>        HEAD:refs/heads/&lt;head&gt;</screen>\r
 852 </section>\r
 853 </simplesect>\r
 854 <simplesect id="git-fetch(1)__configured_remote_tracking_branches_anchor_id_git_fetch_1__crtb_xreflabel_crtb">\r
 855 <title>CONFIGURED REMOTE-TRACKING BRANCHES<anchor id="git-fetch(1)_CRTB" xreflabel="[CRTB]"/></title>\r
 856 <simpara>You often interact with the same remote repository by\r
 857 regularly and repeatedly fetching from it.  In order to keep track\r
 858 of the progress of such a remote repository, <emphasis>git fetch</emphasis> allows you\r
 859 to configure <emphasis>remote.&lt;repository&gt;.fetch</emphasis> configuration variables.</simpara>\r
 860 <simpara>Typically such a variable may look like this:</simpara>\r
 861 <screen>[remote "origin"]\r
 862         fetch = +refs/heads/*:refs/remotes/origin/*</screen>\r
 863 <simpara>This configuration is used in two ways:</simpara>\r
 864 <itemizedlist>\r
 865 <listitem>\r
 866 <simpara>\r
 867 When <emphasis>git fetch</emphasis> is run without specifying what branches\r
 868   and/or tags to fetch on the command line, e.g. <emphasis>git fetch origin</emphasis>\r
 869   or <emphasis>git fetch</emphasis>, <emphasis>remote.&lt;repository&gt;.fetch</emphasis> values are used as\r
 870   the refspecs--they specify which refs to fetch and which local refs\r
 871   to update.  The example above will fetch\r
 872   all branches that exist in the <emphasis>origin</emphasis> (i.e. any ref that matches\r
 873   the left-hand side of the value, <emphasis>refs/heads/*</emphasis>) and update the\r
 874   corresponding remote-tracking branches in the <emphasis>refs/remotes/origin/*</emphasis>\r
 875   hierarchy.\r
 876 </simpara>\r
 877 </listitem>\r
 878 <listitem>\r
 879 <simpara>\r
 880 When <emphasis>git fetch</emphasis> is run with explicit branches and/or tags\r
 881   to fetch on the command line, e.g. <emphasis>git fetch origin master</emphasis>, the\r
 882   &lt;refspec&gt;s given on the command line determine what are to be\r
 883   fetched (e.g. <emphasis>master</emphasis> in the example,\r
 884   which is a short-hand for <emphasis>master:</emphasis>, which in turn means\r
 885   "fetch the <emphasis>master</emphasis> branch but I do not explicitly say what\r
 886   remote-tracking branch to update with it from the command line"),\r
 887   and the example command will\r
 888   fetch <emphasis>only</emphasis> the <emphasis>master</emphasis> branch.  The <emphasis>remote.&lt;repository&gt;.fetch</emphasis>\r
 889   values determine which\r
 890   remote-tracking branch, if any, is updated.  When used in this\r
 891   way, the <emphasis>remote.&lt;repository&gt;.fetch</emphasis> values do not have any\r
 892   effect in deciding <emphasis>what</emphasis> gets fetched (i.e. the values are not\r
 893   used as refspecs when the command-line lists refspecs); they are\r
 894   only used to decide <emphasis>where</emphasis> the refs that are fetched are stored\r
 895   by acting as a mapping.\r
 896 </simpara>\r
 897 </listitem>\r
 898 </itemizedlist>\r
 899 <simpara>The latter use of the <emphasis>remote.&lt;repository&gt;.fetch</emphasis> values can be\r
 900 overridden by giving the <emphasis>--refmap=&lt;refspec&gt;</emphasis> parameter(s) on the\r
 901 command line.</simpara>\r
 902 </simplesect>\r
 903 <simplesect id="git-fetch(1)__pruning">\r
 904 <title>PRUNING</title>\r
 905 <simpara>Git has a default disposition of keeping data unless it's explicitly\r
 906 thrown away; this extends to holding onto local references to branches\r
 907 on remotes that have themselves deleted those branches.</simpara>\r
 908 <simpara>If left to accumulate, these stale references might make performance\r
 909 worse on big and busy repos that have a lot of branch churn, and\r
 910 e.g. make the output of commands like <emphasis>git branch -a --contains\r
 911 &lt;commit&gt;</emphasis> needlessly verbose, as well as impacting anything else\r
 912 that'll work with the complete set of known references.</simpara>\r
 913 <simpara>These remote-tracking references can be deleted as a one-off with\r
 914 either of:</simpara>\r
 915 <screen># While fetching\r
 916 $ git fetch --prune &lt;name&gt;\r
 917 \r
 918 # Only prune, don't fetch\r
 919 $ git remote prune &lt;name&gt;</screen>\r
 920 <simpara>To prune references as part of your normal workflow without needing to\r
 921 remember to run that, set <emphasis>fetch.prune</emphasis> globally, or\r
 922 <emphasis>remote.&lt;name&gt;.prune</emphasis> per-remote in the config. See\r
 923 <xref linkend="git-config(1)" />.</simpara>\r
 924 <simpara>Here's where things get tricky and more specific. The pruning feature\r
 925 doesn't actually care about branches, instead it'll prune local &lt;&#8594;\r
 926 remote-references as a function of the refspec of the remote (see\r
 927 <emphasis>&lt;refspec&gt;</emphasis> and <link linkend="git-fetch(1)_CRTB">CONFIGURED REMOTE-TRACKING BRANCHES</link> above).</simpara>\r
 928 <simpara>Therefore if the refspec for the remote includes\r
 929 e.g. <emphasis>refs/tags/*:refs/tags/*</emphasis>, or you manually run e.g. <emphasis>git fetch\r
 930 --prune &lt;name&gt; "refs/tags/*:refs/tags/*"</emphasis> it won't be stale remote\r
 931 tracking branches that are deleted, but any local tag that doesn't\r
 932 exist on the remote.</simpara>\r
 933 <simpara>This might not be what you expect, i.e. you want to prune remote\r
 934 <emphasis>&lt;name&gt;</emphasis>, but also explicitly fetch tags from it, so when you fetch\r
 935 from it you delete all your local tags, most of which may not have\r
 936 come from the <emphasis>&lt;name&gt;</emphasis> remote in the first place.</simpara>\r
 937 <simpara>So be careful when using this with a refspec like\r
 938 <emphasis>refs/tags/*:refs/tags/*</emphasis>, or any other refspec which might map\r
 939 references from multiple remotes to the same local namespace.</simpara>\r
 940 <simpara>Since keeping up-to-date with both branches and tags on the remote is\r
 941 a common use-case the <emphasis>--prune-tags</emphasis> option can be supplied along with\r
 942 <emphasis>--prune</emphasis> to prune local tags that don't exist on the remote, and\r
 943 force-update those tags that differ. Tag pruning can also be enabled\r
 944 with <emphasis>fetch.pruneTags</emphasis> or <emphasis>remote.&lt;name&gt;.pruneTags</emphasis> in the config. See\r
 945 <xref linkend="git-config(1)" />.</simpara>\r
 946 <simpara>The <emphasis>--prune-tags</emphasis> option is equivalent to having\r
 947 <emphasis>refs/tags/*:refs/tags/*</emphasis> declared in the refspecs of the remote. This\r
 948 can lead to some seemingly strange interactions:</simpara>\r
 949 <screen># These both fetch tags\r
 950 $ git fetch --no-tags origin 'refs/tags/*:refs/tags/*'\r
 951 $ git fetch --no-tags --prune-tags origin</screen>\r
 952 <simpara>The reason it doesn't error out when provided without <emphasis>--prune</emphasis> or its\r
 953 config versions is for flexibility of the configured versions, and to\r
 954 maintain a 1=1 mapping between what the command line flags do, and\r
 955 what the configuration versions do.</simpara>\r
 956 <simpara>It's reasonable to e.g. configure <emphasis>fetch.pruneTags=true</emphasis> in\r
 957 <emphasis>~/.gitconfig</emphasis> to have tags pruned whenever <emphasis>git fetch --prune</emphasis> is\r
 958 run, without making every invocation of <emphasis>git fetch</emphasis> without <emphasis>--prune</emphasis>\r
 959 an error.</simpara>\r
 960 <simpara>Pruning tags with <emphasis>--prune-tags</emphasis> also works when fetching a URL\r
 961 instead of a named remote. These will all prune tags not found on\r
 962 origin:</simpara>\r
 963 <screen>$ git fetch origin --prune --prune-tags\r
 964 $ git fetch origin --prune 'refs/tags/*:refs/tags/*'\r
 965 $ git fetch &lt;url of origin&gt; --prune --prune-tags\r
 966 $ git fetch &lt;url of origin&gt; --prune 'refs/tags/*:refs/tags/*'</screen>\r
 967 </simplesect>\r
 968 <simplesect id="git-fetch(1)__output">\r
 969 <title>OUTPUT</title>\r
 970 <simpara>The output of "git fetch" depends on the transport method used; this\r
 971 section describes the output when fetching over the Git protocol\r
 972 (either locally or via ssh) and Smart HTTP protocol.</simpara>\r
 973 <simpara>The status of the fetch is output in tabular form, with each line\r
 974 representing the status of a single ref. Each line is of the form:</simpara>\r
 975 <screen> &lt;flag&gt; &lt;summary&gt; &lt;from&gt; -&gt; &lt;to&gt; [&lt;reason&gt;]</screen>\r
 976 <simpara>The status of up-to-date refs is shown only if the --verbose option is\r
 977 used.</simpara>\r
 978 <simpara>In compact output mode, specified with configuration variable\r
 979 fetch.output, if either entire <emphasis>&lt;from&gt;</emphasis> or <emphasis>&lt;to&gt;</emphasis> is found in the\r
 980 other string, it will be substituted with <emphasis>*</emphasis> in the other string. For\r
 981 example, <emphasis>master -&gt; origin/master</emphasis> becomes <emphasis>master -&gt; origin/*</emphasis>.</simpara>\r
 982 <variablelist>\r
 983 <varlistentry>\r
 984 <term>\r
 985 flag\r
 986 </term>\r
 987 <listitem>\r
 988 <simpara>\r
 989         A single character indicating the status of the ref:\r
 990 </simpara>\r
 991 <variablelist>\r
 992 <varlistentry>\r
 993 <term>\r
 994 (space)\r
 995 </term>\r
 996 <listitem>\r
 997 <simpara>\r
 998 for a successfully fetched fast-forward;\r
 999 </simpara>\r
1000 </listitem>\r
1001 </varlistentry>\r
1002 <varlistentry>\r
1003 <term>\r
1004 <emphasis>+</emphasis>\r
1005 </term>\r
1006 <listitem>\r
1007 <simpara>\r
1008 for a successful forced update;\r
1009 </simpara>\r
1010 </listitem>\r
1011 </varlistentry>\r
1012 <varlistentry>\r
1013 <term>\r
1014 <emphasis>-</emphasis>\r
1015 </term>\r
1016 <listitem>\r
1017 <simpara>\r
1018 for a successfully pruned ref;\r
1019 </simpara>\r
1020 </listitem>\r
1021 </varlistentry>\r
1022 <varlistentry>\r
1023 <term>\r
1024 <emphasis>t</emphasis>\r
1025 </term>\r
1026 <listitem>\r
1027 <simpara>\r
1028 for a successful tag update;\r
1029 </simpara>\r
1030 </listitem>\r
1031 </varlistentry>\r
1032 <varlistentry>\r
1033 <term>\r
1034 <emphasis>*</emphasis>\r
1035 </term>\r
1036 <listitem>\r
1037 <simpara>\r
1038 for a successfully fetched new ref;\r
1039 </simpara>\r
1040 </listitem>\r
1041 </varlistentry>\r
1042 <varlistentry>\r
1043 <term>\r
1044 <emphasis>!</emphasis>\r
1045 </term>\r
1046 <listitem>\r
1047 <simpara>\r
1048 for a ref that was rejected or failed to update; and\r
1049 </simpara>\r
1050 </listitem>\r
1051 </varlistentry>\r
1052 <varlistentry>\r
1053 <term>\r
1054 <emphasis>=</emphasis>\r
1055 </term>\r
1056 <listitem>\r
1057 <simpara>\r
1058 for a ref that was up to date and did not need fetching.\r
1059 </simpara>\r
1060 </listitem>\r
1061 </varlistentry>\r
1062 </variablelist>\r
1063 </listitem>\r
1064 </varlistentry>\r
1065 <varlistentry>\r
1066 <term>\r
1067 summary\r
1068 </term>\r
1069 <listitem>\r
1070 <simpara>\r
1071         For a successfully fetched ref, the summary shows the old and new\r
1072         values of the ref in a form suitable for using as an argument to\r
1073         <emphasis>git log</emphasis> (this is <emphasis>&lt;old&gt;..&lt;new&gt;</emphasis> in most cases, and\r
1074         <emphasis>&lt;old&gt;...&lt;new&gt;</emphasis> for forced non-fast-forward updates).\r
1075 </simpara>\r
1076 </listitem>\r
1077 </varlistentry>\r
1078 <varlistentry>\r
1079 <term>\r
1080 from\r
1081 </term>\r
1082 <listitem>\r
1083 <simpara>\r
1084         The name of the remote ref being fetched from, minus its\r
1085         <emphasis>refs/&lt;type&gt;/</emphasis> prefix. In the case of deletion, the name of\r
1086         the remote ref is "(none)".\r
1087 </simpara>\r
1088 </listitem>\r
1089 </varlistentry>\r
1090 <varlistentry>\r
1091 <term>\r
1092 to\r
1093 </term>\r
1094 <listitem>\r
1095 <simpara>\r
1096         The name of the local ref being updated, minus its\r
1097         <emphasis>refs/&lt;type&gt;/</emphasis> prefix.\r
1098 </simpara>\r
1099 </listitem>\r
1100 </varlistentry>\r
1101 <varlistentry>\r
1102 <term>\r
1103 reason\r
1104 </term>\r
1105 <listitem>\r
1106 <simpara>\r
1107         A human-readable explanation. In the case of successfully fetched\r
1108         refs, no explanation is needed. For a failed ref, the reason for\r
1109         failure is described.\r
1110 </simpara>\r
1111 </listitem>\r
1112 </varlistentry>\r
1113 </variablelist>\r
1114 </simplesect>\r
1115 <simplesect id="git-fetch(1)__examples">\r
1116 <title>EXAMPLES</title>\r
1117 <itemizedlist>\r
1118 <listitem>\r
1119 <simpara>\r
1120 Update the remote-tracking branches:\r
1121 </simpara>\r
1122 <screen>$ git fetch origin</screen>\r
1123 <simpara>The above command copies all branches from the remote refs/heads/\r
1124 namespace and stores them to the local refs/remotes/origin/ namespace,\r
1125 unless the branch.&lt;name&gt;.fetch option is used to specify a non-default\r
1126 refspec.</simpara>\r
1127 </listitem>\r
1128 <listitem>\r
1129 <simpara>\r
1130 Using refspecs explicitly:\r
1131 </simpara>\r
1132 <screen>$ git fetch origin +seen:seen maint:tmp</screen>\r
1133 <simpara>This updates (or creates, as necessary) branches <emphasis>seen</emphasis> and <emphasis>tmp</emphasis> in\r
1134 the local repository by fetching from the branches (respectively)\r
1135 <emphasis>seen</emphasis> and <emphasis>maint</emphasis> from the remote repository.</simpara>\r
1136 <simpara>The <emphasis>seen</emphasis> branch will be updated even if it does not fast-forward,\r
1137 because it is prefixed with a plus sign; <emphasis>tmp</emphasis> will not be.</simpara>\r
1138 </listitem>\r
1139 <listitem>\r
1140 <simpara>\r
1141 Peek at a remote's branch, without configuring the remote in your local\r
1142   repository:\r
1143 </simpara>\r
1144 <screen>$ git fetch git://git.kernel.org/pub/scm/git/git.git maint\r
1145 $ git log FETCH_HEAD</screen>\r
1146 <simpara>The first command fetches the <emphasis>maint</emphasis> branch from the repository at\r
1147 <emphasis>git://git.kernel.org/pub/scm/git/git.git</emphasis> and the second command uses\r
1148 <emphasis>FETCH_HEAD</emphasis> to examine the branch with <xref linkend="git-log(1)" />.  The fetched\r
1149 objects will eventually be removed by git's built-in housekeeping (see\r
1150 <xref linkend="git-gc(1)" />).</simpara>\r
1151 </listitem>\r
1152 </itemizedlist>\r
1153 </simplesect>\r
1154 <simplesect id="git-fetch(1)__security">\r
1155 <title>SECURITY</title>\r
1156 <simpara>The fetch and push protocols are not designed to prevent one side from\r
1157 stealing data from the other repository that was not intended to be\r
1158 shared. If you have private data that you need to protect from a malicious\r
1159 peer, your best option is to store it in another repository. This applies\r
1160 to both clients and servers. In particular, namespaces on a server are not\r
1161 effective for read access control; you should only grant read access to a\r
1162 namespace to clients that you would trust with read access to the entire\r
1163 repository.</simpara>\r
1164 <simpara>The known attack vectors are as follows:</simpara>\r
1165 <orderedlist numeration="arabic">\r
1166 <listitem>\r
1167 <simpara>\r
1168 The victim sends "have" lines advertising the IDs of objects it has that\r
1169   are not explicitly intended to be shared but can be used to optimize the\r
1170   transfer if the peer also has them. The attacker chooses an object ID X\r
1171   to steal and sends a ref to X, but isn't required to send the content of\r
1172   X because the victim already has it. Now the victim believes that the\r
1173   attacker has X, and it sends the content of X back to the attacker\r
1174   later. (This attack is most straightforward for a client to perform on a\r
1175   server, by creating a ref to X in the namespace the client has access\r
1176   to and then fetching it. The most likely way for a server to perform it\r
1177   on a client is to "merge" X into a public branch and hope that the user\r
1178   does additional work on this branch and pushes it back to the server\r
1179   without noticing the merge.)\r
1180 </simpara>\r
1181 </listitem>\r
1182 <listitem>\r
1183 <simpara>\r
1184 As in #1, the attacker chooses an object ID X to steal. The victim sends\r
1185   an object Y that the attacker already has, and the attacker falsely\r
1186   claims to have X and not Y, so the victim sends Y as a delta against X.\r
1187   The delta reveals regions of X that are similar to Y to the attacker.\r
1188 </simpara>\r
1189 </listitem>\r
1190 </orderedlist>\r
1191 </simplesect>\r
1192 <simplesect id="git-fetch(1)__bugs">\r
1193 <title>BUGS</title>\r
1194 <simpara>Using --recurse-submodules can only fetch new commits in already checked\r
1195 out submodules right now. When e.g. upstream added a new submodule in the\r
1196 just fetched commits of the superproject the submodule itself cannot be\r
1197 fetched, making it impossible to check out that submodule later without\r
1198 having to do a fetch again. This is expected to be fixed in a future Git\r
1199 version.</simpara>\r
1200 </simplesect>\r
1201 <simplesect id="git-fetch(1)__see_also">\r
1202 <title>SEE ALSO</title>\r
1203 <simpara><xref linkend="git-pull(1)" /></simpara>\r
1204 </simplesect>\r
1205 <simplesect id="git-fetch(1)__git">\r
1206 <title>GIT</title>\r
1207 <simpara>Part of the <xref linkend="git(1)" /> suite</simpara>\r
1208 </simplesect>\r
1209 </sect2>\r