Re: [PATCH] Add examples section to 'git fetch' manual

[Junio C Hamano <gitster@pobox.com>]

Teemu Likonen <tlikonen@iki.fi> writes:

> +EXAMPLES
> +--------
> +
> +git fetch git://host.xz/repo.git/ master:pu::
> +	Fetch branch `master` from given repository URL and store it locally
> +	as `pu`.

While this may technically be correct (and I'll say upfront that all of
your "examples" may technically be correct), I would suggest strongly
against putting this into EXAMPLES section.  People look at examples
section to look up something they need to do often; the section should
describe the best practices we can suggest them in real life.

The above command line is a _great_ way to explain what happens under the
hood when you have the matching configuration in .git/config for the
remote, so that people would know how to update .git/config entries from
what git-clone and "git-remote add" give them by default to suit their
needs (e.g. instead of storing all branches in remotes/origin/*, you can
configure to only fetch and store a few selected branches).  But, fetching
from somewhere and storing it explicitly _from the command line_ like your
example command line is something you would _never_ do in real life if you
know git.

> +git fetch git://host.xz/repo.git/ master:remotes/pu::
> +	Fetch branch `master` from given repository URL and store it locally as
> +	remote tracking branch `pu`.

And this example is even worse, as the common example is to have remote
name between "remotes" and "pu".

> +git fetch git://host.xz/repo.git/ master::
> +	Fetch branch `master` from given repository URL but do not create the
> +	branch locally. Only the temporary pointer FETCH_HEAD is set to refer
> +	to the fetched branch.

This one is a fine example of a one-shot command to look at what they
have without actually affecting your own history.  Use of this form in
real life is very sane.

> +git fetch alice master:remotes/alice/pu::
> +	Fetch branch `master` from remote named `alice` and store it locally as
> +	remote tracking branch `alice/pu`. See linkgit:git-remote[1] for more
> +	information on configuring remotes.

This is a wrong example on multiple counts (this is one of the worst one
in your change, so I'll explain in more detail than for others).

First of all, think about the reason _why_ the convention is to use a
separate namespace under remotes/ per remote.  It is to allow us to use
the names that correspond to what the remote repository uses without
having to worry about name collisions, and the reason we took pains to
implement the mechanism to allow you to use such corresponding names is to
avoid having to remember "what she calls master is what I call pu".

"I want to make sure I can tell my master and her master apart without
confusing myself, so I'd call mine master and call hers alice/master" is
the recommended use pattern which "git clone" and "git remote add" give
the user.  An EXAMPLE that deviates from it without explaining why/when it
is a good thing to do is BAD.  Remember, many people blindly copy and
paste the examples section without thinking, assuming that they suggest
the best practice.

If you have nickname "alice" defined, you are by definition interacting
with her regularly.  If you are doing a one-off with such a repository,
running "git fetch alice master" and operating on the resulting FETCH_HEAD
(and you typically use tag or local branch if you want to mark that
commit, with "git tag" or "git branch"), would be much less error prone,
less confusing, and more straightforward recommended approach.  Typically,
you would have the usual refs/heads/*:refs/remotes/alice/* fetch refspec,
so you would not even say "master" and instead run "git fetch alice" and
look at "remotes/alice/master".

Your above command line again may be a great way to explain what you could
do and what the mechanism is equipped to allow you to, but I do not think
there is any reason to use it in the real life.  It should not be in the
EXAMPLE section.

> +git fetch origin::
> +	From the remote named `origin` fetch and store all branches as
> +	configured in `remote.origin.fetch`. Usually this means fetching all
> +	branches and storing them locally as remote tracking branches
> +	`origin/*`. See linkgit:git-remote[1] for more information.

This is a valid thing to add to the examples section, although I suspect
people would already know it when they encouter this page.