setting up tracking on push

setting up tracking on push

[Miles Bader]

[...sorry if this is a dup -- my previous attempt didn't seem to take...]

Is there an "easy" way to set up tracking for a branch which starts out
locally, and is eventually pushed to a remote?

E.g., I create a new local branch "grognul", and then later propagate it
to my remote site using:

  git push origin grognul

That works great (creating origin/grognul), but to set up tracking, I
currently edit .git/config (not insanely difficult, but vaguely
annoying).  This is as opposed to a branch which starts out remotely,
and is pulled, where one can just use "git branch --track" or "git
checkout --track" (or use a config option to do so by default).

I vaguely feel like I should be able to do:

  git push --track origin grognul

[I do this particular action -- creating a branch locally and then
pushing it to origin -- very very often, thus my desire for a handy
option.]

What do other people think?

-miles

--
Inhumanity, n. One of the signal and characteristic qualities of humanity.

Re: setting up tracking on push

[John Tapsell]

2009/3/6 Miles Bader <miles@gnu.org>:
> [...sorry if this is a dup -- my previous attempt didn't seem to take...]
>
> Is there an "easy" way to set up tracking for a branch which starts out
> locally, and is eventually pushed to a remote?
>
> E.g., I create a new local branch "grognul", and then later propagate it
> to my remote site using:
>
>  git push origin grognul
>
> That works great (creating origin/grognul), but to set up tracking, I
> currently edit .git/config (not insanely difficult, but vaguely
> annoying).  This is as opposed to a branch which starts out remotely,
> and is pulled, where one can just use "git branch --track" or "git
> checkout --track" (or use a config option to do so by default).
>
> I vaguely feel like I should be able to do:
>
>  git push --track origin grognul
>
> [I do this particular action -- creating a branch locally and then
> pushing it to origin -- very very often, thus my desire for a handy
> option.]
>
> What do other people think?

I got bitten by this too, and there's no clue given how to set up the
tracking.  I'd like it to even ask the user when pushing:

$ git push origin grognul
Pushing blah blah...
 Do you want to track this? [Y/N/?]

:-)

John

>
> -miles
>
> --
> Inhumanity, n. One of the signal and characteristic qualities of humanity.
> --
> To unsubscribe from this list: send the line "unsubscribe git" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html
>

Re: setting up tracking on push

[Jay Soffian]

On Thu, Mar 5, 2009 at 10:07 PM, Miles Bader <miles@gnu.org> wrote:
> I vaguely feel like I should be able to do:
>
>  git push --track origin grognul

Hmm, I vaguely remember seeing a patch come across the list to do this.

j.

Re: setting up tracking on push

[Johannes Schindelin]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 457 bytes --]

Hi,

On Thu, 5 Mar 2009, Jay Soffian wrote:

> On Thu, Mar 5, 2009 at 10:07 PM, Miles Bader <miles@gnu.org> wrote:
> > I vaguely feel like I should be able to do:
> >
> >  git push --track origin grognul
> 
> Hmm, I vaguely remember seeing a patch come across the list to do this.

Indeed.

http://search.gmane.org/?query=push+track&group=gmane.comp.version-control.git

Summary for the lazy: it needs a lot of work to be implemented properly.

Hth,
Dscho

Re: setting up tracking on push

[Miles Bader]

Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
>> > I vaguely feel like I should be able to do:
>> >
>> >  git push --track origin grognul
>
> http://search.gmane.org/?query=push+track&group=gmane.comp.version-control.git
>
> Summary for the lazy: it needs a lot of work to be implemented properly.

Alternatively, maybe a "git track [REMOTE [BRANCH]]" command that simply
adds makes adding the appropriate config magic more convenient ?

I dunno what the arg syntax would look like in the general case;
I almost always want to use the current branch, and track an identically
named branch in the origin remote though...

-Miles

-- 
Custard, n. A vile concoction produced by a malevolent conspiracy of the hen,
the cow, and the cook.

Re: setting up tracking on push

