Skip to content

Commit adf997c

Browse files
dolfinusdolfinus
authored
#10 Fix examples in README.md
1 parent 64e68cd commit adf997c

File tree

1 file changed

+306
-14
lines changed

1 file changed

+306
-14
lines changed

‎README.md

+306-14
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/setuptools-git-versioning)](https://badge.fury.io/py/setuptools-git-versioning)
55
[![Build Status](https://github.com/dolfinus/setuptools-git-versioning/workflows/Tests/badge.svg)](https://github.com/dolfinus/setuptools-git-versioning/actions)
66

7-
Automatically set package version using git tag/hash
7+
Use git repo data (latest tag, current commit hash, etc) for building a version number according [PEP-440(https://www.python.org/dev/peps/pep-0440/).
88

99
## Compairing with other packages
1010

@@ -25,27 +25,324 @@ Adding `setup_requires=['setuptools-git-versioning']` somewhere in `setup.py` wi
2525

2626
## Usage
2727

28-
To just use the default templates for versioning:
28+
Just add these lines into your `setup.py`:
29+
```python
30+
setuptools.setup(
31+
...
32+
version_config=True,
33+
setup_requires=['setuptools-git-versioning'],
34+
...
35+
)
36+
```
2937

38+
### Release version = git tag
39+
You want to use git tag as a release number instead of duplicating it setup.py or other file.
40+
41+
For example, current repo state is:
42+
```
43+
commit 86269212 Release commit (HEAD, master)
44+
|
45+
commit e7bdbe51 Another commit
46+
|
47+
...
48+
|
49+
commit 273c47eb Long long ago
50+
|
51+
...
52+
```
53+
54+
Then you decided to release new version:
55+
- Tag commit with a proper release version (e.g. `v1.0.0` or `1.0.0`):
56+
```
57+
commit 86269212 Release commit (v1.0.0, HEAD, master)
58+
|
59+
commit e7bdbe51 Another commit
60+
|
61+
...
62+
|
63+
commit 273c47eb Long long ago
64+
|
65+
...
66+
```
67+
- Check current version with command `python setup.py --version`.
68+
- You'll get `1.0.0` as a version number. If tag number had `v` prefix, like `v1.0.0`, it will be trimmed.
69+
70+
#### Version number template
71+
By default, when you try to get current version, you'll receive version number like `1.0.0`.
72+
73+
You can change this template just in the same `setup.py` file:
74+
```python
75+
setuptools.setup(
76+
...
77+
version_config={
78+
"template": "2021.{tag}",
79+
},
80+
setup_requires=['setuptools-git-versioning'],
81+
...
82+
)
83+
```
84+
In this case, for tag `3.4` version number will be `2021.3.4`
85+
86+
#### Dev template
87+
For example, current repo state is:
88+
```
89+
commit 86269212 Current commit (HEAD, master)
90+
|
91+
commit 86269212 Release commit (v1.0.0)
92+
|
93+
commit e7bdbe51 Another commit
94+
|
95+
...
96+
|
97+
commit 273c47eb Long long ago
98+
|
99+
...
100+
```
101+
102+
By default, when you try to get current version, you'll receive version number like `1.0.0.post1+git.64e68cd`.
103+
104+
This is a PEP-440 compilant value, but sometimes you want see just `1.0.0.post1` value or even `1.0.0`.
105+
106+
You can change this template just in the same `setup.py` file:
107+
- For values like `1.0.0.post1`. `N` in `.postN` suffix is a number of commits since previous release (tag):
108+
```python
109+
setuptools.setup(
110+
...
111+
version_config={
112+
"dev_template": "{tag}.dev{ccount}",
113+
},
114+
setup_requires=['setuptools-git-versioning'],
115+
...
116+
)
117+
```
118+
- To return just the latest tag value, like `1.0.0`,use these options:
119+
```python
120+
version_config={
121+
"dev_template": "{tag}",
122+
}
123+
```
124+
125+
#### Dirty template
126+
For example, current repo state is:
127+
```
128+
Unstashed changes (HEAD)
129+
|
130+
commit 86269212 Current commit (master)
131+
|
132+
commit 86269212 Release commit (v1.0.0)
133+
|
134+
commit e7bdbe51 Another commit
135+
|
136+
...
137+
|
138+
commit 273c47eb Long long ago
139+
|
140+
...
141+
```
142+
143+
By default, when you try to get current version, you'll receive version number like `1.0.0.post1+git.64e68cd.dirty`.
144+
This is a PEP-440 compilant value, but sometimes you want see just `1.0.0.post1` value or even `1.0.0`.
145+
146+
You can change this template just in the same `setup.py` file:
147+
- For values like `1.0.0.post1`. `N` in `.postN` suffix is a number of commits since previous release (tag):
148+
```python
149+
setuptools.setup(
150+
...
151+
version_config={
152+
"dirty_template": "{tag}.dev{ccount}",
153+
},
154+
setup_requires=['setuptools-git-versioning'],
155+
...
156+
)
157+
```
158+
- To return just the latest tag value, like `1.0.0`,use these options:
159+
```python
160+
version_config={
161+
"dirty_template": "{tag}",
162+
}
163+
```
164+
165+
#### Set initial version
166+
For example, current repo state is:
167+
```
168+
commit 86269212 Current commit (HEAD, master)
169+
|
170+
commit e7bdbe51 Another commit
171+
|
172+
...
173+
|
174+
commit 273c47eb Long long ago
175+
|
176+
...
177+
```
178+
And there are just no tags in the current branch.
179+
180+
By default, when you try to get current version, you'll receive some initial value, like `0.0.1`
181+
182+
You can change this template just in the same `setup.py` file:
183+
```python
184+
setuptools.setup(
185+
...
186+
version_config={
187+
"starting_version": "1.0.0",
188+
},
189+
setup_requires=['setuptools-git-versioning'],
190+
...
191+
)
192+
```
193+
194+
### Use callback as current version
195+
For example, current repo state is:
196+
```
197+
commit 233f6d72 Dev branch commit (HEAD, dev)
198+
|
199+
| commit 86269212 Current commit (v1.0.0, master)
200+
| |
201+
| commit e7bdbe51 Another commit
202+
| /
203+
...
204+
|
205+
commit 273c47eb Long long ago
206+
|
207+
...
208+
```
209+
And there are just no tags in the current branch (`dev`) because all of them are placed in the `master` branch only.
210+
211+
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?
212+
213+
You can create a function in some file (for example, in the `__init__.py` file of your module):
30214
```python
215+
def get_version():
216+
return '1.0.0'
217+
```
218+
Then place it in both the branches and update your `setup.py` file:
219+
```python
220+
from mymodule import get_version
221+
31222
setuptools.setup(
32223
...
33-
version_config=True,
224+
version_config={
225+
"version_callback": get_version,
226+
},
227+
setup_requires=['setuptools-git-versioning'],
34228
...
229+
)
230+
```
231+
232+
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.
233+
234+
If a value of this option is not a function but just str, it also could be used:
235+
- `__init__.py` file:
236+
```python
237+
__version__ = '1.0.0'
238+
```
239+
- `setup.py` file:
240+
```python
241+
from mymodule import __version__
242+
243+
setuptools.setup(
244+
...
245+
version_config={
246+
"version_callback": __version__,
247+
},
248+
setup_requires=['setuptools-git-versioning'],
249+
...
250+
)
251+
```
252+
253+
**Please take into account that no tag means `dev_template` or `dirty_template` values are not user because current repo state is ignored in such the case**
254+
255+
256+
### Read current version from a file
257+
Just like the previous example, but instead you can save current version in a simple test file instead of `.py` script.
258+
259+
Just create a file (for example, `VERSION` or `VERSION.txt`) and place here a version number:
260+
```
261+
1.0.0
262+
```
263+
Then place it in both the branches and update your `setup.py` file:
264+
```python
265+
import os
266+
267+
HERE = os.path.dirname(__file__)
268+
VERSION_FILE = os.path.join(HERE, 'VERSION')
269+
270+
setuptools.setup(
271+
...
272+
version_config={
273+
"version_file": VERSION_FILE,
274+
},
35275
setup_requires=['setuptools-git-versioning'],
36276
...
37277
)
38278
```
39279

40-
Changing templates (also shows the defaults):
280+
When you'll try to get current version in non-master branch, the content of this file will be returned instead.
281+
282+
### Development releases (prereleases) from `dev`/`develop` branch
283+
284+
For example, current repo state is:
285+
```
286+
commit 233f6d72 Dev branch commit (HEAD, dev)
287+
|
288+
| commit 86269212 Current commit (v1.0.0, master)
289+
| |
290+
| commit e7bdbe51 Another commit
291+
| /
292+
...
293+
|
294+
commit 273c47eb Long long ago
295+
|
296+
...
297+
```
298+
You want to make development releases (prereleases) from this branch.
299+
But there are just no tags in the current branch (`dev`) because all of them are placed in the `master` branch only.
300+
301+
Just like the examples above, create a file with a next release number (e.g. `1.1.0`) in the `dev` branch, e.g. `VERSION.txt`:
302+
```
303+
1.1.0
304+
```
305+
But place here **next** release number instead of current one.
306+
307+
Then update your `setup.py` file:
308+
```python
309+
import os
310+
311+
HERE = os.path.dirname(__file__)
312+
VERSION_FILE = os.path.join(HERE, 'VERSION.txt')
313+
314+
setuptools.setup(
315+
...
316+
version_config={
317+
"count_commits_from_version_file": True,
318+
"dev_template": "{tag}.dev{ccount}", # suffix now is not .post, but .dev
319+
"dirty_template": "{tag}.dev{ccount}", # same thing here
320+
"version_file": VERSION_FILE
321+
},
322+
setup_requires=['setuptools-git-versioning'],
323+
...
324+
)
325+
```
326+
327+
Then you decided to release new version:
328+
- Merge `dev` branch into `master` branch.
329+
- 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.
330+
- Save next release version (e.g. `1.2.0`) in `VERSION` or `version.py` file in the `dev` branch. **Do not place any tags in the `dev` branch!**
331+
- Next commits to a `dev` branch will lead to returning this next release version plus dev suffix, like `1.1.0.dev1` or so.
332+
- `N` in `.devN` suffix is a number of commits since the last change of a certain file.
333+
- **Note: every change of this file in the `dev` branch will lead to this `N` suffix to be reset. Update this file only in the case when you've setting up the next release version!**
334+
335+
## Options
336+
337+
Default options are:
41338

42339
```python
43340
setuptools.setup(
44341
...
45342
version_config={
46343
"template": "{tag}",
47-
"dev_template": "{tag}.dev{ccount}+git.{sha}",
48-
"dirty_template": "{tag}.dev{ccount}+git.{sha}.dirty",
344+
"dev_template": "{tag}.post{ccount}+git.{sha}",
345+
"dirty_template": "{tag}.post{ccount}+git.{sha}.dirty",
49346
"starting_version": "0.0.1",
50347
"version_callback": None,
51348
"version_file": None,
@@ -57,8 +354,6 @@ setuptools.setup(
57354
)
58355
```
59356

60-
### Templates
61-
62357
- `template`: used if no untracked files and latest commit is tagged
63358

64359
- `dev_template`: used if no untracked files and latest commit isn't tagged
@@ -71,14 +366,11 @@ setuptools.setup(
71366

72367
- `version_file`: path to VERSION file, to read version from it instead of using `static_version`
73368

74-
- `count_commits_from_version_file`: `True` to fetch `version_file` last commit instead of tag commit, `False` overwise. Example:
369+
- `count_commits_from_version_file`: `True` to fetch `version_file` last commit instead of tag commit, `False` otherwise
75370

76-
You have a project there tags are added to `master` branch only (e.g. '1.0.0').
77-
But you also wish to build development version (e.g. '1.0.0.dev0') from each commit to `dev` branch.
78-
But you don't want neither setup tag with CI/CD for every commit to `dev` branch, nor set such tags manually.
79-
So just fill up `version_file`, set `count_commits_from_version_file` to `True` and that's all.
371+
### Substitions
80372

81-
### Format Options
373+
You can use these substitutions in `template`, `dev_template` or `dirty_template` options:
82374

83375
- `{tag}`: Latest tag in the repository
84376

0 commit comments

Comments
 (0)