when is a remote a branch?

when is a remote a branch?

[Anand Kumria]

Hi,

I generally tend to use cogito -- it does all the heavy lifting, like
recovering from interrupted fetchs (usually) for me.  One thing I haven't
really gotten my head around is the difference between a branch and a
remote.

git-branch knows of 'remotes' (via the -r parameter) and these to be
unrelated to what cogito thinks remotes are (it seems to look for things
in .git/refs/head/<name> and then a corresponding .git/branches/<name>/
which it then declares a remote).

Yet, git-init-db creates both .git/remotes and .git/branches

What is the difference between the two. From my (naïve) perspective the
two tools (git and cogito) regarded them very differently.

Any explanation, or pointer to some documentation, would be helpful.

Thanks,
Anand

Re: when is a remote a branch?

[Jakub Narebski]

Anand Kumria wrote:

> I generally tend to use cogito -- it does all the heavy lifting, like
> recovering from interrupted fetchs (usually) for me.  One thing I haven't
> really gotten my head around is the difference between a branch and a
> remote.
> 
> git-branch knows of 'remotes' (via the -r parameter) and these to be
> unrelated to what cogito thinks remotes are (it seems to look for things
> in .git/refs/head/<name> and then a corresponding .git/branches/<name>/
> which it then declares a remote).

Not about 'remotes', but about 'remote [read-only] branches', i.e. refs not
from .refs/heads/, but from .refs/remotes/<remotename>/

> Yet, git-init-db creates both .git/remotes and .git/branches
> 
> What is the difference between the two. From my (na?ve) perspective the
> two tools (git and cogito) regarded them very differently.
> 
> Any explanation, or pointer to some documentation, would be helpful.

Read Documentation/repository-layout.txt (ot it's HTML version, either
locally ot at www.kernel.org).

 branches::
         A slightly deprecated way to store shorthands to be used
         to specify URL to `git fetch`, `git pull` and `git push`
         commands is to store a file in `branches/'name'` and
         give 'name' to these commands in place of 'repository'
         argument.

You can store only one branch to fetch per shorthand. I'm not sure about
where it is stored which branch to download, and how to name this branch 
locally.

 remotes::
         Stores shorthands to be used to give URL and default
         refnames to interact with remote repository to `git
         fetch`, `git pull` and `git push` commands.

From Documentation/urls.txt

 In addition to the above, as a short-hand, the name of a
 file in `$GIT_DIR/remotes` directory can be given; the
 named file should be in the following format:

         URL: one of the above URL format
         Push: <refspec>
         Pull: <refspec>

Currently there is yet another way, by using config file:
(also from Documentation/urls.txt):

 Or, equivalently, in the `$GIT_DIR/config` (note the use
 of `fetch` instead of `Pull:`):

 [remote "<remote>"]
         url = <url>
         push = <refspec>
         fetch = <refspec>

where <refspec> is defined in Documentation/fetch-pull-param.txt

 <refspec>::
         The canonical format of a <refspec> parameter is
         `+?<src>:<dst>`; that is, an optional plus `+`, followed
         by the source ref, followed by a colon `:`, followed by
         the destination ref.

(or, simply, in git-pull(1), which includes those files, with exception of
repository layout document).
-- 
Jakub Narebski
Warsaw, Poland
ShadeHawk on #git

Re: when is a remote a branch?

[Petr Baudis]

On Sun, Nov 12, 2006 at 05:11:41PM CET, Jakub Narebski wrote:
> Read Documentation/repository-layout.txt (ot it's HTML version, either
> locally ot at www.kernel.org).
> 
>  branches::
>          A slightly deprecated way to store shorthands to be used
>          to specify URL to `git fetch`, `git pull` and `git push`
>          commands is to store a file in `branches/'name'` and
>          give 'name' to these commands in place of 'repository'
>          argument.
> 
> You can store only one branch to fetch per shorthand. I'm not sure about
> where it is stored which branch to download, and how to name this branch 
> locally.

I think the above is quite confusing description. This really is not
about any "shorthands" at all, but just about branches (how the name
implies, after all).

Git and Cogito share the same models of branches. These branches are
'heads' with commit pointers stored in refs/heads/, etc. The branches/
directory says that some branches do not correspond to local development
(and should never be used for that) but instead they correspond to a
particular branch in some remote repository. Such branches are called
"REMOTE BRANCHES".

So it's "if branch X has corresponding .git/branch/X file, it's not a
local branch but instead a REMOTE BRANCH corresponding to the URL stored
in that file". That simple. The URL is address of the repository plus
optionally a '#branchname' if the branch name in the remote repository
should not default to remote HEAD or master.

