Re: Git terminology: remote, add, track, stage, etc.
On 18 Oct 2010, at 23:41, Matthieu Moy wrote:
Show 6 quoted lines
> We already came up with a better wording, namely "upstream", and used
> in in "git push --set-upstream". Probably a next step would be to
> deprecate any other occurence of --track meaning the same thing (git
> checkout --track seems to me to be a candidate, git branch has both
> --track and --set-upstream). One difficulty is to do that with
> backward compatibility in mind.
I’ve tried to play around with this concept now, *in casu* by trying to edit the Pro Git source.
I’m not sure we all agree on what is what, so let me try to clarify.
In the following, Alice has bobsstuff, bob/master, and (Bob’s) master, which she got from
> alice% git checkout --track -b bobsstuff bob/master
(Or using `git branch`). Git tells her that
> Branch bobsstuff set up to track remote branch master from bob.
(By the way, I think “remote branch” is useful and correct, here.)
Let me see if I can use the proposed terminology:
1. bob/master *tracks* master.
2. bob/master is a remote-tracking branch
3. master is a remote branch
4. bob/master has been marked as "upstream" from bobsstuff
Is master upstream from bobbstuff as well? The man page of `git branch` seems to think so:
> Furthermore, it directs git pull without arguments to pull from the upstream when the new branch is checked out.
So both bob/master and master are sometimes called "upstream", and both bobsstuff and bob/master are sometimes called "tracking".
Let‘s try to look at the relevant Pro Git section, to get a feeling for how this terminology work when you actually try to explain something well:
Show 6 quoted lines
>
> ### Tracking Branches ###
>
> Checking out a local branch from a remote branch automatically creates what is called a _tracking branch_. Tracking branches are local branches that have a direct relationship to a remote branch. If you’re on a tracking branch and type git push, Git automatically knows which server and branch to push to. Also, running `git pull` while on one of these branches fetches all the remote references and then automatically merges in the corresponding remote branch.
>
> When you clone a repository, it generally automatically creates a `master` branch that tracks `origin/master`. That’s why `git push` and `git pull` work out of the box with no other arguments. However, you can set up other tracking branches if you wish — ones that don’t track branches on `origin` and don’t track the `master` branch. The simple case is the example you just saw, running `git checkout -b [branch] [remotename]/[branch]`. If you have Git version 1.6.2 or later, you can also use the `--track` shorthand:
This is a good section, and explains a lot. But, as with much of the Git documentation, the terminology is undisciplined. Take “tracking branches”. The section is about refs like bobbstuff, which is no longer called tracking, but “a branch that has been configured to set up an upstream relation”. Currently, if I understand the proposed terminology, there is no word for what the Pro Git book calls “tracking branches.” (I’d be happy to be wrong about this.)
Let me try
Show 5 quoted lines
> ### Upstream branches ###
>
> A local branch can be set up in a direct relationship to a remote branch; we say the that the remote branch is _upstream_. In this configuration, if you type `git push`, Git automatically knows which server and branch to push to. Also, running `git pull` on one of these branches fetches all the remote references and then automatically merges in the corresponding remote branch.
>
> When you clone a repository, Git automatically creates a `master` branch whose upstream branch is the remote-tracking branch `origin/master`.
This is not really good, because the immediately preceding section is about “remote-tracking branches” (currently called “remote branches”, by the way). And “remote-tracking branches” and “upstream branches” are the same – they both refer to bob/master, but from different perspectives. Now there are two sections about bob/master, yet the conceptually interesting branches are bobsstuff (sometimes called the “tracking branch”) and master (sometimes called the “remote branch”). bob/master is just an elegant implementation that facilitates the communication between these two branches. (This is not impossible to fix with a good rewrite.)
I’d be really happy to rewrite the documentation about this stuff (including submitting a patch to Pro Git and other useful references), but my enthusiasm is tempered by a nagging suspicion that the full terminological effect of no longer having a word for the kind of branch that bobsstuff is has been fully realised.
Thore Husfeldt <thore.husfeldt@gmail.com>