| Name | simple-git-versioning JSON |
| Version |
0.3.7
JSON |
| download |
| home_page | None |
| Summary | Thinly scoped and opinionated tool that computes a version number from git tags and trailers |
| upload_time | 2025-08-21 23:29:23 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | <4,>=3.8.1 |
| license | MIT |
| keywords |
git
git-trailers
versioning
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
Opinionated version numbering CLIs, and library
--------------------------------------------------------------------------------
This project aims at easing the burden of computing and managing a project's
version numbers by leveraging `git` tags and commit trailers.
`simple-git-versioning` provides two CLIs: `semver2` and `pep440`, one for each
supported versioning sheme of the same name: [`SemVer2`](https://semver.org) and
[`PEP440`](https://peps.python.org/pep-0440/).
Integration with [`setuptools`](#setuptools) is supported.
Snippets to expose your project's version number programatically are provided in
the [`Libraries`](#libraries) section.
# Installation
With `pip`:
```python
pip install simple-git-versioning
```
# Usage
By default, `pep440` and `semver2` will compute a version number of the form
`X.Y.Z`. Every project starts at `0.0.0` on their initial commit, and each
commit after that increments the number `Z` by one, unless they include a
`Version-Bump` trailer (case-insensitive) with a value of:
- `major`: `X` is incremented;
- `minor`: `Y` is incremented;
- `patch`: `Z` is incremented (same as the default).
Each tool then provides the ability to _switch_ to a pre-release mode; or
post-release, and/or dev release, etc. in the case of `pep440`.
## CLIs
All CLIs provide comprehensive help messages, available via the `--help` option.
## Libraries
Libraries that wish to expose their version number programatically may do so by
including the following snippet:
### `PEP440`
```python
from importlib.metadata import PackageNotFoundError, version
from pathlib import Path
from versioning.pep440 import NoVersion, Project
try:
__version__ = version("<your python package's name>")
except PackageNotFoundError:
# package is not installed
with Project(path=Path(__file__).parent) as project:
try:
__version__ = str(project.version())
except NoVersion:
__version__ = str(project.release(dev=0))
```
### `SemVer2`
```python
from importlib.metadata import PackageNotFoundError, version
from pathlib import Path
from versioning.semver2 import NoVersion, Project
try:
__version__ = version("<your python package's name>")
except PackageNotFoundError:
# package is not installed
with Project(path=Path(__file__).parent) as project:
try:
__version__ = str(project.version())
except NoVersion:
__version__ = str(project.release(pre=("dev", 0))
```
## `setuptools`
If you use `setuptools` as a build backend for your project, you can configure
`simple-git-versioning` to derive a version automatically as follows:
In your `pyproject.toml`:
- declare `version` as a dynamic metadata field;
- add `simple-git-versioning` to your project's `build-system.requires`;
- enable the `setuptools` integration in your `pyproject.toml`, and pick the
versioning scheme you wish to apply.
```toml
[project]
name = ...
dynamic = ["version"]
[build-system]
requires = ["setuptools>=63", "simple-git-versioning[setuptools]"]
build-backend = "setuptools.build_meta"
[tool.simple-git-versioning.setuptools]
# scheme = "pep440" (default) or "semver2"
```
## `hatchling`
If you use `hatchling` as a build backend for your project, you can configure
`simple-git-versioning` to derive a version automatically as follows:
In your `pyproject.toml`:
- declare `version` as a dynamic metadata field;
- add `simple-git-versioning` to your project's `build-system.requires`;
- enable the `hatchling` integration in your `pyproject.toml`, and pick the
versioning scheme you wish to apply.
```toml
[project]
name = ...
dynamic = ["version"]
[build-system]
requires = ["hatchling", "simple-git-versioning[hatchling]"]
build-backend = "hatchling.build"
[tool.hatch.version]
source = "simple-git-versioning"
# scheme = "pep440" (default) or "semver2"
```
## CI/CD
Maintainers may prefer to keep their CI/CD configuration agnostic to
`simple-git-versioning`. In this case, they should instruct
`simple-git-versioning` to switch to release mode by setting the
`SIMPLE_GIT_VERSIONING_RELEASE` environment variable (to any value other than
the empty string, `0`, or `false`) and use their build frontend to extract the
current (release) version:
```bash
SIMPLE_GIT_VERSIONING_RELEASE=1 pdm show --version
```
> Without `SIMPLE_GIT_VERSIONING_RELEASE`, the version you would extract would
> have a `dev` suffix and a local segment identifying the current commit (e.g.
> `0.3.6.dev0+04aa73b`).
> `uv version` currently does not support computing dynamic versions, but it
> eventually should: https://github.com/astral-sh/uv/issues/14137.
Raw data
{
"_id": null,
"home_page": null,
"name": "simple-git-versioning",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.8.1",
"maintainer_email": null,
"keywords": "git, git-trailers, versioning",
"author": null,
"author_email": "Quentin Bouget <ypsah@devyard.org>",
"download_url": "https://files.pythonhosted.org/packages/0e/f5/7c558ef3018e990a00dbc5201169ddb584c4f0272ec6aa71b33bc05b3b51/simple_git_versioning-0.3.7.tar.gz",
"platform": null,
"description": "Opinionated version numbering CLIs, and library\n\n--------------------------------------------------------------------------------\n\nThis project aims at easing the burden of computing and managing a project's\nversion numbers by leveraging `git` tags and commit trailers.\n\n`simple-git-versioning` provides two CLIs: `semver2` and `pep440`, one for each\nsupported versioning sheme of the same name: [`SemVer2`](https://semver.org) and \n[`PEP440`](https://peps.python.org/pep-0440/).\n\nIntegration with [`setuptools`](#setuptools) is supported.\n\nSnippets to expose your project's version number programatically are provided in\nthe [`Libraries`](#libraries) section.\n\n# Installation\n\nWith `pip`:\n\n```python\npip install simple-git-versioning\n```\n\n# Usage\n\nBy default, `pep440` and `semver2` will compute a version number of the form\n`X.Y.Z`. Every project starts at `0.0.0` on their initial commit, and each\ncommit after that increments the number `Z` by one, unless they include a\n`Version-Bump` trailer (case-insensitive) with a value of:\n- `major`: `X` is incremented;\n- `minor`: `Y` is incremented;\n- `patch`: `Z` is incremented (same as the default).\n\nEach tool then provides the ability to _switch_ to a pre-release mode; or\npost-release, and/or dev release, etc. in the case of `pep440`.\n\n## CLIs\n\nAll CLIs provide comprehensive help messages, available via the `--help` option.\n\n## Libraries\n\nLibraries that wish to expose their version number programatically may do so by\nincluding the following snippet:\n\n### `PEP440`\n\n```python\nfrom importlib.metadata import PackageNotFoundError, version\nfrom pathlib import Path\n\nfrom versioning.pep440 import NoVersion, Project\n\ntry:\n __version__ = version(\"<your python package's name>\")\nexcept PackageNotFoundError:\n # package is not installed\n with Project(path=Path(__file__).parent) as project:\n try:\n __version__ = str(project.version())\n except NoVersion:\n __version__ = str(project.release(dev=0))\n```\n\n### `SemVer2`\n\n```python\nfrom importlib.metadata import PackageNotFoundError, version\nfrom pathlib import Path\n\nfrom versioning.semver2 import NoVersion, Project\n\ntry:\n __version__ = version(\"<your python package's name>\")\nexcept PackageNotFoundError:\n # package is not installed\n with Project(path=Path(__file__).parent) as project:\n try:\n __version__ = str(project.version())\n except NoVersion:\n __version__ = str(project.release(pre=(\"dev\", 0))\n```\n\n## `setuptools`\n\nIf you use `setuptools` as a build backend for your project, you can configure\n`simple-git-versioning` to derive a version automatically as follows:\n\nIn your `pyproject.toml`:\n - declare `version` as a dynamic metadata field;\n - add `simple-git-versioning` to your project's `build-system.requires`;\n - enable the `setuptools` integration in your `pyproject.toml`, and pick the\n versioning scheme you wish to apply.\n\n```toml\n[project]\nname = ...\ndynamic = [\"version\"]\n\n[build-system]\nrequires = [\"setuptools>=63\", \"simple-git-versioning[setuptools]\"]\nbuild-backend = \"setuptools.build_meta\"\n\n[tool.simple-git-versioning.setuptools]\n# scheme = \"pep440\" (default) or \"semver2\"\n```\n\n## `hatchling`\n\nIf you use `hatchling` as a build backend for your project, you can configure\n`simple-git-versioning` to derive a version automatically as follows:\n\nIn your `pyproject.toml`:\n - declare `version` as a dynamic metadata field;\n - add `simple-git-versioning` to your project's `build-system.requires`;\n - enable the `hatchling` integration in your `pyproject.toml`, and pick the\n versioning scheme you wish to apply.\n\n```toml\n[project]\nname = ...\ndynamic = [\"version\"]\n\n[build-system]\nrequires = [\"hatchling\", \"simple-git-versioning[hatchling]\"]\nbuild-backend = \"hatchling.build\"\n\n[tool.hatch.version]\nsource = \"simple-git-versioning\"\n# scheme = \"pep440\" (default) or \"semver2\"\n```\n\n## CI/CD\n\nMaintainers may prefer to keep their CI/CD configuration agnostic to\n`simple-git-versioning`. In this case, they should instruct\n`simple-git-versioning` to switch to release mode by setting the\n`SIMPLE_GIT_VERSIONING_RELEASE` environment variable (to any value other than\nthe empty string, `0`, or `false`) and use their build frontend to extract the\ncurrent (release) version:\n\n```bash\nSIMPLE_GIT_VERSIONING_RELEASE=1 pdm show --version\n```\n\n> Without `SIMPLE_GIT_VERSIONING_RELEASE`, the version you would extract would\n> have a `dev` suffix and a local segment identifying the current commit (e.g.\n> `0.3.6.dev0+04aa73b`).\n\n> `uv version` currently does not support computing dynamic versions, but it\n> eventually should: https://github.com/astral-sh/uv/issues/14137.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Thinly scoped and opinionated tool that computes a version number from git tags and trailers",
"version": "0.3.7",
"project_urls": {
"homepage": "https://gitlab.com/ypsah/simple-git-versioning",
"repository": "https://gitlab.com/ypsah/simple-git-versioning"
},
"split_keywords": [
"git",
" git-trailers",
" versioning"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "eb9f7297f896dcc1ce0e5009b71017dd69471123bd55433cb10c3c1a10abb432",
"md5": "d27ef0cb467b382458117a4293586c9d",
"sha256": "01c3d10069cede7e7f44d04d65baacf862b7ce6f636810bb3042c23c6ea5f294"
},
"downloads": -1,
"filename": "simple_git_versioning-0.3.7-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d27ef0cb467b382458117a4293586c9d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.8.1",
"size": 17005,
"upload_time": "2025-08-21T23:29:22",
"upload_time_iso_8601": "2025-08-21T23:29:22.036602Z",
"url": "https://files.pythonhosted.org/packages/eb/9f/7297f896dcc1ce0e5009b71017dd69471123bd55433cb10c3c1a10abb432/simple_git_versioning-0.3.7-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "0ef57c558ef3018e990a00dbc5201169ddb584c4f0272ec6aa71b33bc05b3b51",
"md5": "fc247ef6e7c02c7224f028498c7d484a",
"sha256": "5719abf54ac41ce97154bf12bdc14d2eed857ce71ff4570e49a672c490b49987"
},
"downloads": -1,
"filename": "simple_git_versioning-0.3.7.tar.gz",
"has_sig": false,
"md5_digest": "fc247ef6e7c02c7224f028498c7d484a",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.8.1",
"size": 116376,
"upload_time": "2025-08-21T23:29:23",
"upload_time_iso_8601": "2025-08-21T23:29:23.051280Z",
"url": "https://files.pythonhosted.org/packages/0e/f5/7c558ef3018e990a00dbc5201169ddb584c4f0272ec6aa71b33bc05b3b51/simple_git_versioning-0.3.7.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 23:29:23",
"github": false,
"gitlab": true,
"bitbucket": false,
"codeberg": false,
"gitlab_user": "ypsah",
"gitlab_project": "simple-git-versioning",
"lcname": "simple-git-versioning"
}
