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

From: Junio C Hamano <gitster@pobox.com>
Date: Apr 5, 2009, 19:59 UTC
Message-ID: <7vzleuq3ci.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <7v7i1yrj3t.fsf@gitster.siamese.dyndns.org>

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

Show 26 quoted lines

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