pygitver


Namepygitver JSON
Version 0.2.3 PyPI version JSON
download
home_pageNone
SummaryManages Git Tag versions and generates ChangeLog
upload_time2025-07-23 17:23:43
maintainerNone
docs_urlNone
authorNone
requires_python>=3.8
licenseGPL-3.0-or-later
keywords changelog changelogs conventional commit git tag semver version versions
VCS
bugtrack_url
requirements Jinja2
Travis-CI No Travis.
coveralls test coverage No coveralls.
            # pygitver

Features:
* Conventional Commit linter
* Generate CHANGELOG and group of CHANGELOGs 
* Bump version based on CHANGELOG

# Install

Use as python CLI (python is required)

```shell
pip install pygitver
```

Use as a docker container (docker engine is required)
```shell
docker pull panpuchkov/pygitver
```

# Users (Developers) Section

## Install Conventional Commit Git Hook Checker
Run in the `git` root folder of the target repository on localhost. 
```shell
docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" --entrypoint '' panpuchkov/pygitver /pygitver/scripts/install.sh
```

* It doesn't matter what the current branch is.
* You should install it in every repository that needs conventional commit messages.

## Update pygitver

Run in a terminal in any folder:

```shell
docker pull panpuchkov/pygitver
```

## Git Conventional Commit Linter

You don't need to use it directly; it will be used automatically on each git commit.

_Example of a commit message that is **NOT VALID** for Conventional Commits:_
```shell
$ git commit -am "test"
ERROR: Commit does not fit Conventional Commits requirements
```

_Example of a commit message that is **VALID** for Conventional Commits:_
```shell
$ git commit -am "feat: test"
[feature/test2 af1a5c4] feat: test
 1 file changed, 1 deletion(-)
```

_Note: repeat this procedure for each repository_



# DevOps and Developers Section

## Examples

You may use it as a CLI tool (Python PIP package) or a Docker container.

### Usage as PIP Package (python is required)

#### Check commit message

```shell
$ pygitver --check-commit-message "feat: conventional commit example"
$ echo $?
0
$ pygitver --check-commit-message "non-conventional commit example"
ERROR: Commit does not fit Conventional Commits requirements
More about Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0/
$ echo $?
1
```

#### Get current/next version
```shell
$ git tag -l
v0.0.1
v0.0.2
$ pygitver --curr-ver
v0.0.2
$ pygitver --next-ver
v0.0.3
```

#### Generate changelog
```shell
$ pygitver changelog
##########
Change Log
##########

Version v0.0.3
=============

Features
--------

* Allow to trigger job manually

Bug Fixes
---------

* Path for the default changelog template

* Readme.md usage

Improved Documentation
----------------------

* Add examples to the readme.md

$ pygitver changelog --format json | jq .
{
  "version": "v0.0.3",
  "bump_rules": {
    "major": false,
    "minor": false,
    "patch": true
  },
  "changelog": {
    "features": [
      "allow to trigger job manually"
    ],
    "bugfixes": [
      "path for the default changelog template",
      "README.md usage"
    ],
    "deprecations": [],
    "others": [],
    "docs": [
      "Add examples to the README.md"
    ],
    "non_conventional_commit": []
  }
}
```

### Usage as Docker container (docker engine is required)

