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

Heya,

[+Scott, who's done a lot of work on making git more newbie friendly]
[+Jonathan, I saw his reply just before sending this]

On Mon, Oct 18, 2010 at 15:45, Thore Husfeldt [off-list ref] wrote:

I’ve just learned Git. What a wonderful system, thanks for building
it.

Thanks.

And what an annoying learning experience.

Thanks again :).

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. Here it is, for what it’s worth. Read it as the friendly, but
somewhat exasperated suggestions of a newcomer. I’d love to help (in
the form of submitting patches to the documentation or CLI responses),
but I’d like to test the waters first.

Awesome! Your experiences are very welcome indeed!

So, remote tracking branches are neither remote (they are *local*
copies of how the remote once was) and they stand completely still
until you tell them to “fetch”. So remote means local, and tracking
means still, “local still-standing” would be a less confusing term
that “remote tracking”. Lovely.

*chortles*, nicely observed.

The hyphenated *remote-tracking* is a lot better terminology already
(and sometimes even used in the documentation), because at least it
doesn't pretend to be a remote branch (`git branch -r`, of course,
still does).

What do you mean with the last part (about `git branch -r`)? The fact
that 'refs/remotes' is not immutable?

So that single hyphen already does some good, and should
be edited for consistency.

If we agree that "remote-tracking" is the way to go, a patch doing
such editing would be very welcome.

And *even if* the word was meaningful and consistently spelt, the
documentation uses it to *refer* to different things. Assume that we
have the branches master, origin/master, and origin’s master
(understanding that they exist, and are different, is another Aha!
moment largely prevented by the documentation).

How could the documentation make this more clear?

Or rather, it is the confirmation one needs that nobody in the Git
community cares much

On the contrary, we care a lot, but once you're not a new user
yourself anymore, it's hard to know what to fix.

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 realise that this terminology is now so ingrained in Git
users that conservatism will probably perpetuate it. But it would be
*very* helpful to think this through, and at least agree on who
“tracks” what. 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”.
[...]
More radically, I am sure some head scratching would be able to find
useful terminology for master, origin/master, and origin’s master. I’d
love to see suggestions. As I said, I admire how wonderfully simple
and clean this has been implemented, and the documentation, CLI, and
terminology should reflect that.

I don't have any objections to changing these terms, but I don't have
any suggestions on what to change them _to_.

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

(or 'git rm --cached' for newly added files)

   nothing added to commit but untracked files present

should be

   nothing staged to commit, but untracked files present

I've always liked the whole 'stage(d)' concept, so I like this, but I
remember Junio being fairly hesitant to use it more extensively.

(Comment: maybe “... but working directory contains untracked files.”
I realise that “directory” is not quite comprehensive here, because
files can reside in subdirectories.

We use "worktree" elsewhere, how about that?

   (use "git track <file>" to track)

So basically you want to split out 'git add' into 'git track' and 'git stage'?

   Changes to be committed:
   (use "git reset HEAD <file>..." to unstage)

should be

   Staged to be committed:
   (use "git unstage <file>" to unstage)

This would be extra nice since 'git unstage' could also be used in a
fresh repository.

But this is a good example of what’s wrong with the way the
documentation thinks: Git’s implementation perspective should not
define how concepts are explained. In particular, *tracking* (in the
sense of making a file known to git) and *staging* are conceptually
different things. In fact, the two things remain conceptually
different later on: un-tracking (removing the file from Git’s
worldview) and un-staging are not the same thing at all, neither
conceptually nor implementationally.

Fair point, I think.

The opposite of staging is `git
reset HEAD <file>` and the opposite of tracking is -- well, I’m not
sure, actually. Maybe `git update-index --force-remove <filename>`?

'git rm --cached'

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

I disagree, many people come from another VCS, and pointing out where
their assumptions are invalid is generally useful.

There’s another issue with this, namely that “added files are
immediately staged”. In fact, I do understand why Git does that, but
conceptually it’s pure evil: one of the conceptual conrnerstones of
Git -- that files can be tracked and changed yet not staged, i.e., the
staging areas is conceptually a first-class citizen -- is violated
every time a new file is “born”. Newborn files are *special* until
their first commit, and that’s a shame, because the first thing the
new file (and, vicariously, the new user) experiences is an
aberration.

Eh, I think it's not an aberration, it's more of a convenience. I
don't think the benefit of making the concept of tracking vs. staging
clear to the user is worth the hassle of having to execute two things
to do one thing (staging a new file). You can also see it the other
way around, why are new files any different from other files? Why
shouldn't you be able to stage new files?

-- 
Cheers,

Sverre Rabbelier