TOWNCRIER(1)

💖 TOWNCRIER 💖

okay so bestie, welcome to the General Commands Manual page for towncrier, and honestly? this one's a bop. let's get into it.

---

✨ 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 🦋

so towncrier is a utility to produce useful, summarised news files for your project. the whole vibe is that instead of reading the VCS history to produce it, or having one single file which developers all write to (chaos, honestly 💀), towncrier reads "news fragments" which contain information useful to end users. it's giving organization. it's giving main character energy. periodt.

---

💅 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

[build] [--name PROJECT_NAME] [--version RELEASE_VERSION]
[--date RELEASE_DATE] [--draft] [--yes] [--keep]

okay so this is the big one. it discovers all the news fragments in FRAGMENTS_DIR, and collates them. it renders them as a news document for project PROJECT_NAME released on RELEASE_DATE as version RELEASE_VERSION. then, it appends the generated news document to the configured news file, uses Git to stage the resulting file, and finally prompts the user for whether to delete the news fragment files. 🔥

(or, if --draft is specified: it emits the news file text to the standard error stream, and does not change any files. tasteful.)

if --yes is specified, it omits the prompt and assumes "yes" to delete news fragment files. if --keep is specified, it omits the prompt and assumes "no" to delete news fragment files. simple as. ✨

💜 create

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

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. detective mode, lowkey. 🔍

---

😭 REPORTING BUGS

please report any bugs using the Towncrier project issue tracker. we're listening, we promise 🫶

---

👑 COPYRIGHT

this manual page is Copyright © 2021–2024 Ben Finney and Sérgio de Almeida Cipriano Junior, and is freely available to anyone under certain conditions. see the source document for details. ⚖️

---

💖 SEE ALSO

the Towncrier project upstream home page. go say hi 🌸

---

not me writing the whole thing and then still needing you to actually read the docs, iykyk 💀

---

and that's the whole page, bestie — towncrier, rendered on 2022-04-26, from the TOWNCRIER(1) source. slay, ate, no cap ✨💅🦋