In addition, Git (not Cogito at this point) supports a completely
different and unrelated abstraction called REMOTES. They don't have
anything to do with branches. Instead, a REMOTE represents a repository
URL and a set of local/remote branch pairs to handle on pulls and
pushes; it has no other obvious mapping to branches and branches can be
even shared between various REMOTES etc. (this is changing lately with
the refs/remotes/ hierarchy, but I think that's still not in wide use).

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: when is a remote a branch?

[Jakub Narebski]

Petr "Pasky" Baudis wrote:
> On Sun, Nov 12, 2006 at 05:11:41PM CET, Jakub Narebski wrote:
>> Read Documentation/repository-layout.txt (ot it's HTML version, either
>> locally ot at www.kernel.org).
>> 
>>  branches::
>>          A slightly deprecated way to store shorthands to be used
>>          to specify URL to `git fetch`, `git pull` and `git push`
>>          commands is to store a file in `branches/'name'` and
>>          give 'name' to these commands in place of 'repository'
>>          argument.
>> 
>> You can store only one branch to fetch per shorthand. I'm not sure about
>> where it is stored which branch to download, and how to name this branch 
>> locally.
> 
> I think the above is quite confusing description. This really is not
> about any "shorthands" at all, but just about branches (how the name
> implies, after all).

Well, it is a shorthand in a way that you can just use "git fetch"
or "cg fetch" to fetch correct branch without need for URL.

But I agree that the description (although of deprecated feature)
could be better.

> Git and Cogito share the same models of branches. These branches are
> 'heads' with commit pointers stored in refs/heads/, etc. 

Not exactly. "Live" branches (i.e. branches you can commit to) are head
refs stored in refs/heads/. But in repository cloned with git-clone
--use-separate-remotes tracking heads (tracking branches) would be at
refs/remotes/<remotename>/. You can fetch to such a ref, but you can't
checkout it, nor commit to it.

> The branches/ 
> directory says that some branches do not correspond to local development
> (and should never be used for that) but instead they correspond to a
Does that _should_ is enforced in Cogito? Is it enforced in Git?

> particular branch in some remote repository. Such branches are called
> "REMOTE BRANCHES".

I'd rather call them "tracking branches", at least in git. So if there
is branch 'localbranch' in refs/heads/ (?), and there is corresponding
branches file branches/localbranch, which contains a single URL
  git://host.domain/path/to/repository#remotebranch
it is AFAICU equivalent to having some remotes file, named e.g. 'repo',
with the following contents:
  URL: git://host.domain/path/to/repository
  Pull: remotebranch:localbranch
  Push: remotebranch:localbranch
or equivalent entry in git config.

> So it's "if branch X has corresponding .git/branch/X file, it's not a
> local branch but instead a REMOTE BRANCH corresponding to the URL stored
> in that file". That simple. The URL is address of the repository plus
> optionally a '#branchname' if the branch name in the remote repository
> should not default to remote HEAD or master.

The whole concept of branches file (and marking some branches as "remote"
branches) is IMHO from the times where there were most common to have one
live branch per repository, and we fetched and pushed single branches.
This simple picture changed with more widespread use of multiple heads,
and with the introduction of tags (I think).
 
> In addition, Git (not Cogito at this point) supports a completely
> different and unrelated abstraction called REMOTES. They don't have
> anything to do with branches. Instead, a REMOTE represents a repository
> URL and a set of local/remote branch pairs to handle on pulls and
> pushes; it has no other obvious mapping to branches and branches can be
> even shared between various REMOTES etc. (this is changing lately with
> the refs/remotes/ hierarchy, but I think that's still not in wide use).

Remote is usually a repository. It is single URL (although it would be
nice to be able to specify alternate URLs for the same repository, or
for different mirrors of the same repository) representing repository
to fetch from/to push to, together with branches we want to fetch (which
parts of DAG we want to fetch), and local names of those branches,
following fetched contents.

By the way, with introduction of branches and remotes in config file,
you can say:
 [branch "localbranch"]
	remote = someremote

 [remote "someremote"]
	fetch = remotebranch:localbranch
	push  = remotebranch:localbranch

and that would be equivalent to example branches file from the beginning
of this email.
-- 
Jakub Narebski

Re: when is a remote a branch?

[Petr Baudis]

On Sun, Nov 12, 2006 at 06:31:18PM CET, Jakub Narebski wrote:
> Petr "Pasky" Baudis wrote:
> > Git and Cogito share the same models of branches. These branches are
> > 'heads' with commit pointers stored in refs/heads/, etc. 
> 
> Not exactly. "Live" branches (i.e. branches you can commit to) are head
> refs stored in refs/heads/. But in repository cloned with git-clone
> --use-separate-remotes tracking heads (tracking branches) would be at
> refs/remotes/<remotename>/. You can fetch to such a ref, but you can't
> checkout it, nor commit to it.

That was meant to be the "etc". ;-))

