Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Since the introduction of opportunisitic updates of remote-tracking
branches, started at around f2690487 (fetch: opportunistically
update tracking refs, 2013-05-11) with a few updates in v1.8.4 era,
the remote.*.fetch configuration always kicks in even when a refspec
to specify what to fetch is given on the command line, and there is
no way to disable or override it per-invocation.

Teach the command to pay attention to the --refmap=<lhs>:<rhs>
command-line options that can be used to override the use of
configured remote.*.fetch as the refmap.

Signed-off-by: Junio C Hamano <gitster@pobox.com>
---

To resurrect a misleading mention removed in the previous step,
add a section to explain how the remote-tracking configuration
interacts with the refspecs given as the command-line arguments.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

It is misleading to mention that <ref> that does not store is to
fetch the ref into FETCH_HEAD, because a refspec that does store is
also to fetch the LHS into FETCH_HEAD.  It is doubly misleading to
list it as part of "short-cut".  <ref> stands for a refspec that has
it on the LHS with a colon and an empty RHS, and that definition
should be given at the beginning of the entry where the format is
defined.

Tentatively remove this misleading description, which leaves the
`tag <tag>` as the only true short-hand, so move it at the beginning
of the entry.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

The text made it sound as if the leading plus is the only thing that
is optional, and forgot that <lhs> is the same as <lhs>:, i.e. fetch
it and do not store anywhere.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

Replace desription of old-style "Pull:" lines in remotes/
configuration with modern remote.*.fetch variables.

As this note applies only to "git pull", enable it only
in git-pull manual page.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

In old days before Git 1.5, it was customery for "git fetch" to use
the same local branch namespace to keep track of the remote-tracking
branches, and it was necessary to tell users not to check them out
and commit on them.  Since everybody uses the separate remote layout
these days, there is no need to warn against the practice to check
out the right-hand side of <refspec> and build on it---the RHS is
typically not even a local branch.

Incidentally, this also kills one mention of "Pull:" line of
$GIT_DIR/remotes/* configuration, which is a lot less familiar to
new people than the more modern remote.*.fetch configuration
variable.

Signed-off-by: Junio C Hamano <gitster@pobox.com>

While it is not *wrong* per-se to say that pulling a rewound/rebased
branch will lead to an unnecessary merge conflict, that is not what
the leading "+" sign to allow non-fast-forward update of remote-tracking
branch is at all.

Helped-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

Signed-off-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

 - "Branches" is a more common way to say "heads" in these days.

 - Remote-tracking branches are used a lot more these days and it is
   worth mentioning that it is one of the primary side effects of
   the command to update them.

 - Avoid "X. That means Y."  If Y is easier to understand to
   readers, just say that upfront.

 - Use of explicit refspec to fetch tags does not have much to do
   with turning "auto following" on or off.  It is a way to fetch
   tags that otherwise would not be fetched by auto-following.

Helped-by: Marc Branchaud <marcnarc@xiplink.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>