Documentation,cmd/dlv: clean up command line usage help (#3395)

Due to some very old mistakes too many of Delve's flags are declared as
persistent on cobra's root command. For example the headless flag is a
global flag but does not apply to connect, dap or trace; the backend
flag does not apply to replay, core and dap; etc.

Almost all global flags should have been declared as local flags on
individual subcommands. Unfortunately we can not change this without
breaking backwards compatibility, for example:

   dlv --headless debug

would not parse if headless was a flag of debug instead of a global
flag.

Instead we alter usage function and the markdown generation script to
strategically hide the flags that don't apply.

Fixes #2361

Documentation/usage/dlv.md

@@ -18,23 +18,7 @@ Pass flags to the program you are debugging using `--`, for example:
 ### Options
 
 ```
-      --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
+  -h, --help   help for dlv
-      --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
-      --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
-      --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
-      --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
-  -h, --help                             help for dlv
-      --init string                      Init file, executed by the terminal client.
-  -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
-      --log                              Enable debugging server logging.
-      --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
-      --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO
@@ -46,7 +30,6 @@ Pass flags to the program you are debugging using `--`, for example:
 * [dlv debug](dlv_debug.md)	 - Compile and begin debugging main package in current directory, or the package specified.
 * [dlv exec](dlv_exec.md)	 - Execute a precompiled binary, and begin a debug session.
 * [dlv replay](dlv_replay.md)	 - Replays a rr trace.
-* [dlv run](dlv_run.md)	 - Deprecated command. Use 'debug' instead.
 * [dlv test](dlv_test.md)	 - Compile test binary and begin debugging program.
 * [dlv trace](dlv_trace.md)	 - Compile and begin tracing program.
 * [dlv version](dlv_version.md)	 - Prints version.

Documentation/usage/dlv_attach.md

@@ -32,9 +32,7 @@ dlv attach pid [executable] [flags]
       --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
       --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
       --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
       --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
       --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
       --init string                      Init file, executed by the terminal client.
   -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
@@ -42,8 +40,6 @@ dlv attach pid [executable] [flags]
       --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
       --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
       --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO

Documentation/usage/dlv_connect.md

@@ -19,22 +19,11 @@ dlv connect addr [flags]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
+      --backend string      Backend selection (see 'dlv help backend'). (default "default")
-      --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
+      --init string         Init file, executed by the terminal client.
-      --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
+      --log                 Enable debugging server logging.
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
+      --log-dest string     Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
+      --log-output string   Comma separated list of components that should produce debug output (see 'dlv help log')
-      --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
-      --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
-      --init string                      Init file, executed by the terminal client.
-  -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
-      --log                              Enable debugging server logging.
-      --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
-      --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO

Documentation/usage/dlv_core.md

@@ -28,10 +28,7 @@ dlv core <executable> <core> [flags]
       --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
       --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
       --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
       --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
       --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
       --init string                      Init file, executed by the terminal client.
   -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
@@ -39,8 +36,6 @@ dlv core <executable> <core> [flags]
       --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
       --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
       --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO

Documentation/usage/dlv_dap.md

@@ -40,22 +40,13 @@ dlv dap [flags]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
+      --check-go-version    Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
+      --disable-aslr        Disables address space randomization
-      --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
+  -l, --listen string       Debugging server listen address. (default "127.0.0.1:0")
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
+      --log                 Enable debugging server logging.
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
+      --log-dest string     Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
+      --log-output string   Comma separated list of components that should produce debug output (see 'dlv help log')
-      --disable-aslr                     Disables address space randomization
+      --only-same-user      Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-      --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
-      --init string                      Init file, executed by the terminal client.
-  -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
-      --log                              Enable debugging server logging.
-      --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
-      --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO

Documentation/usage/dlv_exec.md

@@ -31,7 +31,6 @@ dlv exec <path/to/binary> [flags]
       --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
       --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
       --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
       --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
       --disable-aslr                     Disables address space randomization
       --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.

Documentation/usage/dlv_replay.md

@@ -27,10 +27,7 @@ dlv replay [trace directory] [flags]
       --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
       --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
       --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
       --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --disable-aslr                     Disables address space randomization
       --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
       --init string                      Init file, executed by the terminal client.
   -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
@@ -38,8 +35,6 @@ dlv replay [trace directory] [flags]
       --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
       --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
       --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO

Documentation/usage/dlv_trace.md

@@ -34,22 +34,15 @@ dlv trace [package] regexp [flags]
 ### Options inherited from parent commands
 
 ```
-      --accept-multiclient               Allows a headless server to accept multiple client connections via JSON-RPC or DAP.
+      --backend string         Backend selection (see 'dlv help backend'). (default "default")
-      --allow-non-terminal-interactive   Allows interactive sessions of Delve that don't have a terminal as stdin, stdout and stderr
+      --build-flags string     Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
-      --api-version int                  Selects JSON-RPC API version when headless. New clients should use v2. Can be reset via RPCServer.SetApiVersion. See Documentation/api/json-rpc/README.md. (default 1)
+      --check-go-version       Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
-      --backend string                   Backend selection (see 'dlv help backend'). (default "default")
+      --disable-aslr           Disables address space randomization
-      --build-flags string               Build flags, to be passed to the compiler. For example: --build-flags="-tags=integration -mod=vendor -cover -v"
+      --log                    Enable debugging server logging.
-      --check-go-version                 Exits if the version of Go in use is not compatible (too old or too new) with the version of Delve. (default true)
+      --log-dest string        Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --disable-aslr                     Disables address space randomization
+      --log-output string      Comma separated list of components that should produce debug output (see 'dlv help log')
-      --headless                         Run debug server only, in headless mode. Server will accept both JSON-RPC or DAP client connections.
+  -r, --redirect stringArray   Specifies redirect rules for target process (see 'dlv help redirect')
-      --init string                      Init file, executed by the terminal client.
+      --wd string              Working directory for running the program.
-  -l, --listen string                    Debugging server listen address. (default "127.0.0.1:0")
-      --log                              Enable debugging server logging.
-      --log-dest string                  Writes logs to the specified file or file descriptor (see 'dlv help log').
-      --log-output string                Comma separated list of components that should produce debug output (see 'dlv help log')
-      --only-same-user                   Only connections from the same user that started this instance of Delve are allowed to connect. (default true)
-  -r, --redirect stringArray             Specifies redirect rules for target process (see 'dlv help redirect')
-      --wd string                        Working directory for running the program.
 ```
 
 ### SEE ALSO

Documentation/usage/dlv_version.md

@@ -9,8 +9,7 @@ dlv version [flags]
 ### Options
 
 ```
-  -h, --help      help for version
+  -h, --help   help for version
-  -v, --verbose   print verbose version info
 ```
 
 ### Options inherited from parent commands

_scripts/gen-usage-docs.go

@@ -10,6 +10,7 @@ import (
 	"path/filepath"
 
 	"github.com/go-delve/delve/cmd/dlv/cmds"
+	"github.com/go-delve/delve/cmd/dlv/cmds/helphelpers"
 	"github.com/spf13/cobra/doc"
 )
 
@@ -21,12 +22,19 @@ func main() {
 		usageDir = os.Args[1]
 	}
 	root := cmds.New(true)
+
+	cmdnames := []string{}
+	for _, subcmd := range root.Commands() {
+		cmdnames = append(cmdnames, subcmd.Name())
+	}
+	helphelpers.Prepare(root)
 	doc.GenMarkdownTree(root, usageDir)
+	root = nil
 	// GenMarkdownTree ignores additional help topic commands, so we have to do this manually
-	for _, cmd := range root.Commands() {
+	for _, cmdname := range cmdnames {
-		if cmd.Run == nil {
+		cmd, _, _ := cmds.New(true).Find([]string{cmdname})
-			doc.GenMarkdownTree(cmd, usageDir)
+		helphelpers.Prepare(cmd)
-		}
+		doc.GenMarkdownTree(cmd, usageDir)
 	}
 	fh, err := os.OpenFile(filepath.Join(usageDir, "dlv.md"), os.O_APPEND|os.O_WRONLY, 0)
 	if err != nil {

cmd/dlv/cmds/commands.go

@@ -16,6 +16,7 @@ import (
 	"syscall"
 	"time"
 
+	"github.com/go-delve/delve/cmd/dlv/cmds/helphelpers"
 	"github.com/go-delve/delve/pkg/config"
 	"github.com/go-delve/delve/pkg/gobuild"
 	"github.com/go-delve/delve/pkg/goversion"
@@ -276,6 +277,7 @@ or later, -gcflags="-N -l" on earlier versions of Go.`,
 			fmt.Println("This command is deprecated, please use 'debug' instead.")
 			os.Exit(0)
 		},
