Re: Git terminology: remote, add, track, stage, etc.

[Jonathan Nieder <jrnieder@gmail.com>]

Hi Thore,

Thore Husfeldt wrote:

>     what an annoying learning experience. 
> 
> I promised myself to try to remember what made it all so hard, and to
> write it down in a comprehensive and possibly even constructive
> fashion.

Thanks for doing this work!

> There probably is a radical case to be made for abandoning the word
> “tracking” entirely. First, because tracking branches don’t track, and
> second because “tracking” already means something else in Git (see
> below).

I think you are overthinking this "tracking like a Basset hound" thing.

When a person keeps a diary to track their appointments, is it always
up to date?  No, it is only as up to date as the person is diligent.
Similarly, git provides a namespace for branches that a person can
use to track remote branches, which is only as up to date as one
keeps it.

So what would be a better term?

>                In the ideal world, origin/master would be something
> like “the fetching branch” for the origin’s master, or the “snapshot
> branch” or the “fetched branch”.

Familiarity might be leaving me blind, but these all sound even more
confusing to me.  In fact, origin/master is not only updated by
fetching but by pushing (at least if I remember correctly).  It is
meant to be git's local memory of remote content.

Using the term "remote-tracking" consistently would certainly be an
improvement and would make it easier to do a search-and-destroy (erm,
-and-replace) if another term comes up that seems to fit the concept
better.

> The wonderful and central concept of staging area exists under at
> least three names in Git terminology. And that’s really, really
> annoying. The index, the cache, and the staging area are all the same,
> which is a huge revelation to a newcomer.

Heh.  Personally I tend to think in terms of "the index".

e.g., "git add" registers changes for use in the next commit.
Information about the commit in preparation is stored in the
index.

Why?  Because "staging area" has this misleading feeling of
not-jargon.  It is jargon and when misused can be very confusing
(to me, at least).

> 2. Introduce the alias `git unstage` for `git reset HEAD` in the
> standard distribution.

Doesn't "git reset" ('reset the staged content to match...') fit the
same metaphor?

> 3. Duplicate various occurences of `cached` flags as `staged` (and
> change the documentation and man pages accordingly), so as to have,
> e.g., `git diff --staged`.

Already exists (though in practice it tends to be easier to teach
--cached since that is the option that documents all over the web
use).

> Clean? What’s this now? Clean and dirty are Git slang, and not what I
> want to meet as a new user. The message should inform me that the
> untracked files in the working directory are equal to their previous
> commit.

Huh?

Anyway, improvements welcome (in the form of a simple mockup, or even
better, patches).

>     changed but not updated:
> 
> I’m still not sure what “update” was ever supposed to mean in this
> sentence.

It's historical residue.  (What is now done with "git add" used to be
done with "git update-index").

>     Untracked files:
>     (use "git add <file>..." to include in what will be committed)
>
> should be
>
>     Untracked files:
>     (use "git track <file>" to track)

Is this "git track" a synonym for "git add -N"?

>                                      The opposite of staging is `git
> reset HEAD <file>` and the opposite of tracking is -- well, I’m not
> sure, actually.

Ah, this is a kind of obnoxious thing!  For a newly added file,

	git reset -- <path>

ought to un-add it, but it doesn't.

For a file that has been around for a while, removal is imho just
adding a different kind of change.  It would be nice if

	git add -- <path>

pointed to "git rm --cached" to help the operator to do that.

> The entire quoted paragraph in the tutorial can be removed: there’s
> simply no reason to tell the reader that git behaves differently from
> other version control systems

How will a person used to e.g. cvs ever adjust if they don't even
realize git is different?

Hope that helps,
Jonathan