[Jeremy O'Brien]

Miles Bader <miles@gnu.org> wrote:

> Johannes Schindelin <Johannes.Schindelin@gmx.de> writes:
> >> > I vaguely feel like I should be able to do:
> >> >
> >> >  git push --track origin grognul
> >
> > http://search.gmane.org/?query=push+track&group=gmane.comp.version-control.git
> >
> > Summary for the lazy: it needs a lot of work to be implemented properly.
>
> Alternatively, maybe a "git track [REMOTE [BRANCH]]" command that simply
> adds makes adding the appropriate config magic more convenient ?
>
> I dunno what the arg syntax would look like in the general case;
> I almost always want to use the current branch, and track an identically
> named branch in the origin remote though...
>
> -Miles

I definitely second this approach. It would be very useful.

Re: setting up tracking on push

[Jay Soffian]

On Fri, Mar 6, 2009 at 9:15 AM, Jeremy O'Brien <obrien654j@gmail.com> wrote:
> Miles Bader <miles@gnu.org> wrote:
>
>> Alternatively, maybe a "git track [REMOTE [BRANCH]]" command that simply
>> adds makes adding the appropriate config magic more convenient ?
>>
>> I dunno what the arg syntax would look like in the general case;
>> I almost always want to use the current branch, and track an identically
>> named branch in the origin remote though...

I don't think we need a new command, but it would probably fit into git remote

$ git remote track <remote> [<branch>]

j.

Re: setting up tracking on push

[Miles Bader]

Jay Soffian <jaysoffian@gmail.com> writes:
> I don't think we need a new command, but it would probably fit into
> git remote
>
> $ git remote track <remote> [<branch>]

That seems a bit backwards -- it's more of a branch operation than a
remote operation...

-Miles

-- 
Mayonnaise, n. One of the sauces that serve the French in place of a state
religion.

Re: setting up tracking on push

[Marc Branchaud]

Miles Bader wrote:
> Jay Soffian <jaysoffian@gmail.com> writes:
>> I don't think we need a new command, but it would probably fit into
>> git remote
>>
>> $ git remote track <remote> [<branch>]
> 
> That seems a bit backwards -- it's more of a branch operation than a
> remote operation...

Agreed.

We just ran into this situation today with pull: Someone wanted one of their local branches to start tracking a remote.

It would be good if the branch command allowed modification of a branch's properties.  At the very least, branch-creation commands like "git branch --track foobranch origin/master" could offer to modify if the branch already exists, instead of just quitting.

BTW, I think the following (untested) incantation adds tracking to a branch:

	git config branch.foobranch.remote origin
	git config branch.foobranch.merge refs/heads/master

(Substitute "origin" and "master" to suit your needs.)

		M.

Re: setting up tracking on push

[Jeff King]

On Tue, Mar 10, 2009 at 04:26:03PM -0400, Marc Branchaud wrote:

> It would be good if the branch command allowed modification of a
> branch's properties.  At the very least, branch-creation commands like
> "git branch --track foobranch origin/master" could offer to modify if
> the branch already exists, instead of just quitting.

I agree that it would be nice if an interface could be made around
"branch --track". However, the problem with

  git branch --track foobranch origin/master

is that it does two things: it sets up tracking, and it resets the
foobranch ref. Right now we complain if foobranch already exists. We
have a "-f" to override. But what you want to say is "set foobranch to
track origin/master, but _don't_ actually reset where it points". And I
don't see an intuitive way of doing that with that syntax. If you don't
require "-f", then you are silently ignoring half of what the user asked
you to do.

> BTW, I think the following (untested) incantation adds tracking to a branch:
>
> 	git config branch.foobranch.remote origin
> 	git config branch.foobranch.merge refs/heads/master

Yes, that is right. The only reason it is not a two-line script to
convert "git branch --track" into that is that you have to actually
resolve origin/master into "remote origin, branch refs/heads/master".

-Peff

Re: setting up tracking on push

[Jay Soffian]

On Tue, Mar 10, 2009 at 7:09 PM, Jeff King <peff@peff.net> wrote:
> On Tue, Mar 10, 2009 at 04:26:03PM -0400, Marc Branchaud wrote:
>
>> It would be good if the branch command allowed modification of a
>> branch's properties.  At the very least, branch-creation commands like
>> "git branch --track foobranch origin/master" could offer to modify if
>> the branch already exists, instead of just quitting.
>
> I agree that it would be nice if an interface could be made around
> "branch --track". However, the problem with
>
>  git branch --track foobranch origin/master
>
> is that it does two things: it sets up tracking, and it resets the
> foobranch ref. Right now we complain if foobranch already exists. We
> have a "-f" to override. But what you want to say is "set foobranch to
> track origin/master, but _don't_ actually reset where it points". And I
> don't see an intuitive way of doing that with that syntax. If you don't
> require "-f", then you are silently ignoring half of what the user asked
> you to do.

Maybe a new switch, say -u for update:

-u --track [<branch>] <upstream>

Update tracking information for an existing branch. <branch> is
optional and defaults to the current branch. <upstream> is the branch
you wish to track, e.g. origin/master; normally <upstream> is a remote
tracking branch, but specifying a local branch is valid as well.

-u --no-track [<branch>]

Remove tracking information for an existing branch. <branch> is
optional and defaults to the current branch.

j.

Re: setting up tracking on push

[Jeff King]

On Tue, Mar 10, 2009 at 09:52:44PM -0400, Jay Soffian wrote:

> Maybe a new switch, say -u for update:
> 
> -u --track [<branch>] <upstream>
> 
> Update tracking information for an existing branch. <branch> is
> optional and defaults to the current branch. <upstream> is the branch
> you wish to track, e.g. origin/master; normally <upstream> is a remote
> tracking branch, but specifying a local branch is valid as well.
> 
> -u --no-track [<branch>]
> 
> Remove tracking information for an existing branch. <branch> is
> optional and defaults to the current branch.

Hmm. This seems not quite right to me. Specifically:

  1. Would you ever want to use "-u" without "--track"? If so, then why
     are they two separate options?

  2. In your example, if I give only a single non-option argument, it is
     interpreted as the upstream (and presumably the branch defaults to
     HEAD).  But in other branch commands, it is interpreted as the
     branch, and the upstream defaults to HEAD.

For (1), you could just have a single option. Unfortunately --track is
taken. But maybe you could do --track=. And that helps with (2), as
well, since this syntax would only ever have one or zero arguments. And
then you can default zero to HEAD.

IOW:

  # track origin/master with the current branch
  git branch --track=origin/master

  # track origin/master with a different branch
  git branch --track=origin/master other_branch

  # stop tracking
  git branch --track=

The only two problems I can think of are:

  1. It is perhaps a little confusing that --track= means "don't do the
     normal branch operation, but instead do this totally different
     thing. Of course we already have a similar situation with "-m", but
     it is perhaps more confusing since "--track" and "--track=" have
     totally different semantics.

  2. This would be the only branch command to operate on HEAD if given
     no argument. That isn't necessary for this proposal, but I think it
     makes it nicer to use. An alternative would be for git-branch to
     resolve symrefs (which would also be nice for "git branch -m HEAD
     foo").

-Peff

Re: setting up tracking on push

[Jay Soffian]

On Tue, Mar 10, 2009 at 10:04 PM, Jeff King <peff@peff.net> wrote:
>
>> -u --track [<branch>] <upstream>
>
> Hmm. This seems not quite right to me. Specifically:
>
>  1. Would you ever want to use "-u" without "--track"? If so, then why
>     are they two separate options?

For when branch grows additional long options that update, er,
something else. :-)

And you can also use it with --no-track.

But the primary reason for the -u is to differentiate the operation,
just like -m and -d.

>  2. In your example, if I give only a single non-option argument, it is
>     interpreted as the upstream (and presumably the branch defaults to
>     HEAD).  But in other branch commands, it is interpreted as the
>     branch, and the upstream defaults to HEAD.

No, look at how -m works. [<oldbranch>] <newbranch>. I modeled it after that.

> For (1), you could just have a single option. Unfortunately --track is
> taken. But maybe you could do --track=. And that helps with (2), as
> well, since this syntax would only ever have one or zero arguments. And
> then you can default zero to HEAD.
>
> IOW:
>
>  # track origin/master with the current branch
>  git branch --track=origin/master
>
>  # track origin/master with a different branch
>  git branch --track=origin/master other_branch
>
>  # stop tracking
>  git branch --track=
>
> The only two problems I can think of are:
>
>  1. It is perhaps a little confusing that --track= means "don't do the
>     normal branch operation, but instead do this totally different
>     thing. Of course we already have a similar situation with "-m", but
>     it is perhaps more confusing since "--track" and "--track=" have
>     totally different semantics.
>
>  2. This would be the only branch command to operate on HEAD if given
>     no argument. That isn't necessary for this proposal, but I think it
>     makes it nicer to use. An alternative would be for git-branch to
>     resolve symrefs (which would also be nice for "git branch -m HEAD
>     foo").

Yeah, I like that less than -u, which I agree isn't perfect, but I
think it's closer.

j.

Re: setting up tracking on push

[Jeff King]

On Tue, Mar 10, 2009 at 10:59:01PM -0400, Jay Soffian wrote:

> But the primary reason for the -u is to differentiate the operation,
> just like -m and -d.

OK, that at least makes a bit of sense to me.

> >  2. In your example, if I give only a single non-option argument, it is
> >     interpreted as the upstream (and presumably the branch defaults to
> >     HEAD).  But in other branch commands, it is interpreted as the
> >     branch, and the upstream defaults to HEAD.
> 
> No, look at how -m works. [<oldbranch>] <newbranch>. I modeled it after that.

Hmm. I think of that as "make <newbranch>, move from <oldbranch> or
HEAD". Just as regular branch is "make <newbranch>, start from
<oldbranch> or HEAD". But your proposal is "update <newbranch> or HEAD,
from <oldbranch>".

If "-u" is supposed to be a general mode, then what does it mean to say:

  git branch -u foo

? I would expect that to "update" foo. But if --track is given, then it
means "update HEAD to track foo".

-Peff

Re: setting up tracking on push

[Jay Soffian]

On Tue, Mar 10, 2009 at 11:06 PM, Jeff King <peff@peff.net> wrote:
> If "-u" is supposed to be a general mode, then what does it mean to say:
>
>  git branch -u foo

Nothing, that would emit the usage message since it's not valid.

> ? I would expect that to "update" foo. But if --track is given, then it
> means "update HEAD to track foo".

Maybe branch isn't the best place to put this feature, but it's where
I'd look. I'm not married to -u, it was just the first thing that came
to mind. But I still can't think of anything better.

j.

Re: setting up tracking on push

[Jay Soffian]

On Tue, Mar 10, 2009 at 11:06 PM, Jeff King <peff@peff.net> wrote:
>> No, look at how -m works. [<oldbranch>] <newbranch>. I modeled it after that.
>
> Hmm. I think of that as "make <newbranch>, move from <oldbranch> or
> HEAD".

Um, I think of it as "rename <oldbranch> to <newbranch>" where
<oldbranch> defaults to the current branch (aka HEAD).

> Just as regular branch is "make <newbranch>, start from
> <oldbranch> or HEAD". But your proposal is "update <newbranch> or HEAD,
> from <oldbranch>".

Wait, what? No it isn't. My proposal is add or remove tracking
information to <branch> where <branch> defaults to the current branch
(aka HEAD).

-u w/o --track/--no-track is a usage error.

j.

Re: setting up tracking on push

[Jeff King]

On Tue, Mar 10, 2009 at 11:44:14PM -0400, Jay Soffian wrote:

> > Hmm. I think of that as "make <newbranch>, move from <oldbranch> or
> > HEAD".
> 
> Um, I think of it as "rename <oldbranch> to <newbranch>" where
> <oldbranch> defaults to the current branch (aka HEAD).

Perhaps it is because it was added onto "git branch" which already had
an existing syntax and meaning, but I have always seen it as "operating"
on the new branch.

There was some debate about this when "-m" came about (with respect to
the order of arguments).

So I think it is largely a matter of perception and mental model.

> -u w/o --track/--no-track is a usage error.

Then what is the point of "-u"? You said before that it was a new
operation with room for future growth of additional options. Either it
is _just_ for --track, in which case I think you are better to have a
single option representing the notion of "update the tracking setup", or
it isn't, in which case it needs to have room for future expansion.

-Peff

Re: setting up tracking on push

[Jay Soffian]

On Tue, Mar 10, 2009 at 11:57 PM, Jeff King <peff@peff.net> wrote:
>> -u w/o --track/--no-track is a usage error.
>
> Then what is the point of "-u"? You said before that it was a new
> operation with room for future growth of additional options. Either it
> is _just_ for --track, in which case I think you are better to have a
> single option representing the notion of "update the tracking setup", or
> it isn't, in which case it needs to have room for future expansion.

For *now*, it is just for --track/--no-track, since I can't think of
anything sensible that "-u" without --track nor --no-track would do.

So it means, update the branch config, but you have to tell it what
aspect of the branch config to update.

I agree that currently, a single option could do here, but I can't
think of a good one. --add-tracking and --delete-tracking? I was
trying to re-use the fact that we already have --track and --no-track,
but I needed some way to differentiate the mode from "create a new
branch". Hence -u.

j.

Re: setting up tracking on push

[Junio C Hamano]

Jeff King <peff@peff.net> writes:

>   # track origin/master with a different branch
>   git branch --track=origin/master other_branch

Isn't this one confusing with "git branch other_branch origin/master" (I
thought --track is the default these days)?

In any case, I find these "branch --retrack" proposals too confusing and
probably overengineered.

I need to ask a more fundamental question.  Is it really useful for people
to be able to re-track arbitrary remote/branch with an existing branch?

The only use case I've heard in this thread and nearby is where you are
the one who started the history of the branch, and pushed it into a public
repository as a new branch, making the result _the_ most authoritative
one.  After that, everybody else will be able to have a local branch that
tracks the authoritative one with "branch --track frotz origin/frotz", and
you will be the only one left unable to do so because you already have
that frotz branch.

And for that use case, I find it sensible if we had a way to easily say
"This branch hasn't been tracking anything so far (because it is the
originator of the history), but now it will give up its authority and
start tracking the one it is pushing into", and it would make sense to
somehow link that to the invocation of "git push".

    Side note.  I would also accept "It is only one person in the world,
    who can edit .git/config and be done with it; why bother complicate
    the UI for other people" as a valid argument against it, though ;-).

