Re: Consistent terminology: cached/staged/index

From: Drew Northup <drew.northup@maine.edu>
Date: Mar 1, 2011, 17:41 UTC
Message-ID: <1299001318.5247.57.camel@drew-northup.unet.maine.edu>
In-Reply-To: <AANLkTikCEoc55WuiRNo6Q=sXqTd_WDfVRb6cnN5bRD=0@mail.gmail.com>

On Tue, 2011-03-01 at 19:30 +0200, Alexei Sholik wrote:

Show 21 quoted lines

> On 1 March 2011 19:02, Drew Northup <drew.northup@maine.edu> wrote:
> >
> > On Tue, 2011-03-01 at 11:32 +0200, Alexei Sholik wrote:
> >
> >> I guess, people who are friendly with git using the word "index"
> >> because it's easier to type. But it confuses an unprepared reader. The
> >> solution of the problem with confusion must be relevant to these
> >> points:
> >>  - clarify that "index" means the same thing as the "staging area" (in
> >> man if it isn't there already?)
> >
> > Alas, this isn't quite true. Blobs are copied to the .git/objects
> > directory (which I referred to earlier as an object store without proper
> > qualification) with each "git add" action AND are noted in the Index at
> > the same time. Therefore the Index is quite literally containing
> > information about the blobs to be committed without containing the blobs
> > themselves. This is why I find any specific equivalence between Index
> > and "staging area" distasteful--it is misleading.
> 
> There's no reason to make it more confusing by telling all the
> implementation details users are not interested in.

I am not advocating that.

> Once I add a modified file to index (via 'git add') or even add a new
> file, its content is already tracked by git. This is the most relevant
> part.

Agreed.

Show 11 quoted lines

> It is not relevant from the user's point of view whether it's already
> in .git/objects or not. Once I've staged a file, I can rm it and then
> 'git checkout' it again to the version that's remembered in the
> staging area, i.e. I will not lose it's contents once it's been
> staged.
> 
> If what you're trying to say is that new users think of the 'staging
> area' as some place where the content is stored before a subsequent
> commit, there's nothing bad about it. If they will try to find out
> about it's concrete location in the fs, they'll eventually find out
> about index and its true nature in terms of implementation.

My argument is that we should use "staging area" or "preparation area" or whatever we end up using as tools to explain the USAGE of Git without inferring that IT WORKS THAT WAY DEEP INSIDE. That's why I don't want to claim that the Index is (or means the same thing as) a staging area--we shouldn't be bothering beginner users with the Index yet anyway. Just saying that the information gets put into files in .git that act as a "staging area" is good enough--we don't need to extricate all mentions of "Index" or "cache" from the documentation. Unfortunately, if this is not done carefully we end up with people complaining that the documentation is inconsistent when it is often just blunt and indelicately worded.

-- 
-Drew Northup
________________________________________________
"As opposed to vegetable or mineral error?"
-John Pescatore, SANS NewsBites Vol. 12 Num. 59