[1.8.0] use 'stage' term consistently

[1.8.0] use 'stage' term consistently

[Felipe Contreras]

Proposal:

Avoid the terms 'cache' and 'index' in favor of 'stage'.

Advantages:

The term 'stage' is more intuitive for newcomers which are more
familiar with English than with git, and it seems to be a
straightforward mental notion for people from different mother
tongues.

It is so intuitive that it is used already in a lot online
documentation, and the people that do teach git professionally use
this term.

Risks:

People might be accustomed to the current options, and might take some
time to get used to the new term. Scripts might be relying on the
current options.

There's also the possibility that a lot of people prefer the terms
'cache' and 'index', but from the countless discussions on this
subject, that seems to be rather unlikely.

Migration plan:

Follow a typical obsolete/deprecate process; for a period of time warn
that the options are obsolete and shouldn't be used, in case there's a
lot of people against this, this period would allow for them to shout;
then remove them.

Rationale:

First of all, this discussion _always_ keeps coming back, so its clear
something needs to be done, and in the last big discussion the
consensus was that 'stage' was the best option. In summary:

cache: a 'cache' is a place for easier access; a squirrel caches nuts
so it doesn't have to go looking for them in the future when it might
be much more difficult. Git porcelain is not using the staging area
for easier future access; it's not a cache.

index: an 'index' is a guide of pointers to something else; a book
index has a list of entries so the reader can locate information
easily without having to go through the whole book. Git porcelain is
not using the staging area to find out entries quicker; it's not an
index.

stage: a 'stage' is a special area designated for convenience in order
for some activity to take place; an orator would prepare a stage in
order for her speak to be successful, otherwise many people might not
be able to hear, or see her.  Git porcelain is using the staging area
precisly as a special area to be separated from the working directory
for convenience.

The term 'stage' is a good noun itself, but also 'staging area', it
has a good verb; 'to stage', and a nice past-participle; 'staged'.

-- 
Felipe Contreras

Re: [1.8.0] use 'stage' term consistently

[Philip Oakley]

From: "Felipe Contreras" <felipe.contreras@gmail.com> Sent: Saturday, May 
05, 2012 2:04 PM
> Proposal:
>
> Avoid the terms 'cache' and 'index' in favor of 'stage'.
>
> Advantages:
>
> The term 'stage' is more intuitive for newcomers which are more
> familiar with English than with git, and it seems to be a
> straightforward mental notion for people from different mother
> tongues.
>
> It is so intuitive that it is used already in a lot online
> documentation, and the people that do teach git professionally use
> this term.

I've never found any of the terms to be great (as per this discussion ;-).

The term that helped me most, heard on one of the git videos, was "it's like 
a manifest", alluding to a 'shipping manifest', which then leads to both the 
"staging area" and "index" terms. Though "index" is probably too technical 
for most folk.

The allusion to shipping a consignment or rail marshalling (classification) 
yards, and similar frieght flows, may be another way for _explaining_ the 
term chosen for the preparation, consolidation and aggregation of the next 
shipment (commit). Most other VCS systems hide this stage (sic), hence the 
difficulty in explaining this to the lay person.

> Risks:
>
> People might be accustomed to the current options, and might take some
> time to get used to the new term. Scripts might be relying on the
> current options.
>
> There's also the possibility that a lot of people prefer the terms
> 'cache' and 'index', but from the countless discussions on this
> subject, that seems to be rather unlikely.
>
> Migration plan:
>
> Follow a typical obsolete/deprecate process; for a period of time warn
> that the options are obsolete and shouldn't be used, in case there's a
> lot of people against this, this period would allow for them to shout;
> then remove them.
>
> Rationale:
>
> First of all, this discussion _always_ keeps coming back, so its clear
> something needs to be done, and in the last big discussion the
> consensus was that 'stage' was the best option. In summary:
>
> cache: a 'cache' is a place for easier access; a squirrel caches nuts
> so it doesn't have to go looking for them in the future when it might
> be much more difficult. Git porcelain is not using the staging area
> for easier future access; it's not a cache.
>
> index: an 'index' is a guide of pointers to something else; a book
> index has a list of entries so the reader can locate information
> easily without having to go through the whole book. Git porcelain is
> not using the staging area to find out entries quicker; it's not an
> index.
>
> stage: a 'stage' is a special area designated for convenience in order
> for some activity to take place; an orator would prepare a stage in
> order for her speak to be successful, otherwise many people might not
> be able to hear, or see her.  Git porcelain is using the staging area
> precisly as a special area to be separated from the working directory
> for convenience.
>
> The term 'stage' is a good noun itself, but also 'staging area', it
> has a good verb; 'to stage', and a nice past-participle; 'staged'.
>
> -- 
> Felipe Contreras

Philip 

Re: [1.8.0] use 'stage' term consistently

[Felipe Contreras]

On Sat, May 5, 2012 at 6:52 PM, Philip Oakley <philipoakley@iee.org> wrote:
> From: "Felipe Contreras" <felipe.contreras@gmail.com> Sent: Saturday, May
> 05, 2012 2:04 PM
>
>> Proposal:
>>
>> Avoid the terms 'cache' and 'index' in favor of 'stage'.
>>
>> Advantages:
>>
>> The term 'stage' is more intuitive for newcomers which are more
>> familiar with English than with git, and it seems to be a
>> straightforward mental notion for people from different mother
>> tongues.
>>
>> It is so intuitive that it is used already in a lot online
>> documentation, and the people that do teach git professionally use
>> this term.
>
>
> I've never found any of the terms to be great (as per this discussion ;-).
>
> The term that helped me most, heard on one of the git videos, was "it's like
> a manifest", alluding to a 'shipping manifest', which then leads to both the
> "staging area" and "index" terms. Though "index" is probably too technical
> for most folk.
>
> The allusion to shipping a consignment or rail marshalling (classification)
> yards, and similar frieght flows

Perhaps, but these terms are not already used everywhere, unlike
'stage', and haven't been brought in past discussions. Personally the
word 'manifest' says nothing to me (manifesto?), neither does
consignment, or marshalling. As discussed before, we need a term that
has a nice noun (stage), verb (to stage), and past-participle
(staged). There have been a lot of suggestions, but nothing as good as
'stage', which is presumably the reason why it's so prevalent in
online documentation.

Maybe you are quite familiar with ships :)

Cheers.

-- 
Felipe Contreras

Re: [1.8.0] use 'stage' term consistently

[Philip Oakley]

