friendlier names

friendlier names

[David Abrahams]

I'm absolutely certain I'm not the first person to have raised this
issue, so feel free to point me at the threads where I can get the
rationale... but: to me it looks like git's choice of terminology hurts
its adoption and learnability.  

For example, why couldn't the "index" be called the "stage" instead?
That, along with knowing that "git add" was a synonym for "git stage"
would have flattened the learning curve considerably for me.

Thanks,

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com

Re: friendlier names

[Felipe Contreras]

On Tue, Jan 27, 2009 at 5:30 PM, David Abrahams <dave@boostpro.com> wrote:
>
> I'm absolutely certain I'm not the first person to have raised this
> issue, so feel free to point me at the threads where I can get the
> rationale... but: to me it looks like git's choice of terminology hurts
> its adoption and learnability.
>
> For example, why couldn't the "index" be called the "stage" instead?
> That, along with knowing that "git add" was a synonym for "git stage"
> would have flattened the learning curve considerably for me.

+1

I think several people have mentioned it, and there have been
different possible actions, but nothing concrete AFAIK.

-- 
Felipe Contreras

Re: friendlier names

[Shawn O. Pearce]

David Abrahams <dave@boostpro.com> wrote:
> 
> For example, why couldn't the "index" be called the "stage" instead?
> That, along with knowing that "git add" was a synonym for "git stage"
> would have flattened the learning curve considerably for me.

Historical reasons...

Waaay back the "index" was an index of the files git knows about in
your working directory.  It made sense to call it an index, as like
a book index it was a full listing of what's here, sorted by name.

That's pre-1.0 days.  Like the very first version Linus ever
released.  Aka commit e83c5163316f89bfbde7d9ab23ca2e25604af290.

Much, much later, over many months, the index morphed into what
you see today, which is a "staging area", accessed by "git add".

This was all incremental, in small parts.  Nobody set out to
design a "staging area" or to have "staging actions".  Back
when it was really the index you updated it with a tool called
git-update-index.  Adding new files required the --add flag.

People found --add annoying, so they wrote "git add" as a
wrapper around it.  But modified existing files still had
to be updated with git-update-index.  Then someone pointed
out that add of an existing file and add of a new file are
similiar enough that they should just be the same command,
"git add".

Only late last October at the GitTogether did we start to talk about
creating a command called "git stage", because people have started to
realize we seem to call it a "staging area" as we train newcomers...

The tools are _all_ slowly evolved over time.  Nothing in git
was ever set out from the beginning as a "this is what we are
going to do".  The only part of Git that is like that is the core
data structure on disk for the object store.  That hasn't changed
since Linus switched from SHA1(COMPRESS(data)) to SHA1(data) for
the object naming algorithm, and even that was done in the first
couple of weeks.

-- 
Shawn.

Re: friendlier names

[David Abrahams]

on Tue Jan 27 2009, "Shawn O. Pearce" <spearce-AT-spearce.org> wrote:

> David Abrahams <dave@boostpro.com> wrote:
>> 
>> For example, why couldn't the "index" be called the "stage" instead?
>> That, along with knowing that "git add" was a synonym for "git stage"
>> would have flattened the learning curve considerably for me.
>
> Historical reasons...
>
> Waaay back the "index" was an index of the files git knows about in
> your working directory.  It made sense to call it an index, as like
> a book index it was a full listing of what's here, sorted by name.
>
> That's pre-1.0 days.  Like the very first version Linus ever
> released.  Aka commit e83c5163316f89bfbde7d9ab23ca2e25604af290.

I'm not saying "index" doesn't make sense.  It _still_ makes sense.  It
just doesn't make as much sense as "stage."  Index is a very generic
term; it doesn't communicate enough.

> Much, much later, over many months, the index morphed into what
> you see today, which is a "staging area", accessed by "git add".
>
> This was all incremental, in small parts.  Nobody set out to
> design a "staging area" or to have "staging actions".  Back
> when it was really the index you updated it with a tool called
> git-update-index.  Adding new files required the --add flag.
>
> People found --add annoying, so they wrote "git add" as a
> wrapper around it.  But modified existing files still had
> to be updated with git-update-index.  Then someone pointed
> out that add of an existing file and add of a new file are
> similiar enough that they should just be the same command,
> "git add".
>
> Only late last October at the GitTogether did we start to talk about
> creating a command called "git stage", because people have started to
> realize we seem to call it a "staging area" as we train newcomers...

