Merge pull request #1430 from FGYFFFF/fix/stop_auto_sort_for_help

fix: stop automatic sorting for --help

app.go

@@ -229,7 +229,9 @@ func (a *App) Setup() {
 	a.flagCategories = newFlagCategories()
 	for _, fl := range a.Flags {
 		if cf, ok := fl.(CategorizableFlag); ok {
-			a.flagCategories.AddFlag(cf.GetCategory(), cf)
+			if cf.GetCategory() != "" {
+				a.flagCategories.AddFlag(cf.GetCategory(), cf)
+			}
 		}
 	}
 

app_test.go

@@ -144,8 +144,8 @@ func ExampleApp_Run_appHelp() {
 	//    help, h        Shows a list of commands or help for one command
 	//
 	// GLOBAL OPTIONS:
-	//    --help, -h     show help (default: false)
 	//    --name value   a name to say (default: "bob")
+	//    --help, -h     show help (default: false)
 	//    --version, -v  print the version (default: false)
 }
 
@@ -177,7 +177,7 @@ func ExampleApp_Run_commandHelp() {
 	//    greet describeit - use it to see a description
 	//
 	// USAGE:
-	//    greet describeit [arguments...]
+	//    greet describeit [command options] [arguments...]
 	//
 	// DESCRIPTION:
 	//    This is how we describe describeit the function
@@ -2242,10 +2242,33 @@ func TestApp_VisibleCategories(t *testing.T) {
 }
 
 func TestApp_VisibleFlagCategories(t *testing.T) {
-	app := &App{}
+	app := &App{
+		Flags: []Flag{
+			&StringFlag{
+				Name: "strd", // no category set
+			},
+			&Int64Flag{
+				Name:     "intd",
+				Aliases:  []string{"altd1", "altd2"},
+				Category: "cat1",
+			},
+		},
+	}
+	app.Setup()
 	vfc := app.VisibleFlagCategories()
-	if len(vfc) != 0 {
+	if len(vfc) != 1 {
-		t.Errorf("unexpected visible flag categories %+v", vfc)
+		t.Fatalf("unexpected visible flag categories %+v", vfc)
+	}
+	if vfc[0].Name() != "cat1" {
+		t.Errorf("expected category name cat1 got %s", vfc[0].Name())
+	}
+	if len(vfc[0].Flags()) != 1 {
+		t.Fatalf("expected flag category to have just one flag got %+v", vfc[0].Flags())
+	}
+
+	fl := vfc[0].Flags()[0]
+	if !reflect.DeepEqual(fl.Names(), []string{"intd", "altd1", "altd2"}) {
+		t.Errorf("unexpected flag %+v", fl.Names())
 	}
 }
 

category.go

@@ -102,7 +102,9 @@ func newFlagCategoriesFromFlags(fs []Flag) FlagCategories {
 	fc := newFlagCategories()
 	for _, fl := range fs {
 		if cf, ok := fl.(CategorizableFlag); ok {
-			fc.AddFlag(cf.GetCategory(), cf)
+			if cf.GetCategory() != "" {
+				fc.AddFlag(cf.GetCategory(), cf)
+			}
 		}
 	}
 

command.go

@@ -309,12 +309,7 @@ func (c *Command) VisibleCommands() []*Command {
 // VisibleFlagCategories returns a slice containing all the visible flag categories with the flags they contain
 func (c *Command) VisibleFlagCategories() []VisibleFlagCategory {
 	if c.flagCategories == nil {
-		c.flagCategories = newFlagCategories()
+		c.flagCategories = newFlagCategoriesFromFlags(c.Flags)
-		for _, fl := range c.Flags {
-			if cf, ok := fl.(CategorizableFlag); ok {
-				c.flagCategories.AddFlag(cf.GetCategory(), cf)
-			}
-		}
 	}
 	return c.flagCategories.VisibleCategories()
 }

command_test.go

@@ -6,6 +6,7 @@ import (
 	"flag"
 	"fmt"
 	"io/ioutil"
+	"reflect"
 	"strings"
 	"testing"
 )
@@ -449,3 +450,37 @@ func TestCommand_VisibleSubcCommands(t *testing.T) {
 
 	expect(t, c.VisibleCommands(), []*Command{subc1, subc3})
 }
+
+func TestCommand_VisibleFlagCategories(t *testing.T) {
+
+	c := &Command{
+		Name:  "bar",
+		Usage: "this is for testing",
+		Flags: []Flag{
+			&StringFlag{
+				Name: "strd", // no category set
+			},
+			&Int64Flag{
+				Name:     "intd",
+				Aliases:  []string{"altd1", "altd2"},
+				Category: "cat1",
+			},
+		},
+	}
+
+	vfc := c.VisibleFlagCategories()
+	if len(vfc) != 1 {
+		t.Fatalf("unexpected visible flag categories %+v", vfc)
+	}
+	if vfc[0].Name() != "cat1" {
+		t.Errorf("expected category name cat1 got %s", vfc[0].Name())
+	}
+	if len(vfc[0].Flags()) != 1 {
+		t.Fatalf("expected flag category to have just one flag got %+v", vfc[0].Flags())
+	}
+
+	fl := vfc[0].Flags()[0]
+	if !reflect.DeepEqual(fl.Names(), []string{"intd", "altd1", "altd2"}) {
+		t.Errorf("unexpected flag %+v", fl.Names())
+	}
+}

docs/v2/examples/flags.md

@@ -239,7 +239,7 @@ For example this:
 
 <!-- {
   "args": ["&#45;&#45;help"],
-  "output": ".*Load configuration from FILE\n.*\n.*Language for the greeting.*"
+  "output": ".*Load configuration from FILE\n.*Language for the greeting.*"
 } -->
 ```go
 package main

godoc-current.txt

@@ -73,7 +73,8 @@ DESCRIPTION:
 
 OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
 
-OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}`
+OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
+`
     CommandHelpTemplate is the text template for the command help topic. cli.go
     uses text/template to render templates. You can render custom help text by
     setting this variable.
@@ -144,7 +145,8 @@ COMMANDS:{{template "visibleCommandTemplate" .}}{{end}}{{if .VisibleFlagCategori
 
 OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
 
-OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}`
+OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
+`
     SubcommandHelpTemplate is the text template for the subcommand help topic.
     cli.go uses text/template to render templates. You can render custom help
     text by setting this variable.

help.go

@@ -242,11 +242,7 @@ func ShowCommandHelp(ctx *Context, command string) error {
 				c.Subcommands = append(c.Subcommands, helpCommandDontUse)
 			}
 			if !ctx.App.HideHelp && HelpFlag != nil {
-				if c.flagCategories == nil {
+				c.appendFlag(HelpFlag)
-					c.flagCategories = newFlagCategoriesFromFlags([]Flag{HelpFlag})
-				} else {
-					c.flagCategories.AddFlag("", HelpFlag)
-				}
 			}
 			templ := c.CustomHelpTemplate
 			if templ == "" {

help_test.go

@@ -1366,7 +1366,8 @@ DESCRIPTION:
    case
 
 OPTIONS:
-   --help, -h  show help (default: false)
+   --help, -h show help
+      (default: false)
 `
 
 	if output.String() != expected {
@@ -1435,7 +1436,8 @@ USAGE:
    even more
 
 OPTIONS:
-   --help, -h  show help (default: false)
+   --help, -h show help
+      (default: false)
 `
 
 	if output.String() != expected {
@@ -1510,8 +1512,10 @@ USAGE:
    even more
 
 OPTIONS:
-   --help, -h      show help (default: false)
+   --test-f value my test
-   --test-f value  my test usage
+      usage
+   --help, -h show help
+      (default: false)
 `
 
 	if output.String() != expected {

template.go

@@ -18,8 +18,8 @@ var visibleFlagCategoryTemplate = `{{range .VisibleFlagCategories}}
 {{else}}{{$e}}
    {{end}}{{end}}{{end}}`
 
-var visibleFlagTemplate = `{{range $index, $option := .VisibleFlags}}{{if $index}}{{end}}
+var visibleFlagTemplate = `{{range $i, $e := .VisibleFlags}}
-   {{wrap $option.String 6}}{{end}}`
+   {{wrap $e.String 6}}{{end}}`
 
 var versionTemplate = `{{if .Version}}{{if not .HideVersion}}
 
@@ -73,7 +73,8 @@ DESCRIPTION:
 
 OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
 
-OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}`
+OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
+`
 
 // SubcommandHelpTemplate is the text template for the subcommand help topic.
 // cli.go uses text/template to render templates. You can
@@ -91,7 +92,8 @@ COMMANDS:{{template "visibleCommandTemplate" .}}{{end}}{{if .VisibleFlagCategori
 
 OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
 
-OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}`
+OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
+`
 
 var MarkdownDocTemplate = `{{if gt .SectionNum 0}}% {{ .App.Name }} {{ .SectionNum }}
 

testdata/godoc-v2.x.txt

@@ -73,7 +73,8 @@ DESCRIPTION:
 
 OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
 
-OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}`
+OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
+`
     CommandHelpTemplate is the text template for the command help topic. cli.go
     uses text/template to render templates. You can render custom help text by
     setting this variable.
@@ -144,7 +145,8 @@ COMMANDS:{{template "visibleCommandTemplate" .}}{{end}}{{if .VisibleFlagCategori
 
 OPTIONS:{{template "visibleFlagCategoryTemplate" .}}{{else if .VisibleFlags}}
 
-OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}`
+OPTIONS:{{template "visibleFlagTemplate" .}}{{end}}
+`
     SubcommandHelpTemplate is the text template for the subcommand help topic.
     cli.go uses text/template to render templates. You can render custom help
     text by setting this variable.