In that "my private branch gave autority to the branch at my public
repository" case, it is of course easy to re-clone (or "branch -m" away
and then re-fetch) like everybody else, but then you would lose the reflog
from the time before the branch went public, so it is not a solution but a
poor workaround.

I somehow think it would not make any sense to say "This branch used to
track that branch but now it will start tracking this other one".  People
of course can come up with contrived example to claim it is a useful
operation, but in real life, would it really be?  "The authoritative
repository has moved" is not an example.  It would merely be a change in
remote.<name>.url.  "The upstream renamed the branch" is not an example
either.  It falls into "Don't do that, then.  It will confuse everybody"
case.

Re: setting up tracking on push

[Miles Bader]

On Wed, Mar 11, 2009 at 1:37 PM, Junio C Hamano <gitster@pobox.com> wrote:
> And for that use case, I find it sensible if we had a way to easily say
> "This branch hasn't been tracking anything so far (because it is the
> originator of the history), but now it will give up its authority and
> start tracking the one it is pushing into", and it would make sense to
> somehow link that to the invocation of "git push".

I agree, and that's the use-case that prompted my original query.  I
very often create a new branch locally, and later push it to origin
with an intent to subsequently keep it synced with the new remote
branch.

-Miles

-- 
Do not taunt Happy Fun Ball.