> > The branches/ 
> > directory says that some branches do not correspond to local development
> > (and should never be used for that) but instead they correspond to a
> Does that _should_ is enforced in Cogito? Is it enforced in Git?

Yes (you cannot switch to it). No (AFAIK).

> > particular branch in some remote repository. Such branches are called
> > "REMOTE BRANCHES".
> 
> I'd rather call them "tracking branches", at least in git. So if there
> is branch 'localbranch' in refs/heads/ (?), and there is corresponding
> branches file branches/localbranch, which contains a single URL
>   git://host.domain/path/to/repository#remotebranch
> it is AFAICU equivalent to having some remotes file, named e.g. 'repo',
> with the following contents:
>   URL: git://host.domain/path/to/repository
>   Pull: remotebranch:localbranch
>   Push: remotebranch:localbranch
> or equivalent entry in git config.

Yes, except that the remote must be named 'localbranch'.

> > So it's "if branch X has corresponding .git/branch/X file, it's not a
> > local branch but instead a REMOTE BRANCH corresponding to the URL stored
> > in that file". That simple. The URL is address of the repository plus
> > optionally a '#branchname' if the branch name in the remote repository
> > should not default to remote HEAD or master.
> 
> The whole concept of branches file (and marking some branches as "remote"
> branches) is IMHO from the times where there were most common to have one
> live branch per repository, and we fetched and pushed single branches.
> This simple picture changed with more widespread use of multiple heads,
> and with the introduction of tags (I think).

I completely agree. The original remotes implementation was messy, but
with refs/remotes/ it's simple again. Only lack of time (or laziness) on
my side is why Cogito didn't move to this yet.

> By the way, with introduction of branches and remotes in config file,
> you can say:
>  [branch "localbranch"]
> 	remote = someremote
>  [remote "someremote"]
> 	fetch = remotebranch:localbranch
> 	push  = remotebranch:localbranch
> 
> and that would be equivalent to example branches file from the beginning
> of this email.

According to the documentation, this is not really useful since this
just tells what should git fetch default to when on branch
"localbranch". But "localbranch" is still just a branch representing a
state in a remote repository, so you should never be _on_ it in a sane
setup, but instead on a different branch which tracks it.

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1

Re: when is a remote a branch?

[Jakub Narebski]

Petr "Pasky" Baudis wrote:
> On Sun, Nov 12, 2006 at 06:31:18PM CET, Jakub Narebski wrote:
>>
>> By the way, with introduction of branches and remotes in config file,
>> you can say:
>>  [branch "localbranch"]
>> 	remote = someremote
>>  [remote "someremote"]
>> 	fetch = remotebranch:localbranch
>> 	push  = remotebranch:localbranch
>> 
>> and that would be equivalent to example branches file from
>> the beginning of this email.
> 
> According to the documentation, this is not really useful since this
> just tells what should git fetch default to when on branch
> "localbranch". But "localbranch" is still just a branch representing a
> state in a remote repository, so you should never be _on_ it in a sane
> setup, but instead on a different branch which tracks it.

Oh. Can you "git fetch Localbranch" _without_ repository named 
"localbranch" in above case?
-- 
Jakub Narebski

Re: when is a remote a branch?

[Petr Baudis]

On Tue, Nov 14, 2006 at 09:36:16PM CET, Jakub Narebski wrote:
> Petr "Pasky" Baudis wrote:
> > On Sun, Nov 12, 2006 at 06:31:18PM CET, Jakub Narebski wrote:
> >>
> >> By the way, with introduction of branches and remotes in config file,
> >> you can say:
> >>  [branch "localbranch"]
> >> 	remote = someremote
> >>  [remote "someremote"]
> >> 	fetch = remotebranch:localbranch
> >> 	push  = remotebranch:localbranch
> >> 
> >> and that would be equivalent to example branches file from
> >> the beginning of this email.
> > 
> > According to the documentation, this is not really useful since this
> > just tells what should git fetch default to when on branch
> > "localbranch". But "localbranch" is still just a branch representing a
> > state in a remote repository, so you should never be _on_ it in a sane
> > setup, but instead on a different branch which tracks it.
> 
> Oh. Can you "git fetch Localbranch" _without_ repository named 
> "localbranch" in above case?

So that it would be equivalent to git fetch someremote, and also fetch
any other branches associated with that remote?

I would hope not. :-)

-- 
				Petr "Pasky" Baudis
Stuff: http://pasky.or.cz/
#!/bin/perl -sp0777i<X+d*lMLa^*lN%0]dsXx++lMlN/dsM0<j]dsj
$/=unpack('H*',$_);$_=`echo 16dio\U$k"SK$/SM$n\EsN0p[lN*1