Metadata-Version: 2.2
Name: setuptools-git-versioning
Version: 2.1.0
Summary: Use git repo data for building a version number according PEP-440
Home-page: https://setuptools-git-versioning.readthedocs.io
Author: dolfinus
Author-email: martinov.m.s.8@gmail.com
License: MIT
Project-URL: Documentation, https://setuptools-git-versioning.readthedocs.io
Project-URL: Source, https://github.com/dolfinus/setuptools-git-versioning
Project-URL: CI/CD, https://github.com/dolfinus/setuptools-git-versioning/actions
Project-URL: Coverage, https://app.codecov.io/gh/dolfinus/setuptools-git-versioning
Project-URL: Tracker, https://github.com/dolfinus/setuptools-git-versioning/issues
Keywords: setuptools,git,versioning,pep-440
Classifier: Framework :: Setuptools Plugin
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.7
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
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/x-rst
License-File: LICENSE
Requires-Dist: packaging
Requires-Dist: setuptools
Requires-Dist: tomli>=2.0.1; python_version < "3.11"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

*************************
setuptools-git-versioning
*************************

|status| |PyPI| |PyPI License| |PyPI Python Version|
|ReadTheDocs| |Build| |Coverage| |pre-commit.ci|

.. |status| image:: https://www.repostatus.org/badges/latest/active.svg
    :alt: Project Status: Active – The project has reached a stable, usable state and is being actively developed.
    :target: https://www.repostatus.org/#active
.. |PyPI| image:: https://badge.fury.io/py/setuptools-git-versioning.svg
    :target: https://badge.fury.io/py/setuptools-git-versioning
.. |PyPI License| image:: https://img.shields.io/pypi/l/setuptools-git-versioning.svg
    :target: https://github.com/dolfinus/setuptools-git-versioning/blob/master/LICENSE
.. |PyPI Python Version| image:: https://img.shields.io/pypi/pyversions/setuptools-git-versioning.svg
    :target: https://badge.fury.io/py/setuptools-git-versioning
.. |ReadTheDocs| image:: https://img.shields.io/readthedocs/setuptools-git-versioning.svg
    :target: https://setuptools-git-versioning.readthedocs.io
.. |Build| image:: https://github.com/dolfinus/setuptools-git-versioning/workflows/Tests/badge.svg
    :target: https://github.com/dolfinus/setuptools-git-versioning/actions
.. |Coverage| image:: https://codecov.io/gh/dolfinus/setuptools-git-versioning/branch/master/graph/badge.svg?token=GIMVHUTNW4
    :target: https://codecov.io/gh/dolfinus/setuptools-git-versioning
.. |pre-commit.ci| image:: https://results.pre-commit.ci/badge/github/dolfinus/setuptools-git-versioning/master.svg
    :target: https://results.pre-commit.ci/latest/github/dolfinus/setuptools-git-versioning/master

Use git repo data (latest tag, current commit hash, etc) for building a
version number according :pep:`440`.

**Features:**

- Can be installed & configured through both ``setup.py`` and :pep:`518`'s ``pyproject.toml``

- Does not require to change source code of the project

- Tag-, file-, and callback-based versioning schemas are supported

- Templates for *tag*, *dev* and *dirty* versions are separated

- Templates support a lot of substitutions including git and environment information

- Well-documented

See `comparison <https://setuptools-git-versioning.readthedocs.io/en/stable/comparison.html>`_
between ``setuptools-git-versioning`` and other tools.

**Limitations:**

- Currently the only supported VCS is *Git*

- Only Git v2 is supported

- Only Setuptools build backend is supported (no Poetry & others)

- Currently does not support automatic exporting of package version to a file for runtime use
  (but you can use ``setuptools-git-versioning > file`` redirect instead)

.. documentation

Documentation
--------------

See https://setuptools-git-versioning.readthedocs.io/en/stable/

.. contribution

Contribution Guide
------------------

See ./CONTRIBUTING.rst

.. installation

Install
------------

``pyproject.toml``
~~~~~~~~~~~~~~~~~~

Just add ``setuptools-git-versioning`` to ``build-sytem`` section of your ``pyproject.toml``,
add a section ``tool.setuptools-git-versioning`` with config options, and mark the project
``version`` as dynamic.

.. code:: toml

    [build-system]
    requires = [ "setuptools>=41", "wheel", "setuptools-git-versioning>=2.0,<3", ]
    build-backend = "setuptools.build_meta"

    [tool.setuptools-git-versioning]
    enabled = true

    [project]
    dynamic = ["version"]

And check the package version generated (see `command help <https://setuptools-git-versioning.readthedocs.io/en/stable/command.html>`_):

.. code:: bash

    $ python -m setuptools_git_versioning
    0.0.1

    # or

    $ setuptools-git-versioning
    0.0.1

``setup.py``
~~~~~~~~~~~~

Just add ``setuptools-git-versioning`` to ``setup_requires`` argument of ``setuptools.setup`` function call,
and then add new argument ``setuptools_git_versioning`` with config options:

.. code:: python

    import setuptools

    setuptools.setup(
        ...,
        setuptools_git_versioning={
            "enabled": True,
        },
        setup_requires=["setuptools-git-versioning>=2.0,<3"],
    )

And check the package version generated (see `command help <https://setuptools-git-versioning.readthedocs.io/en/stable/command.html>`_):

.. code:: bash

    $ python setup.py --version
    0.0.1

    # or

    $ python -m setuptools_git_versioning
    0.0.1

    # or

    $ setuptools-git-versioning
    0.0.1