man page for "git remote set-url" seems confusing/contradictory

> i don't understand how you can clearly set the fetch and push URLs of
> a remote independently, while the man page nonetheless insists that
> "even though they can be set differently, must still refer to the same
> place". how can they be set differently yet still must refer to the
> same place?

> On Apr 16 2018, "Robert P. J. Day" <rpjday@crashcourse.ca> wrote:
>
> > i don't understand how you can clearly set the fetch and push URLs
> > of a remote independently, while the man page nonetheless insists
> > that "even though they can be set differently, must still refer to
> > the same place". how can they be set differently yet still must
> > refer to the same place?
>
> They could be using different transport methods.  For example, for
> fetching the unauthenticated git: method could be used, but for
> pushing an authenticated method like ssh: is usually needed.

> On Mon, 16 Apr 2018, Andreas Schwab wrote:
>
>> On Apr 16 2018, "Robert P. J. Day" <rpjday@crashcourse.ca> wrote:
>>
>> > i don't understand how you can clearly set the fetch and push URLs
>> > of a remote independently, while the man page nonetheless insists
>> > that "even though they can be set differently, must still refer to
>> > the same place". how can they be set differently yet still must
>> > refer to the same place?
>>
>> They could be using different transport methods.  For example, for
>> fetching the unauthenticated git: method could be used, but for
>> pushing an authenticated method like ssh: is usually needed.
>
>   ok, point taken, but does that mean the two must actually refer to
> the same "place"? it seems that i'm perfectly free to use this command
> to set the push and fetch URLs to totally different locations.
>
> rday

> Things won't work so well if you set the push url and fetch url to
> different repositories. Git assumes that refs updated by "push" will
> also be reflected via "fetch".
>
> I don't know offhand what will break, but likely something will. For
> one, when you fetch again it will rewind your remotes after the push.

> Jacob Keller <jacob.keller@gmail.com> writes:
>
>> Things won't work so well if you set the push url and fetch url to
>> different repositories. Git assumes that refs updated by "push" will
>> also be reflected via "fetch".
>>
>> I don't know offhand what will break, but likely something will. For
>> one, when you fetch again it will rewind your remotes after the push.
>
> Exactly.  I still haven't fully embraced it myself, but for a long
> time, "git push" pretends as if it fetched from that remote and
> updates the corresponding remote tracking branches (if you have
> any), so you'll be inviting inconsistent behaviour if you set your
> fetch and push URLs pointing at two logically separate places.
>
> This is a tangent, but there probably should be a boolean that
> disables this feature in "git push" per destination repository,
> i.e. "when pushing into this repository, pretend that we immediately
> fetched from the refs we just pushed to and update the remote
> tracking branches we have for them: yes/no".  It is not entirely
> implausible to envision an overly smart remote repository that turns
> a non-fast-forward push into an automatic rebase when it is safe to
> do so, instead of failing such a push, and you'd disable the "assume
> what we pushed would appear there" when talking to such a remote.
>

> Jacob Keller <jacob.keller@gmail.com> writes:
>
> > Things won't work so well if you set the push url and fetch url to
> > different repositories. Git assumes that refs updated by "push"
> > will also be reflected via "fetch".
> >
> > I don't know offhand what will break, but likely something will.
> > For one, when you fetch again it will rewind your remotes after
> > the push.
>
> Exactly.  I still haven't fully embraced it myself, but for a long
> time, "git push" pretends as if it fetched from that remote and
> updates the corresponding remote tracking branches (if you have
> any), so you'll be inviting inconsistent behaviour if you set your
> fetch and push URLs pointing at two logically separate places.

