Consistent terminology: cached/staged/index

classic Classic list List threaded Threaded
65 messages Options
1234
Reply | Threaded
Open this post in threaded view
|

Re: Consistent terminology: cached/staged/index

Drew Northup

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

> On 1 March 2011 19:02, Drew Northup <[hidden email]> 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.

> 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

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

Re: Consistent terminology: cached/staged/index

Felipe Contreras
In reply to this post by Drew Northup
On Tue, Mar 1, 2011 at 6:46 PM, Drew Northup <[hidden email]> wrote:

>
> On Tue, 2011-03-01 at 10:27 +0100, Alexey Feldgendler wrote:
>> On Tue, 01 Mar 2011 10:11:11 +0100, David <[hidden email]> wrote:
>>
>> > A suggestion: could your conceptual bucket be named as "the precommit".
>> >
>> > Motives for this suggestion are:
>> > 1)  I imagine this word will be readily translatable;
>>
>> Less so than “staging area”, at least into Russian.
>>
>> Just my two cents.
>
> I was starting to think about "commit preparation area" this morning,
> but it sounds horribly long. Would "Prep area" work provided that the
> longer version has already been introduced into the discussion? This
> provides a similar language metaphor to "staging area" hopefully without
> the translation problem.
>
> Also, I still think that it is important to note somewhere that the way
> that git handles commits is not the way that most users are likely to
> imagine (the Index doesn't contain the blob objects itself; a finalized
> commit is not just a bundled collection of everything as somebody might
> expect; etc) so this "Prep area" is a logical space not completely
> analogous to stuff found in the ".git" directory. Pretending that
> complexity does not exist will not help; letting the users know that
> they don't need to grok all of the details to get started is, on the
> other hand, quite important.

First I liked this proposal, but then I thought about 'git diff
--preped' (doesn't really sound right). I think the term should:

 1) Have a nice noun version; staging area, preparation area
 2) Have a nice verb version; to stage, to prep
 3) Have a nice past-participle; staged, cached

Casting? Forging? I don't know, staging always seems right.

Cheers.

--
Felipe Contreras
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

Re: Consistent terminology: cached/staged/index

Miles Bader-2
2011/3/5 Felipe Contreras <[hidden email]>:
> First I liked this proposal, but then I thought about 'git diff
> --preped' (doesn't really sound right). I think the term should:
>
>  1) Have a nice noun version; staging area, preparation area
>  2) Have a nice verb version; to stage, to prep
>  3) Have a nice past-participle; staged, cached
>
> Casting? Forging? I don't know, staging always seems right.

I agree.

I don't why so many people seem to be trying so hard to come with
alternatives to "staged" and "staging area", when the latter are
actually quite good; so far all the suggestions have been much more
awkward and less intuitive.

It's true that "staging area" and "stage" as a verb are most intuitive
for native english speakers, but so far none of the alternatives
really seem any better for non-native speakers.  _All_ of these terms
are "learned" to some degree, and in that sense are arbitrary, but the
smoothness and intuitiveness of "staging area"/"stage" for english
speakers is a real plus I think.

As for translations, is it even an issue?  If term "XXX" is the
optimum term in some other language, then that should be the
translation for that langage, _regardless_ of what the english term
used is.

-miles

--
Cat is power.  Cat is peace.
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

Re: Consistent terminology: cached/staged/index

Jonathan Nieder-2
Miles Bader wrote:

> I don't why so many people seem to be trying so hard to come with
> alternatives to "staged" and "staging area", when the latter are
> actually quite good; so far all the suggestions have been much more
> awkward and less intuitive.

*nod*  Actually, "staging area" is intuitive on first reading and
"stage" less so to me, while the alternatives tend to be more
confusing for what it's worth.

I think this thread has outlived its usefulness.  Could people with
concrete proposals (e.g., "the description of 'git add' is confusing
in such-and-such way; this rewording makes it clearer", or "the
glossary does not describe the staging area very well; how about
this description") please start new threads?

Thanks,
Jonathan
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Reply | Threaded
Open this post in threaded view
|

Re: Consistent terminology: cached/staged/index

Drew Northup
In reply to this post by Miles Bader-2

On Sat, 2011-03-05 at 13:53 +0900, Miles Bader wrote:

> 2011/3/5 Felipe Contreras <[hidden email]>:
> > First I liked this proposal, but then I thought about 'git diff
> > --preped' (doesn't really sound right). I think the term should:
> >
> >  1) Have a nice noun version; staging area, preparation area
> >  2) Have a nice verb version; to stage, to prep
> >  3) Have a nice past-participle; staged, cached
> >
> > Casting? Forging? I don't know, staging always seems right.
>
> I agree.
>
> I don't why so many people seem to be trying so hard to come with
> alternatives to "staged" and "staging area", when the latter are
> actually quite good; so far all the suggestions have been much more
> awkward and less intuitive.
>
> It's true that "staging area" and "stage" as a verb are most intuitive
> for native english speakers, but so far none of the alternatives
> really seem any better for non-native speakers.  _All_ of these terms
> are "learned" to some degree, and in that sense are arbitrary, but the
> smoothness and intuitiveness of "staging area"/"stage" for english
> speakers is a real plus I think.

It has already been pointed out that this isn't always quite as
intuitive as it sounds to many. I think we'd be flogging a dead horse to
continue discussing that.

> As for translations, is it even an issue?  If term "XXX" is the
> optimum term in some other language, then that should be the
> translation for that langage, _regardless_ of what the english term
> used is.
>
> -miles

Having translated stuff before, and having helped clean-up / finish
translations from other languages to English, I can say that it most
certainly DOES MATTER what the idiom used in the source language is.
Unless I the translator know more about how something works than the
core developers that wrote it I am highly dependent on the explanations
they have used. That is why it is important to have a complete and
portable metaphor. In fact, that's exactly what I was thinking about
when I suggested "commit preparation area" earlier in this thread--the
translation to Spanish is a tad verbose but it is entirely clear without
further jiggering or expectation of specific cultural knowledge.

I'm not sure why that "fails" the equally arbitrary participle-mapping
test... It sure has one, but as a native English speaker and a brutal
editor I am perfectly comfortable with the notion that not all verbs
have natural noun forms and vice-versa.

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

--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to [hidden email]
More majordomo info at  http://vger.kernel.org/majordomo-info.html
1234