Re: Hyphens and hiding core commands

Carl Worth [off-list ref] 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.