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

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

Hello Michael,

On Mon, Oct 04, 2010 at 10:23:13AM +0200, Michael J Gruber wrote:

quoted

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

quoted

Hello Michael,

On Mon, Oct 04, 2010 at 09:25:17AM +0200, Michael J Gruber wrote:

quoted

Steven Rostedt venit, vidit, dixit 01.10.2010 23:16:

quoted

On Fri, 2010-10-01 at 13:18 -0700, Darren Hart wrote:

quoted

2010/10/1 Uwe Kleine-König [off-list ref]:

quoted

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.

quoted

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

OK.

quoted

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.

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