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

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

[Uwe Kleine-König]

Some people in #linux-rt claimed that you cannot define "--mirror" with
"mirror".

Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
 Documentation/git-clone.txt |   11 ++++++++++-
 1 files changed, 10 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index dc7d3d1..5eedfbd 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -128,7 +128,16 @@ objects from the source repository into a pack in the cloned repository.
 	configuration variables are created.
 
 --mirror::
-	Set up a mirror of the remote repository.  This implies `--bare`.
+	Set up a mirror of the remote repository.
+	Using
+
+		git remote update origin
+
+	(or `<name>` instead of `origin` if -o is given) in the resulting
+	repository overwrites the local branches without asking.
+	This implies `--bare`.
+	Without --mirror (but with --bare) git remote update doesn't touch any
+	branches at all.
 
 --origin <name>::
 -o <name>::
-- 
1.7.2.3

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

[Darren Hart]

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".
>
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>

Acked-by: Darren 'Some People' Hart <darren@dvhart.com>

> ---
>  Documentation/git-clone.txt |   11 ++++++++++-
>  1 files changed, 10 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index dc7d3d1..5eedfbd 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -128,7 +128,16 @@ objects from the source repository into a pack in the cloned repository.
>        configuration variables are created.
>
>  --mirror::
> -       Set up a mirror of the remote repository.  This implies `--bare`.
> +       Set up a mirror of the remote repository.
> +       Using
> +
> +               git remote update origin
> +
> +       (or `<name>` instead of `origin` if -o is given) in the resulting
> +       repository overwrites the local branches without asking.
> +       This implies `--bare`.
> +       Without --mirror (but with --bare) git remote update doesn't touch any
> +       branches at all.
>
>  --origin <name>::
>  -o <name>::
> --
> 1.7.2.3
>
>



-- 
Darren Hart

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

[Steven Rostedt]

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".
> >
> > Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> 
> Acked-by: Darren 'Some People' Hart <darren@dvhart.com>

  Acked-by: Steven Rostedt <rostedt@goodmis.org>

-- Steve

> 
> > ---
> >  Documentation/git-clone.txt |   11 ++++++++++-
> >  1 files changed, 10 insertions(+), 1 deletions(-)
> >
> > diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> > index dc7d3d1..5eedfbd 100644
> > --- a/Documentation/git-clone.txt
> > +++ b/Documentation/git-clone.txt
> > @@ -128,7 +128,16 @@ objects from the source repository into a pack in the cloned repository.
> >        configuration variables are created.
> >
> >  --mirror::
> > -       Set up a mirror of the remote repository.  This implies `--bare`.
> > +       Set up a mirror of the remote repository.
> > +       Using
> > +
> > +               git remote update origin
> > +
> > +       (or `<name>` instead of `origin` if -o is given) in the resulting
> > +       repository overwrites the local branches without asking.
> > +       This implies `--bare`.
> > +       Without --mirror (but with --bare) git remote update doesn't touch any
> > +       branches at all.
> >
> >  --origin <name>::
> >  -o <name>::
> > --
> > 1.7.2.3
> >
> >
> 
> 
> 

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

[Michael J Gruber]

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.

>>> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
>>
>> Acked-by: Darren 'Some People' Hart <darren@dvhart.com>
> 
>   Acked-by: Steven Rostedt <rostedt@goodmis.org>
> 
> -- Steve
> 
>>
>>> ---
>>>  Documentation/git-clone.txt |   11 ++++++++++-
>>>  1 files changed, 10 insertions(+), 1 deletions(-)
>>>
>>> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
>>> index dc7d3d1..5eedfbd 100644
>>> --- a/Documentation/git-clone.txt
>>> +++ b/Documentation/git-clone.txt
>>> @@ -128,7 +128,16 @@ objects from the source repository into a pack in the cloned repository.
>>>        configuration variables are created.
>>>
>>>  --mirror::
>>> -       Set up a mirror of the remote repository.  This implies `--bare`.
>>> +       Set up a mirror of the remote repository.
>>> +       Using
>>> +
>>> +               git remote update origin
>>> +
>>> +       (or `<name>` instead of `origin` if -o is given) in the resulting

"remote" has no "-o" option. You probably mean the "clone" option, but
the way it's written it refers to the preceding command.

>>> +       repository overwrites the local branches without asking.
>>> +       This implies `--bare`.

Again, "this" refers to the preceding sentence. But the update behavior
does not imply "--bare". Specifying "--mirror" for "clone" implies "--bare".

>>> +       Without --mirror (but with --bare) git remote update doesn't touch any
>>> +       branches at all.

That's not true. It just doesn't touch any local branches; it updates
the remote branches, of course.