Re: setting up tracking on push

[Miles Bader]

Miles Bader <miles@gnu.org> writes:
> I agree, and that's the use-case that prompted my original query.  I
> very often create a new branch locally, and later push it to origin
> with an intent to subsequently keep it synced with the new remote
> branch.

Oh, and I also always use the syntax:

   git push origin BRANCH_NAME

As the (apparent) objection adding "git push --track" was the question
of what the behavior would be in the general case (where lots of
branches can be pushed), maybe restricting "--track" to only specific
cases would be a possible solution?

-Miles

-- 
97% of everything is grunge

Re: setting up tracking on push

[Jay Soffian]

On Wed, Mar 11, 2009 at 12:37 AM, Junio C Hamano <gitster@pobox.com> wrote:
> I need to ask a more fundamental question.  Is it really useful for people
> to be able to re-track arbitrary remote/branch with an existing branch?

Actually, for me, I find sometimes I've forgotten to setup tracking,
or I've setup tracking and don't want it. I just fire up an editor on
.git/config, or use git config, but I would appreciate an easy way to
add/remove tracking to a branch after the fact.

j.

Re: setting up tracking on push

[Jeff King]

On Tue, Mar 10, 2009 at 09:37:21PM -0700, Junio C Hamano wrote:

> In any case, I find these "branch --retrack" proposals too confusing and
> probably overengineered.

