Merge branch 'main' into lunny/add_reply_code_review

cmd/login/add.go

@@ -16,10 +16,15 @@ import (
 
 // CmdLoginAdd represents to login a gitea server.
 var CmdLoginAdd = cli.Command{
-	Name:        "add",
-	Usage:       "Add a Gitea login",
-	Description: `Add a Gitea login, without args it will create one interactively`,
-	ArgsUsage:   " ", // command does not accept arguments
+	Name:  "add",
+	Usage: "Add a Gitea login",
+	Description: `Add a Gitea login, without args it will create one interactively.
+
+By default tea only stores the token for its own API use. Pass --git-credentials
+to also register tea as a git credential helper for the login's URL, so that
+'git push' and 'git clone' over HTTPS authenticate silently using the stored
+token. Equivalent to running 'tea login helper setup' afterwards.`,
+	ArgsUsage: " ", // command does not accept arguments
 	Flags: []cli.Flag{
 		&cli.StringFlag{
 			Name:    "name",
@@ -89,9 +94,9 @@ var CmdLoginAdd = cli.Command{
 			Usage:   "Use SSH public key or SSH fingerprint to login (needs a running ssh-agent with ssh key loaded)",
 		},
 		&cli.BoolFlag{
-			Name:    "helper",
-			Aliases: []string{"j"},
-			Usage:   "Add helper",
+			Name:    "git-credentials",
+			Aliases: []string{"helper", "j"},
+			Usage:   "Register tea as a git credential helper for this login's URL, so 'git push' and 'git clone' over HTTPS authenticate silently using the stored token",
 		},
 		&cli.BoolFlag{
 			Name:    "oauth",
@@ -161,6 +166,6 @@ func runLoginAdd(requestCtx context.Context, cmd *cli.Command) error {
 		cmd.Bool("insecure"),
 		sshAgent,
 		!cmd.Bool("no-version-check"),
-		cmd.Bool("helper"),
+		cmd.Bool("git-credentials"),
 	)
 }

cmd/login/helper.go

@@ -19,23 +19,31 @@ import (
 
 // CmdLoginHelper represents to login a gitea helper.
 var CmdLoginHelper = cli.Command{
-	Name:        "helper",
-	Aliases:     []string{"git-credential"},
-	Usage:       "Git helper",
-	Description: `Git helper`,
-	Hidden:      true,
+	Name:    "helper",
+	Aliases: []string{"git-credential"},
+	Usage:   "Act as a git credential helper for stored Gitea logins",
+	Description: `Speaks git's credential helper protocol so that HTTPS push and clone
+operations against your configured Gitea instances authenticate silently
+using the tokens tea already stores.
+
+Typical use is automatic: 'tea login add --git-credentials' (or 'tea login
+helper setup' for existing logins) registers '!tea login helper' as a
+credential helper in ~/.gitconfig. Git then invokes the 'get' subcommand
+when it needs credentials for a configured host.`,
 	Commands: []*cli.Command{
 		{
 			Name:        "store",
-			Description: "Command drops",
 			Aliases:     []string{"erase"},
+			Usage:       "No-op (git credential protocol store/erase)",
+			Description: "No-op invoked by git on credential store/erase; tea persists credentials only in its own config",
 			Action: func(requestCtx context.Context, _ *cli.Command) error {
 				return nil
 			},
 		},
 		{
 			Name:        "setup",
-			Description: "Setup helper to tea authenticate",
+			Usage:       "Register tea as a git credential helper for every configured login",
+			Description: "Register tea as a git credential helper in ~/.gitconfig for every configured login",
 			Action: func(requestCtx context.Context, _ *cli.Command) error {
 				logins, err := config.GetLogins()
 				if err != nil {
@@ -56,7 +64,8 @@ var CmdLoginHelper = cli.Command{
 		},
 		{
 			Name:        "get",
-			Description: "Get token to auth",
+			Usage:       "Return the stored token for a URL (git credential protocol)",
+			Description: "Return the stored token for a given URL in git's credential helper protocol (called by git, reads request from stdin)",
 			Flags: []cli.Flag{
 				&cli.StringFlag{
 					Name:    "login",