When no subcommands are registered, omit command help output #32

smarterclayton · 2014-11-12T04:46:33Z

For a single root command with a Run method, the help output still
contains 'help [command]' as a subcommand (because Help is always
added). Since the only subcommand would be 'help', the help is better
off omitted.

This change allows a command to be used both as a subcommand
or a root command without having to define a custom help that elides
the help command when no subcommands are added. Instead, the default
help command is only added when subcommands are present.

Example:

$ mycommand --help
longdescription

Usage:
  mycommand

Available Flags:
  --help=false
  ....

# no help message displayed at end

If you specify a custom help command, your help command will be used
regardless of subcommand presence.

For a single root command with a Run method, the help output still contains 'help [command]' as a subcommand (because Help is always added). Since the only subcommand would be 'help', the help is better off omitted. This change allows a command to be used both as a subcommand or a root command without having to define a custom help that elides the help command when no subcommands are added. Instead, the default help command is only added when subcommands are present.

…oot_only_command When no subcommands are registered, omit command help output

k4rtik · 2015-01-31T16:48:50Z

Apart from resulting in #46 (omitting command description), this change conflicts with cobra doc:

The Help Command

Cobra automatically adds a help command to your application. This will be called when a user runs 'app help'."

There are multiple issues:

k4rtik at PlatiniumAir in ~/Projects/go/src/github.com/k4rtik/firstGoApp-Planet
$ go run main.go help

Usage:
  dagobah [flags]

 Available Flags:
  -h, --help=false: help for dagobah
Error: unknown command "help"
Run 'help' for usage.

dagobah: invalid command [`help`]
Run 'dagobah help' for usage
unknown command "help"
Run 'help' for usage.

exit status 255

Returning error 255 for valid command
Conflicting messages about help.

k4rtik · 2015-01-31T16:49:42Z

I am trying to fix this, but feel that this commit should be reverted and rethought about. @smarterclayton ideas?

smarterclayton · 2015-01-31T18:29:34Z

So a command that has no children by choice (because Run does the thing you want) doesn't seem to need a help command. As soon as you add your own subcommands, then help becomes a reasonable subcommand. It's the difference between the 'git' command and 'git-filter-branch'.

Since someone who wants to use commander is trying to group a lot of related commands together, there are occasionally cases where you want to be able to expose a single command. With the previous behavior, you were always left with a bizarre suncommand that did nothing useful.

When I made the change, I did not suggest a change to the readme or example, but that would clarify things. The example should demonstrate subcommands, but I don't think its the case that cobra shouldn't support more sophisticated use.

smarterclayton · 2015-01-31T18:30:51Z

The run 'help' for usage message should definitely be fixed in the context of my intended change and was not intentional.

spf13 · 2015-01-31T22:06:06Z

Thanks for the clarification. Agree with the rational. Can someone update the readme?

Steve Francia
spf13.com
@spf13

On Jan 31, 2015, at 1:30 PM, Clayton Coleman notifications@github.com wrote:

The run 'help' for usage message should definitely be fixed in the context of my intended change and was not intentional.

—
Reply to this email directly or view it on GitHub.

smarterclayton · 2015-01-31T22:45:41Z

Will do

On Jan 31, 2015, at 5:06 PM, Steve Francia notifications@github.com wrote:

Thanks for the clarification. Agree with the rational. Can someone update the readme?

Steve Francia
spf13.com
@spf13

On Jan 31, 2015, at 1:30 PM, Clayton Coleman notifications@github.com wrote:

The run 'help' for usage message should definitely be fixed in the context of my intended change and was not intentional.

—
Reply to this email directly or view it on GitHub.

—
Reply to this email directly or view it on GitHub.

k4rtik · 2015-02-01T01:48:22Z

Great, editing README is also an option. But in context of this PR, I feel help should stay as an implicit subcommand, but should not be counted as a subcommand or displayed in the "Available Commands" section. This is consistent with how help works in go help or git help.

This is also necessary because as I documented in #46, now there is no way to see the description of the root command with the default help gone.

spf13 · 2015-02-01T01:57:50Z

You definitely have a good point about the root help being essential. I
don't think I agree with it not being displayed in the "Available Commands"
section.

Perhaps the logic should be..

If the only subcommand is help then don't display "Available Commands" at
all. Otherwise it should be included in the list.

If there is only a root command with no subcommands then help by itself
also seems weird. It's already also defined as a flag. If no subcommands
are in use at all, then help only as a flag seems appropriate.

Does this make sense?

k4rtik · 2015-02-01T02:37:17Z

Let me illustrate with an example:

Old behavior:

