{"id":49782213,"url":"https://github.com/arnaud-deprez/gsemver","last_synced_at":"2026-05-11T22:02:39.557Z","repository":{"id":38973813,"uuid":"179023855","full_name":"arnaud-deprez/gsemver","owner":"arnaud-deprez","description":"gsemver uses git commit convention to automate the generation of your next semver version","archived":false,"fork":false,"pushed_at":"2026-05-01T22:20:36.000Z","size":217,"stargazers_count":72,"open_issues_count":6,"forks_count":2,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-05-01T22:24:50.077Z","etag":null,"topics":["ci","conventional-commits","git","git-convention","go","golang","semantic-versioning","semver"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arnaud-deprez.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2019-04-02T07:35:12.000Z","updated_at":"2026-05-01T22:15:30.000Z","dependencies_parsed_at":"2024-04-04T10:29:49.742Z","dependency_job_id":"43c1a503-cca9-4ea5-91f3-c60f4e75f138","html_url":"https://github.com/arnaud-deprez/gsemver","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/arnaud-deprez/gsemver","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arnaud-deprez%2Fgsemver","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arnaud-deprez%2Fgsemver/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arnaud-deprez%2Fgsemver/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arnaud-deprez%2Fgsemver/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arnaud-deprez","download_url":"https://codeload.github.com/arnaud-deprez/gsemver/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arnaud-deprez%2Fgsemver/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32914533,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-11T17:09:15.040Z","status":"ssl_error","status_checked_at":"2026-05-11T17:08:45.420Z","response_time":120,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ci","conventional-commits","git","git-convention","go","golang","semantic-versioning","semver"],"created_at":"2026-05-11T22:02:36.127Z","updated_at":"2026-05-11T22:02:39.543Z","avatar_url":"https://github.com/arnaud-deprez.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# gsemver\n\ngsemver is a command line tool developed in [Go (Golang)](https://golang.org/) that uses git commit convention to automate the generation of your next version compliant with [semver 2.0.0 spec](https://semver.org/spec/v2.0.0.html).\n\n[![Build Status](https://github.com/arnaud-deprez/gsemver/workflows/Go/badge.svg)](https://github.com/arnaud-deprez/gsemver/actions/)\n[![GoDoc](https://godoc.org/github.com/arnaud-deprez/gsemver?status.svg)](https://godoc.org/github.com/arnaud-deprez/gsemver)\n[![Downloads](https://img.shields.io/github/downloads/arnaud-deprez/gsemver/total.svg)](https://github.com/arnaud-deprez/gsemver/releases)\n[![Go Report Card](https://goreportcard.com/badge/github.com/arnaud-deprez/gsemver)](https://goreportcard.com/report/github.com/arnaud-deprez/gsemver)\n[![MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/arnaud-deprez/gsemver/blob/main/LICENSE)\n[![codecov](https://codecov.io/gh/arnaud-deprez/gsemver/branch/main/graph/badge.svg)](https://codecov.io/gh/arnaud-deprez/gsemver)\n[![GitHub release](https://img.shields.io/github/release/arnaud-deprez/gsemver.svg)](https://github.com/arnaud-deprez/gsemver/releases)\n\n## Table of Contents\n\n- [gsemver](#gsemver)\n  - [Table of Contents](#table-of-contents)\n  - [Motivations](#motivations)\n  - [Thanks](#thanks)\n  - [Getting Started](#getting-started)\n    - [Installation](#installation)\n      - [Go users](#go-users)\n      - [Manual](#manual)\n    - [Test Installation](#test-installation)\n  - [Usage](#usage)\n    - [Pre-requisites](#pre-requisites)\n    - [CLI](#cli)\n      - [Automatic version bump](#automatic-version-bump)\n      - [Manual version bump](#manual-version-bump)\n      - [Configuration file](#configuration-file)\n    - [API](#api)\n  - [Contributing](#contributing)\n    - [Feedback](#feedback)\n  - [License](#license)\n\n## Motivations\n\nWhy yet another git version tool ?\n\nWhen you try to implement DevOps pipeline for applications and libraries from different horizons (java, go, javascript, etc.), you always need to deal with versions from the moment you want to release your application/library to the deployment in production.\n\nAs DevOps is all about automation, you need a way to automate the generation of your next version.\n\nThen, you have 2 choices:\n\n1. you can use no human meaningful information:\n    * forever increment a number\n    * use git commit hash\n    * use build number injected by your CI server\n    * etc.\n2. you can use a human meaningful convention such as [semver](https://semver.org/spec/v2.0.0.html).\n\nThe first option is easy and does not required any tool.\n\nHowever some tools/tech require you to use a [semver](https://semver.org/spec/v2.0.0.html) compatible format version (eg. [go modules](https://go.dev/wiki/Modules), [helm](https://helm.sh/), etc.).\nYou can still decide to always bump the major, minor or patch number but then your version is not meaningful in you are just doing a hack to be compliant with the spec format but not with spec semantic.\n\nSo for the second option, in order to provide human meaningful information by following the spec semantic, you need to rely on some conventions.\n\nYou can find some git convention such as:\n\n* [conventional commits](https://www.conventionalcommits.org): generalization of angular commit convention to other projects\n* [angular commit convention](https://github.com/angular/angular/blob/main/CONTRIBUTING.md#-commit-message-guidelines)\n* [gitflow](https://datasift.github.io/gitflow/IntroducingGitFlow.html)\n\nThen I looked for existing tools and here is a non exhaustive list of what I've found so far:\n\n* [GitVersion](https://gitversion.readthedocs.io/en/latest/): tool written in .NET.\n* [semantic-release](https://github.com/semantic-release/semantic-release): tool for npm\n* [standard-version](https://github.com/conventional-changelog/standard-version): tool for npm\n* [jgitver](https://github.com/jgitver/jgitver): CLI running on java, maven and gradle plugins.\n* [hartym/git-semver](https://github.com/hartym/git-semver): git plugin written in python.\n* [markchalloner/git-semver](https://github.com/markchalloner/git-semver): another git plugin written in bash\n* [semver-maven-plugin](https://github.com/sidohaakma/semver-maven-plugin)\n\nAll these tools have at least one of these problems:\n\n* They rely on a runtime environment (nodejs, python, java). But what if I want to build an application on another runtime ? On a VM, this is probably not a big deal but in a container where we try keep them as small as possible, this can be annoying.\n* They are not designed to automatically generate a new version based on a convention. Instead, you have to specify what number you want to bump (major, minor, patch) and/or what type of version you want to generate (alpha, beta, build, etc.)\n* They manage the full release lifecycle and so they are tightly coupled to some build tools like `npm`, `maven` or `gradle`.\n\nI've found some libraries written in [go](https://golang.org/) but they don't deal with git commits/tags convention:\n\n* [hashicorp/go-version](https://github.com/hashicorp/go-version)\n* [coreos/go-semver](https://github.com/coreos/go-semver)\n* [Masterminds/semver](https://github.com/Masterminds/semver)\n* [blang/semver](https://github.com/blang/semver)\n\nI needed a tool to generate the next release semver compatible version based on previous git tag that I could use on every type of application/library and so that is not relying on a specific runtime environment.\n\nThat's why I decided to build this tool using [go](https://golang.org/) with inspirations and credits from the tools I've found.\n\n## Thanks\n\nThank you all for the inspirations!\n\nI'd like also to thanks 2 projects that are used in combination with gsemver to better automate the release of this tool:\n\n* [conventional commits](https://www.conventionalcommits.org) a commit convention I've decided to adopt in all my commits.\n* [git-chglog](https://github.com/git-chglog/git-chglog) is a customizable CHANGELOG generator implemented in go based on commits log.\n* [GoGeleaser](https://goreleaser.com) is a release automation tool for Go projects.\n\nWith these 3 tools and `gsemver`, it gets easier to automate the release your projects.\n\n## Getting Started\n\n### Installation\n\nPlease install `gsemver` in a way that matches your environment.\n\n#### Go users\n\n```sh\ngo install github.com/arnaud-deprez/gsemver@latest\n```\n\n#### Manual\n\nFor a manual installation, you can download binary from [release page](https://github.com/arnaud-deprez/gsemver/releases) and place it in directory registered in your `$PATH` environment variable.\n\n### Test Installation\n\nYou can check with the following command whether the `gsemver` command was included in a valid `$PATH`.\n\n```bash\n$ gsemver version\n# output the gsemver version\n```\n\n## Usage\n\n### Pre-requisites\n\nMost of CI server uses - by default - [shallow git clone](https://git-scm.com/docs/git-clone#Documentation/git-clone.txt---depthltdepthgt) when cloning your git repository.\n\nWhen performing such a clone, the local copy of your git repository will contain a _truncated history_ and most probably will be _detached from HEAD_.\n\nAs `gsemver` is currently using `git describe` to compute the next version, it means you should use **annotated tag** instead of _lightweight tag_ to release your code (see [lightweight vs annotated tag](https://git-scm.com/book/en/v2/Git-Basics-Tagging#:~:text=Git%20supports%20two%20types%20of,objects%20in%20the%20Git%20database.)).  \nLikewise, it also needs to have access to at least to the last parent annotated tag.  \nFor these reasons, `gsemver` will execute `git fetch --tags` before computing the next version.\n\nAs `gsemver` also needs to know the current branch and it tries to retrieve it with `git symbolic-ref HEAD` command.\nHowever most of CI server execute the build in _detached from HEAD_ state and then it becomes hard in git to retrieve the branch from where the build has been triggered.\nFortunately, most of CI server injects the branch name in an environment variable.\nThat's why `gsemver` allows you to use the `GIT_BRANCH` environment variable as a backup solution.\n\n### CLI\n\n#### Automatic version bump\n\n```sh\ngsemver bump\n```\n\nThis will use the git commits convention to generate the next version.\n\nThe only current supported convention is [conventional commits](https://www.conventionalcommits.org).\nIt also uses by default `main`, `master` and `release/*` branches by default as release branches and it generates version with build metadata for any branch that does not match.\nThis is a current limitation but the [roadmap](https://github.com/arnaud-deprez/gsemver/issues/4) is to make more configurable.\n\nThe [conventional commits integration tests](test/integration/gsemver_bump_auto_conventionalcommits_test.go) shows you in depth how version is generated.\nFor a more comprehensive view, here is an example of the logs graph these tests generate:\n\n```git\n*   34385d9 (HEAD -\u003e main, tag: v1.2.2) Merge from feature/merge2-release-1.1.x\n|\\  \n| *   b884197 Merge from release/1.1.x\n| |\\  \n|/ /  \n| *   869c83f (tag: v1.1.3, release/1.1.x) Merge from fix/fix-3\n| |\\  \n| | * 22eabaf fix: my bug fix 3 on release/1.1.x\n| |/  \n* |   704fde4 (tag: v1.2.1) Merge from feature/merge-release-1.1.x\n|\\ \\  \n| * \\   61b6a7c Merge from release/1.1.x\n| |\\ \\  \n|/ / /  \n| | _   \n| *   f2d9b5e (tag: v1.1.2) Merge from fix/fix-2\n| |\\  \n| | * f95ccbe fix: my bug fix 2 on release/1.1.x\n| |/  \n* |   99a3662 (tag: v1.2.0) Merge from feature/awesome-3\n|\\ \\  \n| |/  \n|/|   \n| * cc6c1ed feat: my awesome 3rd change\n|/  \n*   145cbff (tag: v1.1.1) Merge from bug/fix-1\n|\\  \n| * 681a11b fix: my bug fix on main\n|/  \n*   e9e7644 (tag: v1.1.0) Merge from feature/awesome-2\n|\\  \n| * f30042e feat: my awesome 2nd change\n|/  \n*   fba50a2 (tag: v1.0.0, tag: v0.2.0) Merge from feature/awesome-1\n|\\  \n| * bf05218 feat: my awesome change\n|/  \n* c619bff (tag: v0.1.1) fix(doc): fix documentation\n* 128a5d9 (tag: v0.1.0) feat: add README.md\n```\n\n#### Manual version bump\n\n```sh\ngsemver bump major\ngsemver bump minor\ngsemver bump patch\n```\n\nAll the CLI options are documented [here](docs/cmd/gsemver.md).\n\n---\n**NOTE**\n\nWhen you specify a CLI option for the bump command, it overrides the whole configuration if defined. See bellow.\n\n---\n\n#### Go module tags\n\nSince v0.8.0, it can extract the version from a [go module tag](https://go.dev/wiki/Modules#publishing-a-release).\n\n**Example:** if your last tag is `foo/v1.2.0`, it will use `v1.2.0` to calculate the next version and return a version in the form of `vX.Y.Z` without the module prefix.\n\n#### Configuration file\n\nYou can also use a configuration file to define your own rules. \nBy default it will look for a file in `.gsemver.yaml` or then in `$HOME/.gsemver.yaml` but you can specify your own configuration file thanks to the `--config` (or `-c`) option:\n\n```sh\ngsemver --config my-config.yaml\n# or\ngsemver -c my-config.yaml\n```\n\nThe configuration file format looks like:\n\n```yaml\nmajorPattern: \"(?:^.+\\!:.*$|(?m)^BREAKING CHANGE:.*$)\"\nminorPattern: \"^(?:feat|chore|build|ci|refactor|perf)(?:\\(.+\\))?:.*$\"\nbumpStrategies:\n- branchesPattern: \"^(main|master|release/.*)$\"\n  strategy: \"AUTO\"\n  preRelease: false\n  preReleaseTemplate:\n  preReleaseOverwrite: false\n  buildMetadataTemplate:\n- branchesPattern: \".*\"\n  strategy: \"AUTO\"\n  preRelease: false\n  preReleaseTemplate:\n  preReleaseOverwrite: false\n  buildMetadataTemplate: \"{{.Commits | len}}.{{(.Commits | first).Hash.Short}}\"\n```\n\nThis is the default configuration used for Conventional Commits. You can adapt the configuration to your needs.  \nThe `bumpStrategies` are applied in order until one matches the `branchesPattern` regular expression with the current branch.\nThis allows you to define your strategies based on your own git flow.\n\n### API\n\nFor the API usage, you can check the [godoc](https://godoc.org/github.com/arnaud-deprez/gsemver) where there are some examples.\n\nYou can also check [version bumper release](internal/release/main.go) which is used to release gsemver itself.\n\n## Contributing\n\nWe are always welcoming your contribution :clap:\n\nBut to make everyone's work easier, please read the [CONTRIBUTING guide](CONTRIBUTING.md) first.\n\n### Feedback\n\nI would like to make `gsemver` a better tool and take more scenario into account and eventually non conventional commits log.\n\nTherefore, your feedback is very useful.  \nI am very happy to hear your opinions on Issues and PR :heart:\n\n## License\n\n[MIT © Arnaud Deprez](./LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farnaud-deprez%2Fgsemver","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farnaud-deprez%2Fgsemver","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farnaud-deprez%2Fgsemver/lists"}