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

Re-added (some of) CC list; at least all quoted authors are there.

Thore Husfeldt [off-list ref] writes:

Thank you all for your many and well-thought out replies. I learned
a lot.

Jonathan Nieder:

JNi> So what would be a better term [for tracking]?

Trailing is better than tracking, since it hints at some degree of
sloth, but I have not thought this through. (I also think that it
may be a strategic mistake to advocate looking for a new name; as
long as tracking is used consistently the problem with a misleading
metaphor is not so big, and the name change alienates a large group
of people whose consent is important.)

It is harder to use as adjective though, compare "remote-tracking
[branch]" with "remote-trailing [branch]"... or is it just "trailing
branch"?

Besides I don't think that 'remote-tracking' has to mean
_automatically_ tracking; it is *used* to track.

Matthiey Moy:

MM> Git's huge sin, after all (judging from most complaints I see
MM> about it), is that It Doesn't Use Exactly The Same Model (and
MM> thus Terminology) That CVS Did...


My analysis of Git’s wickedness is interestingly different. Git has
a clean and simple model that should be very easy to
understand.

The unfortunate consequence of this is that many git command and much
of git documentation is based on this understanding.  It would be
better to have documentation centered around 'user stories', not
techicalities.

For example instead of `git unstage <file>`, one has to use 
`git reset -- <file>`; one has to understand how contents is moved
between repository (commits), staging area (index / cache) and
worktree to arrive at this command.  Fortunately `git status`
and the comments in commit message template help users there,
but it would be nice not to have to rely on this.

Git’s rhetorical traditions prevent that understanding. Git is
really, really hard to learn, no matter where you come from, but
there is no inherent reason for that.

Well, there is a matter of debate how much of git complexity is
accidental complexity which should be eliminated, and how much is
essential complexity.

For example user-visible staging area[1], or git branching model[2]
can be confusing, at least to users coming from other version control
systems.  Those concepts though are necessary to allow much of power
of git.  In the case of visible staging area dealing with conflicts
during merge and choosing piece-by-piece what is to be in next commit.
In the case of git branching model, it allows for interacting with
multiple multi-branch repositories without worrying about single
global namespace for branch names.


[1] Other version control systems have at least a shadow of it,
    because they need to know which files are to be versioned
    (tracked).

[2] I mean here the difference between refs/heads/* and
    refs/remotes/<remote>/* refs, and mapping between tracked branches
    in remote repository and remote-tracking branches in given
    repository.
 

The steepness of the learning curve (rather than the divergence from
other systems’s terminology) is the single biggest complaint against
git, evidenced by my own anecdotal evidence from web surfing, and by
the Git user survey. It should be viewed as Git’s biggest current
problem by an order of magnitude. It makes me think twice and thrice
before asking my colleagues to collaborate with me using Git; I will
probably learn Mercurial and advocate using that instead; it’s
almost as nice, and I don’t feel embarrassed advocating it. Using
git for myself is great (now I understand it) but it is unclear if I
should invest social capital to convince others to use it as well.

I guess that some of _perceived_ ease of use of Mercurial was
generated by the fast that (at least in the past) it had superior
documentation in the form of "Mercurial: The Definitive Guide" aka
hgbook.  Though nowadays there is "Git User's Manual" and "Pro Git",
it is hard to fight prejudice.

Sverre Rabbelier:

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

Well, consider for example the simple obfuscatory mastery of the
following line in the user manual:

quoted

$ git branch -r			# list all remote branches

So you say that it should be instead the following, isn't it?

  $ git branch -r		# list all remote-tracking branches

Yes, I get it *now*. And I begin to feel the corruption spreading in
my own brain already: I myself start to think of origin/master as a
``remote branch''. Give me a few more weeks and I will be
completely assimilated in the mindset.

(Note to self: submit a patch about this before my assimilation is
complete. I already fixed it and committed to my local branch.)

That would be very nice.

Matthieu again:

MM> We already came up with a better wording, namely "upstream", and
MM> used in in "git push --set-upstream".

Oh, I didn’t know that. I was convinced that "upstream" was
cruft from when git was chiefly a tool to help Linus maintain the
Linux kernel. Let's see if I get this right:

The remote-tracking branch "origin/master" is *upstream* (the
upstream?) of the local branch "master",

Right.

and [local branch "master"] *tracks* the remote origin’s branch
"master"? (local) "master" is downstream of "origin/master"?

With above clarification: right.  Though using "track" here was
mistake ("follows" or "is downstream").

This would be useful. And @{u} is good. (Does it have an inverse?)

One branch can have only one "upstream" (in old terminology: it can
track only one branch).  But the reverse doesn't hold: single
remote-tracking branch can be upstream for many branches (e.g. many
feature branches based on the same long-lived branch).  The mapping is
one-to-many, so there is no inverse.

I’m not sure I like the particular word, but that’s a minor complaint. 

( For completeness: A small terminological quibble is that upstream
doesn’t verb well.

That's why git has `--set-upstream` ;-)

A bigger conceptual quibble is that this decision is not
workflow-neutral. It enforces git’s hierarchical linux-kernel
development tradition, rather than embracing a truly distributed
model where everybody is the same. When I think of distributed
version control I like to think of Alice having a remote-tracking
bob/master and Bob having a remote-tracking alice/master. Of course,
it is still meaningful for Alice to say "the upstream of
bobs_latest_crazy_ideas is bob/master", and for Bob to say "the
upstream of alices_inane_ramblings is alice/master". But it
introduces a notion of hierarchy that is inimical to the concept of
distribution, and not workflow-neutral. )

Actually it is inimical to pull-based workflow, not to hierarchical
development.  "Upstream" is where you pull from.

Sidenote: having 'canonical' repository that (almost) everybody pulls
from is I think quite common in DVCS-based development, isn't it?

Of course, upstream could be called supercalifragilistic and I would
still like it. Consistency is more important than having good
metaphors. (But good metaphors would be better, all other things
being equal.)

Jakub Narebski:

JNa> Note that it is not as easy as it seems at first glance.  There
JNa> are *two* such options, which (as you can read in gitcli(7)
JNa> manpage) have slightly different meaning:

Wow. Thanks for pointing this out, I did not know that, and it
explains a lot. I must say that to everybody else than a git
developer, this state of affairs is a proof that something is wrong,
rather than an obstruction for improvement.

What I wanted to say that any proposal for replacing 'cache'/'cached'
and 'index' terms has to take into account that you might want to
operate on staging area *instead of* default target (`--cached`),
or *in addition to* default target (`--index`).

Though it is not widespread issue: only git-apply uses both --cached
and --index, git-stash uses only --index, and all other commands use
only --cached (if any).

Well, there is also outlier of `git diff --no-index`, but it is more
lack of good name for an option :-P

??> I do not think debating on changing the terminology is a
??> particularly productive use of our time.

I agree in the sense that *how* the words are used is more important
than *which* words are used, and I realise that I should not have
put "terminology" in the headline, because that makes it about
words, not *explanations* or terminological *discipline*.

What should you put in headline / subject, then?

-- 
Jakub Narebski
Poland
ShadeHawk on #git