Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Excesive string prefix to usage function output #1532

Closed
HarryMichal opened this issue Nov 11, 2021 · 4 comments
Closed

Excesive string prefix to usage function output #1532

HarryMichal opened this issue Nov 11, 2021 · 4 comments
Labels
kind/support Questions, supporting users, etc.

Comments

@HarryMichal
Copy link

PR #1044 introduced in commit dd3684a a new prefix to the usage function. Example:

var rootCmd = &cobra.Command{
    Use: "cmd"
}

func usage(cmd *cobra.Command) error {
    err := fmt.Errorf("Custom usage message")
    return err
}

rootCmd.SetUsageFunc(usage)

Note that the example is very simplified. The main part is the use of a custom usage function.

Forcing the created binary to print out the usage (e.g., by passing a wrong flag) will yield the following output:

$ cmd --unknown-flag
Error: unknown flag: --unknown-flag
Error: Custom usage message

Note the Error: prefix before the usage text. The only way to bypass this behaviour is to set a template string instead.

The desired output would be:

$ cmd --unknown-flag
Error: unknown flag: --unknown-flag
Custom usage message
HarryMichal added a commit to HarryMichal/toolbox that referenced this issue Nov 11, 2021
@HarryMichal
cmd/root: Use string template instead of function for usage
6af7c77 
In version 1.1.2 of Cobra has been included a change[0] that changes the
behaviour of how custom usage functions are printed. The change prepends
"Error: " to the text. This is not desired since the usage text is not
an error text.

A workaround is to define a template string for the usage instead. The
template uses the templating language of Go[1]. See the default template
string in version 1.2.1[2].

This change has the positive benefit of getting more helpful usage
messages. E.g., for command 'toolbox enter' the usage text is no longer
"Run 'toolbox --help' for usage." but "Run 'toolbox enter --help' for usage.".

Upstream issue: spf13/cobra#1532

[0] spf13/cobra#1044
[1] https://pkg.go.dev/text/template
[2] https://github.com/spf13/cobra/blob/v1.2.1/command.go#L491
HarryMichal added a commit to HarryMichal/toolbox that referenced this issue Nov 16, 2021
@HarryMichal
cmd/root: Use string template instead of function for usage
5ee1518 
In version 1.1.2 of Cobra has been included a change[0] that changes the
behaviour of how custom usage functions are printed. The change prepends
"Error: " to the text. This is not desired since the usage text is not
an error text.

Example of the wrong behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Error: Run 'toolbox --help' for usage.

Desired behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Run 'toolbox --help' for usage.

A workaround is to define a template string for the usage instead. The
template uses the templating language of Go[1]. See the default template
string in version 1.2.1[2].

Because the template is set only once, the executableBase needs to be
set before the template is applied. That required the move of
setUpGlobals() into init() of the cmd package. This is a better place
for the function call as init() is called earlier than Execute()[3].

Upstream issue: spf13/cobra#1532

[0] spf13/cobra#1044
[1] https://pkg.go.dev/text/template
[2] https://github.com/spf13/cobra/blob/v1.2.1/command.go#L491
[3] https://golang.org/doc/effective_go#init
HarryMichal added a commit to HarryMichal/toolbox that referenced this issue Nov 16, 2021
@HarryMichal
cmd/root: Use string template instead of function for usage
8bcb56a 
In version 1.1.2 of Cobra has been included a change[0] that changes the
behaviour of how custom usage functions are printed. The change prepends
"Error: " to the text. This is not desired since the usage text is not
an error text.

Example of the wrong behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Error: Run 'toolbox --help' for usage.

Desired behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Run 'toolbox --help' for usage.

A workaround is to define a template string for the usage instead. The
template uses the templating language of Go[1]. See the default template
string in version 1.2.1[2].

Because the template is set only once, the executableBase needs to be
set before the template is applied. That required the move of
setUpGlobals() into init() of the cmd package. This is a better place
for the function call as init() is called earlier than Execute()[3].

Upstream issue: spf13/cobra#1532

[0] spf13/cobra#1044
[1] https://pkg.go.dev/text/template
[2] https://github.com/spf13/cobra/blob/v1.2.1/command.go#L491
[3] https://golang.org/doc/effective_go#init

containers#917
HarryMichal added a commit to olivergs/toolbox that referenced this issue Nov 21, 2021
@HarryMichal
cmd/root: Use string template instead of function for usage
c36b34a 
In version 1.1.2 of Cobra has been included a change[0] that changes the
behaviour of how custom usage functions are printed. The change prepends
"Error: " to the text. This is not desired since the usage text is not
an error text.

Example of the wrong behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Error: Run 'toolbox --help' for usage.

Desired behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Run 'toolbox --help' for usage.

A workaround is to define a template string for the usage instead. The
template uses the templating language of Go[1]. See the default template
string in version 1.2.1[2].

Because the template is set only once, the executableBase needs to be
set before the template is applied. That required the move of
setUpGlobals() into init() of the cmd package. This is a better place
for the function call as init() is called earlier than Execute()[3].

Upstream issue: spf13/cobra#1532

[0] spf13/cobra#1044
[1] https://pkg.go.dev/text/template
[2] https://github.com/spf13/cobra/blob/v1.2.1/command.go#L491
[3] https://golang.org/doc/effective_go#init

containers#917
HarryMichal added a commit to HarryMichal/toolbox that referenced this issue Dec 15, 2021
@HarryMichal
cmd/root: Use string template instead of function for usage
a1691f4 
In version 1.1.2 of Cobra has been included a change[0] that changes the
behaviour of how custom usage functions are printed. The change prepends
"Error: " to the text. This is not desired since the usage text is not
an error text.

