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

[Sverre Rabbelier <srabbelier@gmail.com>]

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 <thore.husfeldt@gmail.com> 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