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

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

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