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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: Apr 5, 2009, 20:41 UTC
Message-ID: <94a0d4530904051341s7e8718c2uced945a16c26670e@mail.gmail.com>
In-Reply-To: <7vzleuq3ci.fsf@gitster.siamese.dyndns.org>

On Sun, Apr 5, 2009 at 10:59 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 31 quoted lines

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

Thanks for the clarification.

<snip/>

Consider this:

== cache ==

This word is barely used in the English language, perhaps only used in computing nowadays. The 'cache' is often referred to a place for temporary storage, the purpose being rapid access. It is usually transparent to the user.

Git uses the term in a completely different manner and the --cached option is used in important command such as rm and diff. However, people rarely use the term "git cache", probably because it immediately evokes multiple caches for better performances.

== index ==

It is unclear to me what the word means in English language, but it is generally used as a list of things, the purpose being for easy retrieval.

Again, git is using the term in a different manner, however it is the most widely used term to identify the concept "the git index", probably due to the fact that the word "index" evokes a single entity. But for some reason it's not used in any important commands as '--index' or '--indexed'.

== stage ==

The word "stage" is used widely in the English language, and it immediately evokes a theatrical stage. Generally, it means a different (upper) level.

In git it is barely used, mostly on the "documentation industry" probably because it's easier to understand for most people (even non-native-English speakers).

Ideally the term should evoke the concept of a *single* area that has no other purpose to differentiate from the contents of the working directory. Also, the action to add and remove content from this area should sound natural.

That rules out "cache" since "uncache" makes no sense. Something similar happens with "unindex", although it doesn't sound completely bad. On the other hand "stage" and "unstage" sound perfectly fine.

Show 13 quoted lines

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

Why is it so natural to co-relate "stage" to "adding to the index"? Would such a relation make sense outside of the git world? No. It is natural to you because you already know what is the "git index"... it is a *staging* area for commit preparation, logically it's natural to co-relate this area with the action "to stage".

Please note it is not an _indexing_ area, nor a _caching_ area.

I agree that the internal (plumbing) term does not need to match the conceptual term (used in documentation, tutorials, etc.), but the higher level (porcelain) term *must* match in order for new comers to grasp it quickly and avoid confusion.

I understand there are historic reasons for the names "cache" and "index" and those should be thought before considering any change.

But also consider that I'm not proposing any big change... the term "stage" is already being used, and there's already a "git stage" command. I'm only proposing to add a few more options :)

I would be very pleased if you could at least try the patch for a few days, and try "git stage diff" (or "git s diff" with an alias). I've become very fond of "git s" "git s diff" and "git s -p -u".

Cheers.

-- 
Felipe Contreras