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

From: Jeff King <peff@peff.net>
Date: Nov 11, 2008, 00:15 UTC
Message-ID: <20081111001534.GB26223@coredump.intra.peff.net>
In-Reply-To: <ee77f5c20811101537u6061e5b4w420e9692e0cefad3@mail.gmail.com>

On Tue, Nov 11, 2008 at 10:37:37AM +1100, David Symonds wrote:

Show 8 quoted lines

> > And I am not proposing a change here (except to perhaps "git diff
> > --staged" instead of "--cached"). Just pointing out that it does not
> > follow the "--staged operates on both, --staged-only operates on just
> > the index" rule.
> 
> So apart from the wider discussion, I think this patch by itself is a
> nice step forward towards improving the UI of this part of git. Is
> there any further discussion on this one alone?

I think --staged for --cached is definitely an improvement. Even if we don't have a set rule for "this is when you use --staged, and this is when you use --staged-only", I think everyone so far agrees that any such rule will have to incorporate "diff --staged" somehow, since it reads pretty clearly.

So yes, I would like to see this applied. However, there are two possible improvements:

  1. Your documentation update says --staged is a synonym. Should
     --staged perhaps be the "new" way of doing this, and --cached is
     left as a historical alias? IOW, point users at the name we think
     is more sensible.

  2. Part of the point of this is to avoid using the world "cached" in
     instructional materials. The tutorial and user manual should
     probably be updated to use --staged (and it is reasonably safe to
     do so immediately, since they are tied to the installed git
     version; I hope Scott will update his materials eventually, but
     lagging makes sense there as people will still be using existing
     versions for some time).

     And of course, such updates would be a small part of any larger
     decision to call the index something else (the "stage" or
     whatever) in those materials, but I think your point is to do this
     one positive thing and not wait for the other bits.

-Peff