Re: [1.8.0] use 'stage' term consistently

From: Jakub Narebski <jnareb@gmail.com>
Date: May 6, 2012, 10:21 UTC
Message-ID: <201205061221.29592.jnareb@gmail.com>
In-Reply-To: <CAMP44s1qqpTxRvjEH32MNqzUeNhgZ1gB+fu=cgvxnSbMB6oBGA@mail.gmail.com>

On Sat, 5 May 2012, Felipe Contreras wrote:

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

[...]

Show 10 quoted lines

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

Show 5 quoted lines

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

Show 6 quoted lines

> 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