Skip to main content

Builds a pythonic version number based on scm tags and branches

Project description


Builds a pythonic version number based on information available on your scm (tag, branch, and number of commits).

See LICENSE for important licensing information.


Your will need jfaleiro.setup_scmversion to start - so you either make sure you have it pre-installed using pip:

pip install jfaleiro.setup-scmversion


A pythonic version number is created from standard data available in your scm, i.e. tag, branch name, and number of differences from master.

Simplest Use

Should apply to most projects. Assumes your project has one main package. For this example let's name this package mypackage. After installation add this to your

import mypackage
setup( ...

Add this to your or

from ._version import __version__

Done. Now you just have to make sure you execute scmversion tag-version after installation and before any setuptools task that requires a version:

scmversion tag-version
python sdist # or any other command that requires a tagged version 

Examples of other possible setup commands are develop, install, bdist, and others.

To know usage details refer to scmversion --help

Way More Complicated

Add this on the very top of your and forget about it moving forward.

    import setup_scmversion
except ModuleNotFoundError as e:
    from pip._internal import main
    assert main('install jfaleiro.setup-scmversion'.split()) == 0
from setup_scmversion import version

Add these parameters to your version and setup_requires parameters in


Versioning Schema

Release tags release/<version> with nnn differences from master will produce version <version>.dev<nnn> and a tagged version <tag> on master will produce the version <tag>. Everything else will produce<nnn> for master or<nnn> for any other branch.

You can also use a command line based shortcut to peek at the current version:

jfaleiro@itacoatiara:~/gitrepos/setup_scmversion (release/0.0.1 *+)$ scmversion version

or the type of version, i.e.:

jfaleiro@itacoatiara:~/gitrepos/setup_scmversion (release/0.0.1 *+)$ scmversion version-type

The type of release can be one of RELEASE, RELEASE_BRANCH, FEATURE_BRANCH, or OTHER

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for jfaleiro.setup-scmversion, version 0.0.2
Filename, size File type Python version Upload date Hashes
Filename, size jfaleiro.setup_scmversion-0.0.2.tar.gz (7.3 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page