caarlos0/svu

Semantic Version Util

svu

Semantic Version Util is a tool to manage semantic versions at ease!

You can print the current version, increase patch/minor/major manually or just get the next tag based on your git log!

example usage

svu

Based on the log between the latest tag and HEAD, prints the next tag.

aliases: svu next and svu n

$ svu
v1.3.0

commit messages vs what they do

Commit message	Tag increase
fix: fixed something	Patch
feat: added new button to do X	Minor
fix: fixed thing xyz BREAKING CHANGE: this will break users because of blah	Major
fix!: fixed something	Major
feat!: added blah	Major
chore: foo	Nothing

svu current

Prints the current tag with no changes.

alias: svu c

Examples:

$ svu current
v1.2.3

$ svu current
v1.2.3-alpha.1+22

svu major

Increases the major of the latest tag and prints it. As per the Semver spec, it'll also clear the pre-release and build identifiers are cleaned up.

Examples:

$ svu current
v1.2.3-alpha.2+123

$ svu major
v2.0.0

$ svu major --pre-release alpha.3 --build 243
v2.0.0-alpha.3+243

svu minor

Increases the minor of the latest tag and prints it. As per the Semver spec, it'll also clear the pre-release and build identifiers are cleaned up.

alias: svu m

Examples:

$ svu current
v1.2.3-alpha.2+123

$ svu minor
v1.3.0

$ svu minor --pre-release alpha.3 --build 243
v1.3.0-alpha.3+243

svu patch

Increases the patch of the latest tag and prints it. As per the Semver spec, if the version has a pre-release or build identifier, they'll be cleaned up and no patch increment will be made. You can force a patch increment by using svu next --force-patch-increment.

alias: svu p

Examples:

$ svu current
v1.2.3-alpha.2+123

$ svu patch
v1.2.3

$ svu patch --pre-release alpha.3 --build 243
v1.2.3-alpha.3+243

$ svu next --force-patch-increment
v1.2.4

svu prerelease

Increases the pre-release of the latest tag and prints it. If a pre-release identifier is passed in and it differs from the current pre-release tag that the identifier passed in will be used. If the current tag is not a pre-release tag then passing in --pre-release is required.

alias: svu pr

Examples:

$ svu current
v1.2.3-alpha.2+123

$ svu prerelease
v1.2.3-alpha.3

$ svu prerelease --pre-release alpha.33 --build 243
v1.2.3-alpha.33+243

tag mode

By default svu will get the latest tag from the current branch. Using the --tag-mode flag this behaviour can be altered:

Flag	Description	Git command used under the hood
--tag-mode current-branch	Get latest tag from current branch.	git describe --tags --abbrev=0
--tag-mode all-branches	Get latest tag across all branches.	git describe --tags $(git rev-list --tags --max-count=1)

stripping the tag prefix

--strip-prefix removes any prefix from the version output. For example, v1.2.3 would be output as 1.2.3.

The default prefix is v, however a custom prefix can be supplied using --prefix. So for --prefix=foo/v --strip-prefix and tag foo/v1.2.3, the output would be 1.2.3.

adding a suffix

You can use --pre-release and --build to set the respective Semver identifiers to the resulting version.

force patch version increment

Setting the --force-patch-increment flag forces a patch version increment regardless of the commit message content.

Example:

svu next --force-patch-increment

creating tags

The idea is that svu will just print things, so it's safe to run at any time.

You can create tags by wrapping it in an alias. For example, I have one like this:

alias gtn='git tag $(svu next)'

So, whenever I want to create a tag, I just run gtn.

install

macOS

brew install caarlos0/tap/svu

linux

apt

echo 'deb [trusted=yes] https://apt.fury.io/caarlos0/ /' | sudo tee /etc/apt/sources.list.d/caarlos0.list
sudo apt update
sudo apt install svu

yum

echo '[caarlos0]
name=caarlos0
baseurl=https://yum.fury.io/caarlos0/
enabled=1
gpgcheck=0' | sudo tee /etc/yum.repos.d/caarlos0.repo
sudo yum install svu

docker

docker run --rm -v $PWD:/tmp --workdir /tmp ghcr.io/caarlos0/svu --help

Using go install

Make sure that $GOPATH/bin is in your $PATH, because that's where this gets installed:

go install github.com/caarlos0/svu@latest

manually

Or download one from the releases tab and install manually.

use as library

You can use svu as a library without the need to install the binary. For example to use it from a magefile:

//go:build mage
// +build mage

