diff mbox series

[v2] doc: gitcredentials: link to helper list

Message ID pull.1538.v2.git.1687332624780.gitgitgadget@gmail.com (mailing list archive)
State Superseded
Headers show
Series [v2] doc: gitcredentials: link to helper list | expand

Commit Message

M Hickford June 21, 2023, 7:30 a.m. UTC 
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.

Signed-off-by: M Hickford <mirth.hickford@gmail.com>
---
    gitcredentials: link to list of helpers
    
    Add link to list of helpers

Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1538%2Fhickford%2Fhelpers-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1538/hickford/helpers-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1538

Range-diff vs v1:

 1:  49e2a6fc9f2 ! 1:  26818290468 doc: gitcredentials: introduce OAuth helpers
     @@ Metadata
      Author: M Hickford <mirth.hickford@gmail.com>
      
       ## Commit message ##
     -    doc: gitcredentials: introduce OAuth helpers
     +    doc: gitcredentials: link to helper list
      
     -    OAuth credential helpers are widely useful but work differently to other
     -    credential helpers, so worth introducing in the docs.
     +    Link to community list of credential helpers. This is useful information
     +    for users.
      
     -    Link to relevant projects.
     +    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.
      
          Signed-off-by: M Hickford <mirth.hickford@gmail.com>
      
       ## Documentation/gitcredentials.txt ##
     -@@ Documentation/gitcredentials.txt: $ git config --global credential.helper foo
     +@@ Documentation/gitcredentials.txt: $ git help credential-foo
     + $ git config --global credential.helper foo
       -------------------------------------------
       
     - 
     -+=== OAuth credential helpers
     -+
     -+An alternative to entering passwords or personal access tokens is to use an
     -+OAuth credential helper. Many popular Git hosts support OAuth. The first time
     -+you authenticate, the helper opens a browser window to the host.
     -+Subsequent authentication is non interactive.
     -+
     -+Two cross-platform open-source OAuth credential helpers are:
     ++=== Available helpers
      +
     -+* https://github.com/git-ecosystem/git-credential-manager[Git Credential Manager]
     -+* https://github.com/hickford/git-credential-oauth[git-credential-oauth]
     ++The community maintains a comprehensive
     ++https://git-scm.com/doc/credential-helpers[list of Git credential helpers]
     ++available.
      +
     ++=== OAuth
      +
     ++An alternative to inputting passwords or personal access tokens is to use an
     ++OAuth credential helper. Initial authentication opens a browser window to the
     ++host. Subsequent authentication happens in the background. Many popular Git
     ++hosts support OAuth.
     + 
       CREDENTIAL CONTEXTS
       -------------------
     - 


 Documentation/gitcredentials.txt | 12 ++++++++++++
 1 file changed, 12 insertions(+)


base-commit: 79bdd48716a4c455bdc8ffd91d57a18d5cd55baa

Comments

Jeff King June 27, 2023, 8:21 a.m. UTC | #1 
On Wed, Jun 21, 2023 at 07:30:24AM +0000, M Hickford via GitGitGadget wrote:

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

> 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
diff mbox series

Patch

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.
+
+=== OAuth
+
+An alternative to inputting passwords or personal access tokens is to use an
+OAuth credential helper. Initial authentication opens a browser window to the
+host. Subsequent authentication happens in the background. Many popular Git
+hosts support OAuth.
 
 CREDENTIAL CONTEXTS
 -------------------