Abstract

This proposal suggests enhancing error handling in the flag package in Go to address the issue of long usage messages. Currently, the package combines error reporting and the display of usage information, making it less flexible for users when error messages or usage messages are lengthy. The proposed change separates error messages from usage information, allowing for more concise and user-friendly output.

Background

Currently, when an error occurs, the package combines error reporting with displaying the usage information. However, this approach can be problematic when usage messages are lengthy. On the other hand, the go command provides a better user experience by presenting a concise error message and suggesting users run 'go help' for more details in the case of unknown subcommands:

% go badcmd
go badcmd: unknown command
Run 'go help' for usage.

For the flag package should be:

% foo -badflag
flag provided but not defined: -badflag
Run 'foo -help' for usage.

% foo -valflag
flag needs an argument: -valflag
Run 'foo -help' for usage.

...

Proposal

The proposal recommends modifying the FlagSet.failf method to return only the error message, addressing the issue of long error messages. Users can then decide when to access the full usage message separately, improving the user experience and making error handling more efficient:

func (f *FlagSet) failf(format string, a ...interface{}) error {
    msg := fmt.Sprintf(format, a...)
-   f.usage()
+   fmt.Fprintf(f.Output(), "Run '%s -help' for usage.\n", f.name)
    return errors.New(msg)
}

Rationale

The proposed change simplifies error handling in the flag package and offers users the flexibility to decide when to view the complete usage message. Note that users may need to adjust existing code to accommodate the separation of error and usage message generation, although this change is expected to be minimal and simple.

Compatibility

The proposed change it does not introduce binary incompatibility and does not change the behavior of existing Go programs. Users can adapt their code to accommodate this change without affecting the overall compatibility of their programs. While the Go team reserves the right to address certain issues (security, etc.), these changes are not expected to impact the proposed modification in the flag package.

Implementation

See "Proposal" section.