```shell
$ git tag -l
v0.0.1
v0.0.2
$ docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" panpuchkov/pygitver --curr-ver
v0.0.2
$ docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" panpuchkov/pygitver --next-ver
v0.0.3
$ docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" panpuchkov/pygitver changelog
##########
Change Log
##########

Version v0.0.3
=============

Features
--------

* Allow to trigger job manually

Bug Fixes
---------

* Path for the default changelog template

* Readme.md usage

Improved Documentation
----------------------

* Add examples to the readme.md

$ docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" panpuchkov/pygitver changelog --format json | jq .
{
  "version": "v0.0.3",
  "bump_rules": {
    "major": false,
    "minor": false,
    "patch": true
  },
  "changelog": {
    "features": [
      "allow to trigger job manually"
    ],
    "bugfixes": [
      "path for the default changelog template",
      "README.md usage"
    ],
    "deprecations": [],
    "others": [],
    "docs": [
      "Add examples to the README.md"
    ],
    "non_conventional_commit": []
  }
}
$ docker run --rm -v $(pwd):/app -w /app --user "$(id -u):$(id -g)" panpuchkov/pygitver --help
usage: pygitver.py [-h] [-v] [-cv] [-nv] [-t] [-ccm CHECK_COMMIT_MESSAGE]
                   {changelog,changelogs} ...

pygitver tool, ver: 0.1.2

options:
  -h, --help            show this help message and exit
  -v, --version         show tool version
  -cv, --curr-ver       get current version (last git tag)
  -nv, --next-ver       get next version (bump last git tag)
  -t, --tags            git tags
  -ccm CHECK_COMMIT_MESSAGE, --check-commit-message CHECK_COMMIT_MESSAGE
                        check if the git commit message is valid for
                        Conventional Commits

Get changelog:
  {changelog,changelogs}
                        Get changelog in TEXT or JSON format
```

## Custom CHANGELOG Templates

* Take as an example: `./src/pygitver/templates/changelog.tmpl`
* Place somewhere in your project custom template
* Send environment variable `PYGITVER_TEMPLATE_CHANGELOG` to docker 
  on run with full template path in Docker (usually `/app/...`)


## Custom Git Tag Version Prefix

If a Git repository has more than one application/service, you may need to have different versions for each of them.
Example 
```bash
$ git tag -l
app_a_1.2.3
...
app_b_2.5.2
...
```
If you want to get the current and next versions for `app_a`, you can use the environment variable `PYGITVER_VERSION_PREFIX`.
Example:
```bash
$ PYGITVER_VERSION_PREFIX=app_a_ python -m pygitver.pygitver --curr-ver
app_a_1.2.3
$ PYGITVER_VERSION_PREFIX=app_a_ python -m pygitver.pygitver --next-ver
app_a_1.3.0
$ PYGITVER_VERSION_PREFIX=app_b_ python -m pygitver.pygitver --curr-ver
app_b_2.5.3
$ PYGITVER_VERSION_PREFIX=app_b_ python -m pygitver.pygitver --next-ver
app_b_2.6.0
```


# Conventional Commits Rules
The tool supports simplified Conventional Commits, which are described in this section.

The commit message should be structured as follows:
```shell
<type>[optional scope]: <description>
```
 
The commit contains the following structural elements to communicate intent to the consumers of your library:
* `fix:` a commit of the type fix patches a bug in your codebase (this correlates with `PATCH` in Semantic Versioning).
* `feat:` a commit of the type feat introduces a new feature to the codebase (this correlates with `MINOR` in Semantic Versioning).
* `BREAKING CHANGE:` a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with `MAJOR` in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.
* Other allowed prefixes: `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`. These correlate with `PATCH` in Semantic Versioning. 

## Conventional Commits Examples:

Commit without scope without breaking change.
```
fix: crash on wrong input data
```
 

Commit message with ! to draw attention to breaking change.
```
feat!: send an email to the customer when a product is shipped
```
 

Commit message with scope and ! to draw attention to breaking change.
```
feat(api)!: send an email to the customer when a product is shipped
```


Commit message with scope.
```
feat(lang): add Polish language
```


# Development

## Build Docker
```shell
docker build -t pygitver .
```

## Install to Localhost
```shell
pip install -r requirements-dev.txt
```

## Test on Localhost

### Run all checks
```shell
tox
```

### A single file of the test run
```shell
tox -e coverage -- ./tests/test_git.py -vv
```
or
```shell
coverage run -m pytest -- ./tests/test_git.py 
```

## Build pip package

Linux
```shell
python -m build
```

