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

From: Michael J Gruber <git@drmicha.warpmail.net>
Date: Oct 4, 2010, 09:28 UTC
Message-ID: <4CA99E43.1000204@drmicha.warpmail.net>
In-Reply-To: <20101004085050.GQ28679@pengutronix.de>

Uwe Kleine-König venit, vidit, dixit 04.10.2010 10:50:

Show 43 quoted lines

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

Yep, my sentence was bad, it could be misunderstood.

Show 5 quoted lines

> 
> So maybe:
> 
> 	Set up a mirror of the remote repository.  This implies `--bare`.
> 	Compared to `--bare`, `--mirror` doesn't only map local branches of

"does not"

> 	the remote to local branches of the target but all refs
> 	(including remote branches, notes etc.) and sets up a refspec

Maybe "of the source" for "of the remote"? Because remote comes up right after in a different meaning.

> 	configuration such that all these refs are overwritten by a
> 	`git remote update` in the target repository.
>

I like that a lot!

> 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?

"update" may be more Git lingo but I think either is fine. "overwritten" makes it clearer this is not a repo to do development in...

Cheers, Michael