From: "Felipe Contreras" <felipe.contreras@gmail.com> Sent: Saturday, May
05, 2012 6:30 PM
> On Sat, May 5, 2012 at 6:52 PM, Philip Oakley <philipoakley@iee.org>
> wrote:
>> From: "Felipe Contreras" <felipe.contreras@gmail.com> Sent: Saturday, May
>> 05, 2012 2:04 PM
>>
>>> Proposal:
>>>
>>> Avoid the terms 'cache' and 'index' in favor of 'stage'.
>>>
>>> Advantages:
>>>
>>> The term 'stage' is more intuitive for newcomers which are more
>>> familiar with English than with git, and it seems to be a
>>> straightforward mental notion for people from different mother
>>> tongues.
>>>
>>> It is so intuitive that it is used already in a lot online
>>> documentation, and the people that do teach git professionally use
>>> this term.
>>
>>
>> I've never found any of the terms to be great (as per this discussion
>> ;-).
>>
>> The term that helped me most, heard on one of the git videos, was "it's
>> like
>> a manifest", alluding to a 'shipping manifest', which then leads to both
>> the
>> "staging area" and "index" terms. Though "index" is probably too
>> technical
>> for most folk.
>>
>> The allusion to shipping a consignment or rail marshalling
>> (classification)
>> yards, and similar freight flows
>
> Perhaps, but these terms are not already used everywhere, unlike
> 'stage', and haven't been brought in past discussions. Personally the
> word 'manifest' says nothing to me (manifesto?), neither does
> consignment, or marshalling.

Useful to know..  The fact that there is such a variety of terms, usually
based on specialist transport, is an indication of our on-going
difficulties - people just don't talk about this aspect of 'work'. Usually
it (packaging)  is 'someone else's problem' ;-)  E.g. what's it called when
the post office batches up mail in the 'sorting' office? - I don't know, nor 
usually care, except when I just post 60 letters to Hawaii - should I put a 
band around them to 'help' the post office ... In the git case, unusually 
for a VCS, we do our own grouping, but need a verb.

Aside: wikipedia notes that even UK and US English railways can't agree 
their term
(http://en.wikipedia.org/wiki/Marshalling_yards) on what to call the
'staging' process we are discussing

I looked up a translation (I hope I haven't mis-chosen):
    shipping manifest (n) (bill or inventory enclosed with a consignment)
    manifiesto de carga (nm)
so (to me) it does look like "index" is the best word for our *list* of what 
we have
prepared, and the stage of preparation of those items for our next commit 
(shipment to the repo).

It probably doesn't help that the concepts and the implementation aren't 
always in alignment (a generic DVCS problem). e.g. when we `add` a file, a 
copy goes straight into our objects store, but isn't actually 'in' the repo. 
So the discussion suffers from knowing too much.

> As discussed before, we need a term that
> has a nice noun (stage), verb (to stage), and past-participle
> (staged). There have been a lot of suggestions, but nothing as good as
> 'stage', which is presumably the reason why it's so prevalent in
> online documentation.

Ooops, my note about my wording suggestions being used for *explanation* got 
lost in
the trimming. I wasn't suggesting a change to the candidate terms.

>
> Maybe you are quite familiar with ships :)
>
UK - home of the railways, and the SS Great Britain, and the Titanic ...
Philip 

Re: [1.8.0] use 'stage' term consistently

[Zbigniew Jędrzejewski-Szmek]

On 05/05/2012 03:04 PM, Felipe Contreras wrote:
> Proposal:
> 
> Avoid the terms 'cache' and 'index' in favor of 'stage'.
Yeah, I think that this is a very good idea. Having three different
terms for this great but relatively obscure idea adds an unnecessary
cognitive burden for newcomers to git. 'stage' is certainly the best of
the three options.

> stage: a 'stage' is a special area designated for convenience in order
> for some activity to take place; an orator would prepare a stage in
> order for her speak to be successful, otherwise many people might not
> be able to hear, or see her.  Git porcelain is using the staging area
> precisly as a special area to be separated from the working directory
> for convenience.
I think you missed the most relevant meaning-of/phrase-with this word in
this context, the one that is really the reason why it is used in git:

"A staging area (or staging point) is a location where organisms,
people, vehicles, equipment or material are assembled before use."
[http://en.wikipedia.org/wiki/Staging_area]

> The term 'stage' is a good noun itself, but also 'staging area', it
> has a good verb; 'to stage', and a nice past-participle; 'staged'.

-
Zbyszek

Re: [1.8.0] use 'stage' term consistently

[Jakub Narebski]

On Sat, 5 May 2012, Felipe Contreras wrote:

> Proposal:
> 
> Avoid the terms 'cache' and 'index' in favor of 'stage'.
[...]
> Rationale:
> 
> First of all, this discussion _always_ keeps coming back, so its clear
> something needs to be done, and in the last big discussion the
> consensus was that 'stage' was the best option. In summary:
> 
> cache: a 'cache' is a place for easier access; a squirrel caches nuts
> so it doesn't have to go looking for them in the future when it might
> be much more difficult. Git porcelain is not using the staging area
> for easier future access; it's not a cache.

Actually Git porcelain does use 'the index' as a cache (computing),
i.e. as a place to store redundant information (stat data, sha-1
for trees with DIRC dircache extension) for faster access.

But is not all it does...
 

Nb. 'the index' started as dircache at the very begining, and this 
historical legacy shows through in a few places (including 
documentation and plumbing error messages).

> index: an 'index' is a guide of pointers to something else; a book
> index has a list of entries so the reader can locate information
> easily without having to go through the whole book. Git porcelain is
> not using the staging area to find out entries quicker; it's not an
> index.

Actually 'the index' is index in that sense; it stores _references_
from filename to file contents, using SHA-1 identifier of a file/tree 
contents in place of page number in the book index.  The SHA-1 
identifier of object which is stored in database of repository, not the 
index itself.

But it is not all it does...

> stage: a 'stage' is a special area designated for convenience in order
> for some activity to take place; an orator would prepare a stage in
> order for her speak to be successful, otherwise many people might not
> be able to hear, or see her.  Git porcelain is using the staging area
> precisly as a special area to be separated from the working directory
> for convenience.

True, 'the index' serves a staging area to build a commit, or to resolve 
a merge conflict.

But from above comments you can see that it is not all it does...

> The term 'stage' is a good noun itself, but also 'staging area', it
> has a good verb; 'to stage', and a nice past-participle; 'staged'.

Anyway another issue to resolve is '--cached' and '--index' command line 
options, as described in gitcli(7) manpage:

  Many commands that can work on files in the working tree
  and/or in the index can take `--cached` and/or `--index`
  options.  Sometimes people incorrectly think that, because
  the index was originally called cache, these two are
  synonyms.  They are *not* -- these two options mean very
  different things.

   * The `--cached` option is used to ask a command that
     usually works on files in the working tree to *only* work
     with the index.  For example, `git grep`, when used
     without a commit to specify from which commit to look for
     strings in, usually works on files in the working tree,
     but with the `--cached` option, it looks for strings in
     the index.

   * The `--index` option is used to ask a command that
     usually works on files in the working tree to *also*
     affect the index.  For example, `git stash apply` usually
     merges changes recorded in a stash to the working tree,
     but with the `--index` option, it also merges changes to
     the index as well.

You can use '--staged' in place of '--cached', but what about '--index'?
How do you replace it?


BTW. here is the list of porcelain commands that use those command
line options:

  Command         --cached        --index
  ----------------------------------------
  git-apply           X               X
  git-diff            X
  git-grep            X
  git-ls-files        X
  git-rm              X
  git-stash^*                         X
  git-submodule^#     X


  Footnotes
  .........
  [*] "git stash pop" and "git stash apply" subcommands
  [#] "git submodule status" and "git submodule summary" subcommands

-- 
Jakub Narebski
Poland

Re: [1.8.0] use 'stage' term consistently

[Matthieu Moy]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> Proposal:
>
> Avoid the terms 'cache' and 'index' in favor of 'stage'.

I completely agree that something needs to be done.

But there are at least two points that were raised during the previous
discussions that need to be taken into account:

* Currenly, "index" and "staging area" are not exactly synonyms. When
  used with "git add" and "git commit" (without -a), the index is the
  staging area for the next commit. But when used by "git merge", the
  index is more a "merging area".

* There is currently a distinction in the meaning of --cached and
  --index. See the end of Documentation/gitcli.txt. I think it is good
  to have this distinction, but I agree that the wording of current
  option name is wrong (i.e. without having read gitcli.txt, I don't
  think anyone could have guessed this distinction). Perhaps something
  like --staged-only/--staged-too?

About the name, an alternative to "stage" was suggested earlier:
"precommit". If we were to rewrite Git from scratch, I'd argue in favor
of this one, which is really easy to understand, especially for
non-native (you really need to know what a "commit" is to use Git, and
then infering the meaning of precommit is easy). But we probably have
already a too long history of changing the name, so introducing yet
another one is perhaps counter-productive. I don't know.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [1.8.0] use 'stage' term consistently

[Matthieu Moy]

Jakub Narebski <jnareb@gmail.com> writes:

> Actually Git porcelain does use 'the index' as a cache (computing),
> i.e. as a place to store redundant information (stat data, sha-1
> for trees with DIRC dircache extension) for faster access.

This is an implementation optimization, that is not supposed to be
visible for the user. Commands refering to the "cache" are not about
stat data cache (e.g. "git diff --cached" is really about the content,
not the stat cache).

>> index: an 'index' is a guide of pointers to something else; a book
>> index has a list of entries so the reader can locate information
>> easily without having to go through the whole book. Git porcelain is
>> not using the staging area to find out entries quicker; it's not an
>> index.
>
> Actually 'the index' is index in that sense; it stores _references_
> from filename to file contents, using SHA-1 identifier of a file/tree 
> contents in place of page number in the book index.  The SHA-1 
> identifier of object which is stored in database of repository, not the 
> index itself.

The implementation is done like this, but the user doesn't really care
about this. For example, git-add(1) says "The index holds a snapshot
of the content of the working tree", not "The index holds a set of
references to sha1sums".

There's no need to expose these two implementation details in the
terminology used in the interface. Indeed, I've often seen people from
other VCS confused by Git's index just because of the terminology.
Because we sometimes call it "cache", they think it is basically a
stat-cache, and wonder why it is shown to the user. I've even seen
Git users think that others VCS didn't have a stat-cache because they
had read that the "cache" was a unique Git feature.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [1.8.0] use 'stage' term consistently

[Felipe Contreras]

On Sun, May 6, 2012 at 12:39 PM, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
>
>> Actually Git porcelain does use 'the index' as a cache (computing),
>> i.e. as a place to store redundant information (stat data, sha-1
>> for trees with DIRC dircache extension) for faster access.
>
> This is an implementation optimization, that is not supposed to be
> visible for the user. Commands refering to the "cache" are not about
> stat data cache (e.g. "git diff --cached" is really about the content,
> not the stat cache).

Exactly; that's an implementation detail that doesn't affect how the
user actually interacts with the staging area.

-- 
Felipe Contreras

Re: [1.8.0] use 'stage' term consistently

[Felipe Contreras]

On Sun, May 6, 2012 at 12:21 PM, Jakub Narebski <jnareb@gmail.com> wrote:

> Anyway another issue to resolve is '--cached' and '--index' command line
> options, as described in gitcli(7) manpage:
>
>  Many commands that can work on files in the working tree
>  and/or in the index can take `--cached` and/or `--index`
>  options.  Sometimes people incorrectly think that, because
>  the index was originally called cache, these two are
>  synonyms.  They are *not* -- these two options mean very
>  different things.
>
>   * The `--cached` option is used to ask a command that
>     usually works on files in the working tree to *only* work
>     with the index.  For example, `git grep`, when used
>     without a commit to specify from which commit to look for
>     strings in, usually works on files in the working tree,
>     but with the `--cached` option, it looks for strings in
>     the index.
>
>   * The `--index` option is used to ask a command that
>     usually works on files in the working tree to *also*
>     affect the index.  For example, `git stash apply` usually
>     merges changes recorded in a stash to the working tree,
>     but with the `--index` option, it also merges changes to
>     the index as well.
>
> You can use '--staged' in place of '--cached', but what about '--index'?
> How do you replace it?

From past discussions it was suggested to use --staged-only for
--cached, and --staged for --index in commands that need this
distinction. Alternatively it could be --cached -> --staged, --index
-> --stage-and-wd, or something like that.

Cheers.

-- 
Felipe Contreras

Re: [1.8.0] use 'stage' term consistently

[Felipe Contreras]

On Sun, May 6, 2012 at 12:26 PM, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> Felipe Contreras <felipe.contreras@gmail.com> writes:

> * Currenly, "index" and "staging area" are not exactly synonyms. When
>  used with "git add" and "git commit" (without -a), the index is the
>  staging area for the next commit. But when used by "git merge", the
>  index is more a "merging area".

And what is the difference? The result of the 'merging area' is still a commit.

> About the name, an alternative to "stage" was suggested earlier:
> "precommit". If we were to rewrite Git from scratch, I'd argue in favor
> of this one, which is really easy to understand, especially for
> non-native (you really need to know what a "commit" is to use Git, and
> then infering the meaning of precommit is easy). But we probably have
> already a too long history of changing the name, so introducing yet
> another one is perhaps counter-productive. I don't know.

I don't know, precommit is not an English word, and it was discussed
before, but not many people vouched for it.

Plus, it's not already widely used in the interwebs documentation as
staging area is.

Cheers.

-- 
Felipe Contreras

Re: [1.8.0] use 'stage' term consistently

[Jakub Narebski]

On Sun, May 6, 2012, Felipe Contreras wrote:
> On Sun, May 6, 2012 at 12:39 PM, Matthieu Moy
> <Matthieu.Moy@grenoble-inp.fr> wrote:
> > Jakub Narebski <jnareb@gmail.com> writes:
> >
> > > Actually Git porcelain does use 'the index' as a cache (computing),
> > > i.e. as a place to store redundant information (stat data, sha-1
> > > for trees with DIRC dircache extension) for faster access.
> >
> > This is an implementation optimization, that is not supposed to be
> > visible for the user. Commands refering to the "cache" are not about
> > stat data cache (e.g. "git diff --cached" is really about the content,
> > not the stat cache).
> 
> Exactly; that's an implementation detail that doesn't affect how the
> user actually interacts with the staging area.

Well, it does (or hopefully just did) affect the user: _if it fails_,
in the form of empty diff on no changes because of stat-dirtyness
or racy-git :-P

-- 
Jakub Narebski
Poland

Re: [1.8.0] use 'stage' term consistently

[Ævar Arnfjörð Bjarmason]

On Sun, May 6, 2012 at 11:16 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> I don't know, precommit is not an English word, and it was discussed
> before, but not many people vouched for it.

FWIW in the Icelandic translation I translated "index/stage" to the
equivalent of "the commit area".

Re: [1.8.0] use 'stage' term consistently

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> On Sun, May 6, 2012 at 11:16 PM, Felipe Contreras
> <felipe.contreras@gmail.com> wrote:
>> I don't know, precommit is not an English word, and it was discussed
>> before, but not many people vouched for it.
>
> FWIW in the Icelandic translation I translated "index/stage" to the
> equivalent of "the commit area".

Care to explain why you did not use a translation of the verb/noun
"stage"?  I actually was having a hard time to come up with Japanese
translation (not that I have plan to contribute to ja_JP.po), as the
shipping/logistics term "to stage" does not cleanly translate to the
language without unnecessary connotation that imply what is described is
something the our "index" actually is _not_.

Re: [1.8.0] use 'stage' term consistently

[Ævar Arnfjörð Bjarmason]

On Mon, May 7, 2012 at 7:52 PM, Junio C Hamano <gitster@pobox.com> wrote:
> Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:
>
>> On Sun, May 6, 2012 at 11:16 PM, Felipe Contreras
>> <felipe.contreras@gmail.com> wrote:
>>> I don't know, precommit is not an English word, and it was discussed
>>> before, but not many people vouched for it.
>>
>> FWIW in the Icelandic translation I translated "index/stage" to the
>> equivalent of "the commit area".
>
> Care to explain why you did not use a translation of the verb/noun
> "stage"?  I actually was having a hard time to come up with Japanese
> translation (not that I have plan to contribute to ja_JP.po), as the
> shipping/logistics term "to stage" does not cleanly translate to the
> language without unnecessary connotation that imply what is described is
> something the our "index" actually is _not_.

Because there's no equivalent of "stage" in Icelandic that would make
sense as both a verb and a noun. There's a word that means "step" (as
in a step on a ladder"), but it doesn't make much sense to say that
you'd "step something".

I also think it makes more sense to pick a translation that associates
the stage with commits. I.e. a commit is "færsla", the stage is
"færslusvæðið".

I might still go for another one, but that's the one I like best so
far.

Re: [1.8.0] use 'stage' term consistently

[Junio C Hamano]

Just a few factoid corrections.

Matthieu Moy <Matthieu.Moy@grenoble-inp.fr> writes:

>> Actually Git porcelain does use 'the index' as a cache (computing),
>> i.e. as a place to store redundant information (stat data, sha-1
>> for trees with DIRC dircache extension) for faster access.
>
> This is an implementation optimization, that is not supposed to be
> visible for the user. Commands refering to the "cache" are not about
> stat data cache (e.g. "git diff --cached" is really about the content,
> not the stat cache).

Yes. It has been pointed out number of times that "--cached" option is
misnamed and deserves a better name, perhaps "--index-only", with the
current name kept as a backward compatibility synonym.

>> Actually 'the index' is index in that sense; it stores _references_
>> from filename to file contents,...

Correct. It is the table-of-contents for whatever tree the next
"write-tree" would write out.  But it also was named "cache" originally
because that it is not a huge loss if you lose it; you can repopulate it
from the working tree. Over time, the operation you can do to the "index"
became richer and finer grained, mostly thanks to "add -p" family of
features, so it no longer is "not a big deal" to lose the distinction
between what has and has not yet been added to the index (iow, "git reset"
without any options), and the reason to consider it "cache" has diminished.

Contrary to the popular belief by outsiders, i.e. what you wrote at the
end of the message I left below, the "stat cache" part was not the primary
origin of the name "dircache".

> ...
> Because we sometimes call it "cache", they think it is basically a
> stat-cache, and wonder why it is shown to the user. I've even seen
> Git users think that others VCS didn't have a stat-cache because they
> had read that the "cache" was a unique Git feature.

Re: [1.8.0] use 'stage' term consistently

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> On Mon, May 7, 2012 at 7:52 PM, Junio C Hamano <gitster@pobox.com> wrote:
>
>> ... I actually was having a hard time to come up with Japanese
>> translation (not that I have plan to contribute to ja_JP.po), as the
>> shipping/logistics term "to stage" does not cleanly translate to the
>> language without unnecessary connotation that imply what is described is
>> something the our "index" actually is _not_.
>
> Because there's no equivalent of "stage" in Icelandic that would make
> sense as both a verb and a noun. There's a word that means "step" (as
> in a step on a ladder"), but it doesn't make much sense to say that
> you'd "step something".

Japanese stopped inventing their own words for imported concepts mid 20th
century and mostly use English words phonetically transliterated these
days. The word "index" is quite well understood: that which points at the
information given a headword that refers to it, which is exactly what the
"index" we have is. On the other hand, "to stage/staging area" is not as
widely used outside the narrow shipping/logistics circles.

I actually was hoping that Japanese was a minority to have trouble with
the word "stage" (and my not being a professional translator did not help
the matter), and we could declare "it is stage from now on", update the
documentation, rename the .git/index to .git/stage (not strictly needed,
and I am not looking forward to it, as it would be a messy and pointless
transition with backward compatibility headaches) and be done with it, if
we wanted to.

But sadly it seems that it may not be the case, at least unless you are
familiar with the shipping/logicstics lingo in English, if you are not
native.  I didn't necessarily wanted to use "stage", it is "sad" because a
new word-hunt may be needed for a replacement to "index" (as "stage" may
not be a good word for i18n audience), and then we would need to keep
"index", "stage" and that third word as interchangeable terms.

Spliting the userbase by introducing a new form to an established
terminology was bad enough, and making that three is worse.

Re: [1.8.0] use 'stage' term consistently

[Ævar Arnfjörð Bjarmason]

On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano <gitster@pobox.com> wrote:

> I didn't necessarily wanted to use "stage", it is "sad" because a
> new word-hunt may be needed for a replacement to "index" (as "stage" may
> not be a good word for i18n audience), and then we would need to keep
> "index", "stage" and that third word as interchangeable terms.
>
> Spliting the userbase by introducing a new form to an established
> terminology was bad enough, and making that three is worse.

I don't think that line of reasoning makes sense at all. We shouldn't
be picking terms in the original English translation of Git that we
think would be more amenable to translation.

We should be picking terms that make the most sense in English, and
then translators will translate those into whatever makes the most
sense in their language.

How translators work also depends largely on the language they're
translating the terms into. In my experience there's three main modes
of translation that people aim for:

 * Do we have a common word for it already? If so use, it, if not
   let's just use the English word. Japanese and German largely fall
   into this category.

 * Do we have a word for it at all or can we concoct one that makes
   sense? If so let's try to use it. Some languages like German are
   evidently struggling with the boundary between this and the first
   category.

 * What ideas are these terms trying to convey, and do we have an
   equivalent for those ideas in our language that we can use?
   Icelandic translations mostly aim for this.

So e.g. for Icelandic I'm not aiming to translate the shipping /
military concept of "stage".

I'm looking at what it means in the workflow of git (a staging are for
commits before they're born) and using a word you'd use in Icelandic
if you were trying to talk about some staging/preparation area.

That I have to do this isn't a failure of the original English
version, it's an inevitable emergence of different languages using
different terms and patterns to express similar ideas.

Re: [1.8.0] use 'stage' term consistently

[Sebastien Douche]

On Sat, May 5, 2012 at 3:04 PM, Felipe Contreras
<felipe.contreras@gmail.com> wrote:
> Proposal:
>
> Avoid the terms 'cache' and 'index' in favor of 'stage'.

+1000. An anecdote: many attendees said to me "I didn't understand
until you explained it that way". Now I use always the term "stage" in
my training (and banned the term index). Far better.


-- 
Sebastien Douche <sdouche@gmail.com>
Twitter: @sdouche / G+: +sdouche

Re: [1.8.0] use 'stage' term consistently

[Junio C Hamano]

Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:

> On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano <gitster@pobox.com> wrote:
>
>> I didn't necessarily wanted to use "stage", it is "sad" because a
>> new word-hunt may be needed for a replacement to "index" (as "stage" may
>> not be a good word for i18n audience), and then we would need to keep
>> "index", "stage" and that third word as interchangeable terms.
>>
>> Spliting the userbase by introducing a new form to an established
>> terminology was bad enough, and making that three is worse.
>
> I don't think that line of reasoning makes sense at all....
> We should be picking terms that make the most sense in English, and
> then translators will translate those into whatever makes the most
> sense in their language.

OK.

Re: [1.8.0] use 'stage' term consistently

[Felipe Contreras]

On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano <gitster@pobox.com> wrote:
> The word "index" is quite well understood: that which points at the
> information given a headword that refers to it, which is exactly what the
> "index" we have is. On the other hand, "to stage/staging area" is not as
> widely used outside the narrow shipping/logistics circles.

That's what git has, *internally*, but that's not how high-level users
interact with it. If 'git add file' was a true index from the point of
view of the user; then the user would have some kind of identifier,
like '1', or possibly and identifier of his own. Then the user could
use this identifier, say; give me the file '1', and the operation
would be much faster. But that's has *absolutely* nothing to do with
how users see these operations. The user does not see an index at all.
Maybe git has an index, but it could be replaced by something else,
and the user would still see the same; it's an implementation detail;
not something the user cares about.

This has been explained and discussed many times.

Cheers.

-- 
Felipe Contreras

Re: [1.8.0] use 'stage' term consistently

[Matthieu Moy]

Felipe Contreras <felipe.contreras@gmail.com> writes:

> On Tue, May 8, 2012 at 6:06 AM, Junio C Hamano <gitster@pobox.com> wrote:
>> The word "index" is quite well understood: that which points at the
>> information given a headword that refers to it, which is exactly what the
>> "index" we have is. On the other hand, "to stage/staging area" is not as
>> widely used outside the narrow shipping/logistics circles.
>
> That's what git has, *internally*, but that's not how high-level users
> interact with it.

I agree with that. Explaining users that the <whatever you call it> is
the place where you stage content in preparation for the next commit is
much more productive than explaining that it is an array of
(name, sha1sum) pairs.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

Re: [1.8.0] use 'stage' term consistently

[Thiago Farina]

On Sun, May 6, 2012 at 7:26 AM, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> About the name, an alternative to "stage" was suggested earlier:
> "precommit"
Thanks! That was the first that explained to me what cache, index, and
stage was talking about. +1 from me (not that count much).

Re: [1.8.0] use 'stage' term consistently

[Mark Lodato]

On Mon, May 7, 2012 at 1:52 PM, Junio C Hamano <gitster@pobox.com> wrote:
> the
> shipping/logistics term "to stage" does not cleanly translate to the
> language without unnecessary connotation that imply what is described is
> something the our "index" actually is _not_.

I agree with Felipe that "staging" is the most appropriate term for
"adding to the index" in git.  As a native English speaker, I have
never thought of "to stage" as relating to shipping in any way.  To
me, by far the most common usage is in real estate.  The seller of a
home "stages" it by setting up furniture and decorations to make the
home as appealing to prospective buyers as possible.  Just search on
Google for "home staging" and you will get plenty of hits.  This usage
clearly originates from theater but can be found in other contexts as
well.

Re: [1.8.0] use 'stage' term consistently

[Jonathan Nieder]

Hi Mark,

Mark Lodato wrote:

> I agree with Felipe that "staging" is the most appropriate term for
> "adding to the index" in git.  As a native English speaker, I have
> never thought of "to stage" as relating to shipping in any way.  To
> me, by far the most common usage is in real estate.  The seller of a
> home "stages" it by setting up furniture and decorations to make the
> home as appealing to prospective buyers as possible.

I think staging a home does not fit very well here, actually.  As you
said, staging a home is like staging a play, creating an illusion and
putting on a production.  It is not obvious how this concept would
help me understand what it means to add content to the index.

By contrast, if you run an image search for "staging area", you will
see examples in all sorts of fields --- shipping, military logistics,
data warehousing, disaster relief.  It is a familiar, non
domain-specific term for native English speakers.  In all these
fields, staging means to put everything needed in one place before
deploying.  This matches the concept of a file that tracks the content
of the commit being prepared very well.

"aire de rassemblement" doesn't get as many hits from a web search,
alas, so I guess the idiom is not as popular in other languages.

For the sake of having a proposal: :)

 - the file representing the content of the next command would still
   be called .git/index and not be renamed

 - adding and removing content to and from the index is "staging a
   change".  Since it is not safe to assume the reader already
   knows what that means, when working on the manual authors should
   try to imagine themselves as a new user and make the text
   unambiguous enough to help such a person.

   For example, the first sentence of the "git add" manual:

	This command updates the index using the current content found in the
	working tree, to prepare the content staged for the next commit.

   should not be changed to:

	This command updates the staging area using ...

   because that just makes it less clear.  Before, it said "the index"
   and I could look in the glossary or the .git directory to at least
   find what file it was talking about.  Afterwards, it is using an
   everyday term and the new user wonders "which staging area?".

   Instead, it would be better to change it to something like:

	This command modifies the content staged for the next commit
	using content found in the working tree.  It typically adds ...

	The "index" file (see gitindex(5)) typically holds a snapshot of
	the content of the working tree, and it is this snapshot that is
	taken as the content of the next commit.  Thus after making any
	changes to the working directory, and before running the commit
	command, you must use the add command to add any new or modified
	files.

Sensible?  If so, patches welcome. :)  If not, what sort of changes
would you like to see instead?

By the way, I don't mean that "the .git/index file will not be
renamed" above to be non-negotiable.  I didn't get the impression
anyone wanted it to be renamed, but if someone does want to rename it
to .git/staging-area, then I suppose we could discuss that.

Hope that helps,
Jonathan

Re: [1.8.0] use 'stage' term consistently

[Jonathan Nieder]

Jonathan Nieder wrote:

> For the sake of having a proposal: :)

