Re: [RFC/PATCH 0/2] New 'stage' command

Junio C Hamano [off-list ref] writes:

 - there are three distinct kinds of states: a committed state, the state
   in the index (aka "what you have staged so far to the index"), and the
   state in your work tree.

 - many commands understand that you want to operate on and/or inspect
   states in one or more of these states.  They default to what is often
   used (e.g. "git diff" compares the index and the work tree, "git grep"
   looks in the work tree, "git apply" patches the work tree [*1*]), but
   you can tell them to use different entities via options and arguments.

How does it help understanding any of the above to introduce STAGE?

For the first, if there are three kinds of states, I would find it
natural to have three kinds of ways to talk about these states.

Sure, it doesn't change the second, since it makes things more
explicit, it doesn't make them more concise.

   - when you want to work with the index, you say --cached;

But that doesn't apply to "git diff". Both "git diff" and "git diff
--cached" work with the index. "git diff" works with the index and work
tree, while "git diff --cached" work with the index and HEAD.

   - when you want to work with both the index and the work tree at the
     same time, you say --index.

... which is everything but intuitive. The option name doesn't tell
the user what the command is doing. First thing is that with Git, the
user has to learn 3 words for one concept (index, cache, staging
area). And then, he has to learn that although people use "index" and
"cache" as synomyms, --index and --cached have different meanings.
And that one can also have a --cache, and that it's possible to have a
--stage too, but with different meaning.

I can understand the historical reasons, but I think finding a way to
get rid of this historical terminology mess should be encourraged.

   - for all commands, working with work tree is the default, so there is
     no --work-tree option (we could add one, if you really want).

Except "git checkout", which takes the index by default, and
a commit if specified. It makes sense since checking-out from the
working tree doesn't make sense, but it is a special case, and
learning the general rules you give doesn't tell the user what "git
checkout" does.

Except "git ls-files", too. And I may have missed some.

See, you complain about special cases with the proposal, but the
current UI _has_ tons of special cases like this.

and the STAGE would work something like this:

   - when you want to work with a committed state (or more in general,
     with a tree-ish), you give the name of the commit;

It's not just "I want to work with". It's also about the role of the
things you want to work with.

"git diff WORKTREE STAGE" would mean "diff from the worktree to the
staging area", while "git diff STAGE WORKTREE" would mean the other
way around.

Think.  What does "git log STAGE" mean?  Can you explain why it does not
make any sense?

It could make sense. Actually, gitk does show the work-tree and the
index in a way similar to commits. Fundamentally, I don't see a
difference between "git log" and "gitk" except that gitk is graphical.

Sure, STAGE and WORKTREE cannot have a commit message, and hardly have
an author, but I could very well imagine "git log --stat WORKTREE"
showing roughly what "git diff --stat; git diff --stat --cached; git
log --stat HEAD" does today. I don't know how usefull this would be,
but I wouldn't say it doesn't make sense either.

-- 
Matthieu