Re: git-scm.com refresh

From: Scott Chacon <schacon@gmail.com>
Date: May 5, 2012, 22:38 UTC
Message-ID: <CAP2yMaJsDysqwwUga+fyWhUV-r78FoK7psY7howNBOCnsKLhvA@mail.gmail.com>
In-Reply-To: <7vd36j8lc3.fsf@alter.siamese.dyndns.org>

Hey,

On Fri, May 4, 2012 at 6:31 PM, Junio C Hamano <gitster@pobox.com> wrote:

Show 7 quoted lines

>
> Thanks.  The Reference Manual area lists "apply" in a very funny place.
> It should go together with "diff", whichever section you decide to put
> "diff" in.  As "diff" is listed in "Basic Snapshotting", and it will not
> be able to achieve that without being able to apply its output back to the
> working tree or to the index, I would suggest moving "apply" to the
> section as well.

I have to disagree. You are thinking of 'apply' from an internals perspective I have to assume, because I use 'diff' every single day for all sorts of stuff ("what is modified and unstaged?", "what is modified and staged?", "what is different between these two branches?" etc) where I can't think of a single time I've ever used 'apply'. In fact, even the times when I have needed to apply a patch generated from 'diff' I used 'patch -p1' because I know it better. I, and most people I would guess, almost never use 'diff' to generate patch files, we use it to see what has changed before committing or things like that - in general usage, it's more like an advanced 'status' honestly.

Show 9 quoted lines

> I am fairly happy about the look of the new site except for a few things
> ;-).
>
> It seems that you are trying to advocate "staging area" as some sort of
> official term.  I think "it is like a staging area" is a good phrase to
> use when answering "what is the index?", but I think repeating it million
> times without telling the casual readers what its official name is is
> counterproductive.  Don't do that.  It will confuse these same people when
> they start reading manuals.

I'm not really trying to advocate it as much as using terminology that is already quite popular. It's true that it's not what is used in the man pages, but neither is 'index' used consistently - there is 'cache' too, in addition to 'index' having two meanings - packfile and cache. I'm open to making things clearer, but I just don't think that changing the terminology to something more technical and vague would be overall less confusing to people.

That said, in most places I use phrases like 'Git has something called the "staging area" or "index"' letting people know that there are multiple phrases for it and what it's technical term tends to be. So your "without telling the casual readers what its official name is" is generally not true - I do try to do that too.

Scott