Metadata-Version: 2.4
Name: simple-git-versioning
Version: 0.3.2
Summary: Thinly scoped and opinionated tool that computes a version number from git tags and trailers
Project-URL: homepage, https://gitlab.com/ypsah/simple-git-versioning
Project-URL: repository, https://gitlab.com/ypsah/simple-git-versioning
Author-email: Quentin Bouget <ypsah@devyard.org>
License: MIT
License-File: LICENSE
Keywords: git,git-trailers,versioning
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Framework :: Hatch
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: <4,>=3.8.1
Requires-Dist: icontract
Requires-Dist: sh<3,>=2
Requires-Dist: toml; python_version < '3.11'
Requires-Dist: typing-extensions; python_version < '3.11'
Provides-Extra: hatchling
Requires-Dist: hatchling; extra == 'hatchling'
Provides-Extra: poetry
Requires-Dist: cleo; extra == 'poetry'
Requires-Dist: poetry; extra == 'poetry'
Provides-Extra: setuptools
Requires-Dist: setuptools; extra == 'setuptools'
Description-Content-Type: text/markdown

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"
```

## `poetry`

If you use `poetry` as a build frontend and backend for your project, you can
configure `simple-git-versioning` to derive a version automatically as follows:

Install `simple-git-versioning` alongside `poetry`:

```bash
poetry self add "simple-git-versioning[poetry]"
```

Enable the `poetry` integration in your `pyproject.toml`, and optionally pick
the versioning scheme you wish to apply:

```toml
[tool.poetry]
...

[tool.simple-git-versioning.poetry]
# scheme = "pep440" (default) or "semver2"
```

> Note that `poetry` mandates a `version` always be set in `pyproject.toml`, so
> you will have to keep a placeholder there (e.g. `version: "0.0.0"`).
