Command Line Reference#
The following options can be passed to all of the commands that explained below:
- --config FILE_PATH#
Pass a custom config file at
pyproject.tomlfile. If both files exist, the first will take precedence
- --dir PATH#
The command is executed relative to
PATH. For instance with the default config news fragments are checked and added in
PATH/newsfragmentsand the news file is built in
Default: current directory.
Build the combined news file from news fragments.
build is also assumed if no command is passed.
If there are no news fragments (including an empty fragments directory or a non-existent directory), a notice of “no significant changes” will be added to the news file.
By default, the processed news fragments are removed using
git, which will
also remove the fragments directory if now empty.
Only render news fragments to standard output. Don’t write to files, don’t check versions. Only renders the news fragments without the surrounding template.
- --name NAME#
Use NAME as project name in the news file. Can be configured.
- --version VERSION#
VERSIONin the rendered news file. Can be configured or guessed (default).
This option requires the
buildcommand to be explicitly passed.
Do not ask for confirmations. Useful for automated tasks.
Don’t delete news fragments after the build and don’t ask for confirmation whether to delete or keep the fragments.
Create a news fragment in the directory that
towncrier is configured to look for fragments:
$ towncrier create 123.bugfix.rst
towncrier create will enforce that the passed type (e.g.
bugfix) is valid.
If the fragments directory does not exist, it will be created.
If the filename exists already,
towncrier create will add (and then increment) a number after the fragment type until it finds a filename that does not exist yet.
In the above example, it will generate
123.bugfix.rst already exists.
- --content, -c CONTENT#
A string to use for content. Default: an instructive placeholder.
Create file and start $EDITOR to edit it right away.
To check if a feature branch adds at least one news fragment, run:
$ towncrier check
The check is automatically skipped when the main news file is modified inside the branch as this signals a release branch that is expected to not have news fragments.
towncrier compares the current branch against
origin/main (and falls back to
origin/master with a warning if it exists, for now).
- --compare-with REMOTE-BRANCH#
$ towncrier check --compare-with origin/trunk