Set flag.Usage to custom Help header func

[atc0005]

While reading over Fun with Flags I learned that the stdlib flag package supports displaying custom help text as a header or lead-in to the auto-generated list of options available to the user. This can be used to display branding, version details and a link back to the main project repo.

[atc0005]

Note to self; starting point for CHANGELOG entry related to this work:

- Usage/branding details shown for invalid subcommands, flags or just general
  Help output

[atc0005]

Really struggling with this one for some reason. Scratch notes below in case writing this out here helps to make things "click".

---

• Use switch statement to check incoming subcommands
• Setup package-level Help function
• Custom flagset for global flags; don't use the package-level flagset as other imported packages could override our app's flags
• default case statement
  • invalid flag name
  • mention supplied subcommand and that it is incorrect
  • show Help which lists valid subcommands
• missing subcommand
  • not provided at all
  • show Help which lists valid subcommands

[atc0005]

Some references that I've consulted thus far:

• https://golang.org/pkg/flag/
• https://gobyexample.com/command-line-subcommands
• https://www.digitalocean.com/community/tutorials/how-to-use-the-flag-package-in-go
• https://blog.gopheracademy.com/advent-2019/flags/
• https://blog.gopheracademy.com/advent-2019/cmdline/

Some I've started looking over, but haven't finished with yet:

• https://blog.rapid7.com/2016/08/04/build-a-simple-cli-tool-with-golang/
• http://blog.ralch.com/tutorial/golang-subcommands/
• https://github.com/shapeshed/golang-book-examples/tree/master/hour17
  • https://github.com/shapeshed/golang-book-examples/blob/master/hour17/example05.go
  • https://github.com/shapeshed/golang-book-examples/blob/master/hour17/example06.go
• https://learning.oreilly.com/library/view/learning-coredns/9781492047957/

[atc0005]

Regarding the references linked above:

• the Digital Ocean tutorial

  • is probably the most flexible/programmatic, but it's a little dense
  • I am not sure that the flexibility is worth the complexity at my current knowledge level

• the Go by Example tutorial

  • common pattern shared by multiple sources
  • one switch statement to key off of os.Args[1] and parse the matching flagset

• the Gopher Academy Blog tutorials (Miki Tebeka)

  • uses a switch statement similar to gobyexample.com tutorial
  • defines usage function for main application or "command" (e.g., os.Args[0])
  • no flags defined on main flagset
  • embeds relevant code into very small, focused functions which contain the subcommand setup code
  • very little package state or potential to accidentally mix up code/logic

• Sam's Teach Yourself Go in 24 Hours

  • Sets flag.Usage to list supported subcommands
  • Sets Usage for each subcommand
  • print Usage details if no subcommand provided

• Learning CoreDNS

  • separate FlagSet for main application to prevent imported packages (their examples are Caddy and Kubernetes) from redefining flags
  • "the global flag.CommandLine is set to the new FlagSet and the flags are parsed with flag.Parse"