For the command-line interface:

Making the "git stage" command more prominent.  Unfortunately it is
currently a synonym for "git add", which makes "git rm" less
discoverable and generally isn't very helpful.  But if we discard that
property, it could become a nice way to make some operations more
discoverable:

	git stage --add <paths>; # stage an addition
	git stage --remove <paths>; # stage a removal
	git stage --edit <paths>; # edit the staged content
	git stage --apply <patch>; # stage the described change

These would be commands that modify the index without touching the
worktree.

If anyone claims this is the command for manipulating "the stage", we
can apologize for the confusing homonym and point them to a dictionary
and images of raised platforms and staging areas and hopefully that
will avoid any confusion.  The command is named after the verb.

Finding a better mnemonic than "also update the current directory cache"
and "trust the current directory cache" for operations like git apply
--index and git grep --cached.  Better concepts would be "search the
content staged for the next commit" and "also update the staged
content".

Maybe:

	git apply --index=(yes | no | only)
		# apply         	= apply --index=no
		# apply --index 	= apply --index=yes
		# apply --cached	= apply --index=only

	git grep --index; # (= git grep --cached)

I imagine others can come up with something better.

Re: [1.8.0] use 'stage' term consistently

[Philip Oakley]

From: "Jonathan Nieder" <jrnieder@gmail.com>
Sent: Saturday, May 19, 2012 7:00 AM
> Hi Mark,
>
> Mark Lodato wrote:
>
>> I agree with Felipe that "staging" is the most appropriate term for
>> "adding to the index" in git.  As a native English speaker, I have
>> never thought of "to stage" as relating to shipping in any way.  To
>> me, by far the most common usage is in real estate.  The seller of a
>> home "stages" it by setting up furniture and decorations to make the
>> home as appealing to prospective buyers as possible.
>
> I think staging a home does not fit very well here, actually.  As you
> said, staging a home is like staging a play, creating an illusion and
> putting on a production.  It is not obvious how this concept would
> help me understand what it means to add content to the index.
>
> By contrast, if you run an image search for "staging area", you will
> see examples in all sorts of fields --- shipping, military logistics,
> data warehousing, disaster relief.  It is a familiar, non
> domain-specific term for native English speakers.  In all these
> fields, staging means to put everything needed in one place before
> deploying.  This matches the concept of a file that tracks the content
> of the commit being prepared very well.

