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⟩.