Sounds like, from everything you've said, "stage" rather than "index"
would have been just as sensible in the beginning as it is today; it's
just that you have a much nicer interface for working with it.

> The tools are _all_ slowly evolved over time.  Nothing in git
> was ever set out from the beginning as a "this is what we are
> going to do".  The only part of Git that is like that is the core
> data structure on disk for the object store.  That hasn't changed
> since Linus switched from SHA1(COMPRESS(data)) to SHA1(data) for
> the object naming algorithm, and even that was done in the first
> couple of weeks.

OK, thanks for the history lesson.  It's good to know someone is paying
attention to these things.  Is there any movement toward addressing
them outside of GitTogether talk?

-- 
Dave Abrahams
BoostPro Computing
http://www.boostpro.com

Re: friendlier names

[Johannes Schindelin]

Hi,

On Tue, 27 Jan 2009, Shawn O. Pearce wrote:

> David Abrahams <dave@boostpro.com> wrote:
> > 
> > For example, why couldn't the "index" be called the "stage" instead?
> > That, along with knowing that "git add" was a synonym for "git stage"
> > would have flattened the learning curve considerably for me.
> 
> Historical reasons...
> 
> Waaay back the "index" was an index of the files git knows about in
> your working directory.  It made sense to call it an index, as like
> a book index it was a full listing of what's here, sorted by name.
> 
> That's pre-1.0 days.  Like the very first version Linus ever
> released.  Aka commit e83c5163316f89bfbde7d9ab23ca2e25604af290.

Actually, it was known by the name "dircache" back then :-)

Ciao,
Dscho

Re: friendlier names

[Junio C Hamano]

"Shawn O. Pearce" <spearce@spearce.org> writes:

> David Abrahams <dave@boostpro.com> wrote:
>> 
>> For example, why couldn't the "index" be called the "stage" instead?
>> That, along with knowing that "git add" was a synonym for "git stage"
>> would have flattened the learning curve considerably for me.
>
> Historical reasons...
>
> Waaay back the "index" was an index of the files git knows about in
> your working directory.  It made sense to call it an index, as like
> a book index it was a full listing of what's here, sorted by name.
>
> That's pre-1.0 days.  Like the very first version Linus ever
> released.  Aka commit e83c5163316f89bfbde7d9ab23ca2e25604af290.

This part is a bit misleading, if not completely incorrect.

Since day 1, the entity we now call "the index aka staging area" has been
just that.  It was originally called "cache" and it implemented a cache of
_contents_ that are meant to go in the tree the next commit records.  It
was renamed to the "index" because it is an index, which you can consult
with a pathname as the key to get to the _contents_ as its value.

It never was "list of pathnames" without _contents_.  So it was a staging
area from day one.

The way to update the cache was called "update-cache" then "update-index".
Because it usually is much rare to actually add a new entry to the index
than updating an existing entry in the index, the command had a safeguard
against "update-cache a-newfile" without explicit request from the user to
say "oh by the way I know I am adding new entries".  "git add" came much
later to give you a shorthand for "update-index --add".  Updating existing
entries in the index was still done with "update-index".

Later Nico taught (after much discussion) "git add" to also serve as
"update-index" for existing entries in the index.

We could have called it "git update-index" when we did that switch-over,
because the operation is exactly that --- updating the index.

But the name somehow stuck.

> Only late last October at the GitTogether did we start to talk about
> creating a command called "git stage", because people have started to
> realize we seem to call it a "staging area" as we train newcomers...

Yeah, you may have to consider the possibility that that particular
training lingo is inconsistent with the rest of the system, exactly
because it came from outside.

Re: friendlier names

[Jakub Narebski]

Junio C Hamano <gitster@pobox.com> writes:
> "Shawn O. Pearce" <spearce@spearce.org> writes:
>> David Abrahams <dave@boostpro.com> wrote:
>>> 
>>> For example, why couldn't the "index" be called the "stage" instead?
>>> That, along with knowing that "git add" was a synonym for "git stage"
>>> would have flattened the learning curve considerably for me.
>>
>> Historical reasons...

