Terminology question about remote branches.

Terminology question about remote branches.

[David Kastrup]

I am trying to dig through man-pages and user manual and trying to
match them with reality.  I seem to have a hard time.  My current
understanding (which definitely differs from the documented state) is
that there are two types of branches, local and remote branches, and
both types of branches can be remote-tracking (it may not be possible
to have a non-remote-tracking remote branch, though).

A local branch is one with a local branch head.  In contrast, checking
out a remote branch, while possible, leaves one with a detached head.

"remote-tracking" basically means that git-pull will update the branch
according to changes in the remote repository.

Creating a branch using git-branch or git-checkout will always create
a local branch which may or may not be remote-tracking according to
the --no-track or --track options.

So there are basically three types of branches in a repository that I
can see:

local branch, not remote-tracking
local branch, remote-tracking
remote branch, remote-tracking

The way to add a remote branch basically is not via git-branch or
git-checkout -b (those always create local branches), but by editing
.git/config.

Is this understanding correct or did I get things completely wrong?
Because there is little sense in myself working on changing the
documentation if I have not understood the situation.

Also, the documentation currently uses "remote-tracking"
interchangeably for "local branch, remote-tracking" and "remote
branch, remote-tracking", at some times claiming that one can locally
switch to a "remote-tracking" branch, at other times not.

So the terminology seems fuzzy at the moment, and my attempt to clear
it up might not be the preferred way of doing it.

Thanks,

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Jeff King]

On Sat, Aug 04, 2007 at 12:55:43PM +0200, David Kastrup wrote:

> A local branch is one with a local branch head.  In contrast, checking
> out a remote branch, while possible, leaves one with a detached head.

Yes, if by "remote branch" you mean a "remote tracking branch".

> "remote-tracking" basically means that git-pull will update the branch
> according to changes in the remote repository.

