Improve "gitea doctor" sub-command and fix "help" commands (#26072)

Replace #21790

And close #25965 by the way (it needs a separate fix for 1.20)

Major changes:

1. Move "gitea convert" to "gitea doctor conver". The old "gitea doctor"
still works as a hidden sub-command (to avoid breaking)
2. Do not write "doctor.log" by default, it's not useful in most cases
and causes bugs like 25965
3. Improve documents
4. Fix the "help" commands. Before, the "./gitea doctor" can't show the
sub-command help correctly (regression of the last cli/v2 refactoring)

After this PR:

```
./gitea help # show all sub-commands for the app
./gitea doctor # show the sub-commands for the "doctor"
./gitea doctor help # show the sub-commands for the "doctor", as above
```

3 files changed, 36 insertions, 27 deletions

diff --git a/cmd/doctor.go b/cmd/doctor.go
index f8866c7b97..d040a3af1c 100644
--- a/cmd/doctor.go
+++ b/cmd/doctor.go
@@ -22,12 +22,11 @@ import (
 	"xorm.io/xorm"
 )
 
-// CmdDoctor represents the available doctor sub-command.
-var CmdDoctor = &cli.Command{
-	Name:        "doctor",
+var cmdDoctorCheck = &cli.Command{
+	Name:        "check",
 	Usage:       "Diagnose and optionally fix problems",
 	Description: "A command to diagnose problems with the current Gitea instance according to the given configuration. Some problems can optionally be fixed by modifying the database or data storage.",
-	Action:      runDoctor,
+	Action:      runDoctorCheck,
 	Flags: []cli.Flag{
 		&cli.BoolFlag{
 			Name:  "list",
@@ -51,7 +50,7 @@ var CmdDoctor = &cli.Command{
 		},
 		&cli.StringFlag{
 			Name:  "log-file",
-			Usage: `Name of the log file (default: "doctor.log"). Set to "-" to output to stdout, set to "" to disable`,
+			Usage: `Name of the log file (no verbose log output by default). Set to "-" to output to stdout`,
 		},
 		&cli.BoolFlag{
 			Name:    "color",
@@ -59,8 +58,18 @@ var CmdDoctor = &cli.Command{
 			Usage:   "Use color for outputted information",
 		},
 	},
+}
+
+// CmdDoctor represents the available doctor sub-command.
+var CmdDoctor = &cli.Command{
+	Name:        "doctor",
+	Usage:       "Diagnose and optionally fix problems",
+	Description: "A command to diagnose problems with the current Gitea instance according to the given configuration. Some problems can optionally be fixed by modifying the database or data storage.",
+
 	Subcommands: []*cli.Command{
+		cmdDoctorCheck,
 		cmdRecreateTable,
+		cmdDoctorConvert,
 	},
 }
 
@@ -133,16 +142,9 @@ func setupDoctorDefaultLogger(ctx *cli.Context, colorize bool) {
 	setupConsoleLogger(log.FATAL, log.CanColorStderr, os.Stderr)
 
 	logFile := ctx.String("log-file")
-	if !ctx.IsSet("log-file") {
-		logFile = "doctor.log"
-	}
-
-	if len(logFile) == 0 {
-		// if no doctor log-file is set, do not show any log from default logger
-		return
-	}
-
-	if logFile == "-" {
+	if logFile == "" {
+		return // if no doctor log-file is set, do not show any log from default logger
+	} else if logFile == "-" {
 		setupConsoleLogger(log.TRACE, colorize, os.Stdout)
 	} else {
 		logFile, _ = filepath.Abs(logFile)
@@ -156,7 +158,7 @@ func setupDoctorDefaultLogger(ctx *cli.Context, colorize bool) {
 	}
 }
 
-func runDoctor(ctx *cli.Context) error {
+func runDoctorCheck(ctx *cli.Context) error {
 	stdCtx, cancel := installSignals()
 	defer cancel()
 
diff --git a/cmd/convert.go b/cmd/doctor_convert.go
index 37a260cbd8..2385f23e52 100644
--- a/cmd/convert.go
+++ b/cmd/doctor_convert.go
@@ -13,15 +13,15 @@ import (
 	"github.com/urfave/cli/v2"
 )
 
-// CmdConvert represents the available convert sub-command.
-var CmdConvert = &cli.Command{
+// cmdDoctorConvert represents the available convert sub-command.
+var cmdDoctorConvert = &cli.Command{
 	Name:        "convert",
 	Usage:       "Convert the database",
 	Description: "A command to convert an existing MySQL database from utf8 to utf8mb4 or MSSQL database from varchar to nvarchar",
-	Action:      runConvert,
+	Action:      runDoctorConvert,
 }
 
-func runConvert(ctx *cli.Context) error {
+func runDoctorConvert(ctx *cli.Context) error {
 	stdCtx, cancel := installSignals()
 	defer cancel()
 
diff --git a/cmd/main.go b/cmd/main.go
index b4a38a4523..e44f9382b7 100644
--- a/cmd/main.go
+++ b/cmd/main.go
@@ -11,6 +11,7 @@ import (
 
 	"code.gitea.io/gitea/modules/log"
 	"code.gitea.io/gitea/modules/setting"
+	"code.gitea.io/gitea/modules/util"
 
 	"github.com/urfave/cli/v2"
 )
@@ -23,9 +24,13 @@ func cmdHelp() *cli.Command {
 		Usage:     "Shows a list of commands or help for one command",
 		ArgsUsage: "[command]",
 		Action: func(c *cli.Context) (err error) {
-			args := c.Args()
-			if args.Present() {
-				err = cli.ShowCommandHelp(c, args.First())
+			lineage := c.Lineage() // The order is from child to parent: help, doctor, Gitea, {Command:nil}
+			targetCmdIdx := 0
+			if c.Command.Name == "help" {
+				targetCmdIdx = 1
+			}
+			if lineage[targetCmdIdx+1].Command != nil {
+				err = cli.ShowCommandHelp(lineage[targetCmdIdx+1], lineage[targetCmdIdx].Command.Name)
 			} else {
 				err = cli.ShowAppHelp(c)
 			}
@@ -94,9 +99,8 @@ func prepareSubcommandWithConfig(command *cli.Command, globalFlags []cli.Flag) {
 func prepareWorkPathAndCustomConf(action cli.ActionFunc) func(ctx *cli.Context) error {
 	return func(ctx *cli.Context) error {
 		var args setting.ArgWorkPathAndCustomConf
-		ctxLineage := ctx.Lineage()
-		for i := len(ctxLineage) - 1; i >= 0; i-- {
-			curCtx := ctxLineage[i]
+		// from children to parent, check the global flags
+		for _, curCtx := range ctx.Lineage() {
 			if curCtx.IsSet("work-path") && args.WorkPath == "" {
 				args.WorkPath = curCtx.String("work-path")
 			}
@@ -159,7 +163,6 @@ func NewMainApp() *cli.App {
 		CmdAdmin,
 		CmdMigrate,
 		CmdKeys,
-		CmdConvert,
 		CmdDoctor,
 		CmdManager,
 		CmdEmbedded,
@@ -170,6 +173,10 @@ func NewMainApp() *cli.App {
 		cmdHelp(), // the "help" sub-command was used to show the more information for "work path" and "custom config"
 	}
 
+	cmdConvert := util.ToPointer(*cmdDoctorConvert)
+	cmdConvert.Hidden = true // still support the legacy "./gitea doctor" by the hidden sub-command, remove it in next release
+	subCmdWithConfig = append(subCmdWithConfig, cmdConvert)
+
 	// these sub-commands do not need the config file, and they do not depend on any path or environment variable.
 	subCmdStandalone := []*cli.Command{
 		CmdCert,