Configurable version in usage output

[daenney]

Right now, this library will always output the result of Version() at the start of the usage output:

go-arg/usage.go

Lines 84 to 86 in 74af96c

	if p.version != "" {
	fmt.Fprintln(w, p.version)
	}

From my own observations, doing this is fairly uncommon amongst the CLI utilities installed on my system, especially for those that provide a dedicated flag to retrieve the version. To me personally it also feels a little out of place. If I were going to include the version information in usage output I would probably do it in the epilogue, not in the prologue.

Would you accept a PR which makes this configurable? Something like a func (args) VersionInHelp() bool {} that could return false causing the Version() to not be emitted, or a flag on Config?

[alexflint]

Hey @daenney - why not just have your Version() function return the empty string when you don't want to print a version?

[daenney]

I mean, I still want to print a version. Just not where the current version is being outputted in --help. I'd also still like --version to work, which also seems to require a Version() if I understand it correctly?

[alexflint]

Got it. That's reasonable. I think the best solution would be the ability to specify a custom template for help output, as discussed in a previous issue on the topic. In the absence of that, a workaround would be to omit the Version() function from your argument struct and handle ErrVersion explicitly like this:

var args struct {
  ...
}
p, err := arg.NewParser(&args)
err = p.Parse(os.Args())
if err == arg.ErrVersion {
  fmt.Println("Version: 1.2.3")
  os.Exit(1)
}

This still wouldn't solve your use-case of putting the version string at the bottom...

[daenney]

Ah, I suppose that would work. Thanks for the pointer. Being able to supply a template to customise the usage output sounds useful. I might look into that over the weekend.

[alexflint]

Will add this in upcoming v2 of this library

[hhromic]

Hi, I also think that the output from Version() is not well placed compared to almost all *nix CLI programs.

As the original poster indicated, for example, consider the following program:

package main

import "github.com/alexflint/go-arg"

type args struct {}

func (args) Description() string {
	return "This is my program."
}

func (args) Version() string {
	return "version 1.0.0 (git:master/abcd1234)"
}

func main() {
	var args args
	p := arg.MustParse(&args)
	p.Fail("oops, some error!")
}

This is the output with different combinations of arguments:

$ go run main.go
version 1.0.0 (git:master/abcd1234)
Usage: main
error: oops, some error!
exit status 2

$ go run main.go --help
This is my program.
version 1.0.0 (git:master/abcd1234)
Usage: main

Options:
  --help, -h             display this help and exit
  --version              display version and exit

$ go run main.go --bad
version 1.0.0 (git:master/abcd1234)
Usage: main
error: unknown argument --bad
exit status 2

As it can be seen, the output of Version() appears virtually everywhere and is quite noisy/irrelevant outside of when the user explicitly asks for it via --version, -V, specially on errors.

I personally don't think this needs to be configurable. I doubt anyone is particularly happy with the current behaviour.
Therefore I propose to simply remove the output of Version() everywhere EXCEPT when Description() is printed or when the built-in --version, -V argument is requested.

The other ideas proposed here were (1) supply a template and (2) use ErrVersion manually. However, both of them require more work, i.e. boilerplate code, from the end-user for removing this particular unusual behaviour.

@alexflint if you agree, I'm happy to make a PR fixing this and updating unit tests as needed.

EDIT: As a real-world example, this is what I've resorted to do in my programs to get rid of this behaviour at the expense of having a proper --version, -V argument: https://github.com/hhromic/promrelay-exporter/blob/9d67e2ac357a6dfbb47c8884d69f5bdc5bffba2e/cmd/main.go#L25-L34

[hhromic]

Here is my proposal to fix this issue as described above: master...hhromic:go-arg:fix-193

Let me know if you want me to turn it into a PR.

[alexflint]

I think you're right, it's too noisy at present, better to pare it back as you suggest. For the examples you have here, how do they look with your proposal?

[hhromic]

For the examples you have here, how do they look with your proposal?

$ go run main.go
Usage: main
error: oops, some error!
exit status 2

$ go run main.go --help
This is my program.
version 1.0.0 (git:master/abcd1234)
Usage: main

Options:
  --help, -h             display this help and exit
  --version              display version and exit

$ go run main.go --bad
Usage: main
error: unknown argument --bad
exit status 2

I think it looks much more concise and clean :)

[alexflint]

Yeah seems good to me! Happy to accept a pr

[hhromic]

Yeah seems good to me! Happy to accept a pr

PR with the proposed changed submitted. 👍