I am not sure what needs to be commented on at this point, since

it is not yet clear to me where you want your proposal to lead

us.
I do not agree with your "three commands" or "two semantics"

characterization of the current way "git commit" works.  "git

commit" without any optional argument already acts as if a

sensible default arguments are given, that is "no funny business

with additional paths, commit just what the user has staged

already."
"git commit" is primarily about committing what has been staged

in the index, and "--all" is just a type-saver short-hand (just

like "--include" is) to perform update-index the last minute and

nothing more.  In other words, "--all" is a variant of the

pathname-less form "git commit".  It is not a variant of "git

commit --only paths..." form, as you characterized.
The pathname form (the "--only" variant) on the surface seem to

work differently, but when you think about it, it is not all

that different from the normal commit.  We explain that it

ignores index, but in the bigger picture, it does not really.
In this sequence:
	edit a b

	git update-index a

	git commit --only b

	git commit --all
the first commit does "jump" the changes already made to the

index, but after it makes the commit, the index has the same

contents as if you did "git update-index a b" where you ran that

"git commit".  In other words, it is just a handy short-hand to

pretend as if you did the above sequence in this order instead:
	edit a b

        git update-index b

        git commit

        git update-index a

        git commit
So I actually think it is a mistake to stress the fact that "git

commit --only paths..." seems to act differently from the normal

"git commit" too much.  It just helps to split the changes in

your working tree if the changes happen to be cleanly separable

at file boundaries (aka "CVS mentality").  When the changes are

not cleanly separable at file boundaries, the "more painfully

index aware" variant also allows you to spl...
[ message continues ]

Thanks for the comments you made here---that's the kind of thing I was

looking for.
As for where I'm trying to lead us, what I really want to do is to

help improve the learnability of git. A big part of that is about

improving the set of "use-oriented" documentation, (which describes

how to achieve tasks, as opposed to what might be termed "technically

oriented" documentation which describes how individual tools work). I

think too much of the existing documentation falls into the second

class.
A parallel thread is already talking about some of the important

organizational aspects of use-oriented documentation. And I agree with

that thread is that the short "attention span" is a primary

consideration for this kind of documentation. The user has a task to

be accomplish, and any text or concepts that aren't contributing to

the solution of that task should be eliminated.
Note that when I talk about eliminating unnecessary concepts, I do not

mean lying to the user about the underlying model or any concepts. We

can't have a sugar-coated tutorial that says one thing, and then

expect users to "unlearn" that if they go deeper into the reference

manual. That's a recipe for disaster.
Also, when I say "use-oriented" I'm not suggesting that the

documentation be shallow. It can go as deep as any workflow we care to

document and introduce whatever concepts of git are necessary to

support that workflow. (There is, though a level at which "technically

oriented" documentation is all that's needed, or even desired, and

that's when the documentation is targeting authors of interfaces that

build on top of git---not users trying to use git to get work done at

the command line).
OK, so if my concern is all about documentation, then what am I doing

proposing new commands or new ways of thinking about existing commands

rather than just sending documentation patches? The problem is that

the current semantics of the following variations of "git commit":
	git commit

	git commit -a

	git commit ...
[ message continues ]