I'm sorry but I can't consider this patch an improvement.

Michael

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

[Uwe Kleine-König]

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?
 
> >>> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> >>
> >> Acked-by: Darren 'Some People' Hart <darren@dvhart.com>
> > 
> >   Acked-by: Steven Rostedt <rostedt@goodmis.org>
> > 
> > -- Steve
> > 
> >>
> >>> ---
> >>>  Documentation/git-clone.txt |   11 ++++++++++-
> >>>  1 files changed, 10 insertions(+), 1 deletions(-)
> >>>
> >>> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> >>> index dc7d3d1..5eedfbd 100644
> >>> --- a/Documentation/git-clone.txt
> >>> +++ b/Documentation/git-clone.txt
> >>> @@ -128,7 +128,16 @@ objects from the source repository into a pack in the cloned repository.
> >>>        configuration variables are created.
> >>>
> >>>  --mirror::
> >>> -       Set up a mirror of the remote repository.  This implies `--bare`.
> >>> +       Set up a mirror of the remote repository.
> >>> +       Using
> >>> +
> >>> +               git remote update origin
> >>> +
> >>> +       (or `<name>` instead of `origin` if -o is given) in the resulting
> 
> "remote" has no "-o" option. You probably mean the "clone" option, but
> the way it's written it refers to the preceding command.
So what do you think about:

	... (or `<name>` instead of `origin` if -o is given to clone)

> 
> >>> +       repository overwrites the local branches without asking.
> >>> +       This implies `--bare`.
> 
> Again, "this" refers to the preceding sentence. But the update behavior
> does not imply "--bare". Specifying "--mirror" for "clone" implies "--bare".
OK.
 
> >>> +       Without --mirror (but with --bare) git remote update doesn't touch any
> >>> +       branches at all.
> 
> That's not true. It just doesn't touch any local branches; it updates
> the remote branches, of course.
Hmm, for me there are no remote branches when using --bare:

	ukleinek@cassiopeia:~/tmp$ git clone --bare ~/gsrc/topgit
	Cloning into bare repository topgit.git...
	done.
	ukleinek@cassiopeia:~/tmp$ cd topgit.git/
	ukleinek@cassiopeia:~/tmp/topgit.git$ git remote update
	Fetching origin
	From /home/ukleinek/gsrc/topgit
	 * branch            HEAD       -> FETCH_HEAD

This is also documented for --bare:

	When this option is used, neither remote-tracking branches nor
	the related configuration variables are created.

Best regards
Uwe

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

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

[Michael J Gruber]

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

Then, when you use the mirror clone, the refspec makes it behave
differently from a normal clone, which is what you notice with "update" etc.

>>>>> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
>>>>
>>>> Acked-by: Darren 'Some People' Hart <darren@dvhart.com>
>>>
>>>   Acked-by: Steven Rostedt <rostedt@goodmis.org>
>>>
>>> -- Steve
>>>
>>>>
>>>>> ---
>>>>>  Documentation/git-clone.txt |   11 ++++++++++-
>>>>>  1 files changed, 10 insertions(+), 1 deletions(-)
>>>>>
>>>>> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
>>>>> index dc7d3d1..5eedfbd 100644
>>>>> --- a/Documentation/git-clone.txt
>>>>> +++ b/Documentation/git-clone.txt
>>>>> @@ -128,7 +128,16 @@ objects from the source repository into a pack in the cloned repository.
>>>>>        configuration variables are created.
>>>>>
>>>>>  --mirror::
>>>>> -       Set up a mirror of the remote repository.  This implies `--bare`.
>>>>> +       Set up a mirror of the remote repository.
>>>>> +       Using
>>>>> +
>>>>> +               git remote update origin
>>>>> +
>>>>> +       (or `<name>` instead of `origin` if -o is given) in the resulting
>>
>> "remote" has no "-o" option. You probably mean the "clone" option, but
>> the way it's written it refers to the preceding command.
> So what do you think about:
> 
> 	... (or `<name>` instead of `origin` if -o is given to clone)

maybe "was given"

> 
>>
>>>>> +       repository overwrites the local branches without asking.
>>>>> +       This implies `--bare`.
>>
>> Again, "this" refers to the preceding sentence. But the update behavior
>> does not imply "--bare". Specifying "--mirror" for "clone" implies "--bare".
> OK.
>  
>>>>> +       Without --mirror (but with --bare) git remote update doesn't touch any
>>>>> +       branches at all.
>>
>> That's not true. It just doesn't touch any local branches; it updates
>> the remote branches, of course.
> Hmm, for me there are no remote branches when using --bare:

I'm sorry, I missed the parenthetical remark. You're completely right
for the case with "--bare" only.

