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

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

[Robert P. J. Day]

  never had cause to examine "git remote set-url" before so i'm a bit
puzzled by this part of the man page:

  set-url

  Changes URLs for the remote. Sets first URL for remote
  <name> that matches regex <oldurl> ...

  With --push, push URLs are manipulated instead of fetch URLs.
 .. snip ...

  Note that the push URL and the fetch URL, even though they can be
  set differently, must still refer to the same place. What you pushed to
  the push URL should be what you would see if you immediately fetched
  from the fetch URL. If you are trying to fetch from one place (e.g.
  your upstream) and push to another (e.g. your publishing
  repository), use two separate remotes.

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?

  i suspect i'll have a couple more questions related to this shortly
after i do a bit more reading.

rday

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

[Andreas Schwab]

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.

Andreas.

-- 
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510  2552 DF73 E780 A9DA AEC1
"And now for something completely different."

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

[Robert P. J. Day]

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

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

[Jacob Keller]

On Mon, Apr 16, 2018 at 9:19 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> 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.

The URLs could be different for lots of reasons, but they need to
ultimately link to the same remote repository. As Andreas said, the
most likely reason is differing transport protocols.

Thanks,
Jake

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

[Junio C Hamano]

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.

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

[Jacob Keller]

On Mon, Apr 16, 2018 at 4:13 PM, Junio C Hamano <gitster@pobox.com> 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.
>
> 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.
>

Not to mention something like gerrit which uses magical references
"refs/publish/branchname" which don't actually get generated on the
server.

Thanks,
Jake

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

[Robert P. J. Day]

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

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

[Jacob Keller]

On Tue, Apr 17, 2018 at 8:34 AM, Robert P. J. Day <rpjday@crashcourse.ca> wrote:
> 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.)

Thanks,
Jake

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

[Junio C Hamano]

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

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

[Todd Zullinger]

Junio C Hamano wrote:
> 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 ;-)

A pointer to the "GIT URLS" section in git-fetch(1) might
also be useful?  That section is provided via urls.txt and
urls-remotes.txt and is included the git-clone, git-fetch,
git-pull, and git-push man pages.

We could also include urls-remotes.txt in git-remote, though
that seems like a lot of text to add to yet another man
page.  Maybe a giturls.txt could be created and referenced
(as a further enhancement if someone is inclined).

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.

The man page produced by asciidoc doesn't include hyperlinks.  The
description of the <repository> argument simply

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

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ultimate result of shielding men from the effects of folly is to
fill the world with fools.
    -- Herbert Spencer

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

[Martin Ågren]

On 18 April 2018 at 22:56, Todd Zullinger <tmz@pobox.com> wrote:
> 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.

s/an/any/?

>
> The man page produced by asciidoc doesn't include hyperlinks.  The
> description of the <repository> argument simply
>

Abandoned first attempt at log message? ;-)

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

Indeed. Matches urls.txt and the others who refer there.

Martin

[PATCH] doc/clone: update caption for GIT URLS cross-reference

[Todd Zullinger]

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

Signed-off-by: Todd Zullinger <tmz@pobox.com>
---
Martin Ågren wrote:
> 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/?

Indeed, thanks.

>> The man page produced by asciidoc doesn't include hyperlinks.  The
>> description of the <repository> argument simply
> 
> Abandoned first attempt at log message? ;-)

That or it was when a squirrel ran by my window. ;)

Thanks for catching both of these mistakes.

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

-- 
Todd
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Whenever you find yourself on the side of the majority, it is time to
pause and reflect.
    -- Mark Twain