From: Todd Zullinger Date: Wed, 18 Apr 2018 20:56:35 GMT Subject: Re: man page for "git remote set-url" seems confusing/contradictory Message-ID: <20180418205635.GU29831@zaya.teonanacatl.net> In-Reply-To: Junio C Hamano wrote: > Jacob Keller 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 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