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

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

Junio C Hamano <gitster@pobox.com> writes:

> Felipe Contreras <felipe.contreras@gmail.com> writes:
>
>> On Sun, Apr 5, 2009 at 10:02 PM, Junio C Hamano <gitster@pobox.com> wrote:
>>> Felipe Contreras <felipe.contreras@gmail.com> writes:
>>>
>>>> This is the list of actions I've mapped:
>>>>
>>>>  * add: git stage = git stage add (git add)
>>>>  * rm: (git rm --cached)
>>>>  * diff: (git rm --cached)
>>>>  * import: stage all files; modified, deleted, new
>>>>  * ls: (git ls-files --stage)
>>>
>>> I do not think these are good ideas at all, as it just spreads more
>>> confusion, not less.
>>
>> Do you agree that there's already a lot of confusion? (stage, cache,
>> index, etc.)
>>
>> And do you agree that many git newbies don't use the stage? Actually
>> most of them don't even know what it is, and just do "git commit -a".
>>
>> If so, how do you think these issues should be handled?
>
> Perhaps not spreading "stage" even wider?  That is the newest confusing
> term that caused the most harm.

This probably needs clarification for new people who do not know the
history.

Before Linus published the very original git, he was designing a system
that can work with the tarball+patches workflow, and dircache (which was
the name of the .git directory) was a mechanism to give various snapshots
a faster access by using the git object machinery by "caching" the result
of applying sequence of patches to certain point of history.  The file
inside the .dircache that records the object names that correspond to the
state in the work tree state was .dircache/index.

We've been living with the cache/index, and many user visible actions have
been called in sentences like "adding contents to the cache" or "comparing
with the index" that used cache/index more or less interchangeably.  Later
we started to standardizing on the term "index" primarily because that is
the entity on the filesystem the end user is aware of (as opposed to
"cache" that still live throughout the code).

Some operations however needed to have two modes of operation, one being
working on both work tree files and the index and another being working
only on the index.  Most of the time, the former was the default (and the
only mode implemented) and the latter mode needed an explicit option to
ask for.  --cached is used when you ask them to ignore work tree
(i.e. "git apply --cached", "git diff --cached").  Unfortunately apply has
a third variant that works only on the work tree and because it is meant
as a replacement of GNU patch that works outside a git repository, that
mode is the default, and you need to ask with "git apply --index" to
affect both the index and the work tree.

If we were already well into "standardize on index, not telling the
end-users about cache" journey back then, and --cached should have been
called --index-only, but unfortunately the history was the other way
around.

Later, some outside people started "git training industry" without talking
with the git development community and started using a new term "to stage"
as a verb to describe "add to the index".  Addition of "git diff --staged"
was supposed to lesson the confusion resulted from this mess, but as we
can see from your patch it had a reverse effect.

I do not think "to stage" as the name of the _concept_ is a bad thing
per-se.  But the name of the concept and the command verb (and option
name) does not have to agree with each other.

    cf. http://gitster.livejournal.com/19427.html

In retrospect, I think it might have been less problematic if we firmly
rejected "stage" as an option name, but instead renamed the --cached
option to --index-only and made the former a synonym to the latter to
really standardize on "index".  I think it still is Ok to use the word "to
stage" to colloquially call the act of "adding to index", but if we did
not add that to the UI but kept it strictly at the concept level, it would
have made the UI less confusing, not more.