package main

import (
	"github.com/caarlos0/svu/pkg/svu"
	"github.com/magefile/mage/sh"
	"strings"
)

// Tag the current commit with the proper next semver.
func Version() error {
	v, err := svu.Next()
	if err != nil {
		return err
	}
	return sh.RunV("git", "tag", "-a", v, "-m", strings.Replace(v, "v", "Version ", 1))
}

commands

All commands are available with a function named accordingly:

• svu.Next()
• svu.Current()
• svu.Major()
• svu.Minor()
• svu.Patch()
• svu.PreRelease()

options

All flags have a matching option function to configure the previous commands beyond their default bahavior:

• svu.Current(svu.WithPattern("p*"))
• svu.Next(svu.WithPrefix("ver"))
• svu.Major(svu.StripPrefix())
• svu.Minor(svu.WithPreRelease("pre"))
• svu.Patch(svu.WithBuild("3"))
• svu.Next(svu.WithDirectory("internal"))
• svu.Next(svu.WithTagMode(svu.AllBranches)) or svu.Next(svu.ForAllBranches())
• svu.Next(svu.WithTagMode(svu.CurrentBranch)) or svu.Next(svu.ForCurrentBranch())
• svu.Next(svu.ForcePatchIncrement())

Or multiple options:

• svu.Next(svu.WithPreRelease("pre"), svu.WithBuild("3"), svu.StripPrefix())
• svu.PreRelease(svu.WithPreRelease("alpha.33"), svu.WithBuild("243"))

stargazers over time

svu's Issues

can't add metadata

there are flags to strip metadata, but there doesn't appear to be a way to add metadata

--suffix flag will always use a - separator

git tag --sort=version:refname

I have no idea why this JUST started happening on my NEW Mac, but I did a fresh clone and now it is pulling the wrong "current" tag.

This is because I used to try and follow the old docker style semver where it was based on the date, but like them decided that wasn't a good way to do it and switch back to traditional semver, but NOW my old tags (which are higher numbers due to the year) are being chosen instead of the real current tag?

I bet what is really happening is I was using an older version of svu and updated to latest on the NEW Mac and that's why? Is there any way for you to get the versions based on "added date" or "commit date" ? instead of sorting by semver?

Thanks for a great tool.

Using gitmoji's instead of convential commits

Introduction

I am heavily inspired of the simplicity of svu - that I would like to request a feature that would help my personal workflow - but I understand that adding a new feature like this may introduce complexity - and I'm happy to make a fork if thats the case.

The basic jist is if we have commits like:

✨ support customer withdrawls
🐛 disallow negative bank balance withdrawls

I would like svu to create a semantic release based on the git log similar to how it is doing it for conventional commits such as fix, feat etc.

gitmoji recently assigned major, minor, patch to each emoji in this PR: carloscuesta/gitmoji#692

FYi - I understand if you think this complicates svu - so I'm happy to create.. a heavily inspired project based on svu (with due credit as per the LICENSE)

Initial version does not work if pattern is supplied

Effectively, if a pattern is supplied and no existing tags are found an error is always returned.

svu/internal/git/git.go

Lines 45 to 54 in 0b3a780

	g, err := glob.Compile(pattern)
	if err != nil {
	return "", err
	}
	for _, tag := range tags {
	if g.Match(tag) {
	return tag, nil
	}
	}
	return "", fmt.Errorf("no tags match '%s'", pattern)

Whereas if no pattern is supplied, it is not an error to find no tags:

svu/internal/git/git.go

Lines 38 to 40 in 0b3a780

	if len(tags) == 0 {
	return "", nil
	}

Wrong version

Hello there,
I have been using this tool for a while, however today it unexpectedly stopped working.

When I run svu current I have v0.0.0 and svu next v0.0.1, however if I run: git -c versionsort.suffix=- tag --sort=-version:refname I do have those tags:

v0.0.4
v0.0.3
v0.0.2
v0.0.1

This is my git history (redacted):

commit 1e9b592c7cbd79943912c2cc5b991... (HEAD -> master, origin/master, origin/HEAD)

    fix(): ...

commit 0dd528783ec1865b3dabdbdc563741...

    fix(): ...

commit ec1ed1c996fd9abe021deb4cc74f9f9...

    fix(): ...

commit 84d8a0b1502185701f7a306355ed7...

    fix(): ...

commit 04e954cfc7651a603e6902b0c61b.....

    fix(): ...

commit 5ff010863cabe044db79e74785f....

    fix(): ...

