help: make help command output less distracting

cmd/help.go

@@ -70,6 +70,9 @@ var helpFlags = &cobra.Command{
 	Short: "Show the global flags for rclone",
 	Run: func(command *cobra.Command, args []string) {
 		command.Flags()
+		if GeneratingDocs {
+			Root.SetUsageTemplate(docFlagsTemplate)
+		} else {
 			if len(args) > 0 {
 				re, err := filter.GlobStringToRegexp(args[0], false)
 				if err != nil {
@@ -78,9 +81,11 @@ var helpFlags = &cobra.Command{
 				fs.Debugf(nil, "Flag filter: %s", re.String())
 				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)
 		}
 		_ = command.Usage()
@@ -152,7 +157,7 @@ func setupRootCommand(rootCmd *cobra.Command) {
 	})
 	cobra.AddTemplateFunc("flagGroups", func(cmd *cobra.Command) []*flags.Group {
 		// 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()
 		cmd.InheritedFlags().VisitAll(func(flag *pflag.Flag) {
 			if _, ok := backendFlags[flag.Name]; ok {
@@ -210,20 +215,16 @@ Aliases:
 Examples:
 {{.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}}
 
 Flags:
 {{.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}}
-{{ end }}{{ end }}
 
+{{ end }}{{ end }}
 Additional help topics:{{range .Commands}}{{if .IsAdditionalHelpTopicCommand}}
   {{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.
 `
 
+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 = `---
 title: "Global Flags"
 description: "Rclone Global Flags"
@@ -245,7 +255,7 @@ split into groups.
 {{ range flagGroups . }}{{ if .Flags.HasFlags }}
 ## {{ .Name }}
 
-{{ .Help }}
+{{ .Help }}.
 
 ` + "```" + `
 {{ .Flags.FlagUsages | trimTrailingWhitespaces}}

fs/config.go

@@ -70,7 +70,7 @@ var ConfigOptionsInfo = Options{{
 	Name:     "checksum",
 	ShortOpt: "c",
 	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",
 }, {
 	Name:    "size_only",

fs/config/flags/flags.go

@@ -111,19 +111,19 @@ var All *Groups
 // Groups of flags for documentation purposes
 func init() {
 	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