Use git repo data for building a version number according PEP-440
Project description
setuptools-git-versioning
Use git repo data (latest tag, current commit hash, etc) for building a version number according PEP-440.
Compairing with other packages
Package/Function | Lastest release | License | Python2 support | Python3 support | Windows support | PEP 440 compatible | Type hints | Supported substitutions | Dev template support | Dirty template support | Initial version support | Callback/variable as current version | Read some file content as current version | Development releases (prereleases) support | Reusing functions in other packages |
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
setuptools-git-versioning | 2021 | MIT | + | 3.3+ | + | + | + | tag, commits_count, short_sha, full_sha, branch | + | + | + | + | + | + | + |
setuptools-git-ver (Base package) | 2019 | MIT | - | 3.7+ | + | + | + | tag, commits_count, short_sha | + | + | - | - | - | - | - |
another-setuptools-git-version | 2020 | MIT | - | 3.5+ | - | + | + | tag, commits_count | + | - | + | - | - | - | + |
bad-setuptools-git-version | 2020 | MIT | + | + | + | + | - | tag, commits_count | + | - | + | - | - | - | + |
even-better-setuptools-git-version | 2019 | MIT | - | + | - | + | - | tag, short_sha | - | - | + | - | - | - | + |
better-setuptools-git-version | 2018 | MIT | - | + | - | - | - | tag, short_sha | - | - | + | - | - | - | + |
very-good-setuptools-git-version | 2018 | MIT | - | + | - | - | - | tag, commits_count, short_sha | - | - | - | - | - | - | + |
setuptools-git-version | 2018 | Unknown | + | + | + | - | - | tag, commits_count, short_sha | - | - | - | - | - | - | - |
Installation
No need.
Adding setup_requires=['setuptools-git-versioning']
somewhere in setup.py
will automatically download the latest version from PyPi and save it in the .eggs
folder when setup.py
is run.
Usage
Just add these lines into your setup.py
:
setuptools.setup(
...
version_config=True,
setup_requires=['setuptools-git-versioning'],
...
)
Release version = git tag
You want to use git tag as a release number instead of duplicating it setup.py or other file.
For example, current repo state is:
commit 86269212 Release commit (HEAD, master)
|
commit e7bdbe51 Another commit
|
...
|
commit 273c47eb Long long ago
|
...
Then you decided to release new version:
- Tag commit with a proper release version (e.g.
v1.0.0
or1.0.0
):commit 86269212 Release commit (v1.0.0, HEAD, master) | commit e7bdbe51 Another commit | ... | commit 273c47eb Long long ago | ...
- Check current version with command
python setup.py --version
. - You'll get
1.0.0
as a version number. If tag number hadv
prefix, likev1.0.0
, it will be trimmed.
Version number template
By default, when you try to get current version, you'll receive version number like 1.0.0
.
You can change this template just in the same setup.py
file:
setuptools.setup(
...
version_config={
"template": "2021.{tag}",
},
setup_requires=['setuptools-git-versioning'],
...
)
In this case, for tag 3.4
version number will be 2021.3.4
Dev template
For example, current repo state is:
commit 86269212 Current commit (HEAD, master)
|
commit 86269212 Release commit (v1.0.0)
|
commit e7bdbe51 Another commit
|
...
|
commit 273c47eb Long long ago
|
...
By default, when you try to get current version, you'll receive version number like 1.0.0.post1+git.64e68cd
.
This is a PEP-440 compilant value, but sometimes you want see just 1.0.0.post1
value or even 1.0.0
.
You can change this template just in the same setup.py
file:
- For values like
1.0.0.post1
.N
in.postN
suffix is a number of commits since previous release (tag):setuptools.setup( ... version_config={ "dev_template": "{tag}.dev{ccount}", }, setup_requires=['setuptools-git-versioning'], ... )
- To return just the latest tag value, like
1.0.0
,use these options:version_config={ "dev_template": "{tag}", }
Dirty template
For example, current repo state is:
Unstashed changes (HEAD)
|
commit 86269212 Current commit (master)
|
commit 86269212 Release commit (v1.0.0)
|
commit e7bdbe51 Another commit
|
...
|
commit 273c47eb Long long ago
|
...
By default, when you try to get current version, you'll receive version number like 1.0.0.post1+git.64e68cd.dirty
.
This is a PEP-440 compilant value, but sometimes you want see just 1.0.0.post1
value or even 1.0.0
.
You can change this template just in the same setup.py
file:
- For values like
1.0.0.post1
.N
in.postN
suffix is a number of commits since previous release (tag):setuptools.setup( ... version_config={ "dirty_template": "{tag}.dev{ccount}", }, setup_requires=['setuptools-git-versioning'], ... )
- To return just the latest tag value, like
1.0.0
,use these options:version_config={ "dirty_template": "{tag}", }
Set initial version
For example, current repo state is:
commit 86269212 Current commit (HEAD, master)
|
commit e7bdbe51 Another commit
|
...
|
commit 273c47eb Long long ago
|
...
And there are just no tags in the current branch.
By default, when you try to get current version, you'll receive some initial value, like 0.0.1
You can change this template just in the same setup.py
file:
setuptools.setup(
...
version_config={
"starting_version": "1.0.0",
},
setup_requires=['setuptools-git-versioning'],
...
)
Callback/variable as current version
For example, current repo state is:
commit 233f6d72 Dev branch commit (HEAD, dev)
|
| commit 86269212 Current commit (v1.0.0, master)
| |
| commit e7bdbe51 Another commit
| /
...
|
commit 273c47eb Long long ago
|
...
And there are just no tags in the current branch (dev
) because all of them are placed in the master
branch only.
By default, when you try to get current version, you'll receive some initial value. But if you want to get syncronized version numbers in both on the branches?
You can create a function in some file (for example, in the __init__.py
file of your module):
def get_version():
return '1.0.0'
Then place it in both the branches and update your setup.py
file:
from mymodule import get_version
setuptools.setup(
...
version_config={
"version_callback": get_version,
},
setup_requires=['setuptools-git-versioning'],
...
)
When you'll try to get current version in non-master branch, the result of executing this function will be returned instead of latest tag number.
If a value of this option is not a function but just str, it also could be used:
__init__.py
file:__version__ = '1.0.0'
setup.py
file:from mymodule import __version__ setuptools.setup( ... version_config={ "version_callback": __version__, }, setup_requires=['setuptools-git-versioning'], ... )
Please take into account that no tag means that dev_template
or dirty_template
values are not used because current repo state is ignored in such a case
Read some file content as current version
Just like the previous example, but instead you can save current version in a simple test file instead of .py
script.
Just create a file (for example, VERSION
or VERSION.txt
) and place here a version number:
1.0.0
Then place it in both the branches and update your setup.py
file:
import os
HERE = os.path.dirname(__file__)
VERSION_FILE = os.path.join(HERE, 'VERSION')
setuptools.setup(
...
version_config={
"version_file": VERSION_FILE,
},
setup_requires=['setuptools-git-versioning'],
...
)
When you'll try to get current version in non-master branch, the content of this file will be returned instead.
Development releases (prereleases) from another branch
For example, current repo state is:
commit 233f6d72 Dev branch commit (HEAD, dev)
|
| commit 86269212 Current commit (v1.0.0, master)
| |
| commit e7bdbe51 Another commit
| /
...
|
commit 273c47eb Long long ago
|
...
You want to make development releases (prereleases) from commits to a dev
branch.
But there are just no tags here because all of them are placed in the master
branch only.
Just like the examples above, create a file with a release number (e.g. 1.1.0
) in the dev
branch, e.g. VERSION.txt
:
1.1.0
But place here next release number instead of current one.
Then update your setup.py
file:
import os
HERE = os.path.dirname(__file__)
VERSION_FILE = os.path.join(HERE, 'VERSION.txt')
setuptools.setup(
...
version_config={
"count_commits_from_version_file": True,
"dev_template": "{tag}.dev{ccount}", # suffix now is not .post, but .dev
"dirty_template": "{tag}.dev{ccount}", # same thing here
"version_file": VERSION_FILE
},
setup_requires=['setuptools-git-versioning'],
...
)
Then you decided to release new version:
- Merge
dev
branch intomaster
branch. - Tag commit in the
master
branch with a proper release version (e.g.v1.1.0
). Tag will be used as a version number for the release. - Save next release version (e.g.
1.2.0
) inVERSION
orversion.py
file in thedev
branch. Do not place any tags in thedev
branch! - Next commits to a
dev
branch will lead to returning this next release version plus dev suffix, like1.1.0.dev1
or so. N
in.devN
suffix is a number of commits since the last change of a certain file.- Note: every change of this file in the
dev
branch will lead to thisN
suffix to be reset to0
. Update this file only in the case when you've setting up the next release version!
Options
Default options are:
setuptools.setup(
...
version_config={
"template": "{tag}",
"dev_template": "{tag}.post{ccount}+git.{sha}",
"dirty_template": "{tag}.post{ccount}+git.{sha}.dirty",
"starting_version": "0.0.1",
"version_callback": None,
"version_file": None,
"count_commits_from_version_file": False
},
...
setup_requires=['setuptools-git-versioning'],
...
)
-
template
: used if no untracked files and latest commit is tagged -
dev_template
: used if no untracked files and latest commit isn't tagged -
dirty_template
: used if untracked files exist or uncommitted changes have been made -
starting_version
: static value, used if not tags exist in repo -
version_callback
: variable or callback function to get version instead of usingstarting_version
-
version_file
: path to VERSION file, to read version from it instead of usingstatic_version
-
count_commits_from_version_file
:True
to fetchversion_file
last commit instead of tag commit,False
otherwise
Substitions
You can use these substitutions in template
, dev_template
or dirty_template
options:
-
{tag}
: Latest tag in the repository -
{ccount}
: Number of commits since last tag or lastversion_file
commit (seecount_commits_from_version_file
) -
{full_sha}
: Full sha hash of the latest commit -
{sha}
: First 8 characters of the sha hash of the latest commit -
{branch}
: Current branch name
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distributions
Hashes for setuptools-git-versioning-1.3.6.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0f3a73565d1093643f81b1e3a9209d030c49052c1b445dc00475b4fc0b56ce19 |
|
MD5 | 1345abdaa7df65bbe721444190555c92 |
|
BLAKE2b-256 | 3bc5fc662b14682eb537cd30c4dadbaaf8729a81226caa0695993fb34249d64f |
Hashes for setuptools_git_versioning-1.3.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | a7f2d6c73ab057047b9c8dc2af277d7b360928caef815421cdc383f9a1a3da00 |
|
MD5 | f437e17a2fe24d7d1e8a9acc00711130 |
|
BLAKE2b-256 | c2ece2b2172808fff1d96802cd5a721425d297293083cad4911fb3b7f1ddeba4 |
Hashes for setuptools_git_versioning-1.3.6-py2-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 1fb040385d5ee07bd85bbfd5bf20cc1b7ea79e73c07fbad9885e9b456d5b76e5 |
|
MD5 | 45860bf5672106a4bb58966b40225194 |
|
BLAKE2b-256 | 4e0430077f52f8e8b194bab49b048c0b3001c42be07240355538169535364696 |