mirror of https://github.com/thegeeklab/git-sv.git synced 2024-06-22 15:00:50 +02:00
Semantic versioning tool for git based on conventional commits
Go to file
2024-06-22 06:51:37 +00:00
.github cleanup docs and repo settings 2023-10-12 17:26:56 +02:00
.gitsv fix: use description for breaking changes if no message in footer (#16) 2023-10-28 22:25:07 +02:00
.woodpecker chore(deps): update quay.io/thegeeklab/wp-docker-buildx docker tag to v4 (#61) 2024-03-27 08:55:26 +01:00
app ci: fix golangci-lint deprecations 2024-05-12 11:08:29 +02:00
cmd/git-sv chore(deps): update golang devdeps non-major (#55) 2024-02-12 09:09:42 +01:00
sv ci: fix golangci-lint deprecations 2024-05-12 11:08:29 +02:00
templates fix gomod version 2023-10-16 21:41:33 +02:00
.dictionary fix spellcheck 2024-06-17 15:58:52 +02:00
.gitignore initial commit after fork 2023-10-12 16:18:25 +02:00
.golangci.yml ci: fix golangci-lint deprecations 2024-05-12 11:08:29 +02:00
.lycheeignore ci: exclude dockerhub from linkcheck due to rate limiting 2023-12-05 11:24:35 +01:00
.markdownlint.yml initial commit after fork 2023-10-12 16:18:25 +02:00
.prettierignore initial commit after fork 2023-10-12 16:18:25 +02:00
Containerfile.multiarch chore(docker): update docker.io/library/golang:1.22 docker digest to a66eda6 2024-06-22 06:51:37 +00:00
CONTRIBUTING.md cleanup docs and repo settings 2023-10-12 17:26:56 +02:00
go.mod fix(deps): update module github.com/rs/zerolog to v1.33.0 (#73) 2024-05-24 09:38:11 +02:00
go.sum fix(deps): update module github.com/rs/zerolog to v1.33.0 (#73) 2024-05-24 09:38:11 +02:00
LICENSE initial commit after fork 2023-10-12 16:18:25 +02:00
Makefile ci: enable cross-compilation for macos 2024-06-17 15:19:45 +02:00
README.md fix information about available binaries 2024-06-17 15:39:38 +02:00
renovate.json initial commit after fork 2023-10-12 16:18:25 +02:00


Semantic versioning tool for git based on conventional commits.

Build Status Go Report Card GitHub contributors License: MIT


  • Git 2.17+


Prebuilt multi-arch binaries are available for Linux and macOS.

curl -SsfL https://github.com/thegeeklab/git-sv/releases/latest/download/git-sv-linux-amd64 -o /usr/local/bin/git-sv
chmod +x /usr/local/bin/git-sv


Build the binary from source with the following command:

make build


The configuration is loaded from a YAML file in the following order (last wins):

  • built-in default
  • .gitsv/config.yml in repository root

To check the default configuration, run:

git sv cfg default
version: "1.1" # Configuration version.

  update-major: [] # Commit types used to bump major.
  update-minor: [feat] # Commit types used to bump minor.
  update-patch: [build, ci, chore, fix, perf, refactor, test] # Commit types used to bump patch.
  # When type is not present on update rules and is unknown (not mapped on commit message types);
  # if ignore-unknown=false bump patch, if ignore-unknown=true do not bump version.
  ignore-unknown: false

  pattern: "%d.%d.%d" # Pattern used to create git tag.
  filter: "" # Enables you to filter for considerable tags using git pattern syntax.

  sections: # Array with each section of release note. Check template section for more information.
    - name: Features # Name used on section.
      section-type: commits # Type of the section, supported types: commits, breaking-changes.
      commit-types: [feat] # Commit types for commit section-type, one commit type cannot be in more than one section.
    - name: Bug Fixes
      section-type: commits
      commit-types: [fix]
    - name: Breaking Changes
      section-type: breaking-changes

branches: # Git branches config.
  prefix: ([a-z]+\/)? # Prefix used on branch name, it should be a regex group.
  suffix: (-.*)? # Suffix used on branch name, it should be a regex group.
  disable-issue: false # Set true if there is no need to recover issue id from branch name.
  skip: [master, main, developer] # List of branch names ignored on commit message validation.
  skip-detached: false # Set true if a detached branch should be ignored on commit message validation.

  # Supported commit types.
  types: [
  header-selector: "" # You can put in a regex here to select only a certain part of the commit message. Please define a regex group 'header'.
    # Define supported scopes, if blank, scope will not be validated, if not, only scope listed will be valid.
    # Don't forget to add "" on your list if you need to define scopes and keep it optional.
    values: []
    issue: # Use "issue: {}" if you wish to disable issue footer.
      key: jira # Name used to define an issue on footer metadata.
      key-synonyms: [Jira, JIRA] # Supported variations for footer metadata.
      use-hash: false # If false, use :<space> separator. If true, use <space># separator.
      add-value-prefix: "" # Add a prefix to issue value.
    regex: "[A-Z]+-[0-9]+" # Regex for issue id.


git-sv uses go templates to format the output for release-notes and changelog, to see how the default template is configured check template directory. It's possible to overwrite the default configuration by adding .gitsv/templates on your repository.

└── templates
    ├── changelog-md.tpl
    └── releasenotes-md.tpl

Everything inside .gitsv/templates will be loaded, so it's possible to add more files to be used as needed.


To execute the template the releasenotes-md.tpl will receive a single ReleaseNote and changelog-md.tpl will receive a list of ReleaseNote as variables.

Each ReleaseNoteSection will be configured according with release-notes.section from configuration file. The order for each section will be maintained and the SectionType is defined according with section-type attribute as described on the table below.

section-type ReleaseNoteSection
commits ReleaseNoteCommitsSection
breaking-changes ReleaseNoteBreakingChangeSection

⚠️ currently only commits and breaking-changes are supported as section-types, using a different value for this field will make the section to be removed from the template variables.


Use --help or -h to get usage information, don't forget that some commands have unique options too:

$ git-sv --help
   git-sv - Semantic version for git.

   git-sv [global options] command [command options] [arguments...]


   config, cfg                   cli configuration
   current-version, cv           get last released version from git
   next-version, nv              generate the next version based on git commit messages
   commit-log, cl                list all commit logs according to range as json
   commit-notes, cn              generate a commit notes according to range
   release-notes, rn             generate release notes
   changelog, cgl                generate changelog
   tag, tg                       generate tag with version based on git commit messages
   commit, cmt                   execute git commit with conventional commit message helper
   validate-commit-message, vcm  use as prepare-commit-message hook to validate and enhance commit message
   help, h                       Shows a list of commands or help for one command

   --help, -h     show help
   --version, -v  print the version

If git-sv is configured on your path, you can also use it like a git command.

git sv
git sv current-version
git sv next-version


Commands like commit-log and commit-notes has a range option. Supported range types are: tag, date and hash.

By default, it's used --date=short at git log, all dates returned from it will be in YYYY-MM-DD format.

Range tag will use git for-each-ref refs/tags to get the last tag available if start is empty, the others types won't use the existing tags. It's recommended to always use a start limit in an old repository with a lot of commits.

Range date use git log --since and --until. It's possible to use all supported formats from git log. If end is in YYYY-MM-DD format, sv will add a day on git log command to make the end date inclusive.

Range tag and hash are used on git log revision range. If end is empty, HEAD will be used instead.

# get commit log as json using a inclusive range
git-sv commit-log --range hash --start 7ea9306~1 --end c444318

# return all commits after last tag
git-sv commit-log --range tag


Special thanks to all contributors. If you would like to contribute, please see the instructions.

This project is a fork of sv4git from Beatriz Vieira. Thanks for your work.


This project is licensed under the MIT License - see the LICENSE file for details.