Re: Consistent terminology: cached/staged/index

[Jonathan Nieder <jrnieder@gmail.com>]

Hi again,

Piotr Krukowiecki wrote:

> is there a plan for using one term

To summarize: everyone knows what the staging area is, no one seems to
know what the index is, and the --cached options are confusing.

We need a new description (terminology, or better yet, story) for
"git's view of the work tree", since just saying "the index! the
index!" without a myth behind it confuses people.

Various commands take --cached (porcelain):

. git diff --cached	- view staged changes relative to the named tree.
. git grep --cached	- search in the staging area instead of the worktree.
. git rm --cached	- only remove from the index.

(plumbing):

. git apply --cached	- apply a patch without touching the worktree.
. git ls-files --cached	- list paths that will have content in the next commit.

It would be reasonable to introduce a synonym --index-only.  That can
be confusing if you don't view the staging area as representing git's
deluded idea of what's in the work tree, though.  For the same reason
and some others, --no-worktree / --ignore-worktree wouldn't work so
well (e.g., "git ls-files --no-worktree" would be terribly confusing).
So, um, we're stuck?

Various commands take --index or related options (porcelain):

. git filter-branch --index-filter	- let hook tweak index before commit
. git stash apply --index	- revive the stashed index changes, too
. git stash save --keep-index	- do not stash changes already added to index

(toys):

. git grep --no-index	- just act as a better "grep"; do not look for .git
. git diff --no-index	- just act as a better "diff"; do not look for .git

(plumbing):

. git apply --index	- next commit will have the patch applied, too
. git checkout-index --index	- update stat() cache while at it
. git read-tree --index-output	- write output to a different index file
. git update-index --index-info	- apply changes in ls-tree or ls-files format
. GIT_INDEX_FILE	- where information about the worktree goes

It would be possible to introduce synonyms along the lines of
GIT_STAGING_AREA_FILE, keeping in mind that they also affect the
merging process (and some of them also affect the stat() cache), if
that seems like the right thing to do.