golang-help-wrapper

golang-help-wrapper

An utility wrapper program for showing Go help topics

Inspired by https://gist.github.com/MawKKe/485ad4ce21223309d2e90713f3b9b5ba - now as a simple Go binary!

What is this?

It annoys me greatly that none of the go subcommands have a help switch (-h or --help), requiring me to use go help <subcommand> instead. This is just annoying, adds more work than is necessary, and results in bad developer experience. I use shell history (ctrl-r, ctrl-p, ...) heavily, and this default mode of operation requires me to type much more than just adding -h at the end of previously executed command.

This wrapper program attempts add the help flag to all the subcommands by reinterpreting the command line arguments: if -h or --help is passed in any position, the respective subcommand help is displayed (the subcommand is assumed to be the first argument passed, if any).

So for example, this command

$ go <subcommand> <whatever arguments> -h

will launch

$ go help <subcommand>

(although this is not always the case; see Usage below.)

Install

Install the executable:

$ go install github.com/MawKKe/golang-help-wrapper@latest

then add

alias go=golang-help-wrapper

in your shell configuration (~/.bashrc or similar). Now each go invocation will be redirected to this wrapper program, which will in turn invoke the actual go executable with (possibly) reinterpreted arguments.

(Note: go install will place the binary in $GOPATH/bin; this directory should exists and be found in your $PATH for the alias to work correctly)

Usage

The program is not intended to be interacted directly; it merely captures and reinterprets command line arguments that you would otherwise pass to the go executable. However, there are two environment flags that may change the behavior of the wrapper program:

Environment variables

The following enviroment variables are understood:

• GOLANG_HELP_WRAPPER_DEBUG Determines whether to print debug information for the user. For example:

    $ env GOLANG_HELP_WRAPPER_DEBUG=1 go build -h
  

  prints the following at the beginning of the output:

    DEBUG: os.Args: [./golang-help-wrapper build -h]
    DEBUG: main.helpFlagMeta{subcmd:"build", help_idx:1, help_arg:"-h", \
            help_flag_found:true, original_args:[]string{"build", "-h"}}
  

  these lines may be helful for deducing problems with the wrapper and/or installation. You may set the variable to any value to enable it.

• GOLANG_HELP_WRAPPER_WARN_SUPPRESS By default the wrapper program prints a warning banner (into stderr) whenever the command line arguments are reinterpreted:

    $ go build -h
    @@@
    @@@ WARNING: help flag "-h" at position 2 reinterpreted by "golang-help-wrapper"
    @@@ WARNING: -> running 'go help build'
    @@@
    ...
  

  You may disable this warning banner by setting the variable to any value.

Bugs

There can be bugs, due to unforeseen edge cases in the go command line interface semantics. If you find such a case, please submit an issue.

Fear not: if you run into problems, you can always invoke the actual go executable directly by prefixing the command name with a backslash. So, instead of:

$ go ...

run

$ \go ...

Note that this is generic behavior found in most(?) shells.

Tips

If you pass -h argument with go run ..., it will always be interpreted as go help run, unless you use the backslash escape trick or you pass arguments using the double dash idiom:

$ \go run my/run/target -h
$ go run -- my/run/target -h

both of these will pass -h to the target application, instead of being reintepreted by the wrapper program.

Dependencies

The program is written in Go, version 1.18. It may compile with older compiler versions. The program does not have any third party dependencies.

License

Copyright 2022 Markus Holmström (MawKKe)

The works under this repository are licenced under Apache License 2.0. See file LICENSE for more information.

Contributing

This project is hosted at https://github.com/MawKKe/golang-help-wrapper

You are welcome to leave bug reports, fixes and feature requests. Thanks!