Re: Document clone of clone loosing branches?

From: Vaclav Hanzl <hanzl@noel.feld.cvut.cz>
Date: Jun 14, 2008, 21:36 UTC
Message-ID: <20080614.233645.71097102.hanzl@noel.feld.cvut.cz>
In-Reply-To: <4853D967.5080903@gmail.com>

Lea Wiemann wrote:

> I got bitten by that, too.  Perhaps the intro paragraph of git-clone.txt 
> (man git-clone) could mention that remote branches are not cloned or so. 
>   (I don't know git-clone well enough to be able to phrase it 
> accurately, but perhaps someone else wants to send a documentation patch...)

This is exactly what I would like to happen. (If nobody seems interested, I might propose my own bad very first patch few days or weeks later...)

Jeff King wrote:

Show 10 quoted lines

> The new repository has remote tracking branches of the _regular_
> branches that are in the original repository. So the statement is
> correct; git-clone creates remote-tracking branches, and it makes one
> such branch for each branch in the cloned repository.
> 
> Unless you are complaining that it makes one for each non-remote branch
> in the cloned repository. But I think it is the general pattern to refer
> to things in refs/heads/ as simply unadorned "branch". If you want to
> say "all refs, including remote-tracking branches", you would typically
> say "refs" (which would also include tags).

I am not sure that the term 'branch' can be reasonably expected to mean 'regular branch' unless specified otherwise. For example, 'man git' says:

       git-branch(1)
          List, create, or delete branches.

It can also list remote-tracking branches, cannot it? Or:

       git-show-branch(1)
          Show branches and their commits.

Can also show remote-tracking branches, cannot it?

Even if 'branch' were very well known to mean 'regular branch', I would still argue that 'man clone' is a very good place to define these vocabulary conventions.

So I still think that 'man clone' is wrong as it stands now. It is not true that all 'branches' are cloned. It would be better to say quite explicitly that regular branches are cloned and remote tracking branches are not.

Jakub Narebski wrote:

Show 8 quoted lines

> The idea is for git-clone to clone (by default) _your_ work, not sb
> else work.  Think about two repositories, fetching from each other:
> you don't want for branches to proliferate like mad, remote of remote,
> then remote of remote of remote, and ad infinitum.
> 
> Besides there is I think implicit assumption that public repositories
> one might want to clone are _bare_ repositories, 1:1 or mirror
> refspecs, which simply do not contain remote tracking branches.

Yes. It would be no shame if an explanation like this made it to 'man clone'?

After all, how many other commands do distinguish regular branches and remote tracking branches? Even if there are any other (I do not know), git-clone is likely the most prominent of them and 'man git-clone' is quite good place to document this. Unless it is explained in 'man git' itself (I think it is not now).

(Thought I am quite happy with UNIX tradition of very exact and very condensed man pages, up to the point of being a hard puzzle, and I agree that man pages are no tutorial, in this case I would be happy to see 'regular branches' and 'remote tracking branches' clearly distinguished in 'man git-clone' itself, without an implicit reference to 'usual' meaning of words among geeks.)

Regards,

Vaclav Hanzl

P.S. Sorry for screwing up mail threads by this synthetic answer but I thought it is not worth 3 messages (?)