gotagger

README

gotagger

Table of Contents

• Overview
  • Installation
• Getting started
  • Running
  • Go Module Support
• Using gotagger as a library
• Contributing
• License

Overview

gotagger is a library and CLI for tagging releases in git repositories as part of a CI process.

gotagger looks through the git history of the current commit for the latest semantic version. This becomes the "base" version. Then gotagger examines all of the commit messages between the current commit and the latest tag, to determine if the most significant change was a feature, bug fix, or breaking change per the Conventional Commits format. gotagger then increments the base version accordingly and print the new version.

If the current commit type is release and the -release flag or GOTAGGER_RELEASE environment variable is set, then gotagger will tag the current commit with the new version. If there are no commits explicitly marked as a feature or a bug fix, then the patch version is incremented.

Installation

You can install gotagger by downloading a pre-built binary for your OS and architecture from our releases page.

Alternatively, you can install gotagger directly with go get. If you go this route, we recommend that you create a "fake" module, so you can ensure you build a supported release:

mkdir tmp
cd tmp
go mod init fake
go get github.com/sassoftware/gotagger

Getting started

Running

Run gotagger inside of a git repository to see what the current version is.

git clone https://github.com/sassoftware/gotagger.git
cd gotagger
make build
build/$(go env GOOS)/gotagger
v0.4.0

Note: The version reported may be different, depending on what unreleased changes exist.

To tag a release, make any changes needed to prepare your project for releasing (ie. update the change log, merge any feature branches). Then create a "release" commit and run gotagger again:

VERSION="$(gotagger)"
git commit -m "release: $VERSION"
gotagger -release

You can now perform any release builds, push the tag to your central git repository, or any other post-release tasks.

gotagger can also push any tags it creates, by using the -push flag.

gotagger -release -push

Go Module Support

By default gotagger will enforce semantic import versioning on any project that has one or more go.mod files. This means gotagger will ignore tags whose major version does not match the major version of the module, as well as tags whose prefix does not match the path to the module's go.mod file.

For projects that are not written in go but do have a go.mod for build tooling, the -modules flag and GOTAGGER_MODULES environment variable can be used to disable this behavior.

gotagger can also tag go multi-module repositories. To tag one ore more modules, include a Modules footer in your commit message containing a comma-separated list of modules to tag:

release:  the bar and baz modules

Modules: foo/bar, foo/baz

You can also use multiple Modules footers if you prefer:

release: the bar and baz modules in separate footers

Modules: foo/bar
Modules: foo/baz

To release the "root" module explicitly list it in the Modules footer:

release: foo and bar

Modules: foo, foo/bar

# "Modules: foo/bar, foo" also works

gotagger will print out all of the versions it tagged in the order they are specified in the Modules footer.

Using gotagger as a library

import github.com/sassoftware/gotagger

Create a Gotagger instance

g, err := gotagger.New("path/to/repo")
if err != nil {
    return err
}

// get the current version of a repository
version, err := g.Version()
if err != nil {
    return err
}
fmt.Println("version:", version)

// Uncomment this to ignore the module example.com/bar or any modules under some/path
// g.Config.ExcludeModules = []string{"example.com/bar", "some/path"}

// get the version of module foo
fooVersion, err := g.ModuleVersion("foo")
if err != nil {
    return err
}
fmt.Println("foo version:", fooVersion)

// Check what versions will be tagged.
// If HEAD is not a release commit,
// then only the the main module version is returned.
versions, err := g.TagRepo()
if err != nil {
    return err
}

for _, v := range versions {
    fmt.Println(v)
}

// Create the tags
g.Config.CreateTag = true

// uncomment to push tags as well
// g.Config.PushTag = true

_, err := g.TagRepo()
if err != nil {
    return err
}

Contributing

We welcome your contributions! Please read CONTRIBUTING.md for details on how to submit contributions to this project.

License

This project is licensed under the Apache 2.0 License.

Documentation

Index

• Variables
• func TagRepo(cfg *Config, r ggit.Repo) (*semver.Version, error)
• type Config
  • func NewDefaultConfig() Config
• type Gotagger
  • func New(path string) (*Gotagger, error)
  • func (g *Gotagger) ModuleVersions(names ...string) ([]string, error)
  • func (g *Gotagger) TagRepo() ([]string, error)
  • func (g *Gotagger) Version() (string, error)

Variables

var (
	ErrNoSubmodule = errors.New("no submodule found")
	ErrNotRelease  = errors.New("HEAD is not a release commit")
)

Functions

func TagRepo

func TagRepo(cfg *Config, r ggit.Repo) (*semver.Version, error)

TagRepo determines what the curent version of the repository is by parsing the commit history since previous release and returns that version. Depending on the state of the Config passed it, it may also create the tag and push it.

This function is deprecated and will be removed before the v1.0.0 release of gotagger.

Types

type Config

type Config struct {
	// CreateTag represents whether to create the tag.
	CreateTag bool

	// ExcludeModules is a list of module names or paths to exclude.
	ExcludeModules []string

	// IgnoreModules controls whether gotagger will ignore the existence of
	// go.mod files when determinging how to version a project.
	IgnoreModules bool

	// RemoteName represents the name of the remote repository. Defaults to origin.
	RemoteName string

	// PreMajor controls whether gotagger will increase the major version from 0
	// to 1 for breaking changes.
	PreMajor bool

	// PushTag represents whether to push the tag to the remote git repository.
	PushTag bool

	// VersionPrefix is a string that will be added to the front of the version. Defaults to 'v'.
	VersionPrefix string
}

Config represents how to tag a repo. If not default is mentioned, the option defaults to go's zero-value.

func NewDefaultConfig

func NewDefaultConfig() Config

NewDefaultConfig returns a Config with default options set.

If an option is not mentioned, then the default is the zero-value for its type.

• RemoteName origin
• VersionPrefix v

type Gotagger

type Gotagger struct {
	Config Config
	// contains filtered or unexported fields
}

func New

func New(path string) (*Gotagger, error)

func (*Gotagger) ModuleVersions

func (g *Gotagger) ModuleVersions(names ...string) ([]string, error)

ModuleVersions returns the current version for all go modules in the repository in the order they were found by a depth-first, lexicographically sorted search.

For example, in a repository with a root go.mod and a submodule foo/bar, the slice returned would be: []string{"v0.1.0", "bar/v0.1.0"}

If module names are passed in, then only the versions for those modules are returned.

func (*Gotagger) TagRepo

func (g *Gotagger) TagRepo() ([]string, error)

TagRepo determines the curent version of the repository by parsing the commit history since the previous release and returns that version. Depending on the CreateTag and PushTag configuration options tags may be created and pushed.

If the current commit contains one or more Modules footers, then tags are created for each module listed. In this case if the root module is not explicitly included in a Modules footer then it will not be included.

func (*Gotagger) Version

func (g *Gotagger) Version() (string, error)

Version returns the current version for the repository.

In a repository that contains multiple go modules, this returns the version of the first module found by a depth-first, lexicographically sorted search. Usually this is the root module, but possibly not if the repo is a monorepo with no root module.