Re: man page for "git remote set-url" seems confusing/contradictory
On 18 April 2018 at 22:56, Todd Zullingerwrote: > 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 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 argument simply > Abandoned first attempt at log message? ;-) > Signed-off-by: Todd Zullinger > --- > 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) > > :: > The (possibly remote) repository to clone from. See the > - < > section below for more information on specifying > + < > section below for more information on specifying > repositories. Indeed. Matches urls.txt and the others who refer there. Martin
Re: man page for "git remote set-url" seems confusing/contradictory
Junio C Hamano wrote: > Jacob Kellerwrites: > >> 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 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 argument simply Signed-off-by: Todd Zullinger --- 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) :: The (possibly remote) repository to clone from. See the - < > section below for more information on specifying + < > section below for more information on specifying repositories. :: -- 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
Jacob Kellerwrites: > 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
On Tue, Apr 17, 2018 at 8:34 AM, Robert P. J. Daywrote: > On Tue, 17 Apr 2018, Junio C Hamano wrote: > >> Jacob Keller 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
On Tue, 17 Apr 2018, Junio C Hamano wrote: > Jacob Kellerwrites: > > > 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
On Mon, Apr 16, 2018 at 4:13 PM, Junio C Hamanowrote: > Jacob Keller 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
Jacob Kellerwrites: > 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
On Mon, Apr 16, 2018 at 9:19 AM, Robert P. J. Daywrote: > On Mon, 16 Apr 2018, Andreas Schwab wrote: > >> On Apr 16 2018, "Robert P. J. Day" 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
On Mon, 16 Apr 2018, Andreas Schwab wrote: > On Apr 16 2018, "Robert P. J. Day"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
On Apr 16 2018, "Robert P. J. Day"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, sch...@linux-m68k.org GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510 2552 DF73 E780 A9DA AEC1 "And now for something completely different."
man page for "git remote set-url" seems confusing/contradictory
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 that matches regex ... 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