For `Debian` based OS:
```shell
DEB_PYTHON_INSTALL_LAYOUT=deb_system python3 -m build
```

            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "pygitver",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": null,
    "keywords": "changelog, changelogs, conventional commit, git tag, semver, version, versions",
    "author": null,
    "author_email": "Yurii Puchkov <panpuchkov@gmail.com>",
    "download_url": "https://files.pythonhosted.org/packages/22/68/9dfb0fe10e474a9db57eb967ed0959262ecad3079c9b67396569d78c54c1/pygitver-0.2.3.tar.gz",
    "platform": null,
    "description": "# pygitver\n\nFeatures:\n* Conventional Commit linter\n* Generate CHANGELOG and group of CHANGELOGs \n* Bump version based on CHANGELOG\n\n# Install\n\nUse as python CLI (python is required)\n\n```shell\npip install pygitver\n```\n\nUse as a docker container (docker engine is required)\n```shell\ndocker pull panpuchkov/pygitver\n```\n\n# Users (Developers) Section\n\n## Install Conventional Commit Git Hook Checker\nRun in the `git` root folder of the target repository on localhost. \n```shell\ndocker run --rm -v $(pwd):/app -w /app --user \"$(id -u):$(id -g)\" --entrypoint '' panpuchkov/pygitver /pygitver/scripts/install.sh\n```\n\n* It doesn't matter what the current branch is.\n* You should install it in every repository that needs conventional commit messages.\n\n## Update pygitver\n\nRun in a terminal in any folder:\n\n```shell\ndocker pull panpuchkov/pygitver\n```\n\n## Git Conventional Commit Linter\n\nYou don't need to use it directly; it will be used automatically on each git commit.\n\n_Example of a commit message that is **NOT VALID** for Conventional Commits:_\n```shell\n$ git commit -am \"test\"\nERROR: Commit does not fit Conventional Commits requirements\n```\n\n_Example of a commit message that is **VALID** for Conventional Commits:_\n```shell\n$ git commit -am \"feat: test\"\n[feature/test2 af1a5c4] feat: test\n 1 file changed, 1 deletion(-)\n```\n\n_Note: repeat this procedure for each repository_\n\n\n\n# DevOps and Developers Section\n\n## Examples\n\nYou may use it as a CLI tool (Python PIP package) or a Docker container.\n\n### Usage as PIP Package (python is required)\n\n#### Check commit message\n\n```shell\n$ pygitver --check-commit-message \"feat: conventional commit example\"\n$ echo $?\n0\n$ pygitver --check-commit-message \"non-conventional commit example\"\nERROR: Commit does not fit Conventional Commits requirements\nMore about Conventional Commits: https://www.conventionalcommits.org/en/v1.0.0/\n$ echo $?\n1\n```\n\n#### Get current/next version\n```shell\n$ git tag -l\nv0.0.1\nv0.0.2\n$ pygitver --curr-ver\nv0.0.2\n$ pygitver --next-ver\nv0.0.3\n```\n\n#### Generate changelog\n```shell\n$ pygitver changelog\n##########\nChange Log\n##########\n\nVersion v0.0.3\n=============\n\nFeatures\n--------\n\n* Allow to trigger job manually\n\nBug Fixes\n---------\n\n* Path for the default changelog template\n\n* Readme.md usage\n\nImproved Documentation\n----------------------\n\n* Add examples to the readme.md\n\n$ pygitver changelog --format json | jq .\n{\n  \"version\": \"v0.0.3\",\n  \"bump_rules\": {\n    \"major\": false,\n    \"minor\": false,\n    \"patch\": true\n  },\n  \"changelog\": {\n    \"features\": [\n      \"allow to trigger job manually\"\n    ],\n    \"bugfixes\": [\n      \"path for the default changelog template\",\n      \"README.md usage\"\n    ],\n    \"deprecations\": [],\n    \"others\": [],\n    \"docs\": [\n      \"Add examples to the README.md\"\n    ],\n    \"non_conventional_commit\": []\n  }\n}\n```\n\n### Usage as Docker container (docker engine is required)\n\n```shell\n$ git tag -l\nv0.0.1\nv0.0.2\n$ docker run --rm -v $(pwd):/app -w /app --user \"$(id -u):$(id -g)\" panpuchkov/pygitver --curr-ver\nv0.0.2\n$ docker run --rm -v $(pwd):/app -w /app --user \"$(id -u):$(id -g)\" panpuchkov/pygitver --next-ver\nv0.0.3\n$ docker run --rm -v $(pwd):/app -w /app --user \"$(id -u):$(id -g)\" panpuchkov/pygitver changelog\n##########\nChange Log\n##########\n\nVersion v0.0.3\n=============\n\nFeatures\n--------\n\n* Allow to trigger job manually\n\nBug Fixes\n---------\n\n* Path for the default changelog template\n\n* Readme.md usage\n\nImproved Documentation\n----------------------\n\n* Add examples to the readme.md\n\n$ docker run --rm -v $(pwd):/app -w /app --user \"$(id -u):$(id -g)\" panpuchkov/pygitver changelog --format json | jq .\n{\n  \"version\": \"v0.0.3\",\n  \"bump_rules\": {\n    \"major\": false,\n    \"minor\": false,\n    \"patch\": true\n  },\n  \"changelog\": {\n    \"features\": [\n      \"allow to trigger job manually\"\n    ],\n    \"bugfixes\": [\n      \"path for the default changelog template\",\n      \"README.md usage\"\n    ],\n    \"deprecations\": [],\n    \"others\": [],\n    \"docs\": [\n      \"Add examples to the README.md\"\n    ],\n    \"non_conventional_commit\": []\n  }\n}\n$ docker run --rm -v $(pwd):/app -w /app --user \"$(id -u):$(id -g)\" panpuchkov/pygitver --help\nusage: pygitver.py [-h] [-v] [-cv] [-nv] [-t] [-ccm CHECK_COMMIT_MESSAGE]\n                   {changelog,changelogs} ...\n\npygitver tool, ver: 0.1.2\n\noptions:\n  -h, --help            show this help message and exit\n  -v, --version         show tool version\n  -cv, --curr-ver       get current version (last git tag)\n  -nv, --next-ver       get next version (bump last git tag)\n  -t, --tags            git tags\n  -ccm CHECK_COMMIT_MESSAGE, --check-commit-message CHECK_COMMIT_MESSAGE\n                        check if the git commit message is valid for\n                        Conventional Commits\n\nGet changelog:\n  {changelog,changelogs}\n                        Get changelog in TEXT or JSON format\n```\n\n## Custom CHANGELOG Templates\n\n* Take as an example: `./src/pygitver/templates/changelog.tmpl`\n* Place somewhere in your project custom template\n* Send environment variable `PYGITVER_TEMPLATE_CHANGELOG` to docker \n  on run with full template path in Docker (usually `/app/...`)\n\n\n## Custom Git Tag Version Prefix\n\nIf a Git repository has more than one application/service, you may need to have different versions for each of them.\nExample \n```bash\n$ git tag -l\napp_a_1.2.3\n...\napp_b_2.5.2\n...\n```\nIf you want to get the current and next versions for `app_a`, you can use the environment variable `PYGITVER_VERSION_PREFIX`.\nExample:\n```bash\n$ PYGITVER_VERSION_PREFIX=app_a_ python -m pygitver.pygitver --curr-ver\napp_a_1.2.3\n$ PYGITVER_VERSION_PREFIX=app_a_ python -m pygitver.pygitver --next-ver\napp_a_1.3.0\n$ PYGITVER_VERSION_PREFIX=app_b_ python -m pygitver.pygitver --curr-ver\napp_b_2.5.3\n$ PYGITVER_VERSION_PREFIX=app_b_ python -m pygitver.pygitver --next-ver\napp_b_2.6.0\n```\n\n\n# Conventional Commits Rules\nThe tool supports simplified Conventional Commits, which are described in this section.\n\nThe commit message should be structured as follows:\n```shell\n<type>[optional scope]: <description>\n```\n \nThe commit contains the following structural elements to communicate intent to the consumers of your library:\n* `fix:` a commit of the type fix patches a bug in your codebase (this correlates with `PATCH` in Semantic Versioning).\n* `feat:` a commit of the type feat introduces a new feature to the codebase (this correlates with `MINOR` in Semantic Versioning).\n* `BREAKING CHANGE:` a commit that has a footer `BREAKING CHANGE:`, or appends a `!` after the type/scope, introduces a breaking API change (correlating with `MAJOR` in Semantic Versioning). A BREAKING CHANGE can be part of commits of any type.\n* Other allowed prefixes: `build:`, `chore:`, `ci:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`. These correlate with `PATCH` in Semantic Versioning. \n\n## Conventional Commits Examples:\n\nCommit without scope without breaking change.\n```\nfix: crash on wrong input data\n```\n \n\nCommit message with ! to draw attention to breaking change.\n```\nfeat!: send an email to the customer when a product is shipped\n```\n \n\nCommit message with scope and ! to draw attention to breaking change.\n```\nfeat(api)!: send an email to the customer when a product is shipped\n```\n\n\nCommit message with scope.\n```\nfeat(lang): add Polish language\n```\n\n\n# Development\n\n## Build Docker\n```shell\ndocker build -t pygitver .\n```\n\n## Install to Localhost\n```shell\npip install -r requirements-dev.txt\n```\n\n## Test on Localhost\n\n### Run all checks\n```shell\ntox\n```\n\n### A single file of the test run\n```shell\ntox -e coverage -- ./tests/test_git.py -vv\n```\nor\n```shell\ncoverage run -m pytest -- ./tests/test_git.py \n```\n\n## Build pip package\n\nLinux\n```shell\npython -m build\n```\n\nFor `Debian` based OS:\n```shell\nDEB_PYTHON_INSTALL_LAYOUT=deb_system python3 -m build\n```\n",
    "bugtrack_url": null,
    "license": "GPL-3.0-or-later",
    "summary": "Manages Git Tag versions and generates ChangeLog",
    "version": "0.2.3",
    "project_urls": {
        "Homepage": "https://github.com/panpuchkov/pygitver"
    },
    "split_keywords": [
        "changelog",
        " changelogs",
        " conventional commit",
        " git tag",
        " semver",
        " version",
        " versions"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "97e250abd893821c61895ccbf1b5c03cf6deaaaca2d054c8c1a316fe5fdc0dc5",
                "md5": "46ab9234af1c03767527974d6e865383",
                "sha256": "4a978ce4c3c794e21dc43a71b45a910e5967f4ba5763e9c3239335c2a2745fc3"
            },
            "downloads": -1,
            "filename": "pygitver-0.2.3-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "46ab9234af1c03767527974d6e865383",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 24174,
            "upload_time": "2025-07-23T17:23:42",
            "upload_time_iso_8601": "2025-07-23T17:23:42.586191Z",
            "url": "https://files.pythonhosted.org/packages/97/e2/50abd893821c61895ccbf1b5c03cf6deaaaca2d054c8c1a316fe5fdc0dc5/pygitver-0.2.3-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "22689dfb0fe10e474a9db57eb967ed0959262ecad3079c9b67396569d78c54c1",
                "md5": "96e44360a6937e3c1cf22befd4fe0968",
                "sha256": "2a6621f0f6bbedbf12c23833da38cb0d93af60fcf728e6197887571964e489ba"
            },
            "downloads": -1,
            "filename": "pygitver-0.2.3.tar.gz",
            "has_sig": false,
            "md5_digest": "96e44360a6937e3c1cf22befd4fe0968",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 26490,
            "upload_time": "2025-07-23T17:23:43",
            "upload_time_iso_8601": "2025-07-23T17:23:43.372155Z",
            "url": "https://files.pythonhosted.org/packages/22/68/9dfb0fe10e474a9db57eb967ed0959262ecad3079c9b67396569d78c54c1/pygitver-0.2.3.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-23 17:23:43",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "panpuchkov",
    "github_project": "pygitver",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "requirements": [
        {
            "name": "Jinja2",
            "specs": [
                [
                    "==",
                    "3.1.2"
                ]
            ]
        }
    ],
    "tox": true,
    "lcname": "pygitver"
}
        
Elapsed time: 1.52807s