Re: [PATCH] Documentation/git-clone: describe --mirror more verbose

["Uwe Kleine-König" <u.kleine-koenig@pengutronix.de>]

Hello Michael,

On Mon, Oct 04, 2010 at 10:23:13AM +0200, Michael J Gruber wrote:
> Uwe Kleine-König venit, vidit, dixit 04.10.2010 09:50:
> > Hello Michael,
> > 
> > On Mon, Oct 04, 2010 at 09:25:17AM +0200, Michael J Gruber wrote:
> >> Steven Rostedt venit, vidit, dixit 01.10.2010 23:16:
> >>> On Fri, 2010-10-01 at 13:18 -0700, Darren Hart wrote:
> >>>> 2010/10/1 Uwe Kleine-König <u.kleine-koenig@pengutronix.de>:
> >>>>> Some people in #linux-rt claimed that you cannot define "--mirror" with
> >>>>> "mirror".
> >>>>>
> >>
> >> I'd say "mirror" is a commonly known term for an exact copy. Moreover,
> >> the text below doesn't explain what a mirror is either, only how
> >> "update" behaves in it.
> > hmm.  The --mirror option doesn't have any effect (apart from the
> > changes in the config file) until you update.  So I think it's natural
> > to talk about git update.  No?
> 
> "git clone" (with or without --mirror) does a couple of things, and it
> does them differently when "--mirror" is used. It mirrors each branch
> from the source repo in the target repo under the same name, including
> for example any remote branches in the source repo. This is completely
> different without "--mirror", where clone does not look at the source's
> remote branches at all. Also, it sets up a mirroring refspec, i.e.
> +refs/*:refs/*
Ah, didn't notice that.

> [...]
> This makes me think that --mirror should be explained on top of --bare.
OK.

> For example:
> 
> In addition to the mapping of local branches to local branches which
> --bare does, --mirror maps all refs which the source has under the same
> name in the target (including remote branches, notes etc.) and sets up a
> refspec configuration so that all these refs are updated by a `git
> update` in the target repo.
Hmm, I didn't understand this when I read it the first few times.  The
special thing is that --mirror maps *all* refs, not *same name*.

So maybe:

	Set up a mirror of the remote repository.  This implies `--bare`.
	Compared to `--bare`, `--mirror` doesn't only map local branches of
	the remote to local branches of the target but all refs
	(including remote branches, notes etc.) and sets up a refspec
	configuration such that all these refs are overwritten by a
	`git remote update` in the target repository.

I choosed to write "overwritten" instead of "updated" to make it clearer
that it makes no sence to push into these branches from a different
source.  Should this be noted more explicit?

Best regards
Uwe

-- 
Pengutronix e.K.                           | Uwe Kleine-König            |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |