---
name: "towncrier"
section: "1"
platform: "linux"
package: "towncrier"
version: "24.8.0-2"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/towncrier"
---

# towncrier(1)

manage a useful, summarised news file for your project

## NAME

towncrier - manage a useful, summarised news file for your project

## SYNOPSIS

**towncrier** … \[**--config** *CONFIG\_FILE*\] \[**--dir** *FRAGMENTS\_DIR*\] …

**towncrier** \[**build**\] \[**--name** *PROJECT\_NAME*\] \[**--version** *RELEASE\_VERSION*\] \[**--date** *RELEASE\_DATE*\] \[**--draft**\] \[**--yes**\] \[**--keep**\]

**towncrier create** \[**--content** *CONTENT*\] \[**--edit**\|**--no-edit**\] *FRAGMENT\_FILE*

**towncrier check** \[**--compare-with** *GIT\_COMMIT*\]

**towncrier** **--help**

**towncrier** **--version**

## DESCRIPTION

**towncrier** is a utility to produce useful, summarised news files for your project. Rather than reading the VCS history to produce it, or having one single file which developers all write to, towncrier reads “news fragments” which contain information useful to end users.

## OPTIONS

- **--config** *CONFIG\_FILE*

  Use the specified *CONFIG\_FILE* to configure program behaviour. (Default: **towncrier.toml** or, if that does not exist, **pyproject.toml**)

- **--dir** *FRAGMENTS\_DIR*

  Manage news fragments in the directory *FRAGMENTS\_DIR*, relative to the project directory. (Default: **newsfragments**)

- **-v** **--version**

  Emit the program version.

- **-h** **--help**

  Describe how to use the program.

## COMMANDS

\[**build**\] \[**--name** *PROJECT\_NAME*\] \[**--version** *RELEASE\_VERSION*\] \[**--date** *RELEASE\_DATE*\] \[**--draft**\] \[**--yes**\] \[**--keep**\]

-

  Discover all the news fragments in *FRAGMENTS\_DIR*, and collate them. Render them as a news document for project *PROJECT\_NAME* released on *RELEASE\_DATE* as version *RELEASE\_VERSION*. Then, append the generated news document to the configured news file, use Git to stage the resulting file, and finally prompt the user for whether to delete the news fragment files. (Or, if **--draft** is specified: Emit the news file text to the standard error stream, and do not change any files.) If **--yes** is specified, omit the prompt and assume “yes” to delete news fragment files.

  If **--keep** is specified, omit the prompt and assume “no” to delete news fragment files.

**create** \[**--content** *CONTENT*\] \[**--edit**\|**--no-edit**\] *FRAGMENT\_FILE*

-

  Create a news fragment with filename *FRAGMENT\_FILE*. If **--content** is specified, populate the news fragment file with text content *CONTENT*. If **--edit** is specified, launch the default text editor with the news fragment file.

**check** \[**--compare-with** *GIT\_COMMIT*\]

-

  Compare the current news file and fragments to those in the Git commit *GIT\_COMMIT* (default: **origin/master**); then, if the news file is the same, report any additional fragments found.

## REPORTING BUGS

Please report any bugs using the Towncrier project issue tracker ⟨https://github.com/twisted/towncrier/issues/new⟩.

## COPYRIGHT

This manual page is Copyright © 2021–2024 Ben Finney ⟨bignose@debian.org⟩ and Sérgio de Almeida Cipriano Junior ⟨sergiosacj@hotmail.com.br⟩, and is freely available to anyone under certain conditions. See the source document for details.

## SEE ALSO

The Towncrier project upstream home page ⟨https://github.com/twisted/towncrier⟩.