fix docs, add more docs, allow different package name

README.md

@@ -2,16 +2,27 @@
 
 Use git tags to add semver to your go package.
 
->     Goal: Either use an exact version like v1.0.0
+```txt
->           or translate the git version like v1.0.0-4-g0000000
+Goal: Either use an exact version like v1.0.0
->           to a semver like v1.0.1-pre4+g0000000
+      or translate the git version like v1.0.0-4-g0000000
->
+      to a semver like v1.0.1-pre4+g0000000
->           Fail gracefully when git repo isn't available.
+
+      Fail gracefully when git repo isn't available.
+```
 
 # Demo
 
+Generate a `generated-version.go` file:
+
 ```bash
 go run git.rootprojects.org/root/go-gitver
+cat generated-version.go
+```
+
+See `go-gitver`s self-generated version:
+
+```bash
+go run git.rootprojects.org/root/go-gitver version
 ```
 
 # QuickStart
@@ -26,7 +37,7 @@ Add this to the top of your main file:
 Add a file that imports go-gitver (for versioning)
 
 ```go
-// build +tools
+// +build tools
 
 package example
 
@@ -46,8 +57,9 @@ You don't have to use `mod vendor`, but I highly recommend it.
 # Options
 
 ```
-version   print version and exit
+version           print version and exit
---fail    will cause non-zero exit status on failure
+--fail            exit with non-zero status code on failure
+--package <name>  will set the package name
 ```
 
 ENVs
@@ -73,7 +85,7 @@ go run -mod=vendor git.rootprojects.org/root/go-gitver version
 See `examples/basic`
 
 1. Create a `tools` package in your project
-2. Guard it against regular builds with `// build +tools`
+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
@@ -81,7 +93,7 @@ See `examples/basic`
 `tools/tools.go`:
 
 ```go
-// build +tools
+// +build tools
 
 // This is a dummy package for build tooling
 package tools

examples/basic/README.md

@@ -20,6 +20,8 @@ These are the instructions that someone cloning the repo might use.
 ```bash
 go generate -mod=vendor ./...
 go build -mod=vendor -o hello *.go
+./hello
+./hello --version
 ```
 
 Note: If the source is distributed in a non-git tarball then

examples/basic/go.mod

@@ -1,3 +1,5 @@
 module example.com/hello
 
 go 1.12
+
+require git.rootprojects.org/root/go-gitver v1.0.1

examples/basic/tools/tools.go

@@ -1,4 +1,4 @@
-// build +tools
+// +build tools
 
 // This is a dummy package for build tooling
 package tools

examples/no-tools/README.md

@@ -0,0 +1,25 @@
+# Example
+
+Prints the version or a nice message
+
+# Doesn't have a separate tools package
+
+This is just like `examples/basic`,
+but it uses a normal file with a build tag
+rather than a tools package.
+
+See `examples/basic` for more details.
+
+# Demo
+
+```bash
+go mod tidy
+go mod vendor
+```
+
+```bash
+go generate -mod=vendor ./...
+go build -mod=vendor -o hello *.go
+./hello
+./hello --version
+```

examples/no-tools/go.mod

@@ -0,0 +1,5 @@
+module example.com/hello
+
+go 1.12
+
+require git.rootprojects.org/root/go-gitver v1.0.1

examples/no-tools/main.go

@@ -0,0 +1,28 @@
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver --fail
+
+package main
+
+import (
+	"flag"
+	"fmt"
+)
+
+var (
+	GitRev       = "0000000"
+	GitVersion   = "v0.0.0-pre0+0000000"
+	GitTimestamp = "0000-00-00T00:00:00+0000"
+)
+
+func main() {
+	showVersion := flag.Bool("version", false, "Print version and exit")
+	flag.Parse()
+
+	if *showVersion {
+		fmt.Println(GitRev)
+		fmt.Println(GitVersion)
+		fmt.Println(GitTimestamp)
+		return
+	}
+
+	fmt.Println("Hello, World!")
+}

examples/no-tools/tools.go

@@ -0,0 +1,6 @@
+// +build tools
+
+// This is a dummy file for build tooling
+package main
+
+import _ "git.rootprojects.org/root/go-gitver"

examples/sub-package/README.md

@@ -0,0 +1,24 @@
+# Example
+
+Prints the version or a nice message
+
+# Put version in its own packge
+
+This is just like `examples/basic`,
+but it uses the package name `version` instead of `main`.
+
+See `examples/basic` for more details.
+
+# Demo
+
+```bash
+go mod tidy
+go mod vendor
+```
+
+```bash
+go generate -mod=vendor ./...
+go build -mod=vendor -o hello *.go
+./hello
+./hello --version
+```

examples/sub-package/go.mod

@@ -0,0 +1,5 @@
+module example.com/hello
+
+go 1.12
+
+require git.rootprojects.org/root/go-gitver v1.0.1

examples/sub-package/main.go

@@ -0,0 +1,22 @@
+package main
+
+import (
+	"flag"
+	"fmt"
+
+	"example.com/hello/version"
+)
+
+func main() {
+	showVersion := flag.Bool("version", false, "Print version and exit")
+	flag.Parse()
+
+	if *showVersion {
+		fmt.Println(version.GitRev)
+		fmt.Println(version.GitVersion)
+		fmt.Println(version.GitTimestamp)
+		return
+	}
+
+	fmt.Println("Hello, World!")
+}

examples/sub-package/tools/tools.go

@@ -0,0 +1,8 @@
+// +build tools
+
+// This is a dummy package for build tooling
+package tools
+
+import (
+	_ "git.rootprojects.org/root/go-gitver"
+)

examples/sub-package/version/version.go

@@ -0,0 +1,9 @@
+//go:generate go run -mod=vendor git.rootprojects.org/root/go-gitver --package version
+
+package version
+
+var (
+	GitRev       = "0000000"
+	GitVersion   = "v0.0.0-pre0+0000000"
+	GitTimestamp = "0000-00-00T00:00:00+0000"
+)

gitver.go

@@ -37,11 +37,16 @@ func init() {
 }
 
 func main() {
+	pkg := "main"
+
 	args := os.Args[1:]
 	for i := range args {
 		arg := args[i]
 		if "-f" == arg || "--fail" == arg {
 			exitCode = 1
+		} else if "--package" == arg && len(args) > i+1 {
+			pkg = args[i+1]
+			args[i+1] = ""
 		} else if "-V" == arg || "version" == arg || "-version" == arg || "--version" == arg {
 			fmt.Println(GitRev)
 			fmt.Println(GitVersion)
@@ -66,10 +71,12 @@ func main() {
 	}
 
 	v := struct {
+		Package   string
 		Timestamp string
 		Version   string
 		GitRev    string
 	}{
+		Package:   pkg,
 		Timestamp: ts.Format(time.RFC3339),
 		Version:   ver,
 		GitRev:    rev,
@@ -195,7 +202,7 @@ func gitTimestamp(desc string) (time.Time, error) {
 }
 
 var versionTpl = template.Must(template.New("").Parse(`// Code generated by go generate; DO NOT EDIT.
-package main
+package {{ .Package }}
 
 func init() {
 	GitRev = "{{ .GitRev }}"