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

[Junio C Hamano <gitster@pobox.com>]

David Kågedal <davidk@lysator.liu.se> writes:

> What do you mean? This was a suggestion for how git diff should
> work. I fail to see how you would need a WORKTREEANDTHEINDEX there.

You are talking only about "git diff".  I am talking about the whole git
suite, because you have to worry about how such a proposal would affect
other parts of the UI.

For example, what, if anything, should be done to "git grep --cached" and
"git apply --index"?  Leave them unchanged and only change "git diff"?

> I think this is a basic usability issue for a high-level porcelain
> command such as diff.

I do not think there is any usability issue.  Why do you think saying
STAGE in all capital makes it easier to _use_ instead of saying --cached
(or --index-only)?  In either way, you need to understand the underlying
concept, such as:

 - 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?

The only difference I see is that you change "via options and arguments"
to "via arguments of different kinds, either a real commit object name or
some fake token that stands for the index or the work tree state".

Spelled out more explicitly, the current "options and arguments" works
this way:

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

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

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

   - 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).

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;

   - when you want to work with the index, you say STAGE; not that you
     cannot have a ref called STAGE and if you have a file in the work
     tree whose name is STAGE you need to say "git command ... -- STAGE"
     to name the file, or "git command ... STAGE --" to clarify that you
     do not mean the file but you mean to use the fake toekn STAGE.

   - when you want to work with both the index and the work tree at the
     same time, you say STAGEANDWORKTREE (the same disambiguation caveat
     applies).

   - for all commands, working with work tree is the default, but you can
     still say WORKTREE (the same disambiguation caveat applies).

If anything, I think these capitalized fake tokens spread more confusion.

Sure, "git diff HEAD STAGED" and "git diff HEAD WORKTREE" may make the
command lines look as if what these fake tokens represent are "sort of"
commits, but that is only true while you are using a command that has
modes to work on the index and/or on the work tree.

These fake tokens do not work everywhere, and it is not an implementation
limit.  Fundamentally they cannot work everywhere.

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

The user needs to be aware that the index is NOT a commit to understand
why such a command line doesn't make sense _anyway_.

I think it is counterproductive for the learning curve of new people to
make these different concepts look as if they belong to the same family by
using STAGE (that look too similar to HEAD).  You seem to think it would
make it easier for them to learn if these different concepts are not
presented as different.  But they are different, and if new people start
with a false impression that these are "sort of" commits, they need to
unlearn that at some point, and that "some point" is not "advanced use".
Even bog standard "git log" exposes why hiding the conceptual differences
between these three states does not work.

Teach that different things are different, and express that in the UI.
That would avoid the confusion down the line.


[Footnote]

*1* "git apply" was originally done to replace use of "GNU patch" in
Linus's workflow because "patch" was deliberately too lenient, and as
such, it does not look at the index by default.  In a git repository, as
long as a patch does not contain creation of new files, this is a good
default, too.  You can "git apply incoming.patch && git diff -U20" to see
what the patch does in wider context, for example.  If "git apply --index"
were the default, the same can be done with "git diff -U20 HEAD" and it
won't risk forgetting new files.  But it is a huge backward incompatible
change that won't happen without deep thought.