Configuration

Scriv tries hard to be adaptable to your project’s needs. Many aspects of its behavior can be customized with a settings file.

Files read

Scriv will read settings from any of these files:

• setup.cfg
• tox.ini
• pyproject.toml
• scriv.ini in the fragment directory (“changelog.d/” by default)

In .ini or .cfg files, scriv will read settings from a section named either [scriv] or [tool.scriv].

A .toml file will only be read if the tomli or tomllib modules is available. You can install scriv with the [toml] extra to install tomli, or tomllib is available with Python 3.11 or greater. In a .toml file, settings will only be read from the [tool.scriv] section.

All of the possible files will be read, and settings will cascade. So for example, setup.cfg can set the fragment directory to “scriv.d”, then “scriv.d/scriv.ini” will be read.

Settings Syntax

Settings use the usual syntax, but with some extra features:

• A prefix of file: reads the setting from a file.
• A prefix of literal: reads a literal data from a source file.
• Value substitutions can make a setting depend on another setting.

File Prefix

A file: prefix means the setting value is a file name, and the actual setting value will be read from that file. If the file name has path separators, it is relative to the current directory. If it doesn’t have path separators, then it is either in the fragment directory (changelog.d by default), or one of the built-in provided templates.

Scriv provides two built-in templates:

• new_fragment.md.j2: The default Jinja template for new Markdown fragments:

  <!--
  A new scriv changelog fragment.
  
  Uncomment the section that is right (remove the HTML comment wrapper).
  -->
  
  {% for cat in config.categories -%}
  <!--
  ### {{ cat }}
  
  - A bullet item for the {{ cat }} category.
  
  -->
  {% endfor -%}
  

• new_fragment.rst.j2: The default Jinja template for new reStructuredText fragments:

  .. A new scriv changelog fragment.
  {% if config.categories -%}
  ..
  .. Uncomment the header that is right (remove the leading dots).
  ..
  {% for cat in config.categories -%}
  .. {{ cat }}
  .. {{ config.rst_header_chars[1] * (cat|length) }}
  ..
  .. - A bullet item for the {{ cat }} category.
  ..
  {% endfor -%}
  {% else %}
  - A bullet item for this fragment. EDIT ME!
  {% endif -%}
  

Literal Prefix

A literal: prefix means the setting value will be a literal string read from a source file. The setting provides a file name and value name separated by colons:

[scriv]
version = literal: myproj/__init__.py: __version__

In this case, the file myproj/__init__.py will be read, and the __version__ value will be found and used as the version setting.

Currently Python, TOML and YAML files are supported for literals, but other syntaxes can be supported in the future.

When using a TOML file, the value is specified using periods to separate the sections and key names:

[scriv]
version = literal: pyproject.toml: project.version

In a YAML file, use periods in the value name to access dictionary keys:

[scriv]
version = literal: galaxy.yaml: myproduct.versionString

Value Substitution

The chosen fragment format can be used in settings by referencing ${config:format} in the setting. For example, the default template for new fragments depends on the format because the default setting is:

new_fragment_template = file: new_fragment.${config:format}.j2

Settings

These are the specifics about all of the settings read from the configuration file.

categories

Categories to use as headings for changelog items. See Categories.

Default: Removed, Added, Changed, Deprecated, Fixed, Security

end_marker

A marker string indicating where in the changelog file the changelog ends.

Default: scriv-end-here

entry_title_template

The Jinja template to use for the entry heading text for changelog entries created by “scriv collect”.

Default: A combination of version (if specified) and date.

format

The format to use for fragments and for the output changelog file. Can be either “rst” or “md”.

Default: rst

fragment_directory

The directory for fragments. This directory must exist, it will not be created.

Default: changelog.d

ghrel_template

The template to use for GitHub releases created by the scriv github-release command.

The extracted Markdown text is available as {{body}}. You must include this to use the text from the changelog file. The version is available as {{version}}.

The data for the release is available in a {{release}} object, including {{release.prerelease}}. It’s a boolean, true if this is a pre-release version.

The scriv configuration is available in a {{config}} object.

Default: {{body}}

insert_marker

A marker string indicating where in the changelog file new entries should be inserted.

Default: scriv-insert-here

main_branches

The branch names considered uninteresting to use in new fragment file names.

Default: master, main, develop

md_header_level

A number: for Markdown changelog files, this is the heading level to use for the entry heading.

Default: 1

new_fragment_template

The Jinja template to use for new fragments.

Default: file: new_fragment.${config:format}.j2

output_file

The changelog file updated by “scriv collect”.

Default: CHANGELOG.${config:format}

rst_header_chars

Two characters: for reStructuredText changelog files, these are the two underline characters to use. The first is for the heading for each changelog entry, the second is for the category sections within the entry.

Default: =-

skip_fragments

A glob pattern for files in the fragment directory that should not be collected.

Default: README.*

version

The string to use as the version number in the next header created by scriv collect. Often, this will be a literal: directive, to get the version from a string in a source file.

Default: (empty)

Per-User Git Settings

Some aspects of scriv’s behavior are configurable for each user rather than for the project as a whole. These settings are read from git.

These settings determine whether the “scriv create” and “scriv collect” commands will launch an editor, and “git add” the result:

• scriv.create.edit
• scriv.create.add
• scriv.collect.edit
• scriv.collect.add

All of these are either “true” or “false”, and default to false. You can create these settings with git config commands, either in the current repo:

$ git config scriv.create.edit true

or globally for all of your repos:

$ git config --global scriv.create.edit true