Re: man page for "git remote set-url" seems confusing/contradictory
- From
Todd Zullinger <tmz@pobox.com>
- Date
- Apr 18, 2018, 20:56 UTC
- Message-ID
- <20180418205635.GU29831@zaya.teonanacatl.net>
- In-Reply-To
- <xmqqd0yxl6n9.fsf@gitster-ct.c.googlers.com>
Junio C Hamano wrote:
Show 16 quoted lines
> 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