Agreed. (both sentences)
It's about making it up as you go along. (1: it = the commit ;-)
In particular it's about the 'area' (noun) that we use for that 
preparation.
Unfortunately there are no common terms because every industry, and
language, came up with its own terminology. To assist translation, we
should avoid being too concise in the explanation, while being 
consistent
with our base terms.

>
> "aire de rassemblement" doesn't get as many hits from a web search,
> alas, so I guess the idiom is not as popular in other languages.
>
> For the sake of having a proposal: :)
>
> - the file representing the content of the next command would still
>   be called .git/index and not be renamed
>
> - adding and removing content to and from the index is "staging a
>   change".  Since it is not safe to assume the reader already
>   knows what that means, when working on the manual authors should
>   try to imagine themselves as a new user and make the text
>   unambiguous enough to help such a person.
>
>   For example, the first sentence of the "git add" manual:
>
> This command updates the index using the current content found in the
> working tree, to prepare the content staged for the next commit.
>
>   should not be changed to:
>
> This command updates the staging area using ...
>
>   because that just makes it less clear.  Before, it said "the index"
>   and I could look in the glossary or the .git directory to at least
>   find what file it was talking about.  Afterwards, it is using an
>   everyday term and the new user wonders "which staging area?".
>
>   Instead, it would be better to change it to something like:
>
> This command modifies the content staged for the next commit
> using content found in the working tree.  It typically adds ...
>
> The "index" file (see gitindex(5)) typically holds a snapshot of
> the content of the working tree, and it is this snapshot that is

