https://github.com/linkdata/gitsemver
Build a semver compliant version string for a git repository
https://github.com/linkdata/gitsemver
git git-semver git-tag go golang semver
Last synced: 18 days ago
JSON representation
Build a semver compliant version string for a git repository
- Host: GitHub
- URL: https://github.com/linkdata/gitsemver
- Owner: linkdata
- License: mit
- Created: 2025-02-07T07:06:19.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-03-03T13:41:43.000Z (19 days ago)
- Last Synced: 2026-03-03T13:41:56.245Z (19 days ago)
- Topics: git, git-semver, git-tag, go, golang, semver
- Language: Go
- Homepage:
- Size: 96.7 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://github.com/linkdata/gitsemver/actions/workflows/build.yml)
[](https://html-preview.github.io/?url=https://github.com/linkdata/gitsemver/blob/coverage/main/report.html)
[](https://goreportcard.com/report/github.com/linkdata/gitsemver)
[](https://godoc.org/github.com/linkdata/gitsemver)
# gitsemver
Build a SemVer-inspired version string for a git repository.
Using tree hashes it returns the latest matching semver tag. If no tree hash
match exactly, it falls back to the latest semver tag reachable from the
current HEAD.
If the match is not exact or the current branch is not the default branch
or a protected branch (`CI_COMMIT_REF_PROTECTED` or `GITHUB_REF_PROTECTED` are set),
it creates a work-in-progress semver string like `v0.1.2-myfeature.123`.
Supports raw git repositories as well as GitLab and GitHub builders.
### Scope and limitations
`gitsemver` is a CLI-first tool, one process run per repository.
Tag matching is intentionally relaxed: `vMAJOR`, `vMAJOR.MINOR`, and
`vMAJOR.MINOR.PATCH` (and the same forms without `v`) are all accepted and
preserved in output. If you require strict SemVer 2.0.0 output, use full
`MAJOR.MINOR.PATCH` tags in Git.
The implementation package is intentionally internal to this module and is not a
supported external API.
If reused anyway, create a new `GitSemVer` instance per version lookup
snapshot; reusing one instance across repository changes can return stale data
because tag metadata is cached.
### Installing
```sh
$ go install github.com/linkdata/gitsemver@latest
```
### Command line parameters
```
Usage of gitsemver:
-debug
write debug info to stderr
-git string
path to Git executable (default "git")
-gopackage
write Go source with PkgName and PkgVersion
-incpatch
increment the patch level and create a new tag
-name string
override the Go PkgName, default is to use last portion of module in go.mod
-nofetch
don't fetch remote tags
-nonewline
don't print a newline after the output
-out string
write to file instead of stdout (relative paths are relative to repo)
```
### Examples
#### Print current version of a git repository
```sh
$ gitsemver $HOME/myreleasedpackage
v1.2.3
```
#### Increment the patch level and push a new lightweight tag to the origin
```sh
$ gitsemver
v1.2.3-main.456
$ gitsemver -incpatch
v1.2.4
```
#### Generate a go package file with version information
```go
//go:generate go run github.com/linkdata/gitsemver@latest -gopackage -out version.gen.go
```
Generates a file called `version.gen.go` with contents like
```go
// Code generated by gitsemver at 2025-02-10 07:47:15 UTC DO NOT EDIT.
// branch "mybranch", build 456
package mypackage
const PkgName = "mypackage"
const PkgVersion = "v1.2.3-mybranch.456"
```