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.
And this example is even worse, as the common example is to have remote
name between "remotes" and "pu".
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.
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.
This is a valid thing to add to the examples section, although I suspect
people would already know it when they encouter this page.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at http://vger.kernel.org/majordomo-info.html