> 
> 	ukleinek@cassiopeia:~/tmp$ git clone --bare ~/gsrc/topgit
> 	Cloning into bare repository topgit.git...
> 	done.
> 	ukleinek@cassiopeia:~/tmp$ cd topgit.git/
> 	ukleinek@cassiopeia:~/tmp/topgit.git$ git remote update
> 	Fetching origin
> 	From /home/ukleinek/gsrc/topgit
> 	 * branch            HEAD       -> FETCH_HEAD
> 
> This is also documented for --bare:
> 
> 	When this option is used, neither remote-tracking branches nor
> 	the related configuration variables are created.
> 
> Best regards
> Uwe
> 

This makes me think that --mirror should be explained on top of --bare.
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.

Michael

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

[Uwe Kleine-König]

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

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

[Michael J Gruber]

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

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

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

[Uwe Kleine-König]

Some people in #linux-rt claimed that you cannot define "--mirror" with
"mirror" only.

Cc: Steven Rostedt <rostedt@goodmis.org>
Cc: Darren 'Some People' Hart <darren@dvhart.com>
Cc: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
 Documentation/git-clone.txt |    7 ++++++-
 1 files changed, 6 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index dc7d3d1..524a080 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -128,7 +128,12 @@ objects from the source repository into a pack in the cloned repository.
 	configuration variables are created.
 
 --mirror::
-	Set up a mirror of the remote repository.  This implies `--bare`.
+	Set up a mirror of the source repository.  This implies `--bare`.
+	Compared to `--bare`, `--mirror` does not only map local branches of
+	the source 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.
 
 --origin <name>::
 -o <name>::
-- 
1.7.2.3

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

[Steven Rostedt]

On Mon, 2010-10-04 at 11:51 +0200, Uwe Kleine-König wrote:
> Some people in #linux-rt claimed that you cannot define "--mirror" with
> "mirror" only.
> 

Acked-by: Steven Rostedt <rostedt@goodmis.org>

-- Steve

> Cc: Darren 'Some People' Hart <darren@dvhart.com>
> Cc: Michael J Gruber <git@drmicha.warpmail.net>
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> ---
>  Documentation/git-clone.txt |    7 ++++++-
>  1 files changed, 6 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index dc7d3d1..524a080 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -128,7 +128,12 @@ objects from the source repository into a pack in the cloned repository.
>  	configuration variables are created.
>  
>  --mirror::
> -	Set up a mirror of the remote repository.  This implies `--bare`.
> +	Set up a mirror of the source repository.  This implies `--bare`.
> +	Compared to `--bare`, `--mirror` does not only map local branches of
> +	the source 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.
>  
>  --origin <name>::
>  -o <name>::

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

[Michael J Gruber]

Uwe Kleine-König venit, vidit, dixit 04.10.2010 11:51:
> Some people in #linux-rt claimed that you cannot define "--mirror" with
> "mirror" only.
> 
> Cc: Steven Rostedt <rostedt@goodmis.org>
> Cc: Darren 'Some People' Hart <darren@dvhart.com>
> Cc: Michael J Gruber <git@drmicha.warpmail.net>
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> ---
>  Documentation/git-clone.txt |    7 ++++++-
>  1 files changed, 6 insertions(+), 1 deletions(-)
> 
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index dc7d3d1..524a080 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -128,7 +128,12 @@ objects from the source repository into a pack in the cloned repository.
>  	configuration variables are created.
>  
>  --mirror::
> -	Set up a mirror of the remote repository.  This implies `--bare`.
> +	Set up a mirror of the source repository.  This implies `--bare`.
> +	Compared to `--bare`, `--mirror` does not only map local branches of
> +	the source 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.
>  
>  --origin <name>::
>  -o <name>::

Yep, and thanks for being patient! JC may prefer a grammatically correct
commit subject ("more verbosely") but in any case, thanks for hanging in
there ;)

Michael

Acked-by: sender

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

[Darren Hart]

Hi Uwe,

(sorry for the dup Uwe)

Thanks for iterating on this with Michael. The following looks good to
me, with one exception below:

2010/10/4 Uwe Kleine-König <u.kleine-koenig@pengutronix.de>:
> Some people in #linux-rt claimed that you cannot define "--mirror" with
> "mirror" only.
>
> Cc: Steven Rostedt <rostedt@goodmis.org>
> Cc: Darren 'Some People' Hart <darren@dvhart.com>
> Cc: Michael J Gruber <git@drmicha.warpmail.net>
> Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
> ---
>  Documentation/git-clone.txt |    7 ++++++-
>  1 files changed, 6 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index dc7d3d1..524a080 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -128,7 +128,12 @@ objects from the source repository into a pack in the cloned repository.
>        configuration variables are created.
>
>  --mirror::
> -       Set up a mirror of the remote repository.  This implies `--bare`.
> +       Set up a mirror of the source repository.  This implies `--bare`.
> +       Compared to `--bare`, `--mirror` does not only map local branches of

s/does not only map/not only maps/

> +       the source to local branches of the target but all refs (including

s/but all refs/, it maps all refs/

These changes form a more parallel sentence structure and is easier to
read/parse IMO.

Thanks,

Darren Hart

> +       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.
>
>  --origin <name>::
>  -o <name>::
> --
> 1.7.2.3
>
>



--
Darren Hart

[PATCH v3] Documentation/git-clone: describe --mirror more verbosely

[Uwe Kleine-König]

Some people in #linux-rt claimed that you cannot define "--mirror" with
"mirror" only.

Cc: Steven Rostedt <rostedt@goodmis.org>
Cc: Darren 'Some People' Hart <darren@dvhart.com>
Cc: Michael J Gruber <git@drmicha.warpmail.net>
Signed-off-by: Uwe Kleine-König <u.kleine-koenig@pengutronix.de>
---
 Documentation/git-clone.txt |    7 ++++++-
 1 files changed, 6 insertions(+), 1 deletions(-)

diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
index dc7d3d1..ab72933 100644
--- a/Documentation/git-clone.txt
+++ b/Documentation/git-clone.txt
@@ -128,7 +128,12 @@ objects from the source repository into a pack in the cloned repository.
 	configuration variables are created.
 
 --mirror::
-	Set up a mirror of the remote repository.  This implies `--bare`.
+	Set up a mirror of the source repository.  This implies `--bare`.
+	Compared to `--bare`, `--mirror` not only maps local branches of the
+	source to local branches of the target, it maps 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.
 
 --origin <name>::
 -o <name>::
-- 
1.7.2.3

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

[Junio C Hamano]

Michael J Gruber <git@drmicha.warpmail.net> writes:

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

In a repository with remote.origin.mirror set to true, "git fetch origin"
does not seem to prune a ref that has been removed from the origin.  I
think that is a design bug, albeit a minor one ("git fetch -p origin" can
fix, but "-p" should not be necessary).  A "mirror"'s purpose is to, ehh,
mirror a remote so that local people can share it as a nearby copy.

A wording that also implies this automatic deletion of a stale ref would
be nice; "overwritten" does not exactly sound like that, though.

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

[Matthieu Moy]

Junio C Hamano <gitster@pobox.com> writes:

> A "mirror"'s purpose is to, ehh, mirror a remote so that local
> people can share it as a nearby copy.

I think this is the one sentence that is missing in the description.
Even after the patch, the reader knows _what_ --mirror does, still not
really _how_ to use it.

-- 
Matthieu Moy
http://www-verimag.imag.fr/~moy/

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

[Darren Hart]

On Mon, Oct 4, 2010 at 10:39 AM, Matthieu Moy
<Matthieu.Moy@grenoble-inp.fr> wrote:
> Junio C Hamano <gitster@pobox.com> writes:
>
>> A "mirror"'s purpose is to, ehh, mirror a remote so that local
>> people can share it as a nearby copy.
>
> I think this is the one sentence that is missing in the description.
> Even after the patch, the reader knows _what_ --mirror does, still not
> really _how_ to use it.

Agreed, that would be a nice addition.

-- 
Darren Hart

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

[Uwe Kleine-König]

Hi Junio,

On Mon, Oct 04, 2010 at 10:29:43AM -0700, Junio C Hamano wrote:
> Michael J Gruber <git@drmicha.warpmail.net> writes:
> 
> >> 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...
> 
> In a repository with remote.origin.mirror set to true, "git fetch origin"
> does not seem to prune a ref that has been removed from the origin.  I
> think that is a design bug, albeit a minor one ("git fetch -p origin" can
> fix, but "-p" should not be necessary).  A "mirror"'s purpose is to, ehh,
> mirror a remote so that local people can share it as a nearby copy.
> 
> A wording that also implies this automatic deletion of a stale ref would
> be nice; "overwritten" does not exactly sound like that, though.
So you intend to change git fetch origin to remove stale refs, right?

Best regards
Uwe

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

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

[Junio C Hamano]

Uwe Kleine-König <u.kleine-koenig@pengutronix.de> writes:

> So you intend to change git fetch origin to remove stale refs, right?

I personally?  Am too lazy for doing it myself ;-)

I am just

 (1) pointing it out as a potential design bug; and

 (2) seeing if somebody who is depending on the current behaviour to
     object.