dover v0.5.1¶
A commandline utility for incrementing your project version numbers.
Installation¶
... pip install dover
What does it do?¶
When dover
is run from the root directory of your project, it does the
following:
looks for a configuration file (
.dover
,.dover.ini
,setup.cfg
,pyproject.toml
)reads any
dover
configuration line in this format:[dover:file:relatvie/file.pth]Or in the case of
pyproject.toml
:[tool.dover] versioned_files = ["pyproject.toml", "dover/cli.py"]
- searches the configured file references for “version” strings
- validates all version strings across all configured files.
- displays and/or increments the version strings based upon cli options.
Usage¶
... dover --help
dover v0.5.1
dover is a commandline utility for
tracking and incrementing your
project version numbers.
Usage:
dover [--list] [--debug] [--format=<fmt>]
dover increment ((--major|--minor|--patch)
[--dev|--alpha|--beta|--rc] |
[--major|--minor|--patch]
(--dev|--alpha|--beta|--rc) | --release)
[--apply] [--debug] [--no-list] [--format=<fmt>]
Options:
-M --major Update major version segment.
-m --minor Update minor version segment.
-p --patch Update patch version segment.
-d --dev Update dev version segment.
-a --alpha Update alpha pre-release segment.
-b --beta Update beta pre-release segment.
-r --rc Update release candidate segment.
-R --release Clear pre-release version.
-x --no-list Do not list files.
--format=<fmt> Apply format string.
--debug Print full exception info.
-h --help Display this help message
--version Display dover version.
Basics¶
dover
will look for either a .dover,
setup.cfg, or pyproject.toml file within the current directory.
Files that are to be tracked by dover
should be listed in the
following format:
[dover:file:relative-file-path.ext]
Example:
[dover:file:setup.py]
[dover:file:setup.cfg]
[dover:file:dover/cli.py]
For projects using the pyproject.toml the format will be:
[tool.dover]
versioned_files = ["pyproject.toml", "dover/cli.py"]
Fetch Current Project Version¶
Calling dover
without any arguments returns the current version
number of the project.
... dover
0.1.0
This is useful for capturing your project version for use with other commandline utilities.
Currently Tracked File Status¶
Calling dover
with the --list
option, prints the project version
and the list of all files and version strings being tracked, and the line
they appear on:
... dover --list
Current Version: 0.1.0
Files:
setup.py 0005 (__version__ = '0.1.0')
setup.cfg 0002 (version = 0.1.0)
dover/cli.py 0025 (__version__ = '0.1.0')
Reviewing Version Increment Changes¶
Calling dover increment
with one the the segment options
(e.g. --minor
), will print a listing of the propsed version
change and the files that will be effected:
... dover increment --minor
Current Version: 0.1.0
New Version: 0.2.0
Files:
setup.py (0.1.0 -> 0.2.0)
setup.cfg (0.1.0 -> 0.2.0)
dover/cli.py (0.1.0 -> 0.2.0)
Attention
Only the use of the –apply option will perform a update to your files.
Applying Version Increment Changes¶
To save the change make the same call with the --apply
option:
... dover increment --minor --apply
Current Version: 0.1.0
New Version: 0.2.0
Files:
setup.py (0.1.0 -> 0.2.0)
setup.cfg (0.1.0 -> 0.2.0)
dover/cli.py (0.1.0 -> 0.2.0)
Version updates applied.
Pre-Release Options¶
Applying a pre-release option (–dev, –alpha, –beta or –rc), simply appends the pre-release to the current version:
... dover increment --alpha --no-list
Current Version: 0.1.0
New Version: 0.1.0-alpha
Tip
the –no-list option suppresses listing the files.
Applying a pre-release option to an existing pre-release of the same name increments the pre-release:
... dover increment --alpha --no-list
Current Version: 0.1.0
New Version: 0.1.0-alpha.1
Applying a pre-release option with a segment option, increments the segment and appends the pre-relase value:
... dover increment --minor --alpha --no-list
Current Version: 0.1.0
New Version: 0.2.0-alpha
Use the --release
option to move from a pre-release version to the production version:
... dover increment --release --no-list
Current Version: 0.4.0-dev
New Version: 0.4.0
Version Formats¶
The default version format dover uses is:
major.minor[.patch][-(dev|alpha|beta|rc)[.version]]
The output format can be controlled with the --format
option with these options:
00[0][(.|-)](r|R)[(.|-)][0]
Segment | Format Value | Note |
---|---|---|
Major | 0 | |
Minor | 0 | |
Patch | 0 | Optional - if left off, patch value of 0 is dropped from output. |
separator | . - | Optional. Dash or dot. |
Pre-Release | r or R | r = short name ‘a’, ‘b’, etc. R = long name ‘alpha’, ‘beta’, etc. |
separator | . - | Optional. Dash or dot. |
Pre-Release Version | 0 | Optional. Pre-release version number will always display. |
Usage examples:
dover command | output |
---|---|
dover | 0.4.0-dev.1 |
dover –format 000-R.0 | 0.0.0-dev.1 |
dover –format 000-R-0 | 0.4.0-dev-1 |
dover –format 00-R-0 | 0.4-dev-1 |
dover –format 00R | 0.4dev1 |
dover –format 00r | 0.4d1 |
dover –format 00.r | 0.4.d1 |
dover –format 00r0 | 0.4d1 |
dover –format 00-r0 | 0.4-d1 |
dover –format 00-r-0 | 0.4-d-1 |
What If There Is a Problem?¶
If at any point the version numbers between files being tracked are
missaligned, dover
will raise an error:
... dover increment --major --apply
Not all file versions match:
setup.py 0.1.0 (__version__ = '0.1.0')
setup.cfg 0.3.0 (version = 0.3.0)
dover/cli.py 0.1.0 (__version__ = '0.1.0')