Consistent terminology: cached/staged/index

Hi,

is there a plan for using one term instead of three to describe
operations on index?

From quick search:

* "add" mentions index and staging
* all commands except one take "--cached" only
* "diff" also takes "--staged"
* "diff" mentions index and staging
* "log" mentions index
* "reset" mentions index


-- 
Piotrek

Piotr Krukowiecki wrote:

is there a plan for using one term instead of three to describe
operations on index?

No.  But ideas (and especially patches) for improving the
documentation would be appreciated.

From quick search:
* "add" mentions index and staging
* all commands except one take "--cached" only
* "diff" also takes "--staged"
* "diff" mentions index and staging
* "log" mentions index
* "reset" mentions index

If I understand correctly, the intended semantics are:

--index versus --cached
~~~~~~~~~~~~~~~~~~~~~~~
The place where changes for the next commit get registered is called
the "index file".

Commands that pay attention to the registered content of files rather
than the copies in the work tree use the option name "--cached".  This
is mostly for historical reasons --- early on, it was not obvious that
making the index not match the worktree was going to be useful.

Commands that update the registered content of files in addition to
the worktree use the option name "--index".

--staged
~~~~~~~~
diff takes --staged, but that is only to support some people's habits.

The term "to stage" is generally an abbreviation for "to stage in the
index", meaning "to mark for use in the next commit".  It is used to
paint a certain picture of the process in which one makes sure
everything is just right before committing to the result.

Hope that helps,
Jonathan

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.