Re: Consistent terminology: cached/staged/index

Hi again,

Piotr Krukowiecki wrote:

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.