docs: fix typo

.gitignore

@@ -1,6 +1,10 @@
 xversion.go
 zversion.go
 
+/go-gitver
+hello
+examples/*/*.sum
+
 # ---> Go
 # Binaries for programs and plugins
 *.exe

.prettierrc

@@ -0,0 +1 @@
+{}

README.md

@@ -1,24 +1,84 @@
-# git-version.go
+# [Go GitVer](https://git.rootprojects.org/root/go-gitver)
 
-Use git tags to add semver to your go package.
+Use **git tags** to add (GoReleaser-compatible) [**semver**](https://semver.org/)
+to your go package in under 150
+[lines of code](https://git.rootprojects.org/root/go-gitver/src/branch/master/gitver/gitver.go).
 
 ```txt
-Goal: Either use an exact version like v1.0.0
-      or translate the git version like v1.0.0-4-g0000000
-      to a semver like v1.0.1-pre4+g0000000
+Goals:
+
+      1. Use an exact `git tag` version, like v1.0.0, when clean
+      2. Translate the `git describe` version  (v1.0.0-4-g0000000)
+	     to semver (1.0.1-pre4+g0000000) in between releases
+      3. Note when `dirty` (and have build timestamp)
 
       Fail gracefully when git repo isn't available.
 ```
 
+# GoDoc
+
+See <https://pkg.go.dev/git.rootprojects.org/root/go-gitver/v2>.
+
+# How it works
+
+1. You define the fallback version and version printing in `main.go`:
+
+```go
+//go:generate go run git.rootprojects.org/root/go-gitver/v2
+
+package main
+
+import (
+	"fmt"
+	"strings"
+)
+
+var (
+	commit  = "0000000"
+	version = "0.0.0-pre0+0000000"
+	date    = "0000-00-00T00:00:00+0000"
+)
+
+func main() {
+	if (len(os.Args) > 1 && "version" == strings.TrimLeft(os.Args[1], "-")) {
+		fmt.Printf("Foobar v%s (%s) %s\n", version, commit[:7], date)
+	}
+	// ...
+}
+```
+
+2. You `go generate` or `go run git.rootprojects.org/root/go-gitver/v2` to generate `xversion.go`:
+
+```go
+package main
+
+func init() {
+    commit  = "0921ed1e"
+    version = "1.1.2"
+    date    = "2019-07-01T02:32:58-06:00"
+}
+```
+
 # Demo
 
 Generate an `xversion.go` file:
 
 ```bash
-go run git.rootprojects.org/root/go-gitver
+go run git.rootprojects.org/root/go-gitver/v2
 cat xversion.go
 ```
 
+```go
+// Code generated by go generate; DO NOT EDIT.
+package main
+
+func init() {
+	commit  = "6dace8255b52e123297a44629bc32c015add310a"
+	version = "1.1.4-pre2+g6dace82"
+	date    = "2020-07-16T20:48:15-06:00"
+}
+```
+
 <small>**Note**: The file is named `xversion.go` by default so that the
 generated file's `init()` will come later, and thus take priority, over
 most other files.</small>
@@ -26,15 +86,21 @@ most other files.</small>
 See `go-gitver`s self-generated version:
 
 ```bash
-go run git.rootprojects.org/root/go-gitver version
+go run git.rootprojects.org/root/go-gitver/v2 version
+```
+
+```txt
+6dace8255b52e123297a44629bc32c015add310a
+v1.1.4-pre2+g6dace82
+2020-07-16T20:48:15-06:00
 ```
 
 # QuickStart
 
-Add this to the top of your main file:
+Add this to the top of your main file, so that it runs with `go generate`:
 
 ```go
-//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver/v2
 
 ```
 
@@ -45,7 +111,7 @@ Add a file that imports go-gitver (for versioning)
 
 package example
 
-import _ "git.rootprojects.org/root/go-gitver"
+import _ "git.rootprojects.org/root/go-gitver/v2"
 ```
 
 Change you build instructions to be something like this:
@@ -56,7 +122,7 @@ go generate -mod=vendor ./...
 go build -mod=vendor -o example cmd/example/*.go
 ```
 
-You don't have to use `mod vendor`, but I highly recommend it.
+You don't have to use `-mod=vendor`, but I highly recommend it (just `go mod tidy; go mod vendor` to start).
 
 # Options
 
@@ -77,12 +143,12 @@ GITVER_FAIL=true
 For example:
 
 ```go
-//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver --fail
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver/v2 --fail
 
 ```
 
 ```bash
-go run -mod=vendor git.rootprojects.org/root/go-gitver version
+go run -mod=vendor git.rootprojects.org/root/go-gitver/v2 version
 ```
 
 # Usage
@@ -91,9 +157,9 @@ See `examples/basic`
 
 1. Create a `tools` package in your project
 2. Guard it against regular builds with `// +build tools`
-3. Include `_ "git.rootprojects.org/root/go-gitver"` in the imports
-4. Declare `var GitRev, GitVersion, GitTimestamp string` in your `package main`
-5. Include `//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver` as well
+3. Include `_ "git.rootprojects.org/root/go-gitver/v2"` in the imports
+4. Declare `var commit, version, date string` in your `package main`
+5. Include `//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver/v2` as well
 
 `tools/tools.go`:
 
@@ -104,29 +170,29 @@ See `examples/basic`
 package tools
 
 import (
-	_ "git.rootprojects.org/root/go-gitver"
+	_ "git.rootprojects.org/root/go-gitver/v2"
 )
 ```
 
 `main.go`:
 
 ```go
-//go:generate go run git.rootprojects.org/root/go-gitver --fail
+//go:generate go run git.rootprojects.org/root/go-gitver/v2 --fail
 
 package main
 
 import "fmt"
 
 var (
-	GitRev       = "0000000"
-	GitVersion   = "v0.0.0-pre0+0000000"
-	GitTimestamp = "0000-00-00T00:00:00+0000"
+	commit  = "0000000"
+	version = "0.0.0-pre0+0000000"
+	date    = "0000-00-00T00:00:00+0000"
 )
 
 func main() {
-  fmt.Println(GitRev)
-  fmt.Println(GitVersion)
-  fmt.Println(GitTimestamp)
+  fmt.Println(commit)
+  fmt.Println(version)
+  fmt.Println(date)
 }
 ```
 
@@ -134,7 +200,7 @@ If you're using `go mod vendor` (which I highly recommend that you do),
 you'd modify the `go:generate` ever so slightly:
 
 ```go
-//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver --fail
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver/v2 --fail
 ```
 
 The only reason I didn't do that in the example is that I'd be included
@@ -142,7 +208,7 @@ the repository in itself and that would be... weird.
 
 # Why a tools package?
 
-> import "git.rootprojects.org/root/go-gitver" is a program, not an importable package
+> import "git.rootprojects.org/root/go-gitver/v2" is a program, not an importable package
 
 Having a tools package with a build tag that you don't use is a nice way to add exact
 versions of a command package used for tooling to your `go.mod` with `go mod tidy`,
@@ -182,8 +248,8 @@ git rev-parse HEAD
 ### cannot find package "."
 
 ```txt
-package git.rootprojects.org/root/go-gitver: cannot find package "." in:
-	/Users/me/go-example/vendor/git.rootprojects.org/root/go-gitver
+package git.rootprojects.org/root/go-gitver/v2: cannot find package "." in:
+	/Users/me/go-example/vendor/git.rootprojects.org/root/go-gitver/v2
 cmd/example/example.go:1: running "go": exit status 1
 ```
 

examples/basic/go.mod

@@ -2,4 +2,4 @@ module example.com/hello
 
 go 1.12
 
-require git.rootprojects.org/root/go-gitver v1.1.0
+require git.rootprojects.org/root/go-gitver/v2 v2.0.2

examples/basic/main.go

@@ -1,4 +1,4 @@
-//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver --fail
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver/v2 --fail
 
 package main
 
@@ -8,9 +8,9 @@ import (
 )
 
 var (
-	GitRev       = "0000000"
-	GitVersion   = "v0.0.0-pre0+0000000"
-	GitTimestamp = "0000-00-00T00:00:00+0000"
+	commit  = "0000000"
+	version = "0.0.0-pre0+0000000"
+	date    = "0000-00-00T00:00:00+0000"
 )
 
 func main() {
@@ -18,9 +18,9 @@ func main() {
 	flag.Parse()
 
 	if *showVersion {
-		fmt.Println(GitRev)
-		fmt.Println(GitVersion)
-		fmt.Println(GitTimestamp)
+		fmt.Println(commit)
+		fmt.Println(version)
+		fmt.Println(date)
 		return
 	}
 

examples/basic/tools/tools.go

@@ -4,5 +4,5 @@
 package tools
 
 import (
-	_ "git.rootprojects.org/root/go-gitver"
+	_ "git.rootprojects.org/root/go-gitver/v2"
 )

examples/no-tools/go.mod

@@ -2,4 +2,4 @@ module example.com/hello
 
 go 1.12
 
-require git.rootprojects.org/root/go-gitver v1.1.0
+require git.rootprojects.org/root/go-gitver/v2 v2.0.2

examples/no-tools/main.go

@@ -1,4 +1,4 @@
-//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver --fail
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver/v2 --fail
 
 package main
 
@@ -8,9 +8,9 @@ import (
 )
 
 var (
-	GitRev       = "0000000"
-	GitVersion   = "v0.0.0-pre0+0000000"
-	GitTimestamp = "0000-00-00T00:00:00+0000"
+	commit  = "0000000"
+	version = "0.0.0-pre0+0000000"
+	date    = "0000-00-00T00:00:00+0000"
 )
 
 func main() {
@@ -18,9 +18,9 @@ func main() {
 	flag.Parse()
 
 	if *showVersion {
-		fmt.Println(GitRev)
-		fmt.Println(GitVersion)
-		fmt.Println(GitTimestamp)
+		fmt.Println(commit)
+		fmt.Println(version)
+		fmt.Println(date)
 		return
 	}
 

examples/no-tools/tools.go

@@ -3,4 +3,4 @@
 // This is a dummy file for build tooling
 package main
 
-import _ "git.rootprojects.org/root/go-gitver"
+import _ "git.rootprojects.org/root/go-gitver/v2"

examples/special-name/go.mod

@@ -2,4 +2,4 @@ module example.com/hello
 
 go 1.12
 
-require git.rootprojects.org/root/go-gitver v1.1.0
+require git.rootprojects.org/root/go-gitver/v2 v2.0.2

examples/special-name/main.go

@@ -1,4 +1,4 @@
-//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver --package version --outfile ./version/zversion.go
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver/v2 --package version --outfile ./version/zversion.go
 
 package main
 
@@ -14,9 +14,9 @@ func main() {
 	flag.Parse()
 
 	if *showVersion {
-		fmt.Println(version.GitRev)
-		fmt.Println(version.GitVersion)
-		fmt.Println(version.GitTimestamp)
+		fmt.Println(version.Commit())
+		fmt.Println(version.Version())
+		fmt.Println(version.Date())
 		return
 	}
 

examples/special-name/tools/tools.go

@@ -4,5 +4,5 @@
 package tools
 
 import (
-	_ "git.rootprojects.org/root/go-gitver"
+	_ "git.rootprojects.org/root/go-gitver/v2"
 )

examples/special-name/version/version.go

@@ -1,7 +1,22 @@
 package version
 
 var (
-	GitRev       = "0000000"
-	GitVersion   = "v0.0.0-pre0+0000000"
-	GitTimestamp = "0000-00-00T00:00:00+0000"
+	commit  = "0000000"
+	version = "0.0.0-pre0+0000000"
+	date    = "0000-00-00T00:00:00+0000"
 )
+
+// Commit returns the git commit reference
+func Commit() string {
+	return commit
+}
+
+// Version returns the git version, without the leading 'v'
+func Version() string {
+	return version
+}
+
+// Date returns the ISO-formatted date string
+func Date() string {
+	return date
+}

examples/sub-package/go.mod

@@ -2,4 +2,4 @@ module example.com/hello
 
 go 1.12
 
-require git.rootprojects.org/root/go-gitver v1.1.0
+require git.rootprojects.org/root/go-gitver/v2 v2.0.2

examples/sub-package/main.go

@@ -12,9 +12,9 @@ func main() {
 	flag.Parse()
 
 	if *showVersion {
-		fmt.Println(version.GitRev)
-		fmt.Println(version.GitVersion)
-		fmt.Println(version.GitTimestamp)
+		fmt.Println(version.Commit())
+		fmt.Println(version.Version())
+		fmt.Println(version.Date())
 		return
 	}
 

examples/sub-package/tools/tools.go

@@ -4,5 +4,5 @@
 package tools
 
 import (
-	_ "git.rootprojects.org/root/go-gitver"
+	_ "git.rootprojects.org/root/go-gitver/v2"
 )

examples/sub-package/version/version.go

@@ -1,9 +1,24 @@
-//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver --package version
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver/v2 --package version
 
 package version
 
 var (
-	GitRev       = "0000000"
-	GitVersion   = "v0.0.0-pre0+0000000"
-	GitTimestamp = "0000-00-00T00:00:00+0000"
+	commit  = "0000000"
+	version = "0.0.0-pre0+0000000"
+	date    = "0000-00-00T00:00:00+0000"
 )
+
+// Commit returns the git commit reference
+func Commit() string {
+	return commit
+}
+
+// Version returns the git version, without the leading 'v'
+func Version() string {
+	return version
+}
+
+// Date returns the ISO-formatted date string
+func Date() string {
+	return date
+}

gitver.go

@@ -1,4 +1,4 @@
-//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver/v2
 
 package main
 
@@ -10,10 +10,10 @@ import (
 	"text/template"
 	"time"
 
-	"git.rootprojects.org/root/go-gitver/gitver"
+	"git.rootprojects.org/root/go-gitver/v2/gitver"
 )
 
-var GitRev, GitVersion, GitTimestamp string
+var commit, version, date string
 var exitCode int
 var verFile = "xversion.go"
 
@@ -32,9 +32,9 @@ func main() {
 			pkg = args[i+1]
 			args[i+1] = ""
 		} else if "-V" == arg || "version" == arg || "-version" == arg || "--version" == arg {
-			fmt.Println(GitRev)
-			fmt.Println(GitVersion)
-			fmt.Println(GitTimestamp)
+			fmt.Println(commit)
+			fmt.Println(version)
+			fmt.Println(date)
 			os.Exit(0)
 		}
 	}
@@ -59,12 +59,12 @@ func main() {
 		Package   string
 		Timestamp string
 		Version   string
-		GitRev    string
+		Commit    string
 	}{
 		Package:   pkg,
 		Timestamp: v.Timestamp.Format(time.RFC3339),
 		Version:   v.Version,
-		GitRev:    v.Rev,
+		Commit:    v.Rev,
 	}); nil != err {
 		panic(err)
 	}
@@ -93,12 +93,12 @@ var versionTpl = template.Must(template.New("").Parse(`// Code generated by go g
 package {{ .Package }}
 
 func init() {
-	{{ if .GitRev -}}
-	GitRev = "{{ .GitRev }}"
+	{{ if .Commit -}}
+	commit = "{{ .Commit }}"
 	{{ end -}}
 	{{ if .Version -}}
-	GitVersion = "{{ .Version }}"
+	version = "{{ .Version }}"
 	{{ end -}}
-	GitTimestamp = "{{ .Timestamp }}"
+	date = "{{ .Timestamp }}"
 }
 `))

gitver/gitver.go

@@ -21,12 +21,14 @@ func init() {
 	gitVer = regexp.MustCompile(`^(v\d+\.\d+)\.(\d+)(-(\d+))?(-(g[0-9a-f]+))?(-(dirty))?`)
 }
 
+// Versions describes the various version properties
 type Versions struct {
 	Timestamp time.Time
 	Version   string
 	Rev       string
 }
 
+// ExecAndParse will run git and parse the output
 func ExecAndParse() (*Versions, error) {
 	desc, err := gitDesc()
 	if nil != err {
@@ -58,7 +60,7 @@ func gitDesc() (string, error) {
 	out, err := cmd.CombinedOutput()
 	if nil != err {
 		// Don't panic, just carry on
-		//out = []byte("v0.0.0-0-g0000000")
+		//out = []byte("0.0.0-0-g0000000")
 		return "", err
 	}
 	return strings.TrimSpace(string(out)), nil
@@ -83,7 +85,7 @@ func gitRev() (string, error) {
 func semVer(desc string) (string, error) {
 	if exactVer.MatchString(desc) {
 		// v1.0.0
-		return desc, nil
+		return strings.TrimPrefix(desc, "v"), nil
 	}
 
 	if !gitVer.MatchString(desc) {
@@ -122,10 +124,19 @@ func semVer(desc string) (string, error) {
 		ver += vers[8]
 	}
 
-	return ver, nil
+	return strings.TrimPrefix(ver, "v"), nil
 }
 
 func gitTimestamp(desc string) (time.Time, error) {
+	// Other options:
+	//
+	// Commit Date
+	//	git log -1 --format=%cd --date=format:%Y-%m-%dT%H:%M:%SZ%z
+	//
+	// Author Date
+	// git log -1 --format=%ad --date=format:%Y-%m-%dT%H:%M:%SZ%z
+	//
+	// I think I chose this because it would account for dirty-ness better... maybe?
 	args := []string{
 		"git",
 		"show", desc,

go.mod

@@ -1,3 +1,3 @@
-module git.rootprojects.org/root/go-gitver
+module git.rootprojects.org/root/go-gitver/v2
 
 go 1.12

version.go

@@ -3,7 +3,7 @@ package main
 // use recently generated version info as a fallback
 // for when git isn't present (i.e. go run <url>)
 func init() {
-	GitRev = "0921ed1e6007493c886c87ee9a15f2cceecb1f9f"
-	GitVersion = "v1.1.2"
-	GitTimestamp = "2019-07-01T02:32:58-06:00"
+	commit = "37c1fd4b5694fd62c9f0d6ad1df47d938accbeec"
+	version = "2.0.0-pre1-dirty"
+	date = "2020-10-10T16:05:59-06:00"
 }