From 47b8ec43ae9424d52be088e1250eea589ce503f1 Mon Sep 17 00:00:00 2001 From: AJ ONeal Date: Thu, 20 Jun 2019 23:27:41 -0600 Subject: [PATCH] fix docs, add more docs, allow different package name --- README.md | 32 +++++++++++++++++-------- examples/basic/README.md | 2 ++ examples/basic/go.mod | 2 ++ examples/basic/tools/tools.go | 2 +- examples/no-tools/README.md | 25 +++++++++++++++++++ examples/no-tools/go.mod | 5 ++++ examples/no-tools/main.go | 28 ++++++++++++++++++++++ examples/no-tools/tools.go | 6 +++++ examples/sub-package/README.md | 24 +++++++++++++++++++ examples/sub-package/go.mod | 5 ++++ examples/sub-package/main.go | 22 +++++++++++++++++ examples/sub-package/tools/tools.go | 8 +++++++ examples/sub-package/version/version.go | 9 +++++++ gitver.go | 9 ++++++- 14 files changed, 167 insertions(+), 12 deletions(-) create mode 100644 examples/no-tools/README.md create mode 100644 examples/no-tools/go.mod create mode 100644 examples/no-tools/main.go create mode 100644 examples/no-tools/tools.go create mode 100644 examples/sub-package/README.md create mode 100644 examples/sub-package/go.mod create mode 100644 examples/sub-package/main.go create mode 100644 examples/sub-package/tools/tools.go create mode 100644 examples/sub-package/version/version.go diff --git a/README.md b/README.md index 2785b04..fc49d73 100644 --- a/README.md +++ b/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 -> 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. +```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 + + 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 ---fail will cause non-zero exit status on failure +version print version and exit +--fail exit with non-zero status code on failure +--package 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 diff --git a/examples/basic/README.md b/examples/basic/README.md index 9a92e34..f677d64 100644 --- a/examples/basic/README.md +++ b/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 diff --git a/examples/basic/go.mod b/examples/basic/go.mod index be70eb1..61b4360 100644 --- a/examples/basic/go.mod +++ b/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 diff --git a/examples/basic/tools/tools.go b/examples/basic/tools/tools.go index a48cf2e..d09a206 100644 --- a/examples/basic/tools/tools.go +++ b/examples/basic/tools/tools.go @@ -1,4 +1,4 @@ -// build +tools +// +build tools // This is a dummy package for build tooling package tools diff --git a/examples/no-tools/README.md b/examples/no-tools/README.md new file mode 100644 index 0000000..297358f --- /dev/null +++ b/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 +``` diff --git a/examples/no-tools/go.mod b/examples/no-tools/go.mod new file mode 100644 index 0000000..61b4360 --- /dev/null +++ b/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 diff --git a/examples/no-tools/main.go b/examples/no-tools/main.go new file mode 100644 index 0000000..e898c22 --- /dev/null +++ b/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!") +} diff --git a/examples/no-tools/tools.go b/examples/no-tools/tools.go new file mode 100644 index 0000000..af07c0b --- /dev/null +++ b/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" diff --git a/examples/sub-package/README.md b/examples/sub-package/README.md new file mode 100644 index 0000000..fabc952 --- /dev/null +++ b/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 +``` diff --git a/examples/sub-package/go.mod b/examples/sub-package/go.mod new file mode 100644 index 0000000..61b4360 --- /dev/null +++ b/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 diff --git a/examples/sub-package/main.go b/examples/sub-package/main.go new file mode 100644 index 0000000..732e39c --- /dev/null +++ b/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!") +} diff --git a/examples/sub-package/tools/tools.go b/examples/sub-package/tools/tools.go new file mode 100644 index 0000000..d09a206 --- /dev/null +++ b/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" +) diff --git a/examples/sub-package/version/version.go b/examples/sub-package/version/version.go new file mode 100644 index 0000000..891bdce --- /dev/null +++ b/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" +) diff --git a/gitver.go b/gitver.go index 645b25e..af778c5 100644 --- a/gitver.go +++ b/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 }}"