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
• changelog.d/scriv.ini

In any of these files, scriv will read settings from a section named either [scriv] or [tool.scriv].

If the [toml] extra is installed, then scriv will also read settings from pyproject.toml, in the [tool.scriv] section.

Settings Syntax

Settings use the usual “.ini” 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. The file name is relative to the fragment directory (changelog.d), or is the name of a built-in file provided by scriv:

• 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

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