commit 66f8c5a48c7e7994ec58fff44...

    fix(): initial commit

What am I doing wrong?

SVU version:

svu version dev
module version: v1.10.2, checksum: h1:2ukKeauB6pbTeP/2XuMG8LMWCqQdf9OXA8/7J4OoM98=

Git: git version 2.25.1

Container fails in GitHub action with "detected dubious ownership in repository at '/__w/$org/$repo"

Using the container in a GitHub action fails with detected dubious ownership in repository at '/__w/$org/$repo in version v1.10.1, but only since somewhen between 2023-03-07 and 2023-03-11.

Failing run

https://github.com/envelope-zero/backend/actions/runs/4394426078/jobs/7695486001

Workflow file: https://github.com/envelope-zero/backend/blob/7b26e4aa408616d269963a0a07b98d4088c69e1a/.github/workflows/test-and-tag.yml

Error message:

svu: error: failed to get current tag for repo: fatal: detected dubious ownership in repository at '/__w/backend/backend'
To add an exception for this directory, call:

	git config --global --add safe.directory /__w/backend/backend

fatal: detected dubious ownership in repository at '/__w/backend/backend'

Workaround

I decided to test if it is an issue with git, svu or github actions by installing svu from the tar archive, see https://github.com/envelope-zero/backend/actions/runs/4397136490/jobs/7700078830.

Workflow file: https://github.com/envelope-zero/backend/blob/af04c70870006828145516fb2c7fda3f5e2be5ba/.github/workflows/test-and-tag.yml

This ran without issues

Analysis

Checking out some other reports of this issue over the last few months, I think this might be related to the git version or base image version of the svu container. I did not check this any further, though.

Request for new feature: Increment pre-release version number

Currently, there is no straightforward way to increment the pre-release version number in our system. I propose a new functionality to address this issue. With this new feature, users can easily increment the pre-release version number with a single command.

For instance, if the current version is "v1.0.0-alpha.1," users can use the following command to increment the pre-release version number to "v1.0.0-alpha.2":

➜ svu pre-release --pre-release='alpha'
v1.0.0-alpha.2

changelog generation

this tool looks pretty sweet. I was wondering if it could act as an all-in-one release preparation; finding the next tag and generating the changelog for said tag... ?

ability to provide custom commit types

Would you consider supporting custom commit types ?

For example one could consider commits of type let's say perf, that would result in a PATCH bump.

Documentation for svu patch has wrong example

In the README, the docs for svu patch has a wrong example.

It shows svu patch --force-patch-increment but the flag is only available for the svu next command.

Glad to submit a PR if you want.

"fix: " not incrementing patch version

I created an empty repo, added a README.md and tagged with v0.1.0

making a change and committing with the message fix: fixed something

* dfea6e8b - (7 seconds ago) (HEAD -> master) Cuotos - fix: fixed something 
* 1dc551c3 - (82 seconds ago) (tag: v0.1.0) Cuotos - readme 

$ svu
v0.1.0

I would expect this to be v0.1.1. calling svu patch correctly returns v0.1.1.
fix!: message also correctly increases the Major version

Initial version

Given a repo that has no tags (yet), svu does not seem to be able to derive a version (0.1.0 or 1.0.0 for example)
Is this something I am missing in the --help
or is it a "feature request" ?

Breaking changes via ! for other commit types

Following the conventional commit standards you are able to define breaking versions by appending the type of commit with a !.

However, when doing this in-conjunction with any commit type other than fix or feat you are unable to get a major version bump to be generated.

It does appear this was implemented during v1.1.0's life: 30580f2
And then removed: add1a80

For example:

chore!: A breaking chore this should generate a major version bump

Please re-tag a v1.10.3 or v1.11.0 release to include recent main changes

I'd like to use the new --directory= functionality without using main as the version. Could a v1.10.3 or v1.11.0 tag be created?

Sorry for the brevity but this feels self-explanatory. ;-) Thanks!

@caarlos0

breaking change for major version zero should bump minor instead of major

Hi,

currently a breaking change will always bump the major version. However this is not desirable if the major version is 0.

Semver says (link):

4. Major version zero (0.y.z) is for initial development. Anything MAY change at any time. The public API SHOULD NOT be considered stable.

And also (link):

Major version zero is all about rapid development. If you’re changing the API every day you should either still be in version 0.y.z or on a separate development branch working on the next major version.

It would be good that breaking change only increment the major version if it is not 0.

FR: Throw an error if "next" do not change

