help: make help command output less distracting

This commit is contained in:
albertony 2024-08-10 16:50:20 +02:00
parent 482bfae8fa
commit 498abcc062
3 changed files with 41 additions and 31 deletions

View file

@ -70,6 +70,9 @@ var helpFlags = &cobra.Command{
Short: "Show the global flags for rclone", Short: "Show the global flags for rclone",
Run: func(command *cobra.Command, args []string) { Run: func(command *cobra.Command, args []string) {
command.Flags() command.Flags()
if GeneratingDocs {
Root.SetUsageTemplate(docFlagsTemplate)
} else {
if len(args) > 0 { if len(args) > 0 {
re, err := filter.GlobStringToRegexp(args[0], false) re, err := filter.GlobStringToRegexp(args[0], false)
if err != nil { if err != nil {
@ -78,9 +81,11 @@ var helpFlags = &cobra.Command{
fs.Debugf(nil, "Flag filter: %s", re.String()) fs.Debugf(nil, "Flag filter: %s", re.String())
filterFlagsRe = re filterFlagsRe = re
} }
if GeneratingDocs { if filterFlagsGroup != "" {
Root.SetUsageTemplate(docFlagsTemplate) Root.SetUsageTemplate(filterFlagsSingleGroupTemplate)
} else { } else if len(args) > 0 {
Root.SetUsageTemplate(filterFlagsMultiGroupTemplate)
}
Root.SetOutput(os.Stdout) Root.SetOutput(os.Stdout)
} }
_ = command.Usage() _ = command.Usage()
@ -152,7 +157,7 @@ func setupRootCommand(rootCmd *cobra.Command) {
}) })
cobra.AddTemplateFunc("flagGroups", func(cmd *cobra.Command) []*flags.Group { cobra.AddTemplateFunc("flagGroups", func(cmd *cobra.Command) []*flags.Group {
// Add the backend flags and check all flags // Add the backend flags and check all flags
backendGroup := flags.All.NewGroup("Backend", "Backend only flags. These can be set in the config file also.") backendGroup := flags.All.NewGroup("Backend", "Backend-only flags (these can be set in the config file also)")
allRegistered := flags.All.AllRegistered() allRegistered := flags.All.AllRegistered()
cmd.InheritedFlags().VisitAll(func(flag *pflag.Flag) { cmd.InheritedFlags().VisitAll(func(flag *pflag.Flag) {
if _, ok := backendFlags[flag.Name]; ok { if _, ok := backendFlags[flag.Name]; ok {
@ -210,20 +215,16 @@ Aliases:
Examples: Examples:
{{.Example}}{{end}}{{if and (showCommands .) .HasAvailableSubCommands}} {{.Example}}{{end}}{{if and (showCommands .) .HasAvailableSubCommands}}
Available Commands:{{range .Commands}}{{if (or .IsAvailableCommand (eq .Name "help"))}} Available commands:{{range .Commands}}{{if (or .IsAvailableCommand (eq .Name "help"))}}
{{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if and (showLocalFlags .) .HasAvailableLocalFlags}} {{rpad .Name .NamePadding }} {{.Short}}{{end}}{{end}}{{end}}{{if and (showLocalFlags .) .HasAvailableLocalFlags}}
Flags: Flags:
{{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if and (showGlobalFlags .) .HasAvailableInheritedFlags}} {{.LocalFlags.FlagUsages | trimTrailingWhitespaces}}{{end}}{{if and (showGlobalFlags .) .HasAvailableInheritedFlags}}
{{ range flagGroups . }}{{ if .Flags.HasFlags }} {{ range flagGroups . }}{{ if .Flags.HasFlags }}{{ .Help }} (flag group {{ .Name }}):
# {{ .Name }} Flags
{{ .Help }}
{{ .Flags.FlagUsages | trimTrailingWhitespaces}} {{ .Flags.FlagUsages | trimTrailingWhitespaces}}
{{ end }}{{ end }}
{{ end }}{{ end }}
Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}} Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
{{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}} {{rpad .CommandPath .CommandPathPadding}} {{.Short}}{{end}}{{end}}{{end}}
@ -232,6 +233,15 @@ Use "rclone help flags" for to see the global flags.
Use "rclone help backends" for a list of supported services. Use "rclone help backends" for a list of supported services.
` `
var filterFlagsSingleGroupTemplate = `{{ range flagGroups . }}{{ if .Flags.HasFlags }}{{ .Flags.FlagUsages | trimTrailingWhitespaces}}
{{ end }}{{ end }}
`
var filterFlagsMultiGroupTemplate = `{{ range flagGroups . }}{{ if .Flags.HasFlags }}{{ .Help }} (flag group {{ .Name }}):
{{ .Flags.FlagUsages | trimTrailingWhitespaces}}
{{ end }}{{ end }}`
var docFlagsTemplate = `--- var docFlagsTemplate = `---
title: "Global Flags" title: "Global Flags"
description: "Rclone Global Flags" description: "Rclone Global Flags"
@ -245,7 +255,7 @@ split into groups.
{{ range flagGroups . }}{{ if .Flags.HasFlags }} {{ range flagGroups . }}{{ if .Flags.HasFlags }}
## {{ .Name }} ## {{ .Name }}
{{ .Help }} {{ .Help }}.
` + "```" + ` ` + "```" + `
{{ .Flags.FlagUsages | trimTrailingWhitespaces}} {{ .Flags.FlagUsages | trimTrailingWhitespaces}}

View file

@ -70,7 +70,7 @@ var ConfigOptionsInfo = Options{{
Name: "checksum", Name: "checksum",
ShortOpt: "c", ShortOpt: "c",
Default: false, Default: false,
Help: "Check for changes with size & checksum (if available, or fallback to size only).", Help: "Check for changes with size & checksum (if available, or fallback to size only)",
Groups: "Copy", Groups: "Copy",
}, { }, {
Name: "size_only", Name: "size_only",

View file

@ -111,19 +111,19 @@ var All *Groups
// Groups of flags for documentation purposes // Groups of flags for documentation purposes
func init() { func init() {
All = NewGroups() All = NewGroups()
All.NewGroup("Copy", "Flags for anything which can Copy a file.") All.NewGroup("Copy", "Flags for anything which can copy a file")
All.NewGroup("Sync", "Flags just used for `rclone sync`.") All.NewGroup("Sync", "Flags used for sync commands")
All.NewGroup("Important", "Important flags useful for most commands.") All.NewGroup("Important", "Important flags useful for most commands")
All.NewGroup("Check", "Flags used for `rclone check`.") All.NewGroup("Check", "Flags used for check commands")
All.NewGroup("Networking", "General networking and HTTP stuff.") All.NewGroup("Networking", "Flags for general networking and HTTP stuff")
All.NewGroup("Performance", "Flags helpful for increasing performance.") All.NewGroup("Performance", "Flags helpful for increasing performance")
All.NewGroup("Config", "General configuration of rclone.") All.NewGroup("Config", "Flags for general configuration of rclone")
All.NewGroup("Debugging", "Flags for developers.") All.NewGroup("Debugging", "Flags for developers")
All.NewGroup("Filter", "Flags for filtering directory listings.") All.NewGroup("Filter", "Flags for filtering directory listings")
All.NewGroup("Listing", "Flags for listing directories.") All.NewGroup("Listing", "Flags for listing directories")
All.NewGroup("Logging", "Logging and statistics.") All.NewGroup("Logging", "Flags for logging and statistics")
All.NewGroup("Metadata", "Flags to control metadata.") All.NewGroup("Metadata", "Flags to control metadata")
All.NewGroup("RC", "Flags to control the Remote Control API.") All.NewGroup("RC", "Flags to control the Remote Control API")
} }
// installFlag constructs a name from the flag passed in and // installFlag constructs a name from the flag passed in and