Re: [PATCH v2] doc: gitcredentials: link to helper list

From: Jeff King <peff@peff.net>
Date: Jun 27, 2023, 08:21 UTC
Message-ID: <20230627082101.GG1226768@coredump.intra.peff.net>
In-Reply-To: <pull.1538.v2.git.1687332624780.gitgitgadget@gmail.com>

On Wed, Jun 21, 2023 at 07:30:24AM +0000, M Hickford via GitGitGadget wrote:

Show 9 quoted lines

> From: M Hickford <mirth.hickford@gmail.com>
> 
> Link to community list of credential helpers. This is useful information
> for users.
> 
> Describe how OAuth credential helpers work. OAuth is a user-friendly
> alternative to personal access tokens and SSH keys. Reduced setup cost
> makes it easier for users to contribute to projects across multiple
> forges.

Kind of seems like two topics in one patch, but OK.

I don't have much of an opinion on either topic, but...

Show 13 quoted lines

> diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
> index 100f045bb1a..a266870a042 100644
> --- a/Documentation/gitcredentials.txt
> +++ b/Documentation/gitcredentials.txt
> @@ -104,6 +104,18 @@ $ git help credential-foo
>  $ git config --global credential.helper foo
>  -------------------------------------------
>  
> +=== Available helpers
> +
> +The community maintains a comprehensive
> +https://git-scm.com/doc/credential-helpers[list of Git credential helpers]
> +available.

I'd note that full hyperlinks like this are kind of lousy in the manpage builds. You get:

     Available helpers
	The community maintains a comprehensive list of Git credential
	helpers[1] available.

in the text, and then way down at the bottom of the manpage:

  NOTES
	1. list of Git credential helpers
	   https://git-scm.com/doc/credential-helpers

Something like:

diff --git a/Documentation/gitcredentials.txt b/Documentation/gitcredentials.txt
index fd5ecede13..1c7d302f18 100644
--- a/Documentation/gitcredentials.txt
+++ b/Documentation/gitcredentials.txt
@@ -106,9 +106,8 @@ $ git config --global credential.helper foo
 
 === Available helpers
 
-The community maintains a comprehensive
-https://git-scm.com/doc/credential-helpers[list of Git credential helpers]
-available.
+The community maintains a comprehensive list of Git credential helpers
+at https://git-scm.com/doc/credential-helpers.
 
 === OAuth
 

yields nicer text in the manpage, and asciidoc is smart enough to turn
it into a hyperlink in the html version.

-Peff