I agree. I was hoping to find something that _wasn't_ confusing, but I
don't think we've succeeded.

> I need to ask a more fundamental question.  Is it really useful for people
> to be able to re-track arbitrary remote/branch with an existing branch?

I do it occasionally, but I have never had a problem with editing
.git/config.

My use case is usually something like:

  1. make an experimental commit on some long-running branch like 'next'
     or 'master'

  2. realize it's going to take several commits and would work better as
     a topic branch

  3. git checkout -b topic

in which case I have no tracking setup. But if I had realized it was
going to be a topic in the first place and done "git checkout -b topic
origin/master" then I would.

But again, I don't have a problem with editing .git/config. I was trying
in this thread to respond to user request.

-Peff

Re: setting up tracking on push

[Nanako Shiraishi]

Quoting Junio C Hamano <gitster@pobox.com>:

> The only use case I've heard in this thread and nearby is where you are
> the one who started the history of the branch, and pushed it into a public
> repository as a new branch, making the result _the_ most authoritative
> one.  After that, everybody else will be able to have a local branch that
> tracks the authoritative one with "branch --track frotz origin/frotz", and
> you will be the only one left unable to do so because you already have
> that frotz branch.
>
> And for that use case, I find it sensible if we had a way to easily say
> "This branch hasn't been tracking anything so far (because it is the
> originator of the history), but now it will give up its authority and
> start tracking the one it is pushing into", and it would make sense to
> somehow link that to the invocation of "git push".
>
>     Side note.  I would also accept "It is only one person in the world,
>     who can edit .git/config and be done with it; why bother complicate
>     the UI for other people" as a valid argument against it, though ;-).
>
> In that "my private branch gave autority to the branch at my public
> repository" case, it is of course easy to re-clone (or "branch -m" away
> and then re-fetch) like everybody else, but then you would lose the reflog
> from the time before the branch went public, so it is not a solution but a
> poor workaround.

I'm sorry, but I don't understand why you want to keep the entries in the reflog that were made before you pushed your branch to make it public in this scenario.

Especially because you are relinquishing the authority to the public repository by wishing to be able to "track" it, you can't rewind the branch beyond the point you initially pushed out any more. At that point, wouldn't it make more sense to drop the old reflog data and pretend as if the branch were fetched from the branch from your public repository it now follows, just like everybody else does?

-- 
Nanako Shiraishi
http://ivory.ap.teacup.com/nanako3/

Re: setting up tracking on push

[Jeff King]

On Wed, Mar 11, 2009 at 07:02:07PM +0900, Nanako Shiraishi wrote:

> I'm sorry, but I don't understand why you want to keep the entries in
> the reflog that were made before you pushed your branch to make it
> public in this scenario.
> 
> Especially because you are relinquishing the authority to the public
> repository by wishing to be able to "track" it, you can't rewind the
> branch beyond the point you initially pushed out any more. At that
> point, wouldn't it make more sense to drop the old reflog data and
> pretend as if the branch were fetched from the branch from your public
> repository it now follows, just like everybody else does?

