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

Teemu Likonen <tlikonen@iki.fi> writes:

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.