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.

The settings examples here show .ini syntax. If you are using a pyproject.toml file for settings, you will need to adjust for TOML syntax. This .ini example:

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

would become:

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

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.

• A prefix of command: runs the command and uses the output as the setting.

• Value substitutions can make a setting depend on another setting.

These are each explained below:

File Prefix

A file: prefix means the setting is a file name or path, and the actual setting value will be read from that file. The file name will be searched for in three places: the fragment directory (changelog.d by default), the current directory, or one of a few built-in templates. If the first path component is . or .., then only the current directory is considered.

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, .cfg, TOML, YAML and Cabal files are supported for literals, but other syntaxes can be supported in the future.

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

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

For data from a YAML file, use periods in the value name to access dictionary keys:

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

When using a Cabal file, the version of the package can be accessed using:

[scriv]
version = literal: my-package.cabal: version

Commands

A command: prefix indicates that the setting is a shell command to run. The output will be used as the setting:

[scriv]
version = command: my_version_tool --next

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: {% if version %}{{ version }} — {% endif %}{{ date.strftime('%Y-%m-%d') }}

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.

Editing and Adding

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

User Nickname

Scriv includes your git or GitHub username in the file names of changelog fragments you create. If you don’t like the name it finds for you, you can set a name as the scriv.user_nick git setting.