fix docs, add more docs, allow different package name

This commit is contained in:
AJ ONeal 2019-06-20 23:27:41 -06:00
parent f104a3155f
commit 47b8ec43ae
14 changed files with 167 additions and 12 deletions

View File

@ -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 <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

View File

@ -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

View File

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

View File

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

View File

@ -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
```

5
examples/no-tools/go.mod Normal file
View File

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

28
examples/no-tools/main.go Normal file
View File

@ -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!")
}

View File

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

View File

@ -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
```

View File

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

View File

@ -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!")
}

View File

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

View File

@ -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"
)

View File

@ -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 }}"