$ go run main.go help
Dagobah provides planet style RSS aggregation. It
is inspired by python planet. It has a simple YAML configuration
and provides it's own webserver.

Usage:
  dagobah
  dagobah [command]

Available Commands:
  help [command]            Help about any command


Use "dagobah help [command]" for more information about that command.

Suggested new behavior with implicit help:

$ go run main.go help
Dagobah provides planet style RSS aggregation. It
is inspired by python planet. It has a simple YAML configuration
and provides it's own webserver.

Usage:
  dagobah

If help is explicitly defined by the user, then it should be displayed in the 'Available Commands' section, otherwise not. This behavior should remain the same even if help is the only available command.

About the flag, I am not sure if I understand why there were two different outputs for the --help flag and the help command in the first place. I think both can stay and output the same thing, as an unsuspecting user is likely to try out one of the three options when faced with an unfamiliar command:

cmd --help
cmd help
man cmd

Sounds logical? I validated that this is consistent with go --help and git --help as well.

smarterclayton · 2015-02-01T16:46:18Z

What if I want to reserve the first argument for myself (in the above example of reason commander for commands that have subcommands and others that don't?

If say, you have a subcommand that creates a directory, and so you want the first argument to be a directory named "help". The behavior now is that the root command gets all arguments. If you force every use of command to go through command processing, and there is no way to disable this behavior, then you can no longer make a "subcommandless command".

On Jan 31, 2015, at 9:37 PM, Kartik Singhal notifications@github.com wrote:

Let me illustrate with an example:

Old behavior:

$ go run main.go help
Dagobah provides planet style RSS aggregation. It
is inspired by python planet. It has a simple YAML configuration
and provides it's own webserver.

Usage:
dagobah
dagobah [command]

Available Commands:
help [command] Help about any command

Use "dagobah help [command]" for more information about that command.
Suggested new behavior with implicit help:

$ go run main.go help
Dagobah provides planet style RSS aggregation. It
is inspired by python planet. It has a simple YAML configuration
and provides it's own webserver.

Usage:
dagobah
If help is explicitly defined by the user, then it should be displayed in the 'Available Commands' section, otherwise not. This behavior should remain the same even if help is the only available command.

About the flag, I am not sure if I understand why there were two different outputs for the --help flag and the help command in the first place. I think both can stay and output the same thing, as an unsuspecting user is likely to try out one of the three options when faced with an unfamiliar command:

cmd --help

cmd help

man cmd

Sounds logical? I validated that this is consistent with go --help and git --help as well.

—
Reply to this email directly or view it on GitHub.

k4rtik · 2015-02-02T02:07:26Z

I am not sure if I understood what you meant by:

in the above example of reason commander for commands that have subcommands and others that don't?

About the directory named help, I don't see how that could be a problem. The following should work as expected with newdir subcommand as you describe above:

$ rootcmd newdir help

From what I understand with experimentation and reading the code, help is a subcommand inserted by default just for the root command and not for any of the subcommands. What I proposed above is not suggesting otherwise.

However, if you want such behavior when newdir is your root command and you don't intend to add any subcommands:

$ newdir help

then cobra is probably an overkill. Also, this could be worked around by having a flag for the root command to keep the semantics correct.

smarterclayton · 2015-02-02T02:19:58Z

I see cobra as a general command framework for building cli commands in go. Subcommands are hard, so that's where the effort is. But cobra provides value even for commands without subcommands, especially in large projects which want to tweak cobra in the same way across multiple commands.

The behavior we're discussing in the absence of subcommands is essentially the behavior of every major Unix command line utility (--help). It seems strange to me to argue that every cobra command should take a magic "help" subcommand in the absence of subcommands, and behave differently (in an unexpected fashion) to users familiar with other CLIs.

I'm not opposed to having to invoke a flag, it just doesn't seem to be the "right" behavior (I can register a single command and execute it without needing subcommands).

On Feb 1, 2015, at 9:07 PM, Kartik Singhal notifications@github.com wrote:

I am not sure if I understood what you meant by:

in the above example of reason commander for commands that have subcommands and others that don't?

About the directory named help, I don't see how that could be a problem. The following should work as expected with newdir subcommand as you describe above:

$ rootcmd newdir help
From what I understand with experimentation and reading the code, help is a subcommand inserted by default just for the root command and not for any of the subcommands. What I proposed above is not suggesting otherwise.

However, if you want such behavior when newdir is your root command and you don't intend to add any subcommands:

$ newdir help
then cobra is probably an overkill. Also, this could be worked around by having a flag for the root command to keep the semantics correct.

—
Reply to this email directly or view it on GitHub.

k4rtik · 2015-02-02T05:55:56Z

You raise a good point about having cobra as a generic CLI framework. In that case, one easy solution I can think of is to provide a toggle to switch default help off, but unsure if that's the 'right' solution.

Having default help is important as cobra supports $ rootcmd help subcmd by default, not having a default $ rootcmd help is inconsistent.

@spf13 opinion? Design philosophy?

spf13 · 2015-02-02T16:13:53Z

I'll stand by what I said earlier....

If the only subcommand is help then don't display "Available Commands" at all. Otherwise it should be included in the list.
If no subcommands are in use at all, then help only as a flag seems appropriate.

This seems like the ideal behavior for Cobra and fits exactly with the unix tool philosophy as well as the subcommand philosophy.

@smarterclayton I think this agrees with your point, but perhaps I misunderstood. Please correct me if I did.

smarterclayton · 2015-02-02T17:54:02Z

I agree with you - a more succinct way of saying what I was trying to say. I'll update the example and README.

----- Original Message -----

I'll stand by what I said earlier....

If the only subcommand is help then don't display "Available Commands" at
all. Otherwise it should be included in the list.
If no subcommands are in use at all, then help only as a flag seems
appropriate.

This seems like the ideal behavior for Cobra and fits exactly with the unix
tool philosophy as well as the subcommand philosophy.

@smarterclayton I think this agrees with your point, but perhaps I
misunderstood. Please correct me if I did.

Reply to this email directly or view it on GitHub:
#32 (comment)

smarterclayton · 2015-02-02T19:54:12Z

Updated in #50

----- Original Message -----

I agree with you - a more succinct way of saying what I was trying to say.
I'll update the example and README.

----- Original Message -----

I'll stand by what I said earlier....

If the only subcommand is help then don't display "Available Commands" at
all. Otherwise it should be included in the list.
If no subcommands are in use at all, then help only as a flag seems
appropriate.

This seems like the ideal behavior for Cobra and fits exactly with the unix
tool philosophy as well as the subcommand philosophy.

@smarterclayton I think this agrees with your point, but perhaps I
misunderstood. Please correct me if I did.

Reply to this email directly or view it on GitHub:
#32 (comment)

spf13 added a commit that referenced this pull request Nov 12, 2014

Merge pull request #32 from smarterclayton/hide_subcommand_help_for_r…

b825817

…oot_only_command When no subcommands are registered, omit command help output

spf13 merged commit b825817 into spf13:master Nov 12, 2014

k4rtik mentioned this pull request Jan 24, 2015

#32 erroneously omits long description as well for <command> help #46

Closed

smarterclayton mentioned this pull request Feb 2, 2015

Update README.md to describe help behavior without subcommands #50

Closed

MarkDBlackwell mentioned this pull request Aug 18, 2016

'hugo help' command undocumented in --help output gohugoio/hugo#2349

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

When no subcommands are registered, omit command help output #32

When no subcommands are registered, omit command help output #32

Uh oh!

smarterclayton commented Nov 12, 2014

k4rtik commented Jan 31, 2015

The Help Command

k4rtik commented Jan 31, 2015

smarterclayton commented Jan 31, 2015

smarterclayton commented Jan 31, 2015

spf13 commented Jan 31, 2015

smarterclayton commented Jan 31, 2015

k4rtik commented Feb 1, 2015

spf13 commented Feb 1, 2015

k4rtik commented Feb 1, 2015

smarterclayton commented Feb 1, 2015

k4rtik commented Feb 2, 2015

smarterclayton commented Feb 2, 2015

k4rtik commented Feb 2, 2015

spf13 commented Feb 2, 2015

smarterclayton commented Feb 2, 2015

smarterclayton commented Feb 2, 2015

Labels

3 participants

When no subcommands are registered, omit command help output #32

When no subcommands are registered, omit command help output #32

Uh oh!

Conversation

smarterclayton commented Nov 12, 2014

k4rtik commented Jan 31, 2015

The Help Command

k4rtik commented Jan 31, 2015

smarterclayton commented Jan 31, 2015

smarterclayton commented Jan 31, 2015

spf13 commented Jan 31, 2015

smarterclayton commented Jan 31, 2015

k4rtik commented Feb 1, 2015

spf13 commented Feb 1, 2015

k4rtik commented Feb 1, 2015

smarterclayton commented Feb 1, 2015

k4rtik commented Feb 2, 2015

smarterclayton commented Feb 2, 2015

k4rtik commented Feb 2, 2015

spf13 commented Feb 2, 2015

smarterclayton commented Feb 2, 2015

smarterclayton commented Feb 2, 2015

Labels

3 participants