Subject: Re: Document clone of clone loosing branches?

From: Jakub Narebski <[email-masked]>
Date: Sun, 15 Jun 2008 01:03:01 +0200

Vaclav Hanzl wrote:
> Jakub Narebski wrote:
>>
>> 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'?

The question of course is _what_ to put into git-clone(1), what to
generic documentation in git(1), and what in "Git User's Manual".

> After all, how many other commands do distinguish regular branches and
> remote tracking branches?

Errr... many of them? git-branch treats regular branches (refs/heads/*)
and remote-tracking branches (refs/remotes/<remotename>/*) differently
(compare "git branch" and "git branch -r", and "git branch -a").
git-checkout treats regular branches (can checkout) different from
other refs, including remote-tracking branches (result in detached
HEAD).

> 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).

I'm not sure how it is put in documentation, but I wouldn't wonder
if it is not dicumented, because most of gitters who can write this
documentation do know the difference between regular branches and
remote-tracking branches, and know recoomended workflows and best
practices.
 
> (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.)

So, what should be mentioned ar two facts, I think.  (a) that git-clone
copies only regular branches and tags; it does not copy remote-tracking
branches, it does not copy stash, it does not copy reflogs, it does not
copy StGIT stacks...  (b) that recommended workflow (best practice) is
to have public published repository which is bare clone
(1:1 correspondnce) of interesting subset of refs.

-- 
Jakub Narebski
Poland