That only means that you cannot rewind back to some spot in the reflog.
There is nothing to say that you cannot pull useful ideas from the
reflog that you thought were failed experiments, and apply them as
new commits.

-Peff

Re: setting up tracking on push

[Marc Branchaud]

Jay Soffian wrote:
> 
> Actually, for me, I find sometimes I've forgotten to setup tracking,
> or I've setup tracking and don't want it. I just fire up an editor on
> .git/config, or use git config, but I would appreciate an easy way to
> add/remove tracking to a branch after the fact.

I second that -- that's the exact situation I ran into.

Editing .git/config is scary and obscurely documented for new users (who are more likely to forget to set up tracking).  Plus encapsulating this in some porcelain makes it a bit less error-prone.

		M.

Re: setting up tracking on push

[John M. Dlugosz]

On a related note, what exactly does "tracking" mean?  I know that I can push/pull local 
names that match up with names on the origin, and that the latter are in the 
remotes/origin subdirectory.  Those are what I think are called "remote tracking 
branches".  Or is that just a part of the whole story?  What is the correct nomenclature?

--John

Re: setting up tracking on push

[Jay Soffian]

On Wed, Mar 11, 2009 at 8:08 PM, John M. Dlugosz
<ngnr63q02@sneakemail.com> wrote:
> On a related note, what exactly does "tracking" mean?  I know that I can
> push/pull local names that match up with names on the origin, and that the
> latter are in the remotes/origin subdirectory.  Those are what I think are
> called "remote tracking branches".  Or is that just a part of the whole
> story?  What is the correct nomenclature?

http://article.gmane.org/gmane.comp.version-control.git/54822/

j.

Re: setting up tracking on push

[Junio C Hamano]

Jay Soffian <jaysoffian@gmail.com> writes:

> On Wed, Mar 11, 2009 at 8:08 PM, John M. Dlugosz
> <ngnr63q02@sneakemail.com> wrote:
>> On a related note, what exactly does "tracking" mean?  I know that I can
>> push/pull local names that match up with names on the origin, and that the
>> latter are in the remotes/origin subdirectory.  Those are what I think are
>> called "remote tracking branches".  Or is that just a part of the whole
>> story?  What is the correct nomenclature?
>
> http://article.gmane.org/gmane.comp.version-control.git/54822/

I do not think the description of remote-tracking in that article is
correct.  We use the word to call remote/origin/<name> that keeps copies
of what we saw over there when we last observed.

The way to mark local branches to merge with/rebase onto something else
by default is --track option to "git branch" and "git checkout -b", and
that is often used to mark them to --track remote-tracking branches but
they do not have to --track remote-tracking branches.  They can --track 
local branches as well.

Re: setting up tracking on push

[Jay Soffian]

On Wed, Mar 11, 2009 at 8:58 PM, Jay Soffian <jaysoffian@gmail.com> wrote:

> http://article.gmane.org/gmane.comp.version-control.git/54822/

Let me summarize that thread as best I can.

- The branches under refs/remotes (those shown by "git branch -r") are
remote tracking branches. This is because they typically match (i.e.
track) the corresponding branch on a remote.

- The branches under refs/heads (those shown by "git branch") are your
local branches.

- Local branches can be associated with remote tracking branches in
the repo's config (.git/config). This association is done
automatically in current git when creating a new local branch based on
a remote tracking branch (e.g, git checkout -b topic origin/master or
git branch topic origin/master). (You can use --track and --no-track
to be explicit about whether or not you want the association to
happen.)

The association itself is simply an entry in the repo's .git/config. e.g.:

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

So, what does this entry in the .git/config do for you? A number of things:

1) git branch -v, git status, and git checkout will tell you how far
ahead/behind the local branch is from the associated remote tracking
branch.

2) git fetch, w/o arguments, will look in the config, find the remote
for the currently checked out branch, and update the configured
remote-tracking branches for said remote. This requires a bit more
explanation. In the above example, while topic is checked out, git
fetch will find that the associated remote is called "origin". It will
then update origin per its configuration, also in .git/config. e.g.:

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

So that tells git fetch where to fetch from, which remote branches to
fetch, and where to store those branches locally. In this case, each
branch under refs/heads/ on git://git.kernel.org/pub/scm/git/git.git
will be fetched and stored locally as refs/remotes/origin/. Locally
the branches are called "remote tracking branches".

3) git pull, w/o arguments, will run git fetch per above. It then
knows (in this example) to merge refs/remotes/origin/master into
refs/heads/topic. (The value on the "merge =" line is arguably
confusing because it is relative to where the branch is stored on the
remote, not where it is stored locally.)

HTH,

j.

Re: setting up tracking on push

[Jay Soffian]

