Poetry Git Version Plugin

Poetry plugin to set package version based on git tag.

Features

• No needed installed Git
• Git tag parsing
• Different types of release
• Setting found or generated version as package poetry.version
• Maintenance of PEP 440
• Auto-increment depending on release type
• Command to output a new version
• Command to update the pyproject version

Quick start

poetry self add poetry-git-version-plugin
poetry git-version # Write package version based on git tag
poetry build # Build package with version based on git tag

Configs

release_type

Determines which release type to use.

• type: Enum
  • tag
  • alpha
  • beta
  • rc
  • post
  • dev
• Default = "dev"

Value definition:

# Environment
export PACKAGE_VERSION_RELEASE_TYPE=dev
# pyproject.toml
[tool.poetry-git-version-plugin]
release_type = "dev"

Values:

Given: current tag - 1.2.3, distance - 4.

Possible values ​​and version result:

• tag -> 1.2.1
• alpha -> 1.2.1a4
• beta -> 1.2.1b4
• rc -> 1.2.1rc4
• post -> 1.2.3.post4
• dev -> 1.2.3.dev4

local

Determines whether to add locale to the version

• type: bool
• Default = true

Value definition:

# Environment
export PACKAGE_VERSION_LOCAL=true
# pyproject.toml
[tool.poetry-git-version-plugin]
local = true

Values:

Given: current tag - 1.2.3, distance - 4, hash - 09dc5d2d7d8132c94c9c77ac27e1f594963a8ed4.

Possible values ​​and version result:

• false -> 1.2.1a4
• true -> 1.2.1a4+09dc5d2

Commands

poetry git-version

$ poetry git-version # Write package version based on git tag
1.2.3.dev4+09dc5d2

poetry set-git-version

$ poetry git-version # Set new version in pyproject 
The new version has been installed: 1.2.3.dev4+09dc5d2

$ cat pyproject.toml | grep version
version = "1.2.3.dev4+09dc5d2"

Use cases

Publishing python package to pypi via poetry with version equal to git tag

.gitlab-ci.yml:

pypi:
  stage: publishing
  image: python:3.10
  tags:
    - docker
  script:
    - export PACKAGE_VERSION_RELEASE_TYPE=alpha
    - poetry self add poetry-git-version-plugin
    - poetry config repositories.pypi https://upload.pypi.org/legacy/
    - poetry config pypi-token.pypi ${PYPI_TOKEN}
    - poetry publish -r pypi --build
  rules:
    - if: $CI_COMMIT_TAG
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

• When creating a git tag: new package with version == {TAG}
• When pushing to CI_DEFAULT_BRANCH: new package with version == {TAG}a{N}

Publishing python package to private pypi via poetry with version equal to git tag and commit hash

.gitlab-ci.yml:

pypi:
  stage: publishing
  image: python:3.10
  tags:
    - docker
  script:
    - export PACKAGE_VERSION_RELEASE_TYPE=alpha
    - export PACKAGE_VERSION_local=true
    - poetry self add poetry-git-version-plugin
    - poetry config repositories.gitlab "https://gitlab.com/api/v4/projects/$CI_PROJECT_ID/packages/pypi"
    - poetry config http-basic.gitlab gitlab-ci-token "$CI_JOB_TOKEN"
    - poetry publish -r gitlab --build
  rules:
    - if: $CI_COMMIT_TAG
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

• When creating a git tag: new package with version == {TAG}
• When pushing to CI_DEFAULT_BRANCH: new package with version == {TAG}a{N}+{COMMIT_HASH}

Contribute

Issue Tracker: https://gitlab.com/rocshers/python/poetry-git-version-plugin/-/issues
Source Code: https://gitlab.com/rocshers/python/poetry-git-version-plugin

Before adding changes:

make install-dev

After changes:

make format test