Re: Consistent terminology: cached/staged/index

[Jonathan Nieder <jrnieder@gmail.com>]

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