Options¶
Zest.releaser tries not to burden you with lots of command line options. Instead, it asks questions while doing its job. But in some cases, a command line option makes sense.
Related: you can change some settings globally in your ~/.pypirc
file or per project in a setup.cfg
file. This is only for Python
packages.
Command line options¶
These command line options are supported by the release commands
(fullrelease
, prerelease
, release
, postrelease
)
and by the addchangelogentry
command.
- -v, --verbose
Run in verbose mode, printing a bit more, mostly only interesting for debugging.
- -h, --help
Display help text
- --no-input
Don’t ask questions, just use the default values. If you are very sure that all will be fine when you answer all questions with the default answer, and you do not want to press Enter several times, you can use this option. The default answers (sometimes yes, sometimes no, sometimes a version number) are probably sane and safe. But do not blame us if this does something you do not want. :-)
The addchangelogentry
command requires the text you want to add as
argument. For example:
$ addchangelogentry "Fixed bug."
Or on multiple lines:
$ addchangelogentry "Fixed bug.
This was difficult."
The bumpversion
and postrelease
commands accept some mutually exclusive options:
With
--feature
we update the minor version.With
--breaking
we update the major version.With
--final
we remove alpha / beta / rc markers from the version.
Global options¶
You can configure zest.releaser for all projects by editing the
.pypirc
file in your home directory. This is the same file that
needs to contain your PyPI credentials if you want to release to the
Python Packaging Index. See the topic on Uploading. This also has
more info on most options.
Lots of things may be in this file, but zest.releaser looks for a
zest.releaser
section, like this:
[zest.releaser]
some-option = some value
For true/false options, you can use no/false/off/0 or yes/true/on/1 as answers; upper, lower or mixed case are all fine.
Various options change the default answer of a question.
So if you want to use the --no-input
command line option
or want to press Enter a couple of times without thinking too much,
see if you can tweak the default answers by setting one of these options
We have these options:
- release = true / false
Default: true. When this is false, zest.releaser sets
false
as default answer for the question if you want to create a checkout of the tag.- upload-pypi = true / false
Default: true. Normally you won’t use this setting. Only if you want to make a release without actually uploading it, set it to false. (Note that you still need release=true).
- create-wheel = true / false
Default: true, if the recommended
wheel
package is installed. Set to false if you do not want zest.releaser to create Python wheels.- extra-message = [ci skip]
Extra message to add to each commit (prerelease, postrelease).
- prefix-message = [TAG]
Prefix message to add at the beginning of each commit (prerelease, postrelease).
- no-input = true / false
Default: false. Set this to true to accept default answers for all questions.
- register = true / false
Default: false. Set this to true to register a package before uploading. On the official Python Package Index registering a package is no longer needed, and may even fail.
- push-changes = true / false
Default: true. When this is false, zest.releaser sets
false
as default answer for the question if you want to push the changes to the remote.- less-zeroes = true / false
Default: false. This influences the version suggested by the bumpversion command. When set to true:
Instead of 1.3.0 we will suggest 1.3.
Instead of 2.0.0 we will suggest 2.0.
- version-levels = a number
Default: 0. This influences the version suggested by the postrelease and bumpversion commands. The default of zero means: no preference, so use the length of the current number.
This means when suggesting a next version after 1.2:
with 0 we will suggest 1.3: no change in length
with 1 we will still suggest 1.3, as we will not use this to remove numbers, only to add them
with 2 we will suggest 1.3
with 3 we will suggest 1.2.1
If the current version number has more levels, we keep them. So with
version-levels=1
the next version for 1.2.3.4 will be 1.2.3.5.- development-marker = a string
Default:
.dev0
This is the development marker. This is what gets appended to the version in postrelease.- tag-format = a string
Default:
{version}
This is a formatter that changes the name of the tag. It needs to contain{version}
. For backward compatibility, it can contain%(version)s
instead.- tag-message = a string
Default:
Tagging {version}
This formatter defines the commit message passed to thetag
command of the VCS. It must contain{version}
.- tag-signing = true / false
Default: false. When set to true, tags are signed using the signing feature of the respective vcs. Currently tag-signing is only supported for git. Note: When you enable it, everyone releasing the project is required to have git tag signing set up correctly.
- date-format = a string
Default:
%%Y-%%m-%%d
This is the format string for the release date to be mentioned in the changelog.Note: the % signs should be doubled for compatibility with other tools (i.e. pip) that parse setup.cfg using the interpolating ConfigParser.
- history-file = a string
Default: empty Usually zest.releaser can find the correct history or changelog file on its own. But sometimes it may not find anything, or it finds multiple files and selects the wrong one. Then you can set a path here.
- history_format = a string
Default: empty. Set this to
md
to handle changelog entries in Markdown.- run-pre-commit = true / false
Default: false. New in version 7.3.0. When set to true, pre commit hooks are run. This may interfere with releasing when they fail.
Per project options¶
You can change some settings per project by adding instructions for
zest.releaser in a setup.cfg
file. This will only work for a
Python package.
These are the same options as the global ones. If you set an option locally in a project, this will override the global option.
You can also set these options in a pyproject.toml
file. If you do
so, instead of having a [zest.releaser]
section, you should use a
[tool.zest-releaser]
section. For true/false options in a
pyproject.toml
, you must use lowercase true or false; for string
options like extra-message
or prefix-message
, you should put
the value between double quotes, like this:
[tool.zest-releaser]
create-wheel = false
extra-message = "[ci skip]"