Hi,

The actual behavior is to print the last tag when asking next version even if there is no conventional commit who trigger a version bump.
Would be great to throw an error if there is no possibility to bump the version.

Regards,

Need to use svu as a go library

Hi,

I have a use case, where I need to import and use an available go library that can do automatic version management. I explored a couple of options already and I decided to use svu.

The problems that I have encountered so far are the followings:

• git external dependency is used, instead of go-git (go implementation of git)
• no available logic to generate a prerelease automatically
• unable to import the library in my project (most of the methods are in the internal package)

Is there a chance to have any of those implemented in the near future? I'm open to contributing as well

Thanks

Support for custom prefix

I'm maintaining a go monorepo and it builds many releasable artifacts. It's using a convention of prefixing the tag with the artifact name, e.g. for foo and bar you could expect tags:

• foo/v0.1.0
• foo/v0.2.0
• bar/v1.0.0
• bar/v2.0.0
• etc.

I was hoping --pattern would help but it parses the entire tag as a semver:

> svu --pattern='foo/*' current
svu: error: version foo/v0.2.0 is not semantic: Invalid Semantic Version

Would supporting such behaviour be desireable?
Maybe adding a --prefix argument which would be honored by --strip-prefix, like:

> svu --pattern='foo/*' --prefix='foo/v' --strip-prefix current
0.2.0
> svu --pattern='foo/*' --prefix='foo/v' current
foo/v0.2.0

`next` does not handle suffixes

Any versions with a suffix are not incremented when next is called.

Major == 0, no breaking changes

I am curious about this decision. I assume there's a legitimate reason behind it, but it seems pretty prescriptive. With this I can't go from major version 0 to 1 with a breaking change. I am using svu in an automated release pipeline and this tiny bit of logic breaks my automation. Shouldn't this be behind a flag as an option rather than a defacto implementation?

Can you explain the reasoning?

Provide a Docker image

I almost just PR'd this since I think it would be trivial, but better to ask first. Can we publish a docker image for this tool? Assuming the answer is yes, would it then just be sufficient to include https://github.com/caarlos0/.goreleaserfiles/blob/main/docker.yml in the yaml file?

Once a suffix is appended to a tag, all later tags include the suffix

given a tag v0.0.1
if I run

git tag $(svu n --suffix=pr.000-d0a7d4c)

I get v0.0.2-pr.000-d0a7d4c

(where 000 is a pull request number, and d0a7d4c is a short git sha)

subsequent runs just end up taking the old suffix, and add a new suffix

svu n --suffix=pr.000-d0a7d4c
0.0.2-pr.000-d0a7d4c0.0.2-pr.000-d0a7d4c

I'm trying to figure out how to avoid the suffix duplication?
I think maybe I need a --strip-suffix ???

Breaking changes detection is not compliant with the specification

According to the conventional commit specification:

The units of information that make up Conventional Commits MUST NOT be treated as case sensitive by implementors, with the exception of BREAKING CHANGE which MUST be uppercase.
BREAKING-CHANGE MUST be synonymous with BREAKING CHANGE, when used as a token in a footer.

Looking at the code it seems the regex is case insensitive, and does not match the token containing a dash.

How to create prereleases

Hi,

i've checked your project and really like it.
But it seems to weird that there is an option to remove prerelease and other metadata but not to create such metadata.
Or at least i've not found it.

So is it possible to create prerelease tags? e.g. with commit id or date or something?

Thanks

Creates a new tag ?

Hi,

Great little utility, i was hoping on using it with go-releaser :-)

It wasn't clear from the readme, but does this ONLY output the next semantic version based on conventional commits ?

Or does it create the tag ?

is there an option to create the tag ?

Thanks in advance

--no-pre-release stopped working

Hi there,

With the latest release, my Github actions started failing when using --no-pre-release flag:

I was checking and it works ok in version 1.9.0 and starts failing as soon as I upgrade to 1.10.1, not sure if it's working on 1.10.0 tho.
Before the update:

And after the update:

Update Deps

Could you bump dependencies and cut a release?

github.com/Masterminds/semver:
in go.mod: v1.5.0
current release: v3.2.1

github.com/alecthomas/kingpin:
in go.mod: v2.2.6+incompatible
current release: v2.4.0

If the last tagged commit has multiple tags, svu should increment from the highest of those tags

My release logic has blown up a few times and resulted in two svu-created tags going on the same commit, not necessarily with the "highest" tag being applied most recently. I'm not sure how that's happening, but hey, such is life. It'd be great if svu patch was able to handle these cases in such a way that the highest semver of all tags on the most recently tagged commit was used.

