git.vger.kernel.org archive mirror
 help / color / mirror / Atom feed
From: Junio C Hamano <gitster@pobox.com>
To: Felipe Contreras <felipe.contreras@gmail.com>
Cc: git@vger.kernel.org
Subject: Re: [RFC/PATCH 0/2] New 'stage' command
Date: Sun, 05 Apr 2009 12:59:09 -0700	[thread overview]
Message-ID: <7vzleuq3ci.fsf@gitster.siamese.dyndns.org> (raw)
In-Reply-To: <7v7i1yrj3t.fsf@gitster.siamese.dyndns.org> (Junio C. Hamano's message of "Sun, 05 Apr 2009 12:33:26 -0700")

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.

  reply	other threads:[~2009-04-05 20:00 UTC|newest]

Thread overview: 38+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2009-04-05 13:48 Felipe Contreras
2009-04-05 13:48 ` [RFC/PATCH 1/2] git: remote stage Felipe Contreras
2009-04-05 13:48   ` [RFC/PATCH 2/2] Add new 'git stage' script Felipe Contreras
2009-04-05 19:02 ` [RFC/PATCH 0/2] New 'stage' command Junio C Hamano
2009-04-05 19:28   ` Felipe Contreras
2009-04-05 19:33     ` Junio C Hamano
2009-04-05 19:59       ` Junio C Hamano [this message]
2009-04-05 20:41         ` Felipe Contreras
2009-04-05 20:55           ` Jay Soffian
2009-04-05 22:06             ` Felipe Contreras
2009-04-05 19:34     ` [RFC/PATCH 0/2] " Nicolas Sebrecht
2009-04-05 21:58 ` [RFC/PATCH 0/2] " Markus Heidelberg
2009-04-05 22:35   ` Felipe Contreras
2009-04-05 23:06     ` Björn Steinbrink
2009-04-05 23:23       ` Markus Heidelberg
2009-04-06  9:48         ` Björn Steinbrink
2009-04-05 23:17     ` Markus Heidelberg
2009-04-05 23:22       ` Sverre Rabbelier
2009-04-05 23:45         ` Johannes Schindelin
2009-04-06  9:37           ` Felipe Contreras
2009-04-06  3:24         ` David Aguilar
2009-04-06  5:17           ` Junio C Hamano
2009-04-06  5:53             ` David Aguilar
2009-04-06  6:18               ` Junio C Hamano
2009-04-06 13:20             ` David Kågedal
2009-04-06 13:42               ` David Kågedal
2009-04-06 18:30               ` Junio C Hamano
2009-04-06 19:13                 ` Felipe Contreras
2009-04-06 19:25                   ` Björn Steinbrink
2009-04-07 10:01                     ` Felipe Contreras
2009-04-07 12:45                       ` Johannes Schindelin
2009-04-06 20:49                 ` Matthieu Moy
2009-04-07  0:55                   ` Junio C Hamano
     [not found]                 ` <87skkligzb.fsf@krank.kagedal.org>
2009-04-07  1:02                   ` Junio C Hamano
2009-04-07  8:39                     ` Octavio Alvarez
     [not found]                       ` <878wmcj1fs.fsf@krank.kagedal.org>
2009-04-07 15:01                         ` Octavio Alvarez
2009-04-07  1:36                 ` Stefan Karpinski
2009-04-07  7:38                 ` Octavio Alvarez

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:
  https://en.wikipedia.org/wiki/Posting_style#Interleaved_style

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=7vzleuq3ci.fsf@gitster.siamese.dyndns.org \
    --to=gitster@pobox.com \
    --cc=felipe.contreras@gmail.com \
    --cc=git@vger.kernel.org \
    --subject='Re: [RFC/PATCH 0/2] New '\''stage'\'' command' \
    /path/to/YOUR_REPLY

  https://kernel.org/pub/software/scm/git/docs/git-send-email.html

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).