This line, if it is a carry on from the previous, also suffers the same
confusion. The index file by itself does not have any of the content. We
need to say in some way that - The 'staging area' has the content, and
is indexed by the index file. The staging area content itself is held
securely in the object storage ready for the commit.

> taken as the content of the next commit.  Thus after making any
> changes to the working directory, and before running the commit
> command, you must use the add command to add any new or modified
> files.
>
> Sensible?  If so, patches welcome. :)  If not, what sort of changes
> would you like to see instead?
>
> By the way, I don't mean that "the .git/index file will not be
> renamed" above to be non-negotiable.  I didn't get the impression
> anyone wanted it to be renamed, but if someone does want to rename it
> to .git/staging-area, then I suppose we could discuss that.

I'd agree. The file is an index.

>
> Hope that helps,
> Jonathan
> --

Philip

Re: [1.8.0] use 'stage' term consistently

[Felipe Contreras]

On Sat, May 19, 2012 at 8:00 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

> For the sake of having a proposal: :)
>
>  - the file representing the content of the next command would still
>   be called .git/index and not be renamed

Agreed, that is an implementation detail anyway; the changes should be
done with how the a typical user interacts with git, and a  typical
user doesn't need to know the index exists.

>  - adding and removing content to and from the index is "staging a
>   change".  Since it is not safe to assume the reader already
>   knows what that means, when working on the manual authors should
>   try to imagine themselves as a new user and make the text
>   unambiguous enough to help such a person.
>
>   For example, the first sentence of the "git add" manual:
>
>        This command updates the index using the current content found in the
>        working tree, to prepare the content staged for the next commit.
>
>   should not be changed to:
>
>        This command updates the staging area using ...
>
>   because that just makes it less clear.  Before, it said "the index"
>   and I could look in the glossary or the .git directory to at least
>   find what file it was talking about.  Afterwards, it is using an
>   everyday term and the new user wonders "which staging area?".