Example of the wrong behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Error: Run 'toolbox --help' for usage.

Desired behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Run 'toolbox --help' for usage.

A workaround is to define a template string for the usage instead. The
template uses the templating language of Go[1]. See the default template
string in version 1.2.1[2].

Because the template is set only once, the executableBase needs to be
set before the template is applied. That required the move of
setUpGlobals() into init() of the cmd package. This is a better place
for the function call as init() is called earlier than Execute()[3].

Upstream issue: spf13/cobra#1532

[0] spf13/cobra#1044
[1] https://pkg.go.dev/text/template
[2] https://github.com/spf13/cobra/blob/v1.2.1/command.go#L491
[3] https://golang.org/doc/effective_go#init

containers#917
HarryMichal added a commit to HarryMichal/toolbox that referenced this issue Dec 16, 2021
@HarryMichal
cmd/root: Use string template instead of function for usage
8c00233 
In version 1.1.2 of Cobra has been included a change[0] that changes the
behaviour of how custom usage functions are printed. The change prepends
"Error: " to the text. This is not desired since the usage text is not
an error text.

Example of the wrong behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Error: Run 'toolbox --help' for usage.

Desired behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Run 'toolbox --help' for usage.

A workaround is to define a template string for the usage instead. The
template uses the templating language of Go[1]. See the default template
string in version 1.2.1[2].

Because the template is set only once, the executableBase needs to be
set before the template is applied. That required the move of
setUpGlobals() into init() of the cmd package. This is a better place
for the function call as init() is called earlier than Execute()[3].

Upstream issue: spf13/cobra#1532

[0] spf13/cobra#1044
[1] https://pkg.go.dev/text/template
[2] https://github.com/spf13/cobra/blob/v1.2.1/command.go#L491
[3] https://golang.org/doc/effective_go#init

containers#917
@HarryMichal HarryMichal mentioned this issue Dec 17, 2021
Closed
debarshiray pushed a commit to HarryMichal/toolbox that referenced this issue Dec 17, 2021
@HarryMichal @debarshiray
cmd/root: Work around Cobra 1.1.2's handling of usage functions
e598e21 
In version 1.1.2 of Cobra has been included a change[0] that changes
how custom usage functions are handled.

Example of the wrong behaviour:
$ toolbox --foo
Error: unknown flag: --foo
Run 'toolbox --help' for usage.Error: Run 'toolbox --help' for usage.

Desired behaviour:
$ toolbox --foo
Error: unknown flag: --foo
Run 'toolbox --help' for usage.

A workaround is to define a template string for the usage instead. The
template uses the templating language of Go[1]. See the default
template string in version 1.2.1[2].

Because the template is set only once, the executableBase needs to be
set before the template is applied. That required the move of
setUpGlobals() into init() of the cmd package. This is a better place
for the function call as init() is called earlier than Execute()[3].

Upstream issue: spf13/cobra#1532

[0] spf13/cobra#1044
[1] https://pkg.go.dev/text/template
[2] https://github.com/spf13/cobra/blob/v1.2.1/command.go#L491
[3] https://golang.org/doc/effective_go#init

containers#917
HarryMichal added a commit to HarryMichal/toolbox that referenced this issue Dec 17, 2021
@HarryMichal
cmd/root: Work around Cobra 1.1.2's handling of usage functions
e3ebead 
In version 1.1.2 of Cobra has been included a change[0] that changes
how custom usage functions are handled.

Example of the wrong behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Run 'toolbox --help' for usage.Error: Run 'toolbox --help' for usage.

Desired behaviour:

$ toolbox --foo
Error: unknown flag: --foo
Run 'toolbox --help' for usage.

A workaround is to define a template string for the usage instead. The
template uses the templating language of Go[1]. See the default template
string in version 1.2.1[2].

Because the template is set only once, the executableBase needs to be
set before the template is applied. That required the move of
setUpGlobals() into init() of the cmd package. This is a better place
for the function call as init() is called earlier than Execute()[3].

Upstream issue: spf13/cobra#1532

[0] spf13/cobra#1044
[1] https://pkg.go.dev/text/template
[2] https://github.com/spf13/cobra/blob/v1.2.1/command.go#L491
[3] https://golang.org/doc/effective_go#init

containers#917
@github-actions
Copy link

This issue is being marked as stale due to a long period of inactivity

@HarryMichal
Copy link
Author

This issue is still present in Cobra.

@hoshsadiq
Copy link

This seems like correct behaviour to me. If you return an error, it is explicitly communicated as an error. There are plenty of use-cases where the usage function could return an unexpected error (as opposed to an expected error). You should be using fmt.Println or a variation of it, combined returning nil for an error. I.e.:

var rootCmd = &cobra.Command{
    Use: "cmd"
}

func usage(cmd *cobra.Command) error {
    fmt.Println("Custom usage message")
    return nil
}

rootCmd.SetUsageFunc(usage)

@johnSchnake johnSchnake added the kind/support Questions, supporting users, etc. label Feb 17, 2022
@HarryMichal
Copy link
Author

This behaviour should then be documented. It is highly perplexing when encountered at first. Also the reliance on side-effects in the function causes cmd.UsageString() to be s bit clunky to use when assembling custom messages.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
kind/support Questions, supporting users, etc.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@hoshsadiq @johnSchnake @HarryMichal