Package: versioningit
GitHub|PyPI|Documentation|Issues|Changelogversioningit—Versioning It with your Version In Gitversioningitis yet another Python packaging plugin for automatically
determining your package’s version based on your version control repository’s
tags.  Unlike others, it allows easy customization of the version format and
even lets you easily override the separate functions used for version
extraction & calculation.Features:Works with both setuptools andHatchInstalled & configured throughPEP 518’spyproject.tomlSupports Git, modern Git archives, and MercurialFormatting of the final version uses format template strings, with fields for
basic VCS information and separate template strings for distanced vs. dirty
vs. distanced-and-dirty repository statesCan optionally write the final version and other details to a file for
loading at runtimeProvides custom hooks for inserting the final version and other details into
a source file at build timeThe individual methods for VCS querying, tag-to-version calculation, version
bumping, version formatting, and writing the version to a file can all be
customized using either functions defined alongside one’s project code or via
publicly-distributed entry pointsCan alternatively be used as a library for use insetup.pyor the like,
in case you don’t want to or can’t configure it viapyproject.tomlThe only thing it does is calculate your version and optionally write it to a
file; there’s no overriding of your sdist contents based on what’s in your
Git repository, especially not without a way to turn it off, because that
would just be rude.Installation & Setupversioningitrequires Python 3.7 or higher.  Just usepipfor Python 3 (You have pip, right?) to installversioningitand its dependencies:python3 -m pip install versioningitHowever, usually you won’t need to installversioningitin your environment
directly.  Instead, you specify it in your project’spyproject.tomlfile in
thebuild-system.requireskey, like so:# If using Setuptools:[build-system]requires=["setuptools","versioningit",]build-backend="setuptools.build_meta"# If using Hatch:[build-system]requires=["hatchling","versioningit",]build-backend="hatchling.build"# This setting is also required if you're using Hatch:[tool.hatch.version]source="versioningit"Then, you configureversioningitby adding a[tool.versioningit]table
to yourpyproject.toml.  Seethe documentationfor details, but you
can get up & running with just the minimal configuration, an empty table:[tool.versioningit]versioningiteliminates the need to list an explicit version insetup.py,setup.cfg, orpyproject.toml(and any explicit version
you do list will be ignored when usingversioningit), so you should remove
any such settings in order to reduce confusion.Note:If you’re specifying your project metadata via a[project]table
inpyproject.toml, you need to setproject.dynamic = ["version"]in
order forversioningitto work.Once you have a[tool.versioningit]table in yourpyproject.toml— and
once your repository has at least one tag — building your project withbuildor similar will result in your project’s version automatically being set based
on the latest tag in your Git repository.  You can test your configuration and
see what the resulting version will be using theversioningitcommand (see
the documentation).Example ConfigurationsOne ofversioningit’s biggest strengths is its ability to configure the
version format using placeholder strings.  The default format configuration
looks like this:[tool.versioningit.format]# Format used when there have been commits since the most recent tag:distance="{base_version}.post{distance}+{vcs}{rev}"# Example formatted version: 1.2.3.post42+ge174a1f# Format used when there are uncommitted changes:dirty="{base_version}+d{build_date:%Y%m%d}"# Example formatted version: 1.2.3+d20230922# Format used when there are both commits and uncommitted changes:distance-dirty="{base_version}.post{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"# Example formatted version: 1.2.3.post42+ge174a1f.d20230922Other format configurations of interest include:The default format used bysetuptools_scm:[tool.versioningit.next-version]method="smallest"[tool.versioningit.format]distance="{next_version}.dev{distance}+{vcs}{rev}"# Example formatted version: 1.2.4.dev42+ge174a1fdirty="{base_version}+d{build_date:%Y%m%d}"# Example formatted version: 1.2.3+d20230922distance-dirty="{next_version}.dev{distance}+{vcs}{rev}.d{build_date:%Y%m%d}"# Example formatted version: 1.2.4.dev42+ge174a1f.d20230922The format used byversioneer:[tool.versioningit.format]distance="{base_version}+{distance}.{vcs}{rev}"# Example formatted version: 1.2.3+42.ge174a1fdirty="{base_version}+{distance}.{vcs}{rev}.dirty"# Example formatted version: 1.2.3+42.ge174a1f.dirtydistance-dirty="{base_version}+{distance}.{vcs}{rev}.dirty"# Example formatted version: 1.2.3+42.ge174a1f.dirtyThe format used byvcversioner:[tool.versioningit.format]distance="{base_version}.post{distance}"# Example formatted version: 1.2.3.post42dirty="{base_version}"# Example formatted version: 1.2.3distance-dirty="{base_version}.post{distance}"# Example formatted version: 1.2.3.post42