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

1 files changed, 28 insertions, 9 deletions

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