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

[Jakub Narebski <jnareb@gmail.com>]

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

Thore Husfeldt <thore.husfeldt@gmail.com> 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:
> 
> > $ 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