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

NAMEBASE=		python-vcversioner
VERSION=		2.16.0.0
KEYWORDS=		python devel
VARIANTS=		py27 py38 py37
SDESC[py37]=		Extract version from version control tag (PY 37)
SDESC[py38]=		Extract version from version control tag (PY 38)
SDESC[py27]=		Extract version from version control tag (PY 27)
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[py37]=		single
SPKGS[py38]=		single
SPKGS[py27]=		single

OPTIONS_AVAILABLE=	PY27 PY38 PY37
OPTIONS_STANDARD=	none
VOPTS[py37]=		PY27=OFF PY38=OFF PY37=ON
VOPTS[py38]=		PY27=OFF PY38=ON PY37=OFF
VOPTS[py27]=		PY27=ON PY38=OFF PY37=OFF

DISTNAME=		vcversioner-2.16.0.0

GENERATED=		yes

[PY37].USES_ON=				python:py37

[PY38].USES_ON=				python:py38

[PY27].USES_ON=				python:py27

[FILE:3360: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
---------------

``setup.py`` isn't the only place that version information gets
duplicated. By
generating a version module, the ``__init__.py`` file of a package can
import
version information. For example, with a package named ``spam``::

  from setuptools import setup


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