| 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
---------------
|