[...]
> The way to update the cache was called "update-cache" then "update-index".
> Because it usually is much rare to actually add a new entry to the index
> than updating an existing entry in the index, the command had a safeguard
> against "update-cache a-newfile" without explicit request from the user to
> say "oh by the way I know I am adding new entries".  "git add" came much
> later to give you a shorthand for "update-index --add".  Updating existing
> entries in the index was still done with "update-index".
> 
> Later Nico taught (after much discussion) "git add" to also serve as
> "update-index" for existing entries in the index.
> 
> We could have called it "git update-index" when we did that switch-over,
> because the operation is exactly that --- updating the index.
> 
> But the name somehow stuck.
[...]

It is a bit of pity that "git add" was overloaded to also add new
contents and not only add new file (and its contents!), instead of
having new command "git stage" to be porcelain version of 
"git update-index" porcelain.  And perhaps "git resolved" to only
mark resolved entries (so e.g. "git resolved ." would not add new
files, nor add new contents of files which were not in conflict).

Now we have to explain that "git add" adds new contents... OTOH
it is perhaps good idea to emphasize differences between Git and
other lesser^W SCMs. ;-)  And introduce "git add -N"... 

-- 
Jakub Narebski
Poland
ShadeHawk on #git

Re: friendlier names

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> It is a bit of pity that "git add" was overloaded to also add new
> contents and not only add new file (and its contents!), instead of
> having new command "git stage" to be porcelain version of 
> "git update-index" porcelain.  And perhaps "git resolved" to only
> mark resolved entries (so e.g. "git resolved ." would not add new
> files, nor add new contents of files which were not in conflict).

I do not think so.

People who are taught with various means (including "git stage" alias)
understand that you prepare the contents you want to record in the commit
you are about to make by updating the contents registered in the index aka
staging area, then you do not need "git resolved".

You resolve, you have the desired content in your work tree, and you
register the updated contents from your work tree to the index aka staging
area, in exactly the same way as you do when you want to include updated
contents for any commit.

Re: friendlier names

[Jakub Narebski]

Junio C Hamano wrote:
> Jakub Narebski <jnareb@gmail.com> writes:
> 
> > It is a bit of pity that "git add" was overloaded to also add new
> > contents and not only add new file (and its contents!), instead of
> > having new command "git stage" to be porcelain version of 
> > "git update-index" porcelain.  And perhaps "git resolved" to only
> > mark resolved entries (so e.g. "git resolved ." would not add new
> > files, nor add new contents of files which were not in conflict).
> 
> I do not think so.
> 
> People who are taught with various means (including "git stage" alias)
> understand that you prepare the contents you want to record in the commit
> you are about to make by updating the contents registered in the index aka
> staging area, then you do not need "git resolved".

"Who are taught". This makes for Git to be more "user selective".
Not that this matter much, as world domination is not our goal ;-)
 
> You resolve, you have the desired content in your work tree, and you
> register the updated contents from your work tree to the index aka staging
> area, in exactly the same way as you do when you want to include updated
> contents for any commit.

While I don't think that "git resolved" is something really needed,
the difference is with "git add ." and "git resolved ." and between
"git add *" and "git resolved *", where the latter would update only
resolved merge conflict resolutions, and would not pick up independent
changes to the files that were not in conflict.

BTW with "git add" way you have to know that "git add"-ing a file
would clear 'is in merge conflict' flags (well, will hide >0 stages...).

-- 
Jakub Narebski
Poland

Re: friendlier names

[Junio C Hamano]

Jakub Narebski <jnareb@gmail.com> writes:

> BTW with "git add" way you have to know that "git add"-ing a file
> would clear 'is in merge conflict' flags (well, will hide >0 stages...).

Sigh...

Again, you seem to be affected by the same confusion that caused you to
think "git resolved" may have some reason to exist.

An unmerged index with higer stages means that the contents that need to
be in the next commit is _unknown_ for the paths.

If somebody says "I am telling you that this path has the contents I want
to have in the commit I will create next" (which is what "staging" the
contents in the "index" is), what plausible reason does git have to keep
the higher stages for them?  At that point, the contents the user wants to
have for these paths are known.