# Buildsheet autogenerated by ravenadm tool -- Do not edit.

NAMEBASE=		python-vcversioner
VERSION=		2.16.0.0
KEYWORDS=		python
VARIANTS=		v11 v12
SDESC[v11]=		Extract version from version control tag (3.11)
SDESC[v12]=		Extract version from version control tag (3.12)
HOMEPAGE=		https://github.com/habnabit/vcversioner
CONTACT=		Python_Automaton[python@ironwolf.systems]

DOWNLOAD_GROUPS=	main
SITES[main]=		PYPI/v/vcversioner
DISTFILE[1]=		vcversioner-2.16.0.0.tar.gz:main
DF_INDEX=		1
SPKGS[v11]=		single
SPKGS[v12]=		single

OPTIONS_AVAILABLE=	PY311 PY312
OPTIONS_STANDARD=	none
VOPTS[v11]=		PY311=ON PY312=OFF
VOPTS[v12]=		PY311=OFF PY312=ON

DISTNAME=		vcversioner-2.16.0.0

GENERATED=		yes

[PY311].USES_ON=			python:v11,sutools

[PY312].USES_ON=			python:v12,sutools

[FILE:3061:descriptions/desc.single]
.. image:: https://travis-ci.org/habnabit/vcversioner.png

===========
vcversioner
===========

`Elevator pitch`_: you can write a ``setup.py`` with no version information
specified, and vcversioner will find a recent, properly-formatted VCS tag
and
extract a version from it.

It's much more convenient to be able to use your version control system's
tagging mechanism to derive a version number than to have to duplicate that
information all over the place. I eventually ended up copy-pasting the same
code into a couple different ``setup.py`` files just to avoid duplicating
version information. But, copy-pasting is dumb and unit testing
``setup.py``
files is hard. This code got factored out into vcversioner.

Basic usage
-----------

vcversioner installs itself as a setuptools hook, which makes its use
exceedingly simple::

  from setuptools import setup

  setup(
      # [...]
      setup_requires=['vcversioner'],
      vcversioner={},
  )

The presence of a vcversioner argument automagically activates vcversioner
and updates the project's version. The parameter to the vcversioner
argument can also be a dict of keyword arguments which |find_version|
will be called with.

To allow tarballs to be distributed without requiring a ``.git`` (or
``.hg``,
etc.) directory, vcversioner will also write out a file named (by default)
``version.txt``. Then, if there is no VCS program or the program is unable
to
find any version information, vcversioner will read version information
from
the ``version.txt`` file. However, this file needs to be included in a
distributed tarball, so the following line should be added to
``MANIFEST.in``::

  include version.txt

This isn't necessary if ``setup.py`` will always be run from a checkout,
but
otherwise is essential for vcversioner to know what version to use.

The name ``version.txt also can be changed by specifying the version_file``
parameter. For example::

  from setuptools import setup

  setup(
      # [...]
      setup_requires=['vcversioner'],
      vcversioner={
          'version_file': 'custom_version.txt',
      },
  )

For compatibility with `semantic versioning`_, vcversioner will strip
leading 'v'\ s  from version tags. That is, the tag ``v1.0 will be
treated as if it was 1.0``.

Other prefixes can be specified to be stripped by using the strip_prefix
argument to vcversioner. For compatibility with ``git-dch``, one could
specify
the strip_prefix as ``'debian/'``.

Non-hook usage
--------------

It's not necessary to depend on vcversioner; while `pip`_ will take care of
dependencies automatically, sometimes having a self-contained project is
simpler. vcversioner is a single file which is easy to add to a project.
Simply
copy the entire ``vcversioner.py file adjacent to the existing setup.py``
file and update the usage slightly::

  from setuptools import setup
  import vcversioner

  setup(
      # [...]
      version=vcversioner.find_version().version,
  )

This is necessary because the vcversioner distutils hook won't be
available.

Version modules
---------------


[FILE:106:distinfo]
dae60c17a479781f44a4010701833f1829140b1eeccd258762a74974aa06e19b         9024 vcversioner-2.16.0.0.tar.gz