On Wed, Mar 11, 2009 at 9:11 PM, Junio C Hamano <gitster@pobox.com> wrote:
>> http://article.gmane.org/gmane.comp.version-control.git/54822/
>
> I do not think the description of remote-tracking in that article is
> correct.  We use the word to call remote/origin/<name> that keeps copies
> of what we saw over there when we last observed.
>
> The way to mark local branches to merge with/rebase onto something else
> by default is --track option to "git branch" and "git checkout -b", and
> that is often used to mark them to --track remote-tracking branches but
> they do not have to --track remote-tracking branches.  They can --track
> local branches as well.

Yes, I noticed this as I re-read the thread. --track and --no-track
are unfortunately poorly named, but that's ancient history. I've
summarized the thread just before you sent this message. I'll update
my summary to note this point. :-)

j.

Re: setting up tracking on push

[Jay Soffian]

On Wed, Mar 11, 2009 at 9:14 PM, Jay Soffian <jaysoffian@gmail.com> wrote:
> - Local branches can be associated with remote tracking branches in
> the repo's config (.git/config). This association is done
> automatically in current git when creating a new local branch based on
> a remote tracking branch (e.g, git checkout -b topic origin/master or
> git branch topic origin/master). (You can use --track and --no-track
> to be explicit about whether or not you want the association to
> happen.)
>
> The association itself is simply an entry in the repo's .git/config. e.g.:
>
> [branch "topic"]
>        remote = origin
>        merge = refs/heads/master

As Junio points out, a local branch can be associated with another
local branch, not just a remote-tracking branch. In the config, this
looks like:

[branch "topic"]
      remote = .
      merge = refs/heads/master

So now "topic" is associated with *local* branch master, not
remote-tracking branch master, and this is because "remote = ." means
"this repo right here".

But, when making a new branch based on a local branch via git branch
and git checkout, adding this association in the config is not the
default. You have to explicitly ask for it with --track.

Also, the default of whether or not to add the association can itself
be changed. See the entry for branch.autosetupmerge (and related
branch.autosetuprebase, which I didn't go into) in "git help config".

j.

Re: setting up tracking on push

[John M. Dlugosz]

Jay Soffian jaysoffian-at-gmail.com |git| wrote:
> - The branches under refs/remotes (those shown by "git branch -r") are
> remote tracking branches. 
 > So that tells git fetch where to fetch from, which remote branches to
> fetch, and where to store those branches locally. In this case, each
> branch under refs/heads/ on git://git.kernel.org/pub/scm/git/git.git
> will be fetched and stored locally as refs/remotes/origin/. Locally
> the branches are called "remote tracking branches".
>
>   


Things under refs/remotes are remote tracking branches, and local 
branches (under refs/heads) that automatically updated based on a fetch 
("store locally" means merge or rebase, right?) are also called remote 
tracking branches.

I think that's why some of us are confused.

--John

Re: setting up tracking on push

[Jay Soffian]

On Sat, Mar 14, 2009 at 11:28 PM, John M. Dlugosz
<ngnr63q02@sneakemail.com> wrote:

> Things under refs/remotes are remote tracking branches

Yes.

> and local branches
> (under refs/heads) that automatically updated based on a fetch ("store
> locally" means merge or rebase, right?) are also called remote tracking
> branches.

No. The branches under refs/heads are *not* [1] updated by fetch.

- Anything under refs/remotes is a remote tracking branch.
- Anything under refs/heads is a local branch.

Now, often local branches are based on remote tracking branches, in the
sense that you created the local branch _from_ the remote tracking
branch. So periodically, you will want to update the local branch in
order to incorporate your local changes with whatever changes have been
made in the remote tracking branch. Doing this is a two-step process:

1) You update your remote tracking branches using fetch.
2) You integrate the changes from the remote tracking branches into your
   local branches using either merge or rebase.

> I think that's why some of us are confused.

I remember being just as confused, but oddly it seems so clear to me
now. I think there is an inflection point where git goes from
"confusing" to "ah hah, it's ingenious!" :-)

Let me try to draw a little ascii art:

Local Repo                                  Remote Repo (origin)
----------                                  --------------------
refs/remotes/origin/master  <-- fetch ---   refs/heads/master
        |
(merge or rebase)
        |
        v
refs/heads/master

As changes are made to refs/heads/master on the remote repo, the
corresponding remote tracking branch on the local repo
(refs/remotes/origin/master) will fall behind. Performing a fetch in the
local repo updates its refs/remotes/origin/master to match the remote's
refs/heads/master. Then either merge or rebase in the local repo, while
refs/heads/master is checked out, integrates those changes.

If no changes have been made locally to refs/heads/master, then the
merge operation is a so-called "fast forward".

The confusing part is that there is a switch to "git checkout" and "git
branch" named "--track". A better name would have probably been
"--follow". Regardless, this switch [2], configures branch.<name>.remote
and branch.<name>.merge in the local repo's .git/config. And I mentioned
in a previous message the reason for having these. [3]

[1] You could of course configure fetch to do whatever you like, but it
    would be rather unusual to update refs/heads via fetch.