Here's an example of the scenario - a commit somehow ended up with both v1.0.34 and v1.0.35. v1.0.35 was applied before v1.0.34, so svu patch always returns v1.0.35 for the next version, getting my automation stuck in an eternal loop of trying to create v1.0.35, but it already exists, etc.

I would've opened a PR for this if I could figure out a fix, but I haven't managed that yet. =)

[bug] svu next without "V"

$ git tag -l '[0-9]*' --sort=refname
7.11.4
7.12.0
7.14.0
7.15.0
$ echo $(svu next --strip-prefix)
7.14.0

Ignore certain tags or invalid tags?

Hi,

i am trying to use svu on a repo that has tags that do not conform to semVer, but i get the following error:

svu: error: could not get current version from tag: 'early-release': Invalid Semantic Version

Would it be possible to have an option to either skip some specific tags, or to ignore all tags that are not semantic version tags?

Issues on Gitlab-ci

Hello, I can't make it work on my gitlab pipeline.

At a certain point in my pipeline (let's say the release job), i'm running the the following command:

curl -sfL https://install.goreleaser.com/github.com/caarlos0/svu.sh | bash -s -- -b /usr/local/bin

All i get is an exit code 1 and it prevents next commands to be executed (see screenshot)

Since it is erroring and exiting, i cannot tag neither create a release

release:build:
  stage: release
  image:
    name: goreleaser/goreleaser
    entrypoint: [ '' ]
  only:
    - main
  variables:
    # Disable shallow cloning so that goreleaser can diff between tags to
    # generate a changelog.
    GIT_DEPTH: 0
  script:
    -  curl -sfL https://install.goreleaser.com/github.com/caarlos0/svu.sh | bash -s -- -b /usr/local/bin
    - git tag $(svu next)
    - goreleaser release --rm-dist

What am I doing wrong ?

Thanks

--no-metadata stopped working in v1.10.1

Hi there, we have code logic below:

    next_version="$(svu n --force-patch-increment --no-metadata --tag-mode all-branches ${svu_extra_args[@]} 2> /dev/null)"
    if [[ -z "${next_version}" ]]; then
      next_version="$(svu n --force-patch-increment --no-metadata --tag-mode all-branches)"
    fi

We got an error about unknown long flag '--no-metadata'

I wonder if it's intended to deprecate the flag, where can I find more information about the changelogs? thanks

Option to ignore merge commits

We just added svu / goreleaer to one of our repos and it didn't quite work as i would have expected it to.

Previous tag v1.0.3

I made a branch (goreleaser-prerelease) that tagged commits with a prerelease tag via:
svu prerelease --pre-release ${branch} --build ${ci_build_num}

Since the commits here were feat!: this was producing tags like

v2.0.0-goreleaser-prerelease.0+3396

Everything is great up to this point 👍🏻

However once this branch merged back to master, the next tag was producing 2.1.0 instead of the expected v2.0.0 with just the prereleae options removed.

It seems like since we have an external bot merging commits with messages like

Merge pull request $PR-LINK from repo/branch
feat: add goreleaser for po

which include the pr title

svu was using the current tag as the prerelease tag v2.0.0-goreleaser-prerelease.0+3396 then bumping the Minor due to this message.

I saw another issue mentioning a no-prerelease flag that isn't supported anymore and links to other options but I don't think it would have fixed this issue, since this would have also just added on more to the --pre-release / --build options or forced a Minor bump which was happening anyway. Is there anyway to add in a ignore-merge-commits option since the default is just to use the commit as the pr title this seems like it will continue to happen if the branch being merged in had a prerelease.

If log is empty forcePatchIncrement should not increment the version number

if forcePatchIncrement || isPatch(log) {
	return current.IncPatch()
}

means that even if log is empty (no commits since last tag) and forcePatchIncrement is true a new patch version is bumped. But if I am on top a tag means that I am already on a release. IMHO forcePatchIncrement should only work if there are commits (without fix: feat: or ! identifier) on top of the last tag.

flag `--pre-release` description doesn't make much sense

--pre-release              discards pre-release metadata if set to false

svu n --pre-release=false
svu: error: unexpected false, try --help

svu n --pre-release false
svu: error: unexpected false, try --help

svu n --pre-release=true
svu: error: unexpected true, try --help

svu n --pre-release true
svu: error: unexpected true, try --help