From: Jakub Narebski <jnareb@gmail.com>
To: Felipe Contreras <felipe.contreras@gmail.com>
Cc: git@vger.kernel.org, Junio C Hamano <gitster@pobox.com>,
Jonathan Nieder <jrnieder@gmail.com>, Jeff King <peff@peff.net>,
Scott Chacon <schacon@gmail.com>,
Paolo Ciarrocchi <paolo.ciarrocchi@gmail.com>,
Johannes Schindelin <johannes.schindelin@gmx.de>,
Matthieu Moy <matthieu.moy@imag.fr>,
Piotr Krukowiecki <piotr.krukowiecki.news@gmail.com>
Subject: Re: [1.8.0] use 'stage' term consistently
Date: Sun, 6 May 2012 12:21:28 +0200 [thread overview]
Message-ID: <201205061221.29592.jnareb@gmail.com> (raw)
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'.
[...]
> 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
next prev parent reply other threads:[~2012-05-06 10:21 UTC|newest]
Thread overview: 34+ messages / expand[flat|nested] mbox.gz Atom feed top
2012-05-05 13:04 [1.8.0] use 'stage' term consistently Felipe Contreras
2012-05-05 16:52 ` Philip Oakley
2012-05-05 17:30 ` Felipe Contreras
2012-05-05 19:53 ` Philip Oakley
2012-05-06 9:53 ` Zbigniew Jędrzejewski-Szmek
2012-05-06 10:21 ` Jakub Narebski [this message]
2012-05-06 10:39 ` Matthieu Moy
2012-05-06 20:15 ` Felipe Contreras
2012-05-06 21:21 ` Jakub Narebski
2012-05-08 3:51 ` Junio C Hamano
2012-05-06 21:09 ` Felipe Contreras
2012-05-06 10:26 ` Matthieu Moy
2012-05-06 21:16 ` Felipe Contreras
2012-05-06 21:30 ` Ævar Arnfjörð Bjarmason
2012-05-07 17:52 ` Junio C Hamano
2012-05-07 20:05 ` Ævar Arnfjörð Bjarmason
2012-05-08 4:06 ` Junio C Hamano
2012-05-08 8:55 ` Ævar Arnfjörð Bjarmason
2012-05-08 14:53 ` Junio C Hamano
2012-05-09 13:10 ` Felipe Contreras
2012-05-09 17:25 ` Matthieu Moy
2012-05-19 0:50 ` Mark Lodato
2012-05-19 6:00 ` Jonathan Nieder
2012-05-19 6:32 ` Jonathan Nieder
2012-05-20 12:04 ` Felipe Contreras
2012-05-20 18:06 ` Jonathan Nieder
2012-05-19 10:14 ` Philip Oakley
2012-05-20 11:49 ` Felipe Contreras
2012-05-20 17:58 ` Jonathan Nieder
2012-05-20 21:11 ` Junio C Hamano
2012-05-21 1:12 ` Felipe Contreras
2012-05-21 1:32 ` Jonathan Nieder
2012-05-18 20:34 ` Thiago Farina
2012-05-08 14:01 ` Sebastien Douche
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=201205061221.29592.jnareb@gmail.com \
--to=jnareb@gmail.com \
--cc=felipe.contreras@gmail.com \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=johannes.schindelin@gmx.de \
--cc=jrnieder@gmail.com \
--cc=matthieu.moy@imag.fr \
--cc=paolo.ciarrocchi@gmail.com \
--cc=peff@peff.net \
--cc=piotr.krukowiecki.news@gmail.com \
--cc=schacon@gmail.com \
/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
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).