Teemu Likonen <tlikonen@xxxxxx> 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. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
