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

From: Björn Steinbrink <b.steinbrink@gmx.de>
Date: Nov 2, 2008, 12:35 UTC
Message-ID: <20081102123519.GA21251@atjola.homenet>
In-Reply-To: <20081029171122.GA12167@sigill.intra.peff.net>

On 2008.10.29 13:11:22 -0400, Jeff King wrote:

Show 16 quoted lines

> 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