+		Hidden: true,
 	}
 	rootCommand.AddCommand(runCommand)
 
@@ -452,6 +454,8 @@ File redirects can also be changed using the 'restart' command.
 
 	rootCommand.DisableAutoGenTag = true
 
+	configUsageFunc(rootCommand)
+
 	return rootCommand
 }
 
@@ -1099,3 +1103,19 @@ func parseRedirects(redirects []string) ([3]string, error) {
 	}
 	return r, nil
 }
+
+func configUsageFunc(cmd *cobra.Command) {
+	for _, subcmd := range cmd.Commands() {
+		configUsageFunc(subcmd)
+	}
+
+	if cmd.Run == nil && cmd.Name() != "dlv" {
+		return
+	}
+
+	usage := cmd.UsageFunc()
+	cmd.SetUsageFunc(func(cmd *cobra.Command) error {
+		helphelpers.Prepare(cmd)
+		return usage(cmd)
+	})
+}

cmd/dlv/cmds/helphelpers/help.go

@@ -0,0 +1,96 @@
+package helphelpers
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/pflag"
+)
+
+// Prepare prepares cmd flag set for the invocation of its usage function by
+// hiding flags that we want cobra to parse but we don't want to show to the
+// user.
+// We do this because not all flags associated with the root command are
+// valid for all subcommands but we don't want to move them out of the root
+// command and into subcommands, since that would change how cobra parses
+// the command line.
+//
+// For example:
+//
+//	dlv --headless debug
+//
+// must parse successfully even though the headless flag is not applicable
+// to the 'connect' subcommand.
+//
+// Prepare is a destructive command, cmd can not be reused after it has been
+// called.
+func Prepare(cmd *cobra.Command) {
+	switch cmd.Name() {
+	case "dlv", "help", "run", "version":
+		hideAllFlags(cmd)
+	case "attach":
+		hideFlag(cmd, "build-flags")
+		hideFlag(cmd, "disable-aslr")
+		hideFlag(cmd, "redirect")
+		hideFlag(cmd, "wd")
+	case "connect":
+		hideFlag(cmd, "accept-multiclient")
+		hideFlag(cmd, "allow-non-terminal-interactive")
+		hideFlag(cmd, "api-version")
+		hideFlag(cmd, "build-flags")
+		hideFlag(cmd, "check-go-version")
+		hideFlag(cmd, "disable-aslr")
+		hideFlag(cmd, "headless")
+		hideFlag(cmd, "listen")
+		hideFlag(cmd, "only-same-user")
+		hideFlag(cmd, "redirect")
+		hideFlag(cmd, "wd")
+	case "dap":
+		hideFlag(cmd, "headless")
+		hideFlag(cmd, "accept-multiclient")
+		hideFlag(cmd, "init")
+		hideFlag(cmd, "backend")
+		hideFlag(cmd, "build-flags")
+		hideFlag(cmd, "wd")
+		hideFlag(cmd, "redirect")
+		hideFlag(cmd, "api-version")
+		hideFlag(cmd, "allow-non-terminal-interactive")
+	case "debug", "test":
+		// All flags apply
+	case "exec":
+		hideFlag(cmd, "build-flags")
+	case "replay", "core":
+		hideFlag(cmd, "backend")
+		hideFlag(cmd, "build-flags")
+		hideFlag(cmd, "disable-aslr")
+		hideFlag(cmd, "redirect")
+		hideFlag(cmd, "wd")
+	case "trace":
+		hideFlag(cmd, "accept-multiclient")
+		hideFlag(cmd, "allow-non-terminal-interactive")
+		hideFlag(cmd, "api-version")
+		hideFlag(cmd, "headless")
+		hideFlag(cmd, "init")
+		hideFlag(cmd, "listen")
+		hideFlag(cmd, "only-same-user")
+	}
+}
+
+func hideAllFlags(cmd *cobra.Command) {
+	cmd.PersistentFlags().VisitAll(func(flag *pflag.Flag) {
+		flag.Hidden = true
+	})
+	cmd.Flags().VisitAll(func(flag *pflag.Flag) {
+		flag.Hidden = true
+	})
+}
+
+func hideFlag(cmd *cobra.Command, name string) {
+	if cmd == nil {
+		return
+	}
+	flag := cmd.Flags().Lookup(name)
+	if flag != nil {
+		flag.Hidden = true
+		return
+	}
+	hideFlag(cmd.Parent(), name)
+}

go.mod

@@ -15,6 +15,7 @@ require (
 	github.com/mattn/go-runewidth v0.0.13 // indirect
 	github.com/sirupsen/logrus v1.6.0
 	github.com/spf13/cobra v1.1.3
+	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/stretchr/testify v1.7.0 // indirect
 	go.starlark.net v0.0.0-20220816155156-cfacd8902214
 	golang.org/x/arch v0.0.0-20190927153633-4e8777c89be4

vendor/modules.txt

@@ -55,6 +55,7 @@ github.com/sirupsen/logrus
 github.com/spf13/cobra
 github.com/spf13/cobra/doc
 # github.com/spf13/pflag v1.0.5
+## explicit
 github.com/spf13/pflag
 # github.com/stretchr/testify v1.7.0
 ## explicit