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

> 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.

> 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.

> 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).

> 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.

>    nothing added to commit but untracked files present
>
> should be
>
>    nothing staged to commit, but untracked files present

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

> 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.

> 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.