Re: Git terminology: remote, add, track, stage, etc.

On Tue, 19 Oct 2010, Matthijs Kooijman wrote:

Note that the excerpt cited (quoted) below is directly from gitcli(7)
manpage.

quoted

 * 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.

Mnemonic: operate on _cached_ contents.  We could use `--staged`
instead of `--cached` here, but for me it doesn't as strong as
`--cached` this meaning.

quoted

 * 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.

Mnemonic: include _index_ (the name for concrete implementation of the
staging area) in operation.  We could use `--stage` here, but it would
be confusingly similar to `--staged`.  We could use `--include-staged`
or `--also-staged`, but it is long and unwieldy, and doesn't read as
nice.

Doesn't this just offer opportunity for two new options? E.g., --staged
and --also-staged or --include-staged or something? In the current form,
these two options provide a variation of the same concept, using
completely different option names (which could lead people to think
that they're really the same option, just inconsistently implemented).

That's why documentation is for.  That is why we have gitcli(7).

Sidenote: there were some proposal of including pseudo-ref name for
cache/index/staging area (and for workdir contents), i.e. to use for
example INDEX or STAGE instead of `--cached`... but they fell flat
because `--cached` / STAGE is not exactly like the ref, and it felt
like it would contribute to confusion rather than reducing it.

So, regardless of changing over to --staged, I guess these two options
could be made more consistent (though sticking to the "index"
terminology is tricky, since that would require --cached to be become
--index and --index to become --include-index, which throws away
backward compatibility...).

Breaking backward compatibility that badly is a big NO.

Unfortunately the need for backward compatibility prevents us from some
of improvements...

FWIW, I do rather like the "staging area" concept, since I feel it
accurately describes its use (or at least the most common use of the
staging area).

I also like "staging area" concept (and "to stage" as a verb), but there
are some difficulties in applying it thorough and through.

-- 
Jakub Narebski
Poland