Commands

scriv create

$ scriv create --help
Usage: scriv create [OPTIONS]

  Create a new scriv 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 ReStructured Text 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 fragments and produce a combined entry in the CHANGELOG file.

Options:
  --add / --no-add     'git add' the updated changelog file.
  --edit / --no-edit   Open the changelog file in your text editor.
  --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 from the version setting) and the current date.

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.