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

From: Jakub Narebski <jnareb@gmail.com>
Date: Oct 19, 2010, 08:27 UTC
Message-ID: <201010191027.44859.jnareb@gmail.com>
In-Reply-To: <20101019080523.GB22067@login.drsnuggles.stderr.nl>

On Tue, 19 Oct 2010, Matthijs Kooijman wrote:

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

Show 7 quoted lines

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

Show 7 quoted lines

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

Show 6 quoted lines

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

Show 6 quoted lines

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