build: reduce complexity for setting the version (#1466)

This change refactors the implementation of how the version is embedded
in the binary to reduce the number of variables necessary to determine
the version information from 3 to 1.

The legacy build variables are still supported, however, a warning will
be emitted instructing users to contact their package maintainer. The
legacy GitExacTag variable, if present, will be used to set main.version
if it is undefined. This ensures that unmigrated package builds will
continue to provide the correct version information.

The legacy build variables will be supported until 0.12.0, giving
package maintainers some time to migrate.

Change-Id: I05fea97169ea1af87b198174afe5b6663f860fd8

4 files changed, 63 insertions, 16 deletions

diff --git a/doc/generate.go b/doc/generate.go
index 0001f1a77..005d9df76 100644
--- a/doc/generate.go
+++ b/doc/generate.go
@@ -34,7 +34,7 @@ func main() {
 		wg.Add(1)
 		go func(name string, f func(*cobra.Command) error) {
 			defer wg.Done()
-			root := commands.NewRootCommand()
+			root := commands.NewRootCommand("")
 			err := f(root)
 			if err != nil {
 				fmt.Printf("  - %s: FATAL\n", name)
diff --git a/doc/man/git-bug-version.1 b/doc/man/git-bug-version.1
index 7183b696e..988849e8a 100644
--- a/doc/man/git-bug-version.1
+++ b/doc/man/git-bug-version.1
@@ -2,7 +2,7 @@
 .TH "GIT-BUG" "1" "Apr 2019" "Generated from git-bug's source code" ""
 
 .SH NAME
-git-bug-version - Show git-bug version information
+git-bug-version - Print version information
 
 
 .SH SYNOPSIS
@@ -10,25 +10,44 @@ git-bug-version - Show git-bug version information
 
 
 .SH DESCRIPTION
-Show git-bug version information
+Print version information.
 
+.PP
+Format:
+  git-bug  [commit[/dirty]]   
 
-.SH OPTIONS
-\fB-n\fP, \fB--number\fP[=false]
-	Only show the version number
+.PP
+Format Description:
+   may be one of:
+  	- A semantic version string, prefixed with a "v", e.g. v1.2.3
+  	- "undefined" (if not provided, or built with an invalid version string)
+
+.PP
+[commit], if present, is the commit hash that was checked out during the
+  build. This may be suffixed with '/dirty' if there were local file
+  modifications. This is indicative of your build being patched, or modified in
+  some way from the commit.
 
 .PP
-\fB-c\fP, \fB--commit\fP[=false]
-	Only show the commit hash
+ is the version of the go compiler used for the build.
 
 .PP
-\fB-a\fP, \fB--all\fP[=false]
-	Show all version information
+ is the target platform (GOOS).
 
 .PP
+ is the target architecture (GOARCH).
+
+
+.SH OPTIONS
 \fB-h\fP, \fB--help\fP[=false]
 	help for version
 
 
+.SH EXAMPLE
+.EX
+git bug version
+.EE
+
+
 .SH SEE ALSO
 \fBgit-bug(1)\fP
diff --git a/doc/md/git-bug.md b/doc/md/git-bug.md
index 03bebb65e..2ef0b7725 100644
--- a/doc/md/git-bug.md
+++ b/doc/md/git-bug.md
@@ -31,7 +31,7 @@ git-bug [flags]
 * [git-bug push](git-bug_push.md)	 - Push updates to a git remote
 * [git-bug termui](git-bug_termui.md)	 - Launch the terminal UI
 * [git-bug user](git-bug_user.md)	 - List identities
-* [git-bug version](git-bug_version.md)	 - Show git-bug version information
+* [git-bug version](git-bug_version.md)	 - Print version information
 * [git-bug webui](git-bug_webui.md)	 - Launch the web UI
 * [git-bug wipe](git-bug_wipe.md)	 - Wipe git-bug from the git repository
 
diff --git a/doc/md/git-bug_version.md b/doc/md/git-bug_version.md
index ceba8790f..a2569aff1 100644
--- a/doc/md/git-bug_version.md
+++ b/doc/md/git-bug_version.md
@@ -1,18 +1,46 @@
 ## git-bug version
 
-Show git-bug version information
+Print version information
+
+### Synopsis
+
+
+Print version information.
+
+Format:
+  git-bug <version> [commit[/dirty]] <compiler version> <platform> <arch>
+
+Format Description:
+  <version> may be one of:
+  	- A semantic version string, prefixed with a "v", e.g. v1.2.3
+  	- "undefined" (if not provided, or built with an invalid version string)
+
+  [commit], if present, is the commit hash that was checked out during the
+  build. This may be suffixed with '/dirty' if there were local file
+  modifications. This is indicative of your build being patched, or modified in
+  some way from the commit.
+
+  <compiler version> is the version of the go compiler used for the build.
+
+  <platform> is the target platform (GOOS).
+
+  <arch> is the target architecture (GOARCH).
+
 
 ```
 git-bug version [flags]
 ```
 
+### Examples
+
+```
+git bug version
+```
+
 ### Options
 
 ```
-  -n, --number   Only show the version number
-  -c, --commit   Only show the commit hash
-  -a, --all      Show all version information
-  -h, --help     help for version
+  -h, --help   help for version
 ```
 
 ### SEE ALSO