Commands¶
scriv create¶
$ scriv create --help
Usage: scriv create [OPTIONS]
Create a new changelog fragment.
Options:
--add / --no-add 'git add' the created file.
--edit / --no-edit Open the created file in your text editor.
-v, --verbosity LVL Either CRITICAL, ERROR, WARNING, INFO or DEBUG
--help Show this message and exit.
The create command creates new fragments.
File creation¶
Fragments are created in the changelog.d directory. The name of the directory can be configured with the fragment_directory setting.
The file name starts with the current date and time, so that entries can later be collected in chronological order. To help make the files understandable, the file name also includes the creator’s git name, and the branch name you are working on. “Main” branch names aren’t included, to cut down on uninteresting noise. The branch names considered uninteresting are settable with the main_branches setting.
The initial contents of the fragment file are populated from the new_fragment_template template. The format is either reStructuredText or Markdown, selectable with the format setting.
The default new fragment templates create empty sections for each category. Uncomment the one you want to use, and create a bullet for the changes you are describing. If you need a different template for new fragments, you can create a Jinja template and name it in the new_fragment_template setting.
Editing¶
If --edit
is provided, or if scriv.create.edit
is set to true in your
git settings, scriv will launch an editor for you to edit
the new fragment. Scriv uses the same editor that git launches for commit
messages.
The format of the fragment should be sections for the categories, with bullets for each change. The file is re-parsed when it is collected, so the specifics of things like header underlines don’t have to match the changelog file, that will be adjusted later.
Once you save and exit the editor, scriv will continue working on the file. If the file is empty because you removed all of the non-comment content, scriv will stop.
Adding¶
If --add
is provided, or if scriv.create.add
is set to true in your
git settings, scriv will “git add” the new file so that
it is ready to commit.
scriv collect¶
$ scriv collect --help
Usage: scriv collect [OPTIONS]
Collect and combine fragments into the changelog.
Options:
--add / --no-add 'git add' the updated changelog file and removed
fragments.
--edit / --no-edit Open the changelog file in your text editor.
--title TEXT The title text to use for this entry.
--keep Keep the fragment files that are collected.
--version TEXT The version name to use for this entry.
-v, --verbosity LVL Either CRITICAL, ERROR, WARNING, INFO or DEBUG
--help Show this message and exit.
The collect command aggregates all the current fragments into the changelog file.
Entry Creation¶
All of the .rst or .md files in the fragment directory are read, parsed, and re-assembled into a changelog entry. The entry’s title is determined by the entry_title_template setting. The default uses the version string (if one is specified in the version setting) and the current date.
Instead of using the title template, you can provide an exact title to use for
the new entry with the --title
option.
The output file is specified by the output_file setting. Scriv looks in the file for a special marker (usually in a comment) to determine where to insert the new entry. The marker is “scriv-insert-here”, but can be changed with the insert_marker setting. Using a marker like this, you can have your changelog be just part of a larger README file. If there is no marker in the file, the new entry is inserted at the top of the file.
Fragment Deletion¶
The fragment files that are read will be deleted, because they are no longer
needed. If you would prefer to keep the fragment files, use the --keep
option.
Editing¶
If --edit
is provided, or if scriv.collect.edit
is set to true in your
git settings, scriv will launch an editor for you to edit
the changelog file. Mostly you shouldn’t need to do this, but you might want
to make some tweaks. Scriv uses the same editor that git launches for commit
messages.
Adding¶
If --add
is provided, or if scriv.collect.add
is set to true in your
git settings, scriv will “git add” the updates to the
changelog file, and the fragment file deletions, so that they are ready to
commit.
scriv github-release¶
$ scriv github-release --help
Usage: scriv github-release [OPTIONS]
Create GitHub releases from the changelog.
Only the most recent changelog entry is used, unless --all is provided.
Options:
--all Use all of the changelog entries.
-v, --verbosity LVL Either CRITICAL, ERROR, WARNING, INFO or DEBUG
--help Show this message and exit.
The github-release
command reads the changelog file, parses it into
entries, and then creates or updates GitHub releases to match. Only the most
recent changelog entry is used, unless --all
is provided.
An entry must have a version number in the title, and that version number must
correspond to a git tag. For example, this changelog entry with the title
v1.2.3 -- 2022-04-06
will be processed and the version number will be
“v1.2.3”. If there’s a “v1.2.3” git tag, then the entry is a valid release.
If there’s no detectable version number in the header, or there isn’t a git
tag with the same number, then the entry can’t be created as a GitHub release.
This command is independent of the other commands. It can be used with a hand-edited changelog file that wasn’t created with scriv.
For writing to GitHub, you need a GitHub personal access token, either stored in your .netrc file, or in the GITHUB_TOKEN environment variable.
If your changelog file is in reStructuredText format, you will need pandoc 2.11.2 or later installed for the command to work.