README.md

git-semver

git-semver is a command line tool to calculate semantic versions based on the git history and tags of a repository.

git-semver assumes that the commit messages in the git history are wellformed according to the conventional commit specification.

Pull Docker Image

$ docker pull psanetra/git-semver

Commands

latest

The latest command prints the latest semantic version in the current repository by comparing all git tags. Tag names may have a "v" prefix, but this commands prints the version always without that prefix.

Examples

Print latest semantic version (ignoring pre-releases).

$ git-semver latest
1.2.3

Print latest semantic version including pre-releases.

$ git-semver latest --include-pre-releases
1.2.3-beta

next

The next command can be used to calculate the next semantic version based on the history of the current branch. It fails if the git tag of the latest semantic version is not reachable on the current branch or if the tagged commit is not reachable because the repository is shallow.

Examples

Calculate next semantic version. (Will print the latest version if there were no relevant changes.)

$ git-semver next
1.2.3

Calculate next unstable semantic version. (Only if there is no stable version tag yet.)

$ git-semver next --stable=false
0.1.2

Calculate next alpha pre-release version with an appended counter.

$ git-semver next --pre-release-tag=alpha --pre-release-counter
1.2.3-alpha.1

log

The log command prints the commit log of all commits, which were contained in a specified version or all commits since the latest version if no version is specified.

Examples

Print the commits, added in version 1.0.0.

$ git-semver log v1.0.0
commit 478bb9dfdca43216cda6cedcab27faf5c8fd68c0
Author: John Doe <[email protected]>
Date:   Wed Jun 03 20:17:23 2020 +0000

    fix(some_component): Add fix

    Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc bibendum vulputate sapien vel mattis.

    Vivamus faucibus leo id libero suscipit, varius tincidunt neque interdum. Mauris rutrum at velit vitae semper.

    Fixes: http://issues.example.com/123
    BREAKING CHANGE: This commit is breaking some API.

commit f716712a4a26491533ba3b6d95e29f9beed85f47
Author: John Doe <[email protected]>
Date:   Wed Jun 03 20:17:23 2020 +0000

    Some non-conventional-commit

commit d44f505f677d52ca23fb9a69de1f5bb6e6085a74
Author: John Doe <[email protected]>
Date:   Wed Jun 03 20:17:22 2020 +0000

    feat: Add feature

Print only conventional commits, formatted as JSON.

$ git-semver log --conventional-commits v1.0.0
[
  {
    "type": "fix",
    "scope": "some_component",
    "breaking_change": true,
    "description": "Add fix",
    "body": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc bibendum vulputate sapien vel mattis.\n\nVivamus faucibus leo id libero suscipit, varius tincidunt neque interdum. Mauris rutrum at velit vitae semper.",
    "footers": {
      "BREAKING CHANGE": [
        "This commit is breaking some API."
      ],
      "Fixes": [
        "http://issues.example.com/123"
      ]
    }
  },
  {
    "type": "feat",
    "description": "Add feature"
  }
]

Print changelog formatted as markdown.

$ git-semver log --markdown v1.0.0
### BREAKING CHANGES

* **some_component** This commit is breaking some API.

### Features

* Add feature

### Bug Fixes

* **some_component** Add fix
Lorem ipsum dolor sit amet, consectetur adipiscing elit. Nunc bibendum vulputate sapien vel mattis.

Vivamus faucibus leo id libero suscipit, varius tincidunt neque interdum. Mauris rutrum at velit vitae semper.

compare

The compare command is an utility command to compare two semantic versions.

• Prints = if both provided versions are equals.
• Prints < if the first provided version is lower than the second version.
• Prints > if the first provided version is greater than the second version.

Examples

Compare the versions 1.2.3 and 1.2.3-beta

$ git-semver compare 1.2.3 1.2.3-beta
>

Compare the versions 1.2.3-alpha and 1.2.3-beta

$ git-semver compare 1.2.3-alpha 1.2.3-beta
<

Compare the versions 1.2.3 and 1.2.3+build-2018-12-31

$ git-semver compare 1.2.3 1.2.3+build-2018-12-31
=

Example GitLab Job Template

stages:
  - tag

tag:
  image:
    name: psanetra/git-semver:latest
    entrypoint:
      - "/usr/bin/env"
      - "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
  stage: tag
  variables:
    GIT_DEPTH: 0
    GIT_FETCH_EXTRA_FLAGS: "--prune --prune-tags --tags"
  before_script:
    - apk add --upgrade --no-cache curl
  script: |
    set -ex
    LATEST_VERSION="$(git semver latest)"
    NEXT_VERSION="$(git semver next)"
    if [ "${LATEST_VERSION}" != "${NEXT_VERSION}" ]; then
      NEXT_TAG="v${NEXT_VERSION}"
      git tag "${NEXT_TAG}"
      CHANGELOG="$(git semver log --markdown ${NEXT_TAG})"
      curl -X POST \
        --header "JOB-TOKEN: ${CI_JOB_TOKEN}" \
        --form "tag_name=v${NEXT_VERSION}" \
        --form "ref=${CI_COMMIT_SHA}" \
        --form "description=${CHANGELOG}" \
        "${CI_API_V4_URL}/projects/${CI_PROJECT_ID}/releases"
    fi
  only:
    - main
    - master
  except:
    - tags
    - schedules

License

MIT