Carl Worth <cworth@xxxxxxxxxx> writes: > There's another rule-of-thumb I would like to propose that's a bit > harder to state, but I think is just as important (if not more): > > For introductory documentation it should never make sense to > introduce a command with specific command-line options before > the same command without options. I tend to disagree. "This is the easiest way to use, even for beginners" and "this way should be the default for all levels of users" are quite different. > As examples, both "commit -a" and "cat-file -p" fail that test and > both appear in the git tutorial here: > > http://www.kernel.org/pub/software/scm/git/docs/tutorial.html > > My proposals to fix those two are: Creating a "git cat" and promote that in the Tutorial makes a lot of sense, but then that can easily be done with aliases ;-). cat-file is plumbing. We did not even have '-p' and you needed to _know_ the type of stuff you are feeding and we had '-t' to help you do so. '-p' was done as a quick hack because showing the representation of any object in semi human readable way was not all that important but occasionally people found it useful, and it just was an easy thing to do inside cat-file. Nobody bothered to do a real Porcelain called "git cat" for that purpose, so far, but that is probably what should have been. On the other hand, if "cat-file -p" needs to be used often, I think there is something ELSE that is wrong. I do not think defaulting to "commit -a" is a fix; rather, it feels exactly what Linus was talking about when he said about "second system syndrome". I would not mind if you created "commit-easy" (just like curl library has curl_x_easy), but the current way the command works is more useful once you grok the index. Being able to work in a slightly dirty tree and commit only the necessary things, and being able to do so even for a merge commit, is damn convenient. Because there is a learning curve involved, an easier way to use git without worrying about the index was added in the form of '-a' for beginners. People who use index regularly should not be forced to spend extra keystrokes for the rest of their lives only because you want to lose '-a' from the tutorial document. The tool should be designed for regular users, not for the first few pages of the tutorial. - 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