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

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