The git's staging area, of course. How is that not clear?

If the (new) user wants to know more about the staging area, she can
read about it, just like she currently can. A 'man git staging-area'
might actually help.

However, there's no 'man git index', or anything like that, so where
do you suppose new users currently look for information when they
wonder "what index"? And looking into the .git directory for an
"index" file? Seriously? I doubt any new user would do that, I haven't
even done so myself. The whole point of documentation is to be user
*friendly*.

>   Instead, it would be better to change it to something like:
>
>        This command modifies the content staged for the next commit
>        using content found in the working tree.  It typically adds ...

>        The "index" file (see gitindex(5)) typically holds a snapshot of
>        the content of the working tree, and it is this snapshot that is
>        taken as the content of the next commit.  Thus after making any
>        changes to the working directory, and before running the commit
>        command, you must use the add command to add any new or modified
>        files.

I find this paragraph completely unnecessary. This is useless
distraction; the user wants to know about 'git add', she doesn't need
to know about the index, and we should hide it from her.

Instead, the 'git add' documentation should point to the 'man git
staging-area', and there, hidden somewhere is the implementation
details; the index, and all the gory details.

Cheers.

-- 
Felipe Contreras

Re: [1.8.0] use 'stage' term consistently

[Felipe Contreras]

On Sat, May 19, 2012 at 8:32 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:
> Jonathan Nieder wrote:
>
>> For the sake of having a proposal: :)
>
> For the command-line interface:
>
> Making the "git stage" command more prominent.  Unfortunately it is
> currently a synonym for "git add", which makes "git rm" less
> discoverable and generally isn't very helpful.  But if we discard that
> property, it could become a nice way to make some operations more
> discoverable:
>
>        git stage --add <paths>; # stage an addition
>        git stage --remove <paths>; # stage a removal
>        git stage --edit <paths>; # edit the staged content
>        git stage --apply <patch>; # stage the described change
>
> These would be commands that modify the index without touching the
> worktree.

If they are commands, why do they start with --?

'git stage add'
'git stage remove'
'git stage edit'

Would be more appropriate.

But I think revamping 'git stage' should be a separate task.

> Finding a better mnemonic than "also update the current directory cache"
> and "trust the current directory cache" for operations like git apply
> --index and git grep --cached.  Better concepts would be "search the
> content staged for the next commit" and "also update the staged
> content".
>
> Maybe:
>
>        git apply --index=(yes | no | only)
>                # apply                 = apply --index=no
>                # apply --index         = apply --index=yes
>                # apply --cached        = apply --index=only
>
>        git grep --index; # (= git grep --cached)
>
> I imagine others can come up with something better.

'index'? That goes contrary to this request; the term 'index' should
be avoided in porcelain commands. s/index/stage/ and the proposal
seems sensible, but I fail to see how --stage=no could be helpful, and
--stage=yes should be the same as --stage, and then I wonder what
would be the purpose of having --stage, and --stage=only, where we
could have a --stage(d)-only for commands that need this distinction
(not all of them). If in the future we want more --stage=foo options,
then it might make sense, but I just don't see that ever happening.

I guess the next step would be to list all the commands that use
--index, --staged, and --cached, and propose new options that would
eventually help to remove --index and --cached (after some period of
deprecation).

Cheers.

-- 
Felipe Contreras

Re: [1.8.0] use 'stage' term consistently

[Jonathan Nieder]

Felipe Contreras wrote:
> On Sat, May 19, 2012 at 8:00 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

>>        The "index" file (see gitindex(5)) typically holds a snapshot of
>>        the content of the working tree, and it is this snapshot that is
>>        taken as the content of the next commit.  Thus after making any
>>        changes to the working directory, and before running the commit
>>        command, you must use the add command to add any new or modified
>>        files.
>
> I find this paragraph completely unnecessary. This is useless
> distraction; the user wants to know about 'git add', she doesn't need
> to know about the index, and we should hide it from her.

Ok.  Have you seen the current git-add(1) manpage?  Do you have
patches that improve it to avoid such useless background information
in a non-confusing way?

Jonathan

Re: [1.8.0] use 'stage' term consistently

[Jonathan Nieder]

Felipe Contreras wrote:
> On Sat, May 19, 2012 at 8:32 AM, Jonathan Nieder <jrnieder@gmail.com> wrote:

>>        git stage --add <paths>; # stage an addition
>>        git stage --remove <paths>; # stage a removal
>>        git stage --edit <paths>; # edit the staged content
>>        git stage --apply <patch>; # stage the described change
>>
>> These would be commands that modify the index without touching the
>> worktree.
>
> If they are commands, why do they start with --?

They are commands because they are passed on the command line.  I don't
care strongly about the details --- I was giving an idea for people to
pick up or not pick up.

[...]
>> Maybe:
>>
>>        git apply --index=(yes | no | only)
[...]
> 'index'? That goes contrary to this request; the term 'index' should
> be avoided in porcelain commands. s/index/stage/ and the proposal
> seems sensible, but I fail to see how --stage=no could be helpful

It is 'index' because the command already has an option with that
name, which makes this more discoverable and less confusing to
existing users.  You can like or not like that choice.

How do you negate the "also stage this change for the next commit"
option passed earlier on the command line?

I also don't care about the details here and wish you had phrased your
critique in terms of an alternate proposal instead of asking me to
defend mine.  The only part I actually care about is that a person
should think carefully about individual changes, in isolation, that
improve git and move towards a more pleasant and consistent interface.

I don't see any reason for a flag day.

Hope that helps,
Jonathan

Re: [1.8.0] use 'stage' term consistently

[Junio C Hamano]

Jonathan Nieder <jrnieder@gmail.com> writes:

> Mark Lodato wrote:
>
>> I agree with Felipe that "staging" is the most appropriate term for
>> "adding to the index" in git.  As a native English speaker, I have
>> never thought of "to stage" as relating to shipping in any way.  To
>> me, by far the most common usage is in real estate.  The seller of a
>> home "stages" it by setting up furniture and decorations to make the
>> home as appealing to prospective buyers as possible.
>
> I think staging a home does not fit very well here, actually....
> By contrast, if you run an image search for "staging area", you will
> see examples in all sorts of fields...
> "aire de rassemblement" doesn't get as many hits from a web search,
> alas, so I guess the idiom is not as popular in other languages.

All true.

>    Instead, it would be better to change it to something like:
>
> 	This command modifies the content staged for the next commit
> 	using content found in the working tree.  It typically adds ...
>
> 	The "index" file (see gitindex(5)) typically holds a snapshot of
> 	the content of the working tree, and it is this snapshot that is
> 	taken as the content of the next commit.  Thus after making any
> 	changes to the working directory, and before running the commit
> 	command, you must use the add command to add any new or modified
> 	files.
>
> Sensible?

