Re: [PATCH] git-diff: Add --staged as a synonym for --cached.

["Björn Steinbrink" <B.Steinbrink@gmx.de>]

On 2008.10.29 13:11:22 -0400, Jeff King wrote:
> On Wed, Oct 29, 2008 at 06:06:09PM +0100, Johannes Schindelin wrote:
> 
> > However, note that we have to hash out what to do about the convention 
> > that --cached traditionally means that only the staging area (formerly 
> > known as "the index") is affected, while --index means that the command 
> > touches the working directory, too.
> 
> If we assume that we have only the word "stage" and variations
> available, then there aren't too many options.
> 
>   only the staging area:
>     --stage-only, --staged-only
> 
>   both:
>     --staged (as opposed to --staged-only) --stage-and-worktree (too
>     long), --both (not descriptive enough), --stage-too (yuck)

Hm, I don't think that would work out nicely with stash. --keep-index
would become --keep-staged-only, which is IMHO pretty confusing, as the
default is to keep nothing. And even if you add another option to keep
all changes, so that the current state is just put onto the stash, but
the working tree and index are unchanged, you would have --keep-staged
and --keep-staged-only. Not really any better.

Admittedly, --keep-index is quite different from --index, but if you're
going to change the CLI to hide the word "index", that option needs to
be changed as well and the usage of the new terms should be unified.

Looking at --cached/--index we have basically three things:

  --cached to refer to the state of the index (diff, grep, [stash], ...)
  --cached to _work on_ the index only (rm, apply, ...)
  --index to _work on_ both the index and the working tree (apply, ...)

Maybe that could be translated to:

  --staged: refer to the state of the index
  --stage: in addition to changing the working tree, also stage the changes
  --stage-only: only stage the changes, don't change the working tree

That would give us, for example:
git diff --staged
git grep --staged

git apply --stage
git apply --stage-only
git rm --stage-only

git stash --keep-staged

A quick look through Documentation/ revealed only one problematic case,
which is ls-files that already has a --stage option. And that looks like
a dealbreaker :-(

Björn