Confusing "Help" Results

[kenji-isuntv]

This issue may be related to #163.

Here is the source code (bug.go, also available at The Go Playground) for the bug report:

package main

import (
	"os"

	"gopkg.in/urfave/cli.v1"
)

func dummyAction(_ *cli.Context) error {
	return nil
}

var (
	command1 = cli.Command{
		Name:        "command1",
		Usage:       "command1.Usage",
		Description: "command1.Description",
		Subcommands: []cli.Command{
			{
				Action:      dummyAction,
				Name:        "action1",
				Usage:       "command1action1.Usage",
				ArgsUsage:   "<arg1>",
				Description: "command1action1.Description",
			},
			{
				Action:      dummyAction,
				Name:        "action2",
				Usage:       "command1action2.Usage",
				ArgsUsage:   "<arg1> [<arg2>]",
				Description: "command1action2.Description",
			},
			{
				Action:      dummyAction,
				Name:        "action3",
				Usage:       "command1action3.Usage",
				ArgsUsage:   "<arg1> [<arg2>]...",
				Description: "command1action3.Description",
			},
		},
	}
	command2 = cli.Command{
		Action:      dummyAction,
		Name:        "command2",
		Usage:       "command2.Usage",
		Description: "command2.Description",
		Subcommands: []cli.Command{
			{
				Action:      dummyAction,
				Name:        "action1",
				Usage:       "command2action1.Usage",
				ArgsUsage:   "<arg1>",
				Description: "command2action1.Description",
			},
			{
				Action:      dummyAction,
				Name:        "action2",
				Usage:       "command2action2.Usage",
				ArgsUsage:   "<arg1> [<arg2>]",
				Description: "command2action2.Description",
			},
			{
				Action:      dummyAction,
				Name:        "action3",
				Usage:       "command2action3.Usage",
				ArgsUsage:   "<arg1> [<arg2>]...",
				Description: "command2action3.Description",
			},
		},
	}
	command3 = cli.Command{
		Action:      dummyAction,
		Name:        "command3",
		Usage:       "command3.Usage",
		ArgsUsage:   "<arg1> [<arg2>]...",
		Description: "command3.Description",
	}
)

func main() {
	app := cli.NewApp()
	app.Name = "app.Name"
	app.Usage = "app.Usage"
	app.Version = "app.Version"
	app.Commands = []cli.Command{
		command1,
		command2,
		command3,
	}
	app.Run(os.Args)
}

When I run go run bug.go, go run bug.go help, or go run bug.go --help, the result is:

NAME:
   app.Name - app.Usage

USAGE:
   bug [global options] command [command options] [arguments...]
   
VERSION:
   app.Version
   
COMMANDS:
     command1  command1.Usage
     command2  command2.Usage
     command3  command3.Usage
     help, h   Shows a list of commands or help for one command

GLOBAL OPTIONS:
   --help, -h     show help
   --version, -v  print the version

This is fine - the behavior is expected, and the result is consistent.

However, when I run go run bug.go help command1, the result is:

NAME:
   bug command1 - command1.Usage

USAGE:
   bug command1 [arguments...]

DESCRIPTION:
   command1.Description

When I run go run bug.go command1 --help, the result is:

NAME:
   app.Name command1 - command1.Description

USAGE:
   app.Name command1 command [command options] [arguments...]

COMMANDS:
     action1  command1action1.Usage
     action2  command1action2.Usage
     action3  command1action3.Usage

OPTIONS:
   --help, -h  show help

When I run go run bug.go command1 help, the result is:

NAME:
   app.Name command1 - command1.Description

USAGE:
   app.Name command1 [global options] command [command options] [arguments...]
   
VERSION:
   app.Version
   
COMMANDS:
     action1  command1action1.Usage
     action2  command1action2.Usage
     action3  command1action3.Usage

GLOBAL OPTIONS:
   --help, -h  show help

This is very confusing. You can see that in the NAME section, sometimes bug is printed, and sometimes app.Name is printed. Besides, sometimes command1.Usage is printed, and sometimes command1.Description is printed. You can also find other discrepancies.

I understand that you target to provide a git like command library, but at least (git help and git --help) and (git help commit and git commit --help) give consistent results.

I also evaluated other commands that comes with sub-commands: openssl, port (MacPorts), lvm (Logical Volume Manager on Linux), parted, apt-get, npm (Node.js Package Manager), lvm and npm behaved very well, while other commands failed fast by, for example, disabling command subcommand --help.

Here is another subcommand library I am evaluating: https://github.com/google/subcommands It is not as full featured as urfave/cli, so I hope that you could fix the issue so that we can keep using it. Thanks!

[jszwedko]

Agreed @kenji-isuntv, this has been a personal annoyance of mine as well; you articulate the issue well here.

I'll try to take a crack at this soon when I have some time, but I'm also happy to review a PR.

Thank you for the report!

[Strift]

I have just started using the lib and it has been great so far but this bug is kind of annoying and really misleading for users.

Are you going to fix this soon or should we make a PR?

Thanks a lot!

[jszwedko]

@Strift PRs would definitely be welcome! I lost track of this issue and unfortunately won't have a ton of time over the next month or so to tackle the implementation myself (but would be able to review).

[relloyd]

+1 from me.

[coilysiren]

Given that this is from last year, I think I'm comfortable closing it 🙂 feel free to re-open / open a new issue / comment in support if there's still interest here!

[xordspar0]

I can reproduce the behavior as reported. The code and commands demonstrate the problem well. I think we should keep the issue open and do a little work to make the help output of subcommands more consistent.

[stale[bot]]

This issue or PR has been automatically marked as stale because it has not had recent activity. Please add a comment bumping this if you're still interested in it's resolution! Thanks for your help, please let us know if you need anything else.

[xordspar0]

Anyone interested in working on this should take a look at help.go and template.go to find out what's causing the different output.

[stale[bot]]

This issue or PR has been bumped and is no longer marked as stale! Feel free to bump it again in the future, if it's still relevant.

[stale[bot]]

This issue or PR has been automatically marked as stale because it has not had recent activity. Please add a comment bumping this if you're still interested in it's resolution! Thanks for your help, please let us know if you need anything else.

[stale[bot]]

Closing this as it has become stale.

[shtirlic]

Still interested in consistent for -h and help

[stale[bot]]

This issue or PR has been bumped and is no longer marked as stale! Feel free to bump it again in the future, if it's still relevant.

[dearchap]

Looking into submitting a PR for this.