Comparing between the one before "Instead" and the above one, I would say
it is.

I am hoping that we are not wasting people's time by the same experiment
that already failed very early in Git's history to hide the "concept" of
that which is used to shape the tree that would be recorded in the next
commit that is different from either the current commit nor the contents
in the working tree, and instead this round is about the name of that
thing, which has been called "the index" and also colloquially known as
"the staging area" in many third-party documents.  

I personally think it is a wrong way of thinking to focus too much on the
"name", though. The goal should be increased clarity and ease of learning.
For example, the first sentence in your example reads equally well if it
said "the content _prepared_ for the next commit" without losing clarity
and tells the most important thing it must tell the user: that "add" is
about updating "that thing" that is different from the working tree and
the latest commit, even if "stage" (verb) does not translate well to other
language.

About the "git stage --add/rm" commands in your follow-up message, I have
mixed feelings.  Once users get that making progress and growing history
with Git is all about interacting with "that thing", writing out a new
tree out of it and recording it in a new commit with appropriate parents,
saying "stage" becomes redundant.  You "add", "remove", "patch", etc. to
affect that is recorded in "that thing" (e.g. you do not "add" to commit).

Another reason of my "mixed feelings" is that an interface organized
around what is affected, instead of around what is achieved, may be
counter-productive.  "add" that adds the contents in the working tree
(i.e. you already made the change you want yourself) to "that thing" makes
sense from the work-flow point of view. It is how you edit, test or
eyeball to convince yourself that you are happy with what is in your
working tree, and then approach one step closer to your next commit.

An interface built around "that thing" may have a subcommand that adds
contents to "that thing" regardless of what is in your working tree, but
it is useful in only special occasions (e.g. in filter-branch script that
does not want/need to use a temporary working tree).  Such a functionality
does have a place to live, namely at the plumbing level, but already is
available as "update-index".  But these commands that are organized around
"what" they operate on are and should be of "specialized" kind, not "end
user everyday activity" commands that are designed to give easier time to
people in learning and using the system.

Re: [1.8.0] use 'stage' term consistently

[Felipe Contreras]

On Sun, May 20, 2012 at 11:11 PM, Junio C Hamano <gitster@pobox.com> wrote:

> I personally think it is a wrong way of thinking to focus too much on the
> "name", though.

Names are important. Name it 'jaberwocky' and people would have a
harder time trying to understand what you are talking about. Maybe
just by hearing the name they would give up, thinking it's too
advanced, or too obscure, or what not.

There have been countless people that say "me too! when I realized it
was X", which suggests the current name does not help.

> The goal should be increased clarity and ease of learning.

And using a common/well understood name is a step in the right direction.

But also, once we accept that "that thing" is not an index, then it
becomes much more easy to distinguish between the abstract concept,
and the actual index, and then we can begin to remove the index from
the high-level documentation and squash it to a corner where the user
does not _have_ to go unless she really does want to know the
implementation details.

Right now it's almost impossible to split the "index", and then index.

If the name is not important, why do you think people avoid the official name?

> For example, the first sentence in your example reads equally well if it
> said "the content _prepared_ for the next commit" without losing clarity
> and tells the most important thing it must tell the user: that "add" is
> about updating "that thing" that is different from the working tree and
> the latest commit, even if "stage" (verb) does not translate well to other
> language.

Indeed, but you are missing the important part; everything else in
that sentence.

I will put my end-user hat and read while thinking aloud the current text:

"This command updates the index"

OK, you lost me there. I don't know what is that "index", do I need to
learn what is that in order to understand the command? Maybe I
shouldn't be reading this documentation at all.

But, OK, let's give it a try... Right, an index, well, an index of
what to what? No idea. Maybe if I keep reading.

"using the current content found in the working tree, to prepare the
content staged for the next commit.

OK, maybe I'm beginning to understand... But I'm still not sure if I
should be touching this index thing, I don't understand what is being
indexed.

> About the "git stage --add/rm" commands in your follow-up message, I have
> mixed feelings.  Once users get that making progress and growing history
> with Git is all about interacting with "that thing", writing out a new
> tree out of it and recording it in a new commit with appropriate parents,
> saying "stage" becomes redundant.  You "add", "remove", "patch", etc. to
> affect that is recorded in "that thing" (e.g. you do not "add" to commit).

While I would not like to touch the 'git stage' at this point--nor do
I think it's needed--, I don't agree with what you said. In certain
commands it might be redundant, but I specially disagree on these:

The 'add' command has a long tradition in SCM; it adds a file for
content tracking--nothing more.

Using 'add' to *update* the staging area seems completely and totally
counter-intuitive to me. Adding something means that something was not
there; if it was there, you couldn't add it.

Of course, that's if you think about files, but it makes sense if you
think about changes instead, but 'git add file' and 'git add file' do
very different things conceptually depending on weather 'file' was
tracked or not; one would "add a file" (to git), and the other would
"add the changes of the file" (to the staging area). Splitting the
command in two would make this difference in concepts clearer.

And then we have all sorts of confusion. --patch; I thought we were
adding patches to the staging area, this is redundant, --selectively
might make more sense. --update; I thought we were updating! --updated
might make more sense. And what happens when you do 'git add --patch
untracked-file' (or --update)? That's very strange.

If we have a 'stage' command things become much simpler:

git add untracked-file # maybe as the current 'git add --intent-to-add'
git add tracked-file # no-op (error?)
git add --patch file # doesn't make sense; option not present
git add --update file # doesn't make sense; option not present

git stage untracked-file # add, and stage it, why not?
git stage tracked-file
git stage --hunks file
git stage --updates file

At this point 'git add' would not be doing much, and might even go
away, but I guess it's nice for people coming from other SCMs.

'rm' is similar, could be solved by 'unstage'.

Either way, I have proposed to use stage/unstage before I think,
without much success, so I think the only realist option to move
forward is to add --stage(d) and --stage-only.

Cheers.

-- 
Felipe Contreras

Re: [1.8.0] use 'stage' term consistently

[Jonathan Nieder]

Hi Felipe,

Felipe Contreras wrote:

> Indeed, but you are missing the important part; everything else in
> that sentence.

You're probably onto something, but I'm missing the point in your
message.  Could you repeat, carefully explaining:

 - what change you would like to propose in git
 - whether it is backward compatible, and if it is not, what
   transition plan you propose
 - briefly, the rationale behind the change, in such a way as to
   convince skeptics like me that it is a good idea and to recruit
   us to help in your cause

?  For that third part, a good example to take inspiration from is the
project to improve Linux to function as a real-time operating system.
Each change is so well justified _individually_ that someone not
interested at all in that goal can still not help but agree with the
changes!

Perhaps your message includes these elements already, but I found it
hard to follow, hence this request.

Thanks,
Jonathan