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

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()
 

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()
 

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,

docs/content/doc/administration/command-line.en-us.md

@@ -388,35 +388,18 @@ NB: Gitea must be running for this command to succeed.
 Migrates the database. This command can be used to run other commands before starting the server for the first time.
 This command is idempotent.
 
-### convert
+### doctor check
 
-Converts an existing MySQL database from utf8 to utf8mb4.
+Diagnose and potentially fix problems with the current Gitea instance.
+Several checks are run by default, but additional ones can be run:
 
-### doctor
+- `gitea doctor check --list` - will list all the available checks
+- `gitea doctor check --all` - will run all available checks
+- `gitea doctor check --default` - will run the default checks
+- `gitea doctor check --run [check(s),]...` - will run the named checks
 
-Diagnose the problems of current Gitea instance according the given configuration.
-Currently there are a check list below:
-
-- Check if OpenSSH authorized_keys file id correct
-  When your Gitea instance support OpenSSH, your Gitea instance binary path will be written to `authorized_keys`
-  when there is any public key added or changed on your Gitea instance.
-  Sometimes if you moved or renamed your Gitea binary when upgrade and you haven't run `Update the '.ssh/authorized_keys' file with Gitea SSH keys. (Not needed for the built-in SSH server.)` on your Admin Panel. Then all pull/push via SSH will not be work.
-  This check will help you to check if it works well.
-
-For contributors, if you want to add more checks, you can write a new function like `func(ctx *cli.Context) ([]string, error)` and
-append it to `doctor.go`.
-
-```go
-var checklist = []check{
-	{
-		title: "Check if OpenSSH authorized_keys file id correct",
-		f:     runDoctorLocationMoved,
-    },
-    // more checks please append here
-}
-```
-
-This function will receive a command line context and return a list of details about the problems or error.
+Some problems can be automatically fixed by passing the `--fix` option.
+Extra logging can be set with `--log-file=...`.
 
 #### doctor recreate-table
 
@@ -448,6 +431,10 @@ gitea doctor recreate-table
 
 It is highly recommended to back-up your database before running these commands.
 
+### doctor convert
+
+Converts a MySQL database from utf8 to utf8mb4 or a MSSQL database from varchar to nvarchar.
+
 ### manager
 
 Manage running server operations:

docs/content/doc/administration/command-line.zh-cn.md

@@ -361,32 +361,18 @@ AuthorizedKeysCommand /path/to/gitea keys -e git -u %u -t %t -k %k
 
 迁移数据库。该命令可用于在首次启动服务器之前运行其他命令。此命令是幂等的。
 
-### convert
+### doctor check
 
-将现有的 MySQL 数据库从 utf8 转换为 utf8mb4。
+对 Gitea 实例进行诊断，可以修复一些可修复的问题。
+默认只运行部分检查，额外的检查可以参考：
 
-### doctor
+- `gitea doctor check --list` - 列出所有可用的检查
+- `gitea doctor check --all` - 运行所有可用的检查
+- `gitea doctor check --default` - 运行默认的检查
+- `gitea doctor check --run [check(s),]...` - 运行指定的名字的检查
 
-根据给定的配置诊断当前 Gitea 实例的问题。目前有以下检查清单:
-
-- 检查 OpenSSH 的 authorized_keys 文件是否正确
-  当您的 Gitea 实例支持 OpenSSH 时，当您的 Gitea 实例添加或更改任何公钥时，Gitea 实例的二进制路径将被写入 `authorized_keys` 文件。
-  有时，如果您在升级时移动或重命名了 Gitea 二进制文件，并且您没有在管理面板上运行“使用 Gitea 的 SSH 密钥更新「.ssh/authorized_keys」文件”操作。那么通过 SSH 的所有拉取/推送操作将无法正常工作。
-  此检查将帮助您检查它是否正常工作。
-
-对于贡献者，如果您想添加更多的检查项，您可以编写一个新的函数，如 `func(ctx *cli.Context) ([]string, error)`，并将其追加到 `doctor.go` 文件中。
-
-```go
-var checklist = []check{
-	{
-		title: "Check if OpenSSH authorized_keys file id correct",
-		f:     runDoctorLocationMoved,
-    },
-    // more checks please append here
-}
-```
-
-此函数将接收一个命令行上下文，并返回有关问题或错误的详细信息列表。
+有些问题可以通过设置 `--fix` 选项进行自动修复。
+额外的日志可以通过 `--log-file=...` 进行设置。
 
 #### doctor recreate-table
 
@@ -416,6 +402,10 @@ gitea doctor recreate-table
 
 强烈建议在运行这些命令之前备份您的数据库。
 
+### doctor convert
+
+将现有的 MySQL 数据库从 utf8 转换为 utf8mb4，或者把 MSSQL 数据库从 varchar 转换为 nvarchar。
+
 ### manager
 
 管理运行中的服务器操作：