[2] Which is the default in current git when a local branch is created
    from a remote tracking branch.
[3] Namely, 1) branch -v, status, and checkout tell you how far
    ahead/behind the local branch is from the remote tracking branch;
    2) pull can be run w/o having to explicitly tell it what to fetch
    and what to merge.

j.

Re: setting up tracking on push

[Junio C Hamano]

"John M. Dlugosz" <ngnr63q02@sneakemail.com> writes:

> Jay Soffian jaysoffian-at-gmail.com |git| wrote:
>> - The branches under refs/remotes (those shown by "git branch -r") are
>> remote tracking branches. So that tells git fetch where to fetch
>> from, which remote branches to
>> fetch, and where to store those branches locally. In this case, each
>> branch under refs/heads/ on git://git.kernel.org/pub/scm/git/git.git
>> will be fetched and stored locally as refs/remotes/origin/. Locally
>> the branches are called "remote tracking branches".
>
> Things under refs/remotes are remote tracking branches, and local
> branches (under refs/heads) that automatically updated based on a
> fetch ("store locally" means merge or rebase, right?) are also called
> remote tracking branches.
>
> I think that's why some of us are confused.

True; the latter wording invites confusion.

What fetch updates directly from remote site are called "remote tracking
branches".  The local branches you intend to keep up to date with respect
to one remote tracking branch is sometimes said to "track" the remote
tracking branch, but because I find it confusing to use the same verb for
this other purpose, I tend to say that local branch (that "tracks" the
other one)

 (1) _forked_ from; or
 (2) _builds_ on

the remote tracking branch, in order to avoid confusion.

Historically, refs/remotes/ hierarchy did not exist, and "git clone"
created these refspecs after cloning from a two branch project:

    refs/heads/master:refs/heads/origin
    refs/heads/maint:refs/heads/maint

and created a local master starting at 'origin'.

The expectation was that everybody would work on 'master', occasionally
referring to 'maint', and because 'master' is always checked out, avoid 
'fetch' from disturbing it by using a separate local branch 'origin' to
keep track of the advance of the other side, while updating 'maint' that
is not checked out directly.

This was the layout used in the good old times, and worked well *only* in
the most simplistic case.  In reality, people used far more branches and
worked on branches other than master.

To fix that, refs/remotes/ hierarchy was introduced, and we started
treating the tracking part of master the same way as other branches, i.e.

    refs/heads/*:refs/remotes/origin/*

The local 'maint' in the old layout was called a remote tracking branch,
too, even though it was local.  These days, if you use the default layout
"git clone" gives you, you can say refs under refs/remotes/ hierarchy are
all remote tracking branches, and you do not have any remote tracking
branches that are local.

Re: setting up tracking on push

[John M. Dlugosz]

Jay Soffian jaysoffian-at-gmail.com |git| wrote:
> I remember being just as confused, but oddly it seems so clear to me
> now. I think there is an inflection point where git goes from
> "confusing" to "ah hah, it's ingenious!" :-)
>
>   

In this case, the confusion is with different people posting different 
meanings for the term, and more generally using the term in different ways.

Re: setting up tracking on push

[Jay Soffian]

On Sun, Mar 15, 2009 at 9:07 PM, John M. Dlugosz
<ngnr63q02@sneakemail.com> wrote:
> Jay Soffian jaysoffian-at-gmail.com |git| wrote:
> In this case, the confusion is with different people posting different
> meanings for the term, and more generally using the term in different ways.

In that case I'll stop replying to this thread, I wouldn't want to
cause any additional confusion. :-)

j.

Re: setting up tracking on push

[Jakub Narebski]

Jay Soffian <jaysoffian@gmail.com> writes:
> On Tue, Mar 10, 2009 at 11:57 PM, Jeff King <peff@peff.net> wrote:

>>> -u w/o --track/--no-track is a usage error.
>>
>> Then what is the point of "-u"? You said before that it was a new
>> operation with room for future growth of additional options. Either it
>> is _just_ for --track, in which case I think you are better to have a
>> single option representing the notion of "update the tracking setup", or
>> it isn't, in which case it needs to have room for future expansion.
> 
> For *now*, it is just for --track/--no-track, since I can't think of
> anything sensible that "-u" without --track nor --no-track would do.
> 
> So it means, update the branch config, but you have to tell it what
> aspect of the branch config to update.
> 
> I agree that currently, a single option could do here, but I can't
> think of a good one. --add-tracking and --delete-tracking? I was
> trying to re-use the fact that we already have --track and --no-track,
> but I needed some way to differentiate the mode from "create a new
> branch". Hence -u.

I would suggest '-n' here, as "git branch" doesn't do its main
function (with a branch), namely create, delete or modify branch head.
Your '-u' is all about _not_ updating branch head, but peripheral
information.

But I do wonder if it is really a good idea...
-- 
Jakub Narebski
Poland
ShadeHawk on #git