Metadata-Version: 2.1
Name: git-versioner
Version: 3.4
Summary: Manage current / next version for project
Home-page: https://gitlab.com/alelec/__version__
Author: Andrew Leech
Author-email: andrew@alelec.net
License: MIT

=============
git-versioner
=============

Manages the version number for the project based on git tags. The goal of this packages versioning scheme is to
avoid ever needing to manually create versions numbers or update version details in files that need to
be committed to the repository.

The general rule is:

- If on a tag, report that as-is.
- When changes are made / git commits added, auto-increment the appropriate level of the semantic version.

When on a git tag like ``v1.2`` the version will be reported as ``v1.2`` in short form or
``v1.2-g<githash>`` in the (default) long form, eg. ``v1.2-ga1b2c3``


After editing you working tree, by default the minor version attribute will be updated, eg ``v1.2`` -> ``v1.3``
or ``1.2.3`` -> ``1.3.0``

Version Increments
------------------

The increment can be changed by adding one of the following footers to any commit since the previous tag:

- ``CHANGE: major``
- ``CHANGE: minor``
- ``CHANGE: patch``

Then the most significant increment specified in any commit will be used.

Alternatively this can be overridden at runtime by setting the environment variable ``VERSION_INCREMENT`` to
one of ``major``, ``minor`` or ``patch``

By default on new projects a 2 point version scheme will be used, eg v1.2, however the patch level (v1.2.3) 
will be used if the previous tag includes it, or it can be enabled on new projects with the env var 
``VERSION_SUPPORT_PATCH`` set to ``1`` 

This setting will be persisted if saved, eg ``VERSION_SUPPORT_PATCH=1 python -m __version__ --save``

Project Version
---------------

The overall goal is for any commit to be suitable as a potential release. As such you can build away, testing your main
branch builds and as soon as one of them is ready to go simply run ``python -m __version__ --tag`` to have it tagged off
with the same version number the build already had. Indeed this step can be done in CI, take at a look at this projects'
`.gitlab-ci.yml
<https://gitlab.com/alelec/__version__/-/blob/main/.gitlab-ci.yml>`_ for an example of a manual CI task
to "release this commit".

To use this to auto-version python packages, this projects' ``setup.py`` the following pattern can be followed: ::

    setup(
        name="git-versioner",
        author="Andrew Leech",
        author_email="andrew@alelec.net",
        use_git_versioner=True,
        setup_requires=["git-versioner"],
        ...
    )

By default the full / long version is provided in this case in [PEP440](https://peps.python.org/pep-0440/#local-version-identifiers) local version format.
If you want to push the package to PyPI however the short version must be used which can be specified with 
`use_git_versioner="short"`.

The full python version number can also added to the description, which can be especially useful when the package is 
published with the short number. Do enable this you can use `use_git_versioner="desc"` in which case a line like 
`version: 1.2.3+ga1b2c3d` will be added to the bottom of the long description metadata. 

Both of these settings can be combined, eg `use_git_versioner="short:desc"`.

If being used in Gitlab CI for builds an automated versioning scheme can be specified with `use_git_versioner="gitlab"`
(and/or `use_git_versioner="gitlab:desc"`). In this mode, builds from the default / main branch or from tags will
use the short version, with anything else (eg. pr's, local builds) using the long version scheme.


Runtime Access
--------------
To access the version in your project at runtime you can either
``from __version__ import version, version_short, git_hash, on_tag`` to auto-calculate each run,
or ``from _version import version, version_short, git_hash, on_tag`` to get the details from previous
run of ``python __version__ --save``


Command Line
------------
Can also be used as command line tool to generate ``_version.py``, print version, rename files or fill a
template file with version details.::


    usage: __version__.py [-h] [--save] [--short] [--git] [--rename RENAME] [--template template output]

    Mange current/next version.

    optional arguments:
      -h, --help            show this help message and exit
      --save                Store in _version.py
      --short               Print the short version string
      --git                 Print the release git hash
      --rename RENAME       Add version numbers to filename(s)
      --template template output
                            Add version to <template> and write result to <output>
      --tag                 Creates git tag to release the current commit


version: 3.4+gf8163c0