A "remote tracking branch" is a branch in refs/remotes/* that is updated
by _git-fetch_ (which is in turn called by git-pull) to track a remote's
position of a branch.

A local branch which tracks a remote branch (I don't recall seeing the
phrase "remote-tracking" -- where did this come from?) has the correct
magic in .git/config to pull from a specific remote branch when
'git-pull' is given without arguments.

> Creating a branch using git-branch or git-checkout will always create
> a local branch which may or may not be remote-tracking according to
> the --no-track or --track options.

Yes, although again, I think calling it a "remote-tracking branch" to
mean "a local branch that tracks a remote branch" is confusingly similar
to the more common "remote tracking branch" to mean "a branch in
refs/remotes that track's a remote repository's idea of a branch".

> So there are basically three types of branches in a repository that I
> can see:
> 
> local branch, not remote-tracking
> local branch, remote-tracking
> remote branch, remote-tracking

No, the remote branch is not remote-tracking in the sense that you
defined above; it is not meant to be pulled into.

I think you are confused by two uses of the word "track". In one case,
we mean that git-fetch will remember the remote's idea of a branch in
refs/remotes/<remote>/<branch>. In another, we mean that a local branch
will default to pulling from a particular (remote,branch) combination.

> So the terminology seems fuzzy at the moment, and my attempt to clear
> it up might not be the preferred way of doing it.

Yes, it is very fuzzy. Using "track" for the concept of a local branch
defaulting to a particular (remote,branch) pair for git-pull is, I
think, more recent and less used. If there were another term for this,
it might be more clear.

-Peff

Re: Terminology question about remote branches.

[David Kastrup]

Jeff King <peff@peff.net> writes:

> On Sat, Aug 04, 2007 at 12:55:43PM +0200, David Kastrup wrote:
>
>> A local branch is one with a local branch head.  In contrast, checking
>> out a remote branch, while possible, leaves one with a detached head.
>
> Yes, if by "remote branch" you mean a "remote tracking branch".

Jeff, I actually have no _clue_ what I "mean" with respect to the
established git terminology because I can't reconcile the
documentation's use of words with my meagre understanding of the
technical processes involved.

So I can't even tell you whether "by remote branch I mean a remote
tracking branch".

>> "remote-tracking" basically means that git-pull will update the
>> branch according to changes in the remote repository.
>
> A "remote tracking branch" is a branch in refs/remotes/* that is
> updated by _git-fetch_ (which is in turn called by git-pull) to
> track a remote's position of a branch.
>
> A local branch which tracks a remote branch (I don't recall seeing
> the phrase "remote-tracking" -- where did this come from?) has the
> correct magic in .git/config to pull from a specific remote branch
> when 'git-pull' is given without arguments.
>
>> Creating a branch using git-branch or git-checkout will always
>> create a local branch which may or may not be remote-tracking
>> according to the --no-track or --track options.
>
> Yes, although again, I think calling it a "remote-tracking branch"
> to mean "a local branch that tracks a remote branch" is confusingly
> similar to the more common "remote tracking branch" to mean "a
> branch in refs/remotes that track's a remote repository's idea of a
> branch".

Well, of _course_ it is confusingly similar.  After all, I am posting
this question because I _am_ confused!  And I am trying to both clear
up my confusion as well as get an idea how to fix the documentation to
be less confusing.

>> So there are basically three types of branches in a repository that
>> I can see:
>> 
>> local branch, not remote-tracking local branch, remote-tracking
>> remote branch, remote-tracking
>
> No, the remote branch is not remote-tracking in the sense that you
> defined above; it is not meant to be pulled into.

Sigh.  But it is cached and updated locally in some manner when
pulling, isn't it?  I can diff against it.

> I think you are confused by two uses of the word "track". In one
> case, we mean that git-fetch will remember the remote's idea of a
> branch in refs/remotes/<remote>/<branch>. In another, we mean that a
> local branch will default to pulling from a particular
> (remote,branch) combination.
>
>> So the terminology seems fuzzy at the moment, and my attempt to
>> clear it up might not be the preferred way of doing it.
>
> Yes, it is very fuzzy. Using "track" for the concept of a local
> branch defaulting to a particular (remote,branch) pair for git-pull
> is, I think, more recent and less used. If there were another term
> for this, it might be more clear.

It is not just git-pull.  I don't get the fine lines between "remote",
"remote tracking" and the respective details in either the user manual
or the manual pages of branch-related commands.

And it's actually worse after your explanations.  Previously I
imagined to have a chance to figure this out on my own, by trying to
abstract from what I see happening when using the various commands.

Now I think that I basically have no chance figuring this out on my
own sufficiently well to be able to improve the documentation.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Lars Hjemli]

On 8/4/07, David Kastrup <dak@gnu.org> wrote:
> Now I think that I basically have no chance figuring this out on my
> own sufficiently well to be able to improve the documentation.

Remote-tracking branch:
  A local copy of a branch in another repository. This kind of branch
  cannot be updated by 'git-commit' but only by 'git-fetch' (hence
  indirectly by 'git-pull' and 'git-remote update'). If you try to
  'git-checkout' a remote-tracking branch, you will get a detached HEAD.

Local branch:
  A branch to which you may commit changes. Optionally, the branch can be
  configured to "follow" one of your remote-tracking branches. This means
  that a 'git-pull' without arguments (when your local branch is checked
  out), will automatically 'git-fetch' and then 'git-merge' the remote-
  tracking branch.

Example:

Your local branch 'master' is setup to "follow" 'refs/remotes/origin/master'.
So if you do this:

$ git checkout master
$ git pull

Then the 'git pull'-command will do this:

$ git fetch -f origin master:remotes/origin/master
$ git merge remotes/origin/master


The magic setup that makes this happen is the following lines in .git/config:

[remote "origin"]
        url = git://git.kernel.org/pub/scm/git/git.git
        fetch = +refs/heads/*:refs/remotes/origin/*

[branch "master"]
        remote = origin
        merge = refs/heads/master


Was this helpful?

-- 
larsh

Re: Terminology question about remote branches.

[David Kastrup]

"Lars Hjemli" <lh@elementstorage.no> writes:

> On 8/4/07, David Kastrup <dak@gnu.org> wrote:
>> Now I think that I basically have no chance figuring this out on my
>> own sufficiently well to be able to improve the documentation.
>
> Remote-tracking branch:
>   A local copy of a branch in another repository. This kind of branch
>   cannot be updated by 'git-commit' but only by 'git-fetch' (hence
>   indirectly by 'git-pull' and 'git-remote update'). If you try to
>   'git-checkout' a remote-tracking branch, you will get a detached HEAD.
>
> Local branch:
>   A branch to which you may commit changes. Optionally, the branch can be
>   configured to "follow" one of your remote-tracking branches. This means
>   that a 'git-pull' without arguments (when your local branch is checked
>   out), will automatically 'git-fetch' and then 'git-merge' the remote-
>   tracking branch.

Does that mean that specifying "--track" to git-checkout or git-branch
never creates a remote-tracking branch?

> Example:
>
> Your local branch 'master' is setup to "follow"
> 'refs/remotes/origin/master'.

So --track/--no-track are actually supposed to be --follow and
--no-follow?

> So if you do this:
>
> $ git checkout master
> $ git pull
>
> Then the 'git pull'-command will do this:
>
> $ git fetch -f origin master:remotes/origin/master

This is then tracking?

> $ git merge remotes/origin/master

And this is then following?

> The magic setup that makes this happen is the following lines in .git/config:
>
> [remote "origin"]
Namely: a remote-tracking branch "origin"

>         url = git://git.kernel.org/pub/scm/git/git.git
>         fetch = +refs/heads/*:refs/remotes/origin/*
>
> [branch "master"]
>         remote = origin

Namely: follow the remote tracking branch origin?

>         merge = refs/heads/master
>
>
> Was this helpful?

So we have remote tracking branches, and we have local branches
following remote tracking branches, and "--track" and "--no-track"
create local branches following or not following a remote tracking
branch?  And have nothing whatsoever to do with tracking or not
tracking a remove branch?

Talk about misleading option names here.

Then in man git-branch we have:

	In its second form, a new branch named <branchname> will be
	created. It will start out with a head equal to the one
	given as <start-point>. If no <start-point> is given, the
	branch will be created with a head equal to that of the
	currently checked out branch.

	When a local branch is started off a remote branch, git can
	setup the branch so that git-pull(1) will appropriately
	merge from that remote branch. If this behavior is desired,
	it is possible to make it the default using the global
	branch.autosetupmerge configuration flag. Otherwise, it can
	be chosen per-branch using the --track and --no-track
	options.

What does "remote branch" in this context mean?  A local branch
following a remote tracked branch?  A remote tracked branch (which by
definition can't be checked out as a branch, since that leads to a
detached head)?  What does "start off" mean in this context?  If I
can't check out a remote branch, I can't start off on it, can I?

Does "--track" mean that the new branch will copy any "remote" lines
which incidentally don't point to remote branches as their name would
suggest, but rather to remote tracking branches?  And we want to have
the relation to the remote tracking branch preserved, not to the
actual remote branch?

I don't get it.  Really.  No chance.  There are fine distinction lines
in the git terminology, it would appear, and those lines are freely
ignored in naming options and configuration parameters.  And the
manual pages themselves are not overly concerned about explaining
those distinctions either.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Lars Hjemli]

On 8/4/07, David Kastrup <dak@gnu.org> wrote:
> "Lars Hjemli" <lh@elementstorage.no> writes:
>
> > On 8/4/07, David Kastrup <dak@gnu.org> wrote:
> >> Now I think that I basically have no chance figuring this out on my
> >> own sufficiently well to be able to improve the documentation.
> >
> > Remote-tracking branch:
> >   A local copy of a branch in another repository. This kind of branch
> >   cannot be updated by 'git-commit' but only by 'git-fetch' (hence
> >   indirectly by 'git-pull' and 'git-remote update'). If you try to
> >   'git-checkout' a remote-tracking branch, you will get a detached HEAD.
> >
> > Local branch:
> >   A branch to which you may commit changes. Optionally, the branch can be
> >   configured to "follow" one of your remote-tracking branches. This means
> >   that a 'git-pull' without arguments (when your local branch is checked
> >   out), will automatically 'git-fetch' and then 'git-merge' the remote-
> >   tracking branch.
>
> Does that mean that specifying "--track" to git-checkout or git-branch
> never creates a remote-tracking branch?

Yes. The "--track" option just adds some extra info in .git/config:

[branch "master"]
  remote = origin
  merge = refs/heads/master


This info is then used by "git-pull" to
1. fetch updates from the remote repository "origin"
2. merge those updates from refs/remotes/origin/master

>
> > Example:
> >
> > Your local branch 'master' is setup to "follow"
> > 'refs/remotes/origin/master'.
>
> So --track/--no-track are actually supposed to be --follow and
> --no-follow?

Maybe ;-)

I just tried to avoid using the word "track" in more than one context,
since it seemed to be a main source of confusion.

>
> > So if you do this:
> >
> > $ git checkout master
> > $ git pull
> >
> > Then the 'git pull'-command will do this:
> >
> > $ git fetch -f origin master:remotes/origin/master
>
> This is then tracking?

Yes, this is the part that downloads objects from the remote
repository and updates refs/remotes/origin/master to refer to the same
commit as the master branch in the remote repository.

>
> > $ git merge remotes/origin/master
>
> And this is then following?

Yes, this updates your local 'master' with the commits downloaded by git-fetch


>
> > The magic setup that makes this happen is the following lines in .git/config:
> >
> > [remote "origin"]
> Namely: a remote-tracking branch "origin"

No. A remote repository: the name 'origin' can be used as an alias for

  git://git.kernel.org/pub/scm/git/git.git

>
> >         url = git://git.kernel.org/pub/scm/git/git.git
> >         fetch = +refs/heads/*:refs/remotes/origin/*
> >
> > [branch "master"]
> >         remote = origin
>
> Namely: follow the remote tracking branch origin?

No. Fetch objects from the remote repository alias "origin"

>
> >         merge = refs/heads/master

And this is the info added  by "git branch --track" which enables the
automatic merging of refs/remotes/origin/master (since
refs/remotes/origin/master is your local copy of refs/heads/master in
the 'origin' repository)


> >
> >
> > Was this helpful?

Talking to myself: obviously not


-- 
larsh

Re: Terminology question about remote branches.

[David Kastrup]

"Lars Hjemli" <hjemli@gmail.com> writes:

>> > Was this helpful?
>
> Talking to myself: obviously not

Disagree.  "Does this answer all questions and makes git's behavior
perfectly transparent" -- no.  But let's not confuse "magical" with
"helpful" here.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[David Kastrup]

David Kastrup <dak@gnu.org> writes:

> "Lars Hjemli" <hjemli@gmail.com> writes:
>
>>> > Was this helpful?
>>
>> Talking to myself: obviously not
>
> Disagree.  "Does this answer all questions and makes git's behavior
> perfectly transparent" -- no.  But let's not confuse "magical" with
> "helpful" here.

Ok, let's have another go.  Maybe I have understood more as compared
with last time.

git-branch/git-commit -b creates and manages local branches, nothing
else.  Local branches' defining feature is that they have a branch
head I can move around myself.

Then there are non-local branches.  Their defining feature is that
they have no locally moving branch head and _must_ track a remote
branch.

But local branches _also_ can track the progress/head of a remote
branch.  Since they have a locally moving branch head, this will often
lead to merge conflicts which must be resolved.

So this is more or less what I understand now.  There really is no
difference between "tracking" and "following" as I thought previously.
It is just that a local branch which happens to track a remote branch
is basically a remote tracking branch with a head of its own.

Which means it can get merge conflicts.  Can we get merge conflicts
with a remote tracking branch, too?  Namely when the remote branch
messed with its history, rebased/reverted stuff?

So that the real difference between a local and a remote tracking
branch is not that the latter tracks a remote branch (the former can
do that as well), but that the latter has no local branch head and
that saves us a lot (but not necessary all) merge conflicts?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Lars Hjemli]

On 8/4/07, David Kastrup <dak@gnu.org> wrote:
> Can we get merge conflicts
> with a remote tracking branch, too?  Namely when the remote branch
> messed with its history, rebased/reverted stuff?

No, since the "fetch" line in .git/config is prefixed by '+', which
gets translated to the '-f' option for 'git-fetch'.

And this was probably the primary reason for refs/remotes/* in the
first place: you have a namespace in which there is no chance for
'git-fetch' to overwrite local changes (ancient git had no such
namespace).

-- 
larsh

Re: Terminology question about remote branches.

[David Kastrup]

"Lars Hjemli" <hjemli@gmail.com> writes:

> On 8/4/07, David Kastrup <dak@gnu.org> wrote:
>> Can we get merge conflicts
>> with a remote tracking branch, too?  Namely when the remote branch
>> messed with its history, rebased/reverted stuff?
>
> No, since the "fetch" line in .git/config is prefixed by '+', which
> gets translated to the '-f' option for 'git-fetch'.
>
> And this was probably the primary reason for refs/remotes/* in the
> first place: you have a namespace in which there is no chance for
> 'git-fetch' to overwrite local changes (ancient git had no such
> namespace).

Ok, so a remote tracking branch is a forcefully merged branch, so we
put it into a separate category where we won't get tempted to have a
branch head which will get overwritten.

This whole "remote tracking" appears to be more a matter of _policy_
rather than inherent design.  It would appear that local and remote
tracking branches have no fundamental differences, they just get
different defaults which make it less likely for the first to lose
local changes, and less likely for the second to miss remote changes
(in particular where those involve messing up the history).

But it would be easy to create chimeras when working outside of the
porcelain, right?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Lars Hjemli]

On 8/4/07, David Kastrup <dak@gnu.org> wrote:
> This whole "remote tracking" appears to be more a matter of _policy_
> rather than inherent design.

Absolutely.

> It would appear that local and remote
> tracking branches have no fundamental differences

I'd say they have no differences at all, it's just that
'git-checkout.sh' will refuse to update HEAD to point at something
outside of refs/heads.

-- 
larsh

Re: Terminology question about remote branches.

[Jeff King]

On Sat, Aug 04, 2007 at 05:09:13PM +0200, David Kastrup wrote:

> Ok, so a remote tracking branch is a forcefully merged branch, so we
> put it into a separate category where we won't get tempted to have a
> branch head which will get overwritten.

I would hesitate to use the word "merge" here at all. You really are
just throwing away the old value, and overwriting it with the new value.
See my other email for more details.

> This whole "remote tracking" appears to be more a matter of _policy_
> rather than inherent design.  It would appear that local and remote
> tracking branches have no fundamental differences, they just get
> different defaults which make it less likely for the first to lose
> local changes, and less likely for the second to miss remote changes
> (in particular where those involve messing up the history).

Yes, I think that's fair to say.

> But it would be easy to create chimeras when working outside of the
> porcelain, right?

Sure, but then you are responsible for the mess it creates. :)

-Peff

Re: Terminology question about remote branches.

[Julian Phillips]

On Sat, 4 Aug 2007, David Kastrup wrote:

> David Kastrup <dak@gnu.org> writes:
>
>> "Lars Hjemli" <hjemli@gmail.com> writes:
>>
>>>>> Was this helpful?
>>>
>>> Talking to myself: obviously not
>>
>> Disagree.  "Does this answer all questions and makes git's behavior
>> perfectly transparent" -- no.  But let's not confuse "magical" with
>> "helpful" here.
>
> Ok, let's have another go.  Maybe I have understood more as compared
> with last time.
>
> git-branch/git-commit -b creates and manages local branches, nothing
> else.  Local branches' defining feature is that they have a branch
> head I can move around myself.
>
> Then there are non-local branches.  Their defining feature is that
> they have no locally moving branch head and _must_ track a remote
> branch.
>
> But local branches _also_ can track the progress/head of a remote
> branch.  Since they have a locally moving branch head, this will often
> lead to merge conflicts which must be resolved.
>
> So this is more or less what I understand now.  There really is no
> difference between "tracking" and "following" as I thought previously.
> It is just that a local branch which happens to track a remote branch
> is basically a remote tracking branch with a head of its own.
>
> Which means it can get merge conflicts.  Can we get merge conflicts
> with a remote tracking branch, too?  Namely when the remote branch
> messed with its history, rebased/reverted stuff?

Well, sort of - they are not really merge conflicts as there is no merging 
involved.  Fetching is strictly an updating process, either we update the 
branch or we don't.

When updating a remote tracking branch there are two possible scenarios:

1) the new head is a superset of the old head (i.e. the old head forms 
part of the history of the new)
2) the new head is not a superset of the old head (i.e. the old head does 
not form part of the history of the new)

The normal case is 1), and we simply update the branch to point at the 
new commit.  However what happens in case 2) depends on the configuration. 
If we have told git to force an update (indicated by the '+' on the 
beginning of the fetch line in the config) then we simply accept the new 
head as with case 1), otherwise we complain to the user and don't update 
that branch

> So that the real difference between a local and a remote tracking
> branch is not that the latter tracks a remote branch (the former can
> do that as well), but that the latter has no local branch head and
> that saves us a lot (but not necessary all) merge conflicts?

Yes.  A remote tracking branch is basically a read-only local cache of 
something that exists in some other repository.

-- 
Julian

  ---
If you're going to do something tonight that you'll be sorry for tomorrow
morning, sleep late.
 		-- Henny Youngman

Re: Terminology question about remote branches.

[David Kastrup]

"Lars Hjemli" <lh@elementstorage.no> writes:

> The magic setup that makes this happen is the following lines in .git/config:
>
> [remote "origin"]
>         url = git://git.kernel.org/pub/scm/git/git.git
>         fetch = +refs/heads/*:refs/remotes/origin/*
>
> [branch "master"]
>         remote = origin
>         merge = refs/heads/master
>
>
> Was this helpful?

It would be helpful.  Except that nothing whatsoever can be found in
.git/config concerning my local and my remote tracking branches.  So
where is that information _really_ hidden away?

.git/FETCH_HEAD maybe?

It also appears that doing

git-checkout --track -b mybranch origin

on a git.git clone does _not_ create a tracking branch.  I can't
figure out what I could specify as an origin to create a tracking
branch that would get reflected in .git/FETCH_HEAD.

What gives?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Julian Phillips]

On Sat, 4 Aug 2007, David Kastrup wrote:

> "Lars Hjemli" <lh@elementstorage.no> writes:
>
>> The magic setup that makes this happen is the following lines in .git/config:
>>
>> [remote "origin"]
>>         url = git://git.kernel.org/pub/scm/git/git.git
>>         fetch = +refs/heads/*:refs/remotes/origin/*
>>
>> [branch "master"]
>>         remote = origin
>>         merge = refs/heads/master
>>
>>
>> Was this helpful?
>
> It would be helpful.  Except that nothing whatsoever can be found in
> .git/config concerning my local and my remote tracking branches.  So
> where is that information _really_ hidden away?

It really is in .git/config, _provided_ that your repo was created by 
1.5.0 or newer.  Older versions had a more distributed setup using files 
in .git/remotes/ and .git/branches/

> .git/FETCH_HEAD maybe?

Nope, that's just information about what got fetched last.  A purely 
temporary thing.

> It also appears that doing
>
> git-checkout --track -b mybranch origin
>
> on a git.git clone does _not_ create a tracking branch.  I can't
> figure out what I could specify as an origin to create a tracking
> branch that would get reflected in .git/FETCH_HEAD.

With pre 1.5 you didn't get remote tracking branches in a separate 
namespace.  The default was to have a local branch called origin which was 
the "remote tracking branch" for the master branch - but this wasn't 
enforced.  So with your repo the origin branch _is_ the remote tracking 
branch ... or at least the closet a pre 1.5 setup gets.

> What gives?

It would appear that your repo was created with an old version of git. 
Which also explains why you were talking about origin as a branch - which 
it used to be (a real local branch too ...), rather than as a remote - 
which it is now.

The whole remotes/tracking mechanism changed in 1.5.0 - now it's much more 
flexible (and probably more complicated too).

-- 
Julian

  ---
Ever notice that even the busiest people are never too busy to tell you
just how busy they are?

Re: Terminology question about remote branches.

[David Kastrup]

Julian Phillips <julian@quantumfyre.co.uk> writes:

> On Sat, 4 Aug 2007, David Kastrup wrote:
>
>> "Lars Hjemli" <lh@elementstorage.no> writes:
>>
>>> The magic setup that makes this happen is the following lines in .git/config:
>> It would be helpful.  Except that nothing whatsoever can be found in
>> .git/config concerning my local and my remote tracking branches.  So
>> where is that information _really_ hidden away?
>
>> What gives?
>
> It would appear that your repo was created with an old version of
> git. Which also explains why you were talking about origin as a
> branch - which it used to be (a real local branch too ...), rather
> than as a remote - which it is now.
>
> The whole remotes/tracking mechanism changed in 1.5.0 - now it's
> much more flexible (and probably more complicated too).

I think I am going to cry.  So I need to rebase my branches, pull out
the resulting patch sets, scrap my repository, clone it new from
upstream, reapply my branches, in order to have a system where the
documentation is somewhat in synch with the actual behavior?

[...]

No, it would seem that I can just
git-clone -l
my repository and be set up in the new order of things.  Nice.

However, it would appear from my experiments up to now that the
--track option _can't_ be made to work with a 1.4 repository.  I think
that is worth mentioning in the docs.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Theodore Tso]

On Sat, Aug 04, 2007 at 08:00:00PM +0200, David Kastrup wrote:
> 
> I think I am going to cry.  So I need to rebase my branches, pull out
> the resulting patch sets, scrap my repository, clone it new from
> upstream, reapply my branches, in order to have a system where the
> documentation is somewhat in synch with the actual behavior?

... or you can you use "git remote" to create the remote tracking
branches.  The important thing to realize is that 99% of what "git
remote" does is purely by editing the config file.  (The last 1% is
running "git fetch" if you specify the -f option.)  So understanding
what gets placed in the .git/config file after doing an initial clone
from a URL for a pre-1.5 git and what gets placed in .git/config file
and how the branches are set up post 1.5 is key to understanding what
is going on.

> No, it would seem that I can just
> git-clone -l
> my repository and be set up in the new order of things.  Nice.

Be careful, not really.  A git-clone -l will set up a new repository
where origin/master is your original repository, i.e.:

[remote "origin"]
        url = /usr/projects/e2fsprogs/base
        fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
        remote = origin
        merge = refs/heads/master

In contrast, if you had done a git-clone of remote repository, you
might see something like this instead:

[remote "origin"]
        url = git://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git
        fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
        remote = origin
        merge = refs/heads/master

In contrast, if you are using git 1.4, after a clone, "origin" and
"master" are by default set to the "master" branch in the source
repository, and in git 1.4 (and in git 1.5 if you don't have any of
the above configuration opions in your .git/config file), the "origin"
branch is magical and works like the remote tracking branch of
origin/master of git 1.5 for the purposes of "git fetch", and then the
implied merge done by "git pull" merges from "origin" branch to the
"master" branch.

> However, it would appear from my experiments up to now that the
> --track option _can't_ be made to work with a 1.4 repository.  I think
> that is worth mentioning in the docs.

Well, there really is no such thing as a "1.4 repository".  The only
real difference is the default configuration which is dropped into the
.config file when you do a "git clone", and whether the head of the
master branch created after the "git clone" is called "origin", with
some magic special casing so that works like a remote tracking branch
of the remote repo's master branch, or whether it is called
"origin/master", with explicit configuration rules in .git/config.

The real issue is that a "1.4 repository" (that is a repository
created by "git clone" from git 1.4 and where the config file hasn't
been updated either by hand-editing the config file or by use of "git
config" or "git remote" to have remote branches) doesn't have any
remote branches, and git branch -track only has significance if you
are creating a new (local) branch from a remote tracking branch.

Regards,

						- Ted

Re: Terminology question about remote branches.

[David Kastrup]

Theodore Tso <tytso@mit.edu> writes:

> On Sat, Aug 04, 2007 at 08:00:00PM +0200, David Kastrup wrote:
>
>> No, it would seem that I can just
>> git-clone -l
>> my repository and be set up in the new order of things.  Nice.
>
> Be careful, not really.  A git-clone -l will set up a new repository
> where origin/master is your original repository, i.e.:
>
> [remote "origin"]
>         url = /usr/projects/e2fsprogs/base
>         fetch = +refs/heads/*:refs/remotes/origin/*
> [branch "master"]
>         remote = origin
>         merge = refs/heads/master
>
> In contrast, if you had done a git-clone of remote repository, you
> might see something like this instead:

Yes, I noticed.  I can do a
git-clone -l --reference /my/local/rep git://the/remote/repo

instead.  That's still very fast, but I miss out on my local changes...

> [remote "origin"]
>         url = git://git.kernel.org/pub/scm/fs/ext2/e2fsprogs.git
>         fetch = +refs/heads/*:refs/remotes/origin/*
> [branch "master"]
>         remote = origin
>         merge = refs/heads/master
>
>> However, it would appear from my experiments up to now that the
>> --track option _can't_ be made to work with a 1.4 repository.  I think
>> that is worth mentioning in the docs.
>
> The real issue is that a "1.4 repository" (that is a repository
> created by "git clone" from git 1.4 and where the config file hasn't
> been updated either by hand-editing the config file or by use of
> "git config" or "git remote" to have remote branches) doesn't have
> any remote branches, and git branch -track only has significance if
> you are creating a new (local) branch from a remote tracking branch.

An error message might be nice, though.  I find git hard to understand
at times.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Jeff King]

On Sat, Aug 04, 2007 at 02:36:07PM +0200, David Kastrup wrote:

> And it's actually worse after your explanations.  Previously I
> imagined to have a chance to figure this out on my own, by trying to
> abstract from what I see happening when using the various commands.
> 
> Now I think that I basically have no chance figuring this out on my
> own sufficiently well to be able to improve the documentation.

I see that Lars and others have provided some explanations in my
absence, but let me try to lay it out from basics, and hopefully between
all of our writing it will make sense. I'm going to try to be as basic
as possible, so if I am telling you something you already know, it's not
because I think you're stupid, but because I'm trying to be thorough.

Git history is a directed graph of commit objects, with each commit
object pointing to its parent (or parents if it is a merge). We have
human-readable names pointing into the history as well, which we call
refs, and generally store under the "refs/" hierarchy (with a few
exceptions, which I will mention in a minute).

There are a few different types of pointers (refs) that are useful to
us. They are differentiated by the types of things we want to do with
them.

  1. refs that track our ongoing commits. This process involves making
     a new commit object whose parent is the previous value of the ref,
     and then pointing the ref at the new commit. We generally call
     these refs "heads", "local branches", or just "branches", and they
     are stored in "refs/heads/".

  2. refs that point to a single commit and aren't changed. These refs
     are "tags", and we store them in "refs/tags/".

  3. refs that represent a remote repository's local branch. These are
     updated by git-fetch, which simply writes the new value of the
     pointer into our local copy, throwing out the old value.  These are
     called "remote tracking branches" and are stored in
     "refs/remotes/<remote>/<branch>".

  4. Temporary pointers to help out some multi-step operation that we're
     in the middle of. These include FETCH_HEAD and MERGE_HEAD.

There is an order of ref lookup which goes like:
  .git/<name>
  .git/refs/<name>
  .git/refs/tags/<name>
  .git/refs/heads/<name>
  .git/refs/remotes/<name>

It used to be the case (prior to git 1.5) that remote tracking branches
and local branches were stored in the same hierarchy (under
refs/heads/). This turned out to be problematic for many users, because
the operations that you perform on them don't play well together.

For example, let's say you have a branch "origin" representing Junio's
"master" branch. You check it out and make a commit. This rewrites the
"origin" ref, but it's safe because the new commit points to the old
value. Now you want to fetch more work from Junio, so you run
"git-fetch". But the value of Junio's ref doesn't ever reference your
work. If git-fetch copies the value of Junio's new ref into your
"origin", then it will throw away the work that you were done (i.e., no
ref will be pointing to it, or to any commit that references it). But if
git-fetch doesn't copy the value of Junio's new ref, then how will you
get to see his new work?

So it is a mistake to create commits on top of a remote tracking branch.
The new strategy is therefore to store them in refs/remotes, which is an
indicator that they are purely for remote tracking. If you attempt to
git-checkout a branch in refs/remotes, you will get a detached HEAD
rather than actually checking out that branch.

Normally "HEAD" is a pointer to a ref in refs/heads/ (which is itself a
pointer to a commit object) representing "the current branch." When HEAD
becomes detached, we mean that instead of pointing to a branch ref, it
points directly to a commit object. So when you do "git-checkout
origin/master" (which, unless you have a local branch named
"origin/master" will end up looking in refs/remotes/origin/master), it
doesn't put "refs/remotes/origin/master" in your HEAD, but rather the
_value_ of that ref.

The implication here is that commits you create on a detached HEAD are
not stored by any ref except HEAD, and will be lost when you move
the HEAD elsewhere (i.e., when you check out a different branch).

Tags are in a similar situation. You don't want to make commits on tags;
instead, you want to simply set them to a pre-existing commit. Thus when
you check out a tag, you get a detached HEAD (and we know it's a tag
because it's in refs/tags, not refs/heads).

So hopefully at this point you understand "local branch" and "remote
tracking branch."

To get to the final concept you mentioned, let's take a look at what
fetch and pull do.

Let's say you run:

  git-fetch git://git.kernel.org/pub/scm/git/git.git

That stores the value of Junio's current branch (which tends to be
"master") into your local FETCH_HEAD (stored in ".git/FETCH_HEAD").

And if you run:

  git-fetch git://git.kernel.org/pub/scm/git/git.git next

Then we store the value of Junio's next branch into your FETCH_HEAD.

And finally, if you run:

  git-fetch \
    git://git.kernel.org/pub/scm/git/git.git \
    next:refs/remotes/junio/next

then we store Junio's next branch in our FETCH_HEAD, but _also_ store it
in the remote tracking branch refs/remotes/junio/next.

The second argument to fetch is called a "refspec", and you can have
several of them. Because all of that gets tedious to type, we have the
concept of configured remotes, which are a shorthand for a URL and
associated refspecs. When you use "git-clone", it creates the following
config:

  [remote "origin"]
    url = git://git.kernel.org/pub/scm/git/git.git
    fetch = +refs/heads/*:refs/remotes/origin/*

The refspec in this case uses a wildcard to get _all_ of Junio's
branches, and store them by name under refs/remotes/origin. So we can
just say "git-fetch origin" and it will populate our FETCH_HEAD as well
as the refs/remotes/origin directory.

If we call "git-fetch" without any arguments, it will look up the
default remote in our configuration. git-clone also creates the
following config:

  [branch "master"]
    remote = origin
    merge = refs/heads/master

which means "if we are on the master branch, default fetches to the
remote 'origin'". I will explain the merge line in a minute.

So now we look at git-pull. Recall that a pull is basically a fetch
followed by a merge. If you run:

  git-pull git://git.kernel.org/pub/scm/git/git.git

it will do a git-fetch of that URL (grabbing the current branch),
followed by a git-merge of FETCH_HEAD.

If you run:

  git-pull origin master

it will fetch the "origin" remote, putting all branches into the
FETCH_HEAD (and storing them in refs/remotes/origin as a side effect).
Then it will pick the branch named 'master' out of FETCH_HEAD, and
merge it.

If you run:

  git-pull origin

it will fetch origin as usual, but which branch gets merged? The answer
is the value of the "merge" field in the 'branch "master"' section of
your config (which is generally created by git-clone).

And of course, if you run:

  git-pull

it will look up the remote to fetch in the config (just as "git-fetch"
would), and then find the branch to merge in the config.

So how do we this configuration set up? There are three ways:

  1. Edit your .git/config by hand. :)
  2. git-clone sets up a master/origin relationship, adding both the
     "remote" and "branch" sections.
  3a. Using git-remote, you can add new "remote" sections easily.
  3b. Using the --track option to git-branch, you can set up the
      "branch" section automatically.

What you had called a "remote-tracking branch" is really a branch for
which the 'branch "<name>"' config section has been set up (which could
come about in several ways). I haven't really seen a term such as
"remote-tracking branch" for this in use in the documentation (and I
think we both agree that is not the right term because of its confusing
similarity to remote tracking branches, discussed above).

I know that was a pretty long email, but hopefully you understand the
context of the terms a bit more, and I didn't bore you too much. ;)
Feel free to ask questions if there are parts that are unclear.

-Peff

Re: Terminology question about remote branches.

[David Kastrup]

Jeff King <peff@peff.net> writes:

[...]

> I know that was a pretty long email, but hopefully you understand
> the context of the terms a bit more, and I didn't bore you too
> much. ;) Feel free to ask questions if there are parts that are
> unclear.

The main question is why I can't find this explained in this manner in
the documentation.  Are you going to put it in yourself, or should I
attempt doing it?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Jeff King]

On Sun, Aug 05, 2007 at 11:29:12AM +0200, David Kastrup wrote:

> The main question is why I can't find this explained in this manner in
> the documentation.  Are you going to put it in yourself, or should I
> attempt doing it?

I guess because nobody complained it wasn't there before. :) Some of the
information is a bit under-the-hood for most end-users, but obviously in
your case the lack of information was creating confusion about the
terms.

Why don't you take a stab at updating the documentation (since you are
the one who knows which parts were confusing you), and I will be more
than happy to help with making sure the changes are accurate.

-Peff

Re: Terminology question about remote branches.

[David Kastrup]

Jeff King <peff@peff.net> writes:

> On Sun, Aug 05, 2007 at 11:29:12AM +0200, David Kastrup wrote:
>
>> The main question is why I can't find this explained in this manner in
>> the documentation.  Are you going to put it in yourself, or should I
>> attempt doing it?
>
> I guess because nobody complained it wasn't there before. :) Some of the
> information is a bit under-the-hood for most end-users, but obviously in
> your case the lack of information was creating confusion about the
> terms.
>
> Why don't you take a stab at updating the documentation (since you are
> the one who knows which parts were confusing you),

Well, one problem is that there simply _is_ no part of the
documentation where such an explanation would have a place.  It does
not fit in the man pages of git-branch/git-commit, it has some passing
relation to the repository layout explanation (even though the latter
should not be something that the user has to read and understand for
basic operation), it may have some place in the user manual, but may
be a bit technical/long for that.  Or one places it into another
isolated file and hopes that a user will stumble across it when in
need of the information.

Hm.  Probably the usermanual is the best option in the current scheme
of things.

> and I will be more than happy to help with making sure the changes
> are accurate.

Thanks.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Jeff King]

On Sun, Aug 05, 2007 at 11:44:12AM +0200, David Kastrup wrote:

> Well, one problem is that there simply _is_ no part of the
> documentation where such an explanation would have a place.  It does
> [...]
> Hm.  Probably the usermanual is the best option in the current scheme
> of things.

I'm not too familiar with the usermanual, it having come about long
after I started with git. But I wonder if a subsection on "refs" under
the "Git internals" section might make sense.

-Peff

Re: Terminology question about remote branches.

[Jakub Narebski]

[Cc: David Kastrup <dak@gnu.org>, git@vger.kernel.org]

David Kastrup wrote:

> The way to add a remote branch basically is not via git-branch or
> git-checkout -b (those always create local branches), but by editing
> .git/config.

Or by using "git remote" command.

-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: Terminology question about remote branches.

[Sean]

On Sat, 04 Aug 2007 12:55:43 +0200
David Kastrup <dak@gnu.org> wrote:

> I am trying to dig through man-pages and user manual and trying to
> match them with reality.  I seem to have a hard time.  My current
> understanding (which definitely differs from the documented state) is
> that there are two types of branches, local and remote branches, and
> both types of branches can be remote-tracking (it may not be possible
> to have a non-remote-tracking remote branch, though).
>
> A local branch is one with a local branch head.  In contrast, checking
> out a remote branch, while possible, leaves one with a detached head.

Yes.

> "remote-tracking" basically means that git-pull will update the branch
> according to changes in the remote repository.

To be clear, it's the job of git-fetch to update remote-tracking branches
with any changes found in the remote repository.  Git-pull runs git-fetch
and then runs a git-merge to update the currently-checked-out branch.

When this happens, git-merge must decide which remote-tracking-branch
to merge into the currently checked out local branch.  You can set which
remote-tracking-branch will be selected in this situation with
the --track option.

So assuming a remote-repo has two branches "master" and "branchX":

   git clone remote-repo

will give us two remote-branch (AKA remote-tracking-branches) of
"origin/master" and "origin/branchX".  So:

   git branch --track mylocalbranch origin/branchX
   git checkout mylocalbranch

Creates a local branch named "mylocalbranch" that by default will
merge in any changes found in the remote-tracking branch
"origin/branchX".  Thus:

   git pull

First runs git fetch which will update all remote-tracking branches
such as origin/master and origin/branchX.  Then it runs git merge.
Git merge has to decide whether to merge in the changes from
origin/master or origin/branchX.  Because of the --track option used
to setup "mylocalbranch",  "origin/branchX" will be merged.

> Creating a branch using git-branch or git-checkout will always create
> a local branch which may or may not be remote-tracking according to
> the --no-track or --track options.

No, a local branch is never a remote-tracking branch; even when created
with a --track option.  The --track option has muddied the terminology
waters a bit and you're not the first to be confused by it.  The
--track selects a branch from the repo to merge by default.

> So there are basically three types of branches in a repository that I
> can see:
> 
> local branch, not remote-tracking
> local branch, remote-tracking
> remote branch, remote-tracking
> 
> The way to add a remote branch basically is not via git-branch or
> git-checkout -b (those always create local branches), but by editing
> .git/config.
> 
> Is this understanding correct or did I get things completely wrong?
> Because there is little sense in myself working on changing the
> documentation if I have not understood the situation.

Functionally, your understanding is correct.  But it helps when you
understand that remote-branches are the "real" remote-tracking-branches.
You don't commit to them locally, they are essentially read-only copies
of exactly what is happening in a remote repository.

A local --track branch, is one that merges changes from the proper
remote-tracking-branch, and is also a place where you can commit your
own work.

> Also, the documentation currently uses "remote-tracking"
> interchangeably for "local branch, remote-tracking" and "remote
> branch, remote-tracking", at some times claiming that one can locally
> switch to a "remote-tracking" branch, at other times not.

A remote branch and a remote-tracking branch are the same thing.
Strictly speaking a local branch is never a remote-tracking-branch
although the "--track" option makes that harder to explain.

> So the terminology seems fuzzy at the moment, and my attempt to clear
> it up might not be the preferred way of doing it.

Yeah, the documentation could use some fine tuning.

Sean

Re: Terminology question about remote branches.

[David Kastrup]

Sean <seanlkml@sympatico.ca> writes:

> David Kastrup <dak@gnu.org> wrote:
>
>> A local branch is one with a local branch head.  In contrast,
>> checking out a remote branch, while possible, leaves one with a
>> detached head.
>
> Yes.
>
>> "remote-tracking" basically means that git-pull will update the
>> branch according to changes in the remote repository.
>
> To be clear, it's the job of git-fetch to update remote-tracking
> branches with any changes found in the remote repository.  Git-pull
> runs git-fetch and then runs a git-merge to update the
> currently-checked-out branch.
>
> When this happens, git-merge must decide which
> remote-tracking-branch to merge into the currently checked out local
> branch.  You can set which remote-tracking-branch will be selected
> in this situation with the --track option.
>
> So assuming a remote-repo has two branches "master" and "branchX":
>
>    git clone remote-repo
>
> will give us two remote-branch (AKA remote-tracking-branches) of
> "origin/master" and "origin/branchX".  So:
>
>    git branch --track mylocalbranch origin/branchX
>    git checkout mylocalbranch

So --track does not set up a tracking branch, but makes a local
_following_ branch _refer_ to a tracking branch.

What happens with

    git checkout origin/branchX
    git branch --track mylocalbranch
    git checkout mylocalbranch

?  What if after the checkout (which leads to a detached head) I check
in a few things, and then decide to name the branch and set it up as
following a remote tracking branch?  Instead of using git-branch for
setting up the following, do I have to explicitly add the respective
"remote" line (which does not specify a remote, but a remote tracking
branch) into, uh, where?

> No, a local branch is never a remote-tracking branch; even when
> created with a --track option.  The --track option has muddied the
> terminology waters a bit and you're not the first to be confused by
> it.  The --track selects a branch from the repo to merge by default.

Well, GOOD.  I have already come to the conclusion that the "--track"
option, like the "remote" configuration recorded by it have the main
purpose of confusing people and should not be confused with setting up
a remote tracking branch, or referring to a remote branch.

> A remote branch and a remote-tracking branch are the same thing.
> Strictly speaking a local branch is never a remote-tracking-branch
> although the "--track" option makes that harder to explain.

You bet.

>> So the terminology seems fuzzy at the moment, and my attempt to
>> clear it up might not be the preferred way of doing it.
>
> Yeah, the documentation could use some fine tuning.

It is much too fine-tuned already.  I think that first option names
and config file options need to get some coarse-tuning where one does
not have to split hairs and ignore the meaning of terms in order to
understand them.

I have now "following" or "automerge" local branches which are set up
to follow a "remote tracking" branch.  Presumably, if I do

git-branch -b new-branch --track remote-branch

then I get a following branch set up which follows/automerges a remote
tracking branch.  So far so good.  What do I get with

git-branch -b another-new-branch --track new-branch

Does this follow/automerges with new-branch?  Does this
follow/automerge with remote-branch?

What if I do

git-checkout remote-branch
git-branch -b new-branch --track

Does this follow anything?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Sean]

On Sat, 04 Aug 2007 16:01:55 +0200
David Kastrup <dak@gnu.org> wrote:

> So --track does not set up a tracking branch, but makes a local
> _following_ branch _refer_ to a tracking branch.

Sure, that's one way to describe it; perhaps it would be best if
we switched to that nomenclature in the documentation.

> What happens with
> 
>     git checkout origin/branchX
>     git branch --track mylocalbranch
>     git checkout mylocalbranch

This is easy to test, and the answer is that no tracking is set up.
You must supply the remote-tracking-branch on the command line with
the --track option to git branch.  Actually I realized that with a
new enough version of Git, --track is implied.

> ?  What if after the checkout (which leads to a detached head) I check
> in a few things, and then decide to name the branch and set it up as
> following a remote tracking branch?  Instead of using git-branch for
> setting up the following, do I have to explicitly add the respective
> "remote" line (which does not specify a remote, but a remote tracking
> branch) into, uh, where?

It's not a problem, you could just add an appropriate [branch...] section
in your .git/config.   Actually looking at a typical branch section
is even more confusing to me:

    $ git branch fudge origin/fix1

adds this to the .git/config:

    [branch "fudge"]
        remote = origin
        merge = refs/heads/fix1

The config file does not record the remote-tracking-branch, instead
it explicitly records the remote repository information.  So it sure
appears that if you add the --track option, it _does_ make the local
branch track a remote directly.  Thus it's hard to call it anything
but what you labelled it,  a local tracking-branch.

While I thought i had a handle on this, i'm now officially more
confused than you; hopefully someone with knowledge of the guts
of Git will speak up.   Junio Help!

Sean

Re: Terminology question about remote branches.

[David Kastrup]

Sean <seanlkml@sympatico.ca> writes:

> On Sat, 04 Aug 2007 16:01:55 +0200
> David Kastrup <dak@gnu.org> wrote:
>
>> So --track does not set up a tracking branch, but makes a local
>> _following_ branch _refer_ to a tracking branch.
>
> Sure, that's one way to describe it; perhaps it would be best if
> we switched to that nomenclature in the documentation.

Not according to my current understanding, but that can, of course,
change again in the next few hours.  As far as I understand right now,
such a branch indeed tracks a remote branch (and not a remote tracking
branch), it just does not track it recklessly: it has a head of its
own, and it won't use git-fetch -f for updating it.

> It's not a problem, you could just add an appropriate [branch...] section
> in your .git/config.   Actually looking at a typical branch section
> is even more confusing to me:
>
>     $ git branch fudge origin/fix1
>
> adds this to the .git/config:
>
>     [branch "fudge"]
>         remote = origin
>         merge = refs/heads/fix1
>
> The config file does not record the remote-tracking-branch, instead
> it explicitly records the remote repository information.  So it sure
> appears that if you add the --track option, it _does_ make the local
> branch track a remote directly.  Thus it's hard to call it anything
> but what you labelled it, a local tracking-branch.

Yes, it seems --track does track after all.  Just more cautiously than
a remote tracking branch does.

> While I thought i had a handle on this, i'm now officially more
> confused than you;

Good.  It means that I may not be a complete idiot.  It may also mean
that the documentation can be improved in places.  With a lot of
"grep" and fine-combing I realized that quite a bit of the information
_is_ "available" (and some conflicting information as well).

This is one reason why I would prefer to have something like a typical
Texinfo manual, at least on the organisational level: a manual is
supposed to present a single connected view to the available
documentation.  And the information for git is scattered through a
bunch of mostly disconnected files.

If you want to see a more staggering example of this approach, take a
look at the "guilt" documentation.  It consists only of the man pages
for the individual commands, and then some few README-like files which
mostly say something like "guilt is just like quilt, or like
Mercurial's patch sets".  That's rather extreme as far as
user-accessible information goes.  git has a few more generally useful
files explaining underlying concepts, but they still are basically
thrown into one large self-service heap, not a coherent document.

> hopefully someone with knowledge of the guts of Git will speak up.

I think I am slowly getting it, thanks to Lars and others.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Jeff King]

On Sat, Aug 04, 2007 at 10:48:51AM -0400, Sean wrote:

> The config file does not record the remote-tracking-branch, instead
> it explicitly records the remote repository information.  So it sure
> appears that if you add the --track option, it _does_ make the local
> branch track a remote directly.  Thus it's hard to call it anything
> but what you labelled it,  a local tracking-branch.
> 
> While I thought i had a handle on this, i'm now officially more
> confused than you; hopefully someone with knowledge of the guts
> of Git will speak up.   Junio Help!

There is some discussion in this thread:

http://thread.gmane.org/gmane.comp.version-control.git/35090/focus=35265

-Peff

Re: Terminology question about remote branches.

[Jeff King]

On Sat, Aug 04, 2007 at 04:01:55PM +0200, David Kastrup wrote:

> So --track does not set up a tracking branch, but makes a local
> _following_ branch _refer_ to a tracking branch.

A minor nit, but --track sets up a local following branch to refer to a
remote's branch, _not_ to the tracking branch. In other words, if you
look at the config:

  [branch "master"]
    remote = origin
    merge = refs/heads/master

It does _not_ reference the tracking branch
"refs/remotes/origin/master", but rather the remote's name for the
branch "refs/heads/master".

There was much discussion of this topic, but the general idea was not to
require remote tracking branches for this feature to be used (a position
I somewhat disagree with, but then I'm not the maintainer).

-Peff

Re: Terminology question about remote branches.

[Steffen Prohaska]

On Aug 5, 2007, at 12:05 PM, Jeff King wrote:

> On Sat, Aug 04, 2007 at 04:01:55PM +0200, David Kastrup wrote:
>
>> So --track does not set up a tracking branch, but makes a local
>> _following_ branch _refer_ to a tracking branch.
>
> A minor nit, but --track sets up a local following branch to refer  
> to a
> remote's branch, _not_ to the tracking branch. In other words, if you
> look at the config:
>
>   [branch "master"]
>     remote = origin
>     merge = refs/heads/master
>
> It does _not_ reference the tracking branch
> "refs/remotes/origin/master", but rather the remote's name for the
> branch "refs/heads/master".
>
> There was much discussion of this topic, but the general idea was  
> not to
> require remote tracking branches for this feature to be used (a  
> position
> I somewhat disagree with, but then I'm not the maintainer).

Interesting. I didn't even recognize this detail up to know. It was  
somewhat
beyond my imagination that I could have a local following/automerging
branch that is directly referring to a branch in a remote repo, without
have a remote-tracking branch.

How could I create such a setup in the first place?

     git branch --track something origin/something
     git checkout --track -b something origin/something

are obvious, but what to say if I don't have origin/something?

	Steffen

Re: Terminology question about remote branches.

[Jeff King]

On Sun, Aug 05, 2007 at 12:56:49PM +0200, Steffen Prohaska wrote:

> beyond my imagination that I could have a local following/automerging
> branch that is directly referring to a branch in a remote repo, without
> have a remote-tracking branch.
>
> How could I create such a setup in the first place?
>
>     git branch --track something origin/something
>     git checkout --track -b something origin/something
>
> are obvious, but what to say if I don't have origin/something?

I believe the --track setup uses the tracking branches to figure out
which remote/branch combo to track. To do it without a remote tracking
branch, you would have to add the lines to your .git/config manually.

-Peff

Re: Terminology question about remote branches.

[David Kastrup]

Jeff King <peff@peff.net> writes:

> On Sun, Aug 05, 2007 at 12:56:49PM +0200, Steffen Prohaska wrote:
>
>> beyond my imagination that I could have a local following/automerging
>> branch that is directly referring to a branch in a remote repo, without
>> have a remote-tracking branch.
>>
>> How could I create such a setup in the first place?
>>
>>     git branch --track something origin/something
>>     git checkout --track -b something origin/something
>>
>> are obvious, but what to say if I don't have origin/something?
>
> I believe the --track setup uses the tracking branches to figure out
> which remote/branch combo to track. To do it without a remote tracking
> branch, you would have to add the lines to your .git/config manually.

Fascinating, really fascinating.  Is there actually _anybody_ who
would not revert to phrases like "I believe" when describing git's
interaction with remote branches?

I don't find this particularly logical: origin/something basically
boils down referring to a commit.

Maybe git-branch --track should allow referring to remote:branch or
URLs or something directly rather than a remote tracking branch?

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Jeff King]

On Sun, Aug 05, 2007 at 01:38:07PM +0200, David Kastrup wrote:

> > I believe the --track setup uses the tracking branches to figure out
> > which remote/branch combo to track. To do it without a remote tracking
> > branch, you would have to add the lines to your .git/config manually.
> 
> Fascinating, really fascinating.  Is there actually _anybody_ who
> would not revert to phrases like "I believe" when describing git's
> interaction with remote branches?

By "I believe", I meant "I am pretty sure this is the way it is
implemented, but I have better things to do than read through
builtin-branch.c right now, so please don't take this as gospel and go
read the code yourself."

But the point of --track is that I don't _have_ to care, and that it
deduces the correct remote/branch combination itself.

> I don't find this particularly logical: origin/something basically
> boils down referring to a commit.

Really, "origin/something" refers to "refs/remotes/origin/something",
which we can deduce from the config to be populated by a particular
remote and branch (go read the code).

> Maybe git-branch --track should allow referring to remote:branch or
> URLs or something directly rather than a remote tracking branch?

It could, but at that point, you could just do:

  git-branch newbranch oldbranch
  git-config branch.newbranch.remote someremote
  git-config branch.newbranch.merge remotebranch

Perhaps it's slightly more convenient to be able to do

  git-branch --track someremote:remotebranch newbranch oldbranch

but the real convenience of --track is when it deduces those parameters
itself.

-Peff

Re: Terminology question about remote branches.

[David Kastrup]

Jeff King <peff@peff.net> writes:

> On Sun, Aug 05, 2007 at 01:38:07PM +0200, David Kastrup wrote:
>
>> > I believe the --track setup uses the tracking branches to figure out
>> > which remote/branch combo to track. To do it without a remote tracking
>> > branch, you would have to add the lines to your .git/config manually.
>> 
>> Fascinating, really fascinating.  Is there actually _anybody_ who
>> would not revert to phrases like "I believe" when describing git's
>> interaction with remote branches?
>
> By "I believe", I meant "I am pretty sure this is the way it is
> implemented, but I have better things to do than read through
> builtin-branch.c right now, so please don't take this as gospel and go
> read the code yourself."

Well, that is pretty much exactly what I find fascinating: that the
behavior is arbitrary and undocumented enough that one can't deduce it
either by logic or by recollection or by documentation, but just by
reading the code.

Usually code is supposed to implement a design, but here it seems
rather like the design, if there is any, is to be abstracted from the
code.

Maybe I get fascinated too easily.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Jeff King]

On Sun, Aug 05, 2007 at 02:12:04PM +0200, David Kastrup wrote:

> Well, that is pretty much exactly what I find fascinating: that the
> behavior is arbitrary and undocumented enough that one can't deduce it
> either by logic or by recollection or by documentation, but just by
> reading the code.

I see your point, but I think you are reading too much into my words. I
am 99% sure that is the way it works (because it would make no sense to
work any other way, and that is my mental model of how it works), but I
am very hesitant to state something outright which I haven't
double-checked in the code. Thus I used weak language.

-Peff

Re: Terminology question about remote branches.

[Theodore Tso]

On Sun, Aug 05, 2007 at 02:12:04PM +0200, David Kastrup wrote:
> Well, that is pretty much exactly what I find fascinating: that the
> behavior is arbitrary and undocumented enough that one can't deduce it
> either by logic or by recollection or by documentation, but just by
> reading the code.

The behavior of how references work and how the config file parameters
under remote.* and branch.* are pretty well understood, and the
conceptual model is pretty simple; see Jeff's message.  And most of it
*is* documented if you look at the git-fetch, git-pull, git-config man
pages --- just not systematically in one place.

What's not so well understood I suspect by most people is how the "git
branch" tool edits the config file.  It was added later, and many of
the git hackers who already know the conceptual model and who are used
to editing .git/config directly to get what they want, don't use git
branch much themselves; that's really for more novice users and more
simpler config files.

To use a GNU emacs example, consider M-x customize, which is this
huge, very fancy, *very* complex hierarchical mechanism with a
pointy-clicky interface for setting options.  Most emacs experts
wouldn't use it, preferring to open code raw emacs-lisp settings in
their .emacs.el.  If you ask an old-time emacs user how to set up some
specific feature setting via M-x customize, they might look at you
blankly, because it's not an interface they use much, if at all.

A similar thing can be said of "git branch"; once you are familiar
with how git works at a conceptual level, it can often be
faster/easier to just hack the .git/config file directly, instead of
using "git branch" to set up things the way you want.  And I'm pretty
sure there are ways to set up the config file when you edit it by hand
that you can't set up via "git branch".

						- Ted

Re: Terminology question about remote branches.

[David Kastrup]

Theodore Tso <tytso@mit.edu> writes:

> To use a GNU emacs example, consider M-x customize, which is this
> huge, very fancy, *very* complex hierarchical mechanism with a
> pointy-clicky interface for setting options.  Most emacs experts
> wouldn't use it, preferring to open code raw emacs-lisp settings in
> their .emacs.el.  If you ask an old-time emacs user how to set up
> some specific feature setting via M-x customize, they might look at
> you blankly, because it's not an interface they use much, if at all.

Well, let me throw you back one of your questions: do you have any
statistics backing this up?

As to anecdotal evidence: I am an old-time Emacs user, and I pretty
much use customize _exclusively_ since it generally leaves me with a
_working_ configuration even when the DOC string might be sub-optimal
or misleading or hard to understand, and it makes sure that, say,
everything to make a global minor mode _active_ (like loading some
file, or calling some initialization functions) is done at the right
point of time.

If "old-time Emacs users" would not use customize, why would pretty
much _every_ package come with _working_ defcustoms?  Who writes and
_tests_ those defcustoms if not the "old-time Emacs users"?

> A similar thing can be said of "git branch"; once you are familiar
> with how git works at a conceptual level, it can often be
> faster/easier to just hack the .git/config file directly, instead of
> using "git branch" to set up things the way you want.  And I'm
> pretty sure there are ways to set up the config file when you edit
> it by hand that you can't set up via "git branch".

Sure.  But we don't want to _require_ this sort of special knowledge
before one can even hope to do some basic task.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Randal L. Schwartz]

>>>>> "Theodore" == Theodore Tso <tytso@mit.edu> writes:

Theodore> To use a GNU emacs example, consider M-x customize, which is this
Theodore> huge, very fancy, *very* complex hierarchical mechanism with a
Theodore> pointy-clicky interface for setting options.  Most emacs experts
Theodore> wouldn't use it, preferring to open code raw emacs-lisp settings in
Theodore> their .emacs.el.  If you ask an old-time emacs user how to set up
Theodore> some specific feature setting via M-x customize, they might look at
Theodore> you blankly, because it's not an interface they use much, if at all.

I beg to differ.  I *am* an old-time Emacs user, and I resisted customize when
it first appeared, because *most* of the things still didn't use it.  However,
as of a year ago, I assessed that customize had gotten to "critical mass", and
that 75% of my .emacs could be replaced by it.  So I have, and it's made
things simpler for me.

So, it just has to be complete enough and flexible enough.

-- 
Randal L. Schwartz - Stonehenge Consulting Services, Inc. - +1 503 777 0095
<merlyn@stonehenge.com> <URL:http://www.stonehenge.com/merlyn/>
Perl/Unix/security consulting, Technical writing, Comedy, etc. etc.
See PerlTraining.Stonehenge.com for onsite and open-enrollment Perl training!

Re: Terminology question about remote branches.

[Sean]

On Sun, 05 Aug 2007 14:12:04 +0200
David Kastrup <dak@gnu.org> wrote:

> Well, that is pretty much exactly what I find fascinating: that the
> behavior is arbitrary and undocumented enough that one can't deduce it
> either by logic or by recollection or by documentation, but just by
> reading the code.
> 
> Usually code is supposed to implement a design, but here it seems
> rather like the design, if there is any, is to be abstracted from the
> code.

To me it's yet another example of bad UI design in Git.   Git already
had remote-tracking branches, which conceptually were relatively easy
to explain.  Instead of leveraging this foundation, and adding the
ability for local branches to pick a default remote-tracking branch
to use for merging, Git instead implemented direct remote tracking
from local branches.  After having read the thread Jeff mentioned
earlier i'm still at a loss as to how this decision was justified.

To make it even worse, it turns out that this command:

   $ git branch --track  mybranch  remote/branch

Does _NOT_ tell git to setup mybranch to track remote/branch.  Read that
command line again and then scratch your head as to how anyone without
deep Git knowledge is supposed to infer its real meaning without being
told to read previous email threads etc.   This also means the feature
can't be used to say:

   $ git branch --track mybranch  otherlocalbranch

Being a fan of Git, it's frustrating to see that more weight is not
paid to such UI concerns.   Especially when the concern _was_ raised
when the feature was first added.

Sean

Re: Terminology question about remote branches.

[Jeff King]

On Sun, Aug 05, 2007 at 12:40:50PM -0400, Sean wrote:

> To me it's yet another example of bad UI design in Git.   Git already
> had remote-tracking branches, which conceptually were relatively easy
> to explain.  Instead of leveraging this foundation, and adding the
> ability for local branches to pick a default remote-tracking branch
> to use for merging, Git instead implemented direct remote tracking
> from local branches.  After having read the thread Jeff mentioned
> earlier i'm still at a loss as to how this decision was justified.

To be fair, the default remote-tracking branch stuff predates the thread
I pointed you to. But I do agree it makes the system that much more
confusing to have it this way.

There is a clash between users with different workflows here, I think.
For example, I almost _never_ run git-pull, but instead always fetch,
inspect, and then merge from a tracking branch. So I think of tracking
branches as a first-class item. But I suspect Linus doesn't use tracking
branches at all, since he pulls directly from a variety of different
repositories.

-Peff

Re: Terminology question about remote branches.

[Junio C Hamano]

David Kastrup <dak@gnu.org> writes:

> I am trying to dig through man-pages and user manual and trying to
> match them with reality.  I seem to have a hard time.  My current
> understanding (which definitely differs from the documented state) is
> that there are two types of branches, local and remote branches, and
> both types of branches can be remote-tracking (it may not be possible
> to have a non-remote-tracking remote branch, though).

I think we have a brief discussion on #git before you brought
this up ;-)

 - local branches -- we know what they are.

 - remote tracking branches -- refs that appear in refs/remotes/
   in the current world order; they are updated only by copying
   the corresponding local branches at the remote site, and are
   meant to "keep track of what _they_ are doing".  In olden
   days before 1.5.0 with non separate remote layout,
   'refs/heads/origin' branch, and all the non default branches,
   were treated this way as well.  You were not supposed to make
   commit on them (because of the above "keep track of" reason),
   and having them under refs/heads were too confusing, which
   was the reason the separate remote layout was invented.

You can have a local branch that is created by forking off of a
remote tracking branch, with the intention to "build on top" of
the corresponding remote tracking brach.  You can create such a
branch and mark it as such with --track option introduced in
v1.5.1 timeperiod.  This is a relatively new concept, but many
people find it useful.  We do not have the official term to call
this concept, and some people have misused the term "remote
tracking branches" to describe this, which made things very
confusing.

We would need an official terminology for it.

Re: Terminology question about remote branches.

[Steffen Prohaska]

On Aug 5, 2007, at 9:31 AM, Junio C Hamano wrote:

> David Kastrup <dak@gnu.org> writes:
>
>> I am trying to dig through man-pages and user manual and trying to
>> match them with reality.  I seem to have a hard time.  My current
>> understanding (which definitely differs from the documented state) is
>> that there are two types of branches, local and remote branches, and
>> both types of branches can be remote-tracking (it may not be possible
>> to have a non-remote-tracking remote branch, though).
>
> I think we have a brief discussion on #git before you brought
> this up ;-)
>
>  - local branches -- we know what they are.
>
>  - remote tracking branches -- refs that appear in refs/remotes/
>    in the current world order; they are updated only by copying
>    the corresponding local branches at the remote site, and are
>    meant to "keep track of what _they_ are doing".  In olden
>    days before 1.5.0 with non separate remote layout,
>    'refs/heads/origin' branch, and all the non default branches,
>    were treated this way as well.  You were not supposed to make
>    commit on them (because of the above "keep track of" reason),
>    and having them under refs/heads were too confusing, which
>    was the reason the separate remote layout was invented.

The current user manual defines this case in the glossary as
'tracking branch' (without remote), but mostly uses
'remote-tracking branch' at other places. Tracking branch
and remote-tracking branch seem to be equivalent. And I think
we should leave it this way.


> You can have a local branch that is created by forking off of a
> remote tracking branch, with the intention to "build on top" of
> the corresponding remote tracking brach.  You can create such a
> branch and mark it as such with --track option introduced in
> v1.5.1 timeperiod.  This is a relatively new concept, but many
> people find it useful.  We do not have the official term to call
> this concept, and some people have misused the term "remote
> tracking branches" to describe this, which made things very
> confusing.
>
> We would need an official terminology for it.

Something like 'automerging branch', and replace options with
'--automerge/--no-automerge'?

I'm not fully convinced of this idea because it may be
technically correct but doesn't really reflect the intention of
'building on top' of the remote tracking branch.

	Steffen

Re: Terminology question about remote branches.

[Julian Phillips]

On Sun, 5 Aug 2007, Junio C Hamano wrote:

> David Kastrup <dak@gnu.org> writes:
>
>> I am trying to dig through man-pages and user manual and trying to
>> match them with reality.  I seem to have a hard time.  My current
>> understanding (which definitely differs from the documented state) is
>> that there are two types of branches, local and remote branches, and
>> both types of branches can be remote-tracking (it may not be possible
>> to have a non-remote-tracking remote branch, though).
>
> I think we have a brief discussion on #git before you brought
> this up ;-)
>
> - local branches -- we know what they are.
>
> - remote tracking branches -- refs that appear in refs/remotes/
>   in the current world order; they are updated only by copying
>   the corresponding local branches at the remote site, and are
>   meant to "keep track of what _they_ are doing".  In olden
>   days before 1.5.0 with non separate remote layout,
>   'refs/heads/origin' branch, and all the non default branches,
>   were treated this way as well.  You were not supposed to make
>   commit on them (because of the above "keep track of" reason),
>   and having them under refs/heads were too confusing, which
>   was the reason the separate remote layout was invented.
>
> You can have a local branch that is created by forking off of a
> remote tracking branch, with the intention to "build on top" of
> the corresponding remote tracking brach.  You can create such a
> branch and mark it as such with --track option introduced in
> v1.5.1 timeperiod.  This is a relatively new concept, but many
> people find it useful.  We do not have the official term to call
> this concept, and some people have misused the term "remote
> tracking branches" to describe this, which made things very
> confusing.
>
> We would need an official terminology for it.

Following was mentioned earlier in this thread ... could we use that?

tracking branch:
   ref always points at a commit from the remote repo branch

following branch:
   ref either points at a commit from the remote repo branch, or a
   local commit with a commit from the remote repo branch in the history

perhaps?

-- 
Julian

  ---
An optimist is a man who looks forward to marriage.
A pessimist is a married optimist.

Re: Terminology question about remote branches.

[David Kastrup]

Julian Phillips <julian@quantumfyre.co.uk> writes:

> On Sun, 5 Aug 2007, Junio C Hamano wrote:
>>
>> I think we have a brief discussion on #git before you brought
>> this up ;-)
>>
>> - local branches -- we know what they are.
>>
>> - remote tracking branches -- refs that appear in refs/remotes/
>>   in the current world order; they are updated only by copying
>>   the corresponding local branches at the remote site, and are
>>   meant to "keep track of what _they_ are doing".  In olden
>>   days before 1.5.0 with non separate remote layout,
>>   'refs/heads/origin' branch, and all the non default branches,
>>   were treated this way as well.  You were not supposed to make
>>   commit on them (because of the above "keep track of" reason),
>>   and having them under refs/heads were too confusing, which
>>   was the reason the separate remote layout was invented.
>>
>> You can have a local branch that is created by forking off of a
>> remote tracking branch, with the intention to "build on top" of
>> the corresponding remote tracking brach.  You can create such a
>> branch and mark it as such with --track option introduced in
>> v1.5.1 timeperiod.  This is a relatively new concept, but many
>> people find it useful.  We do not have the official term to call
>> this concept, and some people have misused the term "remote
>> tracking branches" to describe this, which made things very
>> confusing.
>>
>> We would need an official terminology for it.
>
> Following was mentioned earlier in this thread ... could we use that?
>
> tracking branch:
>   ref always points at a commit from the remote repo branch
>
> following branch:
>   ref either points at a commit from the remote repo branch, or a
>   local commit with a commit from the remote repo branch in the history
>
> perhaps?

An auto-merging branch?  The term is somewhat more technical so that
people are less likely to think it just a colloquial alternative
expression for "tracking".

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Terminology question about remote branches.

[Julian Phillips]

On Sun, 5 Aug 2007, David Kastrup wrote:

> Julian Phillips <julian@quantumfyre.co.uk> writes:
>
>> On Sun, 5 Aug 2007, Junio C Hamano wrote:
>>> We would need an official terminology for it.
>>
>> Following was mentioned earlier in this thread ... could we use that?
>>
>> tracking branch:
>>   ref always points at a commit from the remote repo branch
>>
>> following branch:
>>   ref either points at a commit from the remote repo branch, or a
>>   local commit with a commit from the remote repo branch in the history
>>
>> perhaps?
>
> An auto-merging branch?  The term is somewhat more technical so that
> people are less likely to think it just a colloquial alternative
> expression for "tracking".

Personally I don't like auto-merging as it doesn't have any connotations 
of _what_ is auto-merged ... and it's not really an automatic merge 
anyway, you have to ask for it (by running pull).

-- 
Julian

  ---
Don't look back, the lemmings are gaining on you.