> On Tue, 17 Apr 2018, Junio C Hamano wrote:
>
>> Jacob Keller <jacob.keller@gmail.com> writes:
>>
>> > Things won't work so well if you set the push url and fetch url to
>> > different repositories. Git assumes that refs updated by "push"
>> > will also be reflected via "fetch".
>> >
>> > I don't know offhand what will break, but likely something will.
>> > For one, when you fetch again it will rewind your remotes after
>> > the push.
>>
>> Exactly.  I still haven't fully embraced it myself, but for a long
>> time, "git push" pretends as if it fetched from that remote and
>> updates the corresponding remote tracking branches (if you have
>> any), so you'll be inviting inconsistent behaviour if you set your
>> fetch and push URLs pointing at two logically separate places.
>
>   ... snip ...
>
>   oh, i totally buy all that now, i'm just suggesting that the man
> page might be tweaked to make that more obvious. in "man git-remote",
> under "set-url", remember that it reads:
>
> "Note that the push URL and the fetch URL, even though they can be set
> differently, must still refer to the same place."
>
>   i think it would be useful to be more specific about what "can be
> set differently" means, since a lot of readers might not immediately
> appreciate that it means just, say, the transport protocols. it never
> hurts to add that little bit of detail.
>
> rday
>
>

> Maybe something like:
>
> "Note that the push URL and the fetch URL, even though they can be set
> differently, are expected to refer to the same repository. For
> example, the fetch URL might use an unauthenticated transport, while
> the push URL generally requires authentication" Then follow this bit
> with the mention of multiple remotes.
>
> (I think "repository" conveys the meaning better than "place".
> Technically, the URLs can be completely different as long as they end
> up contacting the same real server repository.)

> Jacob Keller <jacob.keller@gmail.com> writes:
> 
>> Maybe something like:
>>
>> "Note that the push URL and the fetch URL, even though they can be set
>> differently, are expected to refer to the same repository. For
>> example, the fetch URL might use an unauthenticated transport, while
>> the push URL generally requires authentication" Then follow this bit
>> with the mention of multiple remotes.
>>
>> (I think "repository" conveys the meaning better than "place".
>> Technically, the URLs can be completely different as long as they end
>> up contacting the same real server repository.)
> 
> Sounds sensible.  Let's see if there is any further input and then
> somebody pleaes wrap this up in a final patch ;-)

> Tangentially (and I don't know if it's worth fixing), while
> poking around the documentation which includes urls.txt I
> noticed that git-clone.txt refers readers to the "URLS
> section below" when the name of the section is "GIT URLS".
>
> I doubt any readers would be confused, but it would be
> consistent with the other files which include urls.txt to
> use "GIT URLS" as the referenced section name.
>
> -- >& --
> Subject: [PATCH] doc/clone: update caption for GIT URLS cross-reference
>
> The description of the <repository> argument directs readers to "See the
> URLS section below".  When generating HTML this becomes a link to the
> "GIT URLS" section.  When reading the man page in a terminal, the
> caption is slightly misleading.  Use "GIT URLS" as the caption to avoid
> an confusion.

> Signed-off-by: Todd Zullinger <tmz@pobox.com>
> ---
>  Documentation/git-clone.txt | 2 +-
>  1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/Documentation/git-clone.txt b/Documentation/git-clone.txt
> index 42ca7b5095..b844b9957c 100644
> --- a/Documentation/git-clone.txt
> +++ b/Documentation/git-clone.txt
> @@ -260,7 +260,7 @@ or `--mirror` is given)
>
>  <repository>::
>         The (possibly remote) repository to clone from.  See the
> -       <<URLS,URLS>> section below for more information on specifying
> +       <<URLS,GIT URLS>> section below for more information on specifying
>         repositories.

> On 18 April 2018 at 22:56, Todd Zullinger <tmz@pobox.com> wrote:
>> Subject: [PATCH] doc/clone: update caption for GIT URLS cross-reference
>>
>> The description of the <repository> argument directs readers to "See the
>> URLS section below".  When generating HTML this becomes a link to the
>> "GIT URLS" section.  When reading the man page in a terminal, the
>> caption is slightly misleading.  Use "GIT URLS" as the caption to avoid
>> an confusion.
> 
> s/an/any/?