Refactor path & config system (#25330)

# The problem

There were many "path tricks":

* By default, Gitea uses its program directory as its work path
* Gitea tries to use the "work path" to guess its "custom path" and
"custom conf (app.ini)"
* Users might want to use other directories as work path
* The non-default work path should be passed to Gitea by GITEA_WORK_DIR
or "--work-path"
* But some Gitea processes are started without these values
    * The "serv" process started by OpenSSH server
    * The CLI sub-commands started by site admin
* The paths are guessed by SetCustomPathAndConf again and again
* The default values of "work path / custom path / custom conf" can be
changed when compiling

# The solution

* Use `InitWorkPathAndCommonConfig` to handle these path tricks, and use
test code to cover its behaviors.
* When Gitea's web server runs, write the WORK_PATH to "app.ini", this
value must be the most correct one, because if this value is not right,
users would find that the web UI doesn't work and then they should be
able to fix it.
* Then all other sub-commands can use the WORK_PATH in app.ini to
initialize their paths.
* By the way, when Gitea starts for git protocol, it shouldn't output
any log, otherwise the git protocol gets broken and client blocks
forever.

The "work path" priority is: WORK_PATH in app.ini > cmd arg --work-path
> env var GITEA_WORK_DIR > builtin default

The "app.ini" searching order is: cmd arg --config > cmd arg "work path
/ custom path" > env var "work path / custom path" > builtin default


## ⚠️ BREAKING

If your instance's "work path / custom path / custom conf" doesn't meet
the requirements (eg: work path must be absolute), Gitea will report a
fatal error and exit. You need to set these values according to the
error log.



----

Close #24818
Close #24222
Close #21606
Close #21498
Close #25107
Close #24981
Maybe close #24503

Replace #23301
Replace #22754

And maybe more

1 files changed, 81 insertions, 88 deletions

diff --git a/main.go b/main.go
index 49093eb8a7..1c87824c83 100644
--- a/main.go
+++ b/main.go
@@ -33,30 +33,58 @@ var (
 	Tags = ""
 	// MakeVersion holds the current Make version if built with make
 	MakeVersion = ""
-
-	originalAppHelpTemplate        = ""
-	originalCommandHelpTemplate    = ""
-	originalSubcommandHelpTemplate = ""
 )
 
 func init() {
 	setting.AppVer = Version
 	setting.AppBuiltWith = formatBuiltWith()
 	setting.AppStartTime = time.Now().UTC()
+}
 
-	// Grab the original help templates
-	originalAppHelpTemplate = cli.AppHelpTemplate
-	originalCommandHelpTemplate = cli.CommandHelpTemplate
-	originalSubcommandHelpTemplate = cli.SubcommandHelpTemplate
+// cmdHelp is our own help subcommand with more information
+// test cases:
+// ./gitea help
+// ./gitea -h
+// ./gitea web help
+// ./gitea web -h (due to cli lib limitation, this won't call our cmdHelp, so no extra info)
+// ./gitea admin help auth
+// ./gitea -c /tmp/app.ini -h
+// ./gitea -c /tmp/app.ini help
+// ./gitea help -c /tmp/app.ini
+// GITEA_WORK_DIR=/tmp ./gitea help
+// GITEA_WORK_DIR=/tmp ./gitea help --work-path /tmp/other
+// GITEA_WORK_DIR=/tmp ./gitea help --config /tmp/app-other.ini
+var cmdHelp = cli.Command{
+	Name:      "help",
+	Aliases:   []string{"h"},
+	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())
+		} else {
+			err = cli.ShowAppHelp(c)
+		}
+		_, _ = fmt.Fprintf(c.App.Writer, `
+DEFAULT CONFIGURATION:
+   AppPath:    %s
+   WorkPath:   %s
+   CustomPath: %s
+   ConfigFile: %s
+
+`, setting.AppPath, setting.AppWorkPath, setting.CustomPath, setting.CustomConf)
+		return err
+	},
 }
 
 func main() {
 	app := cli.NewApp()
 	app.Name = "Gitea"
 	app.Usage = "A painless self-hosted Git service"
-	app.Description = `By default, gitea will start serving using the webserver with no
-arguments - which can alternatively be run by running the subcommand web.`
+	app.Description = `By default, Gitea will start serving using the web-server with no argument, which can alternatively be run by running the subcommand "web".`
 	app.Version = Version + formatBuiltWith()
+	app.EnableBashCompletion = true
 	app.Commands = []cli.Command{
 		cmd.CmdWeb,
 		cmd.CmdServ,
@@ -77,118 +105,83 @@ arguments - which can alternatively be run by running the subcommand web.`
 		cmd.CmdRestoreRepository,
 		cmd.CmdActions,
 	}
-	// Now adjust these commands to add our global configuration options
-
-	// First calculate the default paths and set the AppHelpTemplates in this context
-	setting.SetCustomPathAndConf("", "", "")
-	setAppHelpTemplates()
 
 	// default configuration flags
-	defaultFlags := []cli.Flag{
+	globalFlags := []cli.Flag{
+		cli.HelpFlag,
 		cli.StringFlag{
 			Name:  "custom-path, C",
-			Value: setting.CustomPath,
-			Usage: "Custom path file path",
+			Usage: "Set custom path (defaults to '{WorkPath}/custom')",
 		},
 		cli.StringFlag{
 			Name:  "config, c",
 			Value: setting.CustomConf,
-			Usage: "Custom configuration file path",
+			Usage: "Set custom config file (defaults to '{WorkPath}/custom/conf/app.ini')",
 		},
-		cli.VersionFlag,
 		cli.StringFlag{
 			Name:  "work-path, w",
-			Value: setting.AppWorkPath,
-			Usage: "Set the gitea working path",
+			Usage: "Set Gitea's working path (defaults to the Gitea's binary directory)",
 		},
 	}
 
 	// Set the default to be equivalent to cmdWeb and add the default flags
+	app.Flags = append(app.Flags, globalFlags...)
 	app.Flags = append(app.Flags, cmd.CmdWeb.Flags...)
-	app.Flags = append(app.Flags, defaultFlags...)
-	app.Action = cmd.CmdWeb.Action
-
-	// Add functions to set these paths and these flags to the commands
-	app.Before = establishCustomPath
+	app.Action = prepareWorkPathAndCustomConf(cmd.CmdWeb.Action)
+	app.HideHelp = true // use our own help action to show helps (with more information like default config)
+	app.Commands = append(app.Commands, cmdHelp)
 	for i := range app.Commands {
-		setFlagsAndBeforeOnSubcommands(&app.Commands[i], defaultFlags, establishCustomPath)
+		prepareSubcommands(&app.Commands[i], globalFlags)
 	}
 
-	app.EnableBashCompletion = true
-
 	err := app.Run(os.Args)
 	if err != nil {
-		log.Fatal("Failed to run app with %s: %v", os.Args, err)
+		_, _ = fmt.Fprintf(app.Writer, "\nFailed to run with %s: %v\n", os.Args, err)
 	}
 
 	log.GetManager().Close()
 }
 
-func setFlagsAndBeforeOnSubcommands(command *cli.Command, defaultFlags []cli.Flag, before cli.BeforeFunc) {
+func prepareSubcommands(command *cli.Command, defaultFlags []cli.Flag) {
 	command.Flags = append(command.Flags, defaultFlags...)
-	command.Before = establishCustomPath
+	command.Action = prepareWorkPathAndCustomConf(command.Action)
+	command.HideHelp = true
+	if command.Name != "help" {
+		command.Subcommands = append(command.Subcommands, cmdHelp)
+	}
 	for i := range command.Subcommands {
-		setFlagsAndBeforeOnSubcommands(&command.Subcommands[i], defaultFlags, before)
+		prepareSubcommands(&command.Subcommands[i], defaultFlags)
 	}
 }
 
-func establishCustomPath(ctx *cli.Context) error {
-	var providedCustom string
-	var providedConf string
-	var providedWorkPath string
-
-	currentCtx := ctx
-	for {
-		if len(providedCustom) != 0 && len(providedConf) != 0 && len(providedWorkPath) != 0 {
-			break
-		}
-		if currentCtx == nil {
-			break
-		}
-		if currentCtx.IsSet("custom-path") && len(providedCustom) == 0 {
-			providedCustom = currentCtx.String("custom-path")
-		}
-		if currentCtx.IsSet("config") && len(providedConf) == 0 {
-			providedConf = currentCtx.String("config")
+// prepareWorkPathAndCustomConf wraps the Action to prepare the work path and custom config
+// It can't use "Before", because each level's sub-command's Before will be called one by one, so the "init" would be done multiple times
+func prepareWorkPathAndCustomConf(a any) func(ctx *cli.Context) error {
+	if a == nil {
+		return nil
+	}
+	action := a.(func(*cli.Context) error)
+	return func(ctx *cli.Context) error {
+		var args setting.ArgWorkPathAndCustomConf
+		curCtx := ctx
+		for curCtx != nil {
+			if curCtx.IsSet("work-path") && args.WorkPath == "" {
+				args.WorkPath = curCtx.String("work-path")
+			}
+			if curCtx.IsSet("custom-path") && args.CustomPath == "" {
+				args.CustomPath = curCtx.String("custom-path")
+			}
+			if curCtx.IsSet("config") && args.CustomConf == "" {
+				args.CustomConf = curCtx.String("config")
+			}
+			curCtx = curCtx.Parent()
 		}
-		if currentCtx.IsSet("work-path") && len(providedWorkPath) == 0 {
-			providedWorkPath = currentCtx.String("work-path")
+		setting.InitWorkPathAndCommonConfig(os.Getenv, args)
+		if ctx.Bool("help") {
+			return cmdHelp.Action.(func(ctx *cli.Context) error)(ctx)
 		}
-		currentCtx = currentCtx.Parent()
-
-	}
-	setting.SetCustomPathAndConf(providedCustom, providedConf, providedWorkPath)
-
-	setAppHelpTemplates()
-
-	if ctx.IsSet("version") {
-		cli.ShowVersion(ctx)
-		os.Exit(0)
-	}
-
-	return nil
-}
-
-func setAppHelpTemplates() {
-	cli.AppHelpTemplate = adjustHelpTemplate(originalAppHelpTemplate)
-	cli.CommandHelpTemplate = adjustHelpTemplate(originalCommandHelpTemplate)
-	cli.SubcommandHelpTemplate = adjustHelpTemplate(originalSubcommandHelpTemplate)
-}
-
-func adjustHelpTemplate(originalTemplate string) string {
-	overridden := ""
-	if _, ok := os.LookupEnv("GITEA_CUSTOM"); ok {
-		overridden = "(GITEA_CUSTOM)"
+		return action(ctx)
 	}
-
-	return fmt.Sprintf(`%s
-DEFAULT CONFIGURATION:
-     CustomPath:  %s %s
-     CustomConf:  %s
-     AppPath:     %s
-     AppWorkPath: %s
-
-`, originalTemplate, setting.CustomPath, overridden, setting.CustomConf, setting.AppPath, setting.AppWorkPath)
 }
 
 func formatBuiltWith() string {