The behaviour of ChangeLog can be customized by changing the configuration. All settings are optional and ChangeLog aims to use sensible default values for all of them.
Settings are loaded from a number of setting sources:
Settings are loaded in the above order and sources loaded later can override values for sources loaded before.
The default settings are embedded in the ChangeLog executable and apply, if no other source specifies a specific setting.
The default settings are defined in defaultSettings.json.
You can customize settings by placing them in a configuration file.
The configuration file is a JSON file and uses the same schema as defaultSettings.json.
A JSON Schema for the configuration file can be found at https://raw.githubusercontent.com/ap0llo/changelog/master/schemas/configuration/schema.json.
The schema provides auto-completion support when editing the configuration file in editors that support JSON Schema (e.g. Visual Studio Code).
The use of a configuration file is optional.
By default, ChangeLog will attempt to load settings from a file called changelog.settings.json in the root of the git repository a change log is being generated for.
Alternatively, you can specify the path of the configuration file using the configurationFilePath commandline parameter (see Commandline reference).
Settings will also be loaded from environment variables. This is especially useful for passing secrets (like GitHub access tokens) when running in CI environments.
The environment variables that will be loaded are listed below.
Some settings can also be overridden using commandline parameter. Commandline parameters are considered to be the "most specific" setting for an execution of ChangeLog and can override settings from all other sources.
Which commandline parameters override which setting is listed below.
Setting names in the following table are separated by : which denote keys and sub-keys the JSON configuration file.
For example setting key:subkey to value would need to be specified in the configuration file like this:
{
"key" : {
"subkey" : "value"
}
}- Scopes
- Footers
- Markdown Preset
- Tag Patterns
- Output Path
- Integration Provider
- GitHub Access Token
- GitLab Access Token
- Version Range
- Current Version
- Template Name
- Markdown Preset (Default Template)
- Entry Types
- Parser Mode
| Setting | changelog:scopes |
| Environment Variable | - |
| Commandline Parameter | - |
| Default value | Empty |
| Version Support | 0.1+ |
The Scopes setting configures how Conventional Commit scopes are display. By default, the scopes are included unchanged in the output. Using this setting, you can configure a scope's display name. When a display name is configured, it will be used in the output instead of the scope's name.
{
"changelog" : {
"scopes" : [
{ "name": "myScope", "displayName": "Scope Display Name" }
]
}
}| Setting | changelog:footers |
| Environment Variable | - |
| Commandline Parameter | - |
| Default value | Empty |
| Version Support | 0.1+ |
The Footers setting configures how Conventional Commit footers are displayed. By default, footers are included unchanged in the output. Using this setting, you can configure a footer's display name. When a display name is configured, it will be used in the output instead of the footer's name.
{
"changelog" : {
"footers" : [
{ "name": "see-also", "displayName": "See Also" }
]
}
}| Setting | changelog:markdown:preset |
| Environment Variable | CHANGELOG__MARKDOWN__PRESET |
| Commandline Parameter | - |
| Default value | default |
| Allowed values |
|
| Version Support | 0.1, Removed in version 0.2 |
The Markdown Preset setting can be used to customize the serialization of Markdown.
Supported values are:
default: Produces Markdown that should work in most environments, including GitHub and GitLabMkDocs: Produces Markdown optimized for being rendered by Python-Markdown and MkDocs
For details on the differences between the presets, see also Markdown Generator docs
{
"changelog" : {
"markdown" : {
"preset" : "MkDocs"
}
}
}| Setting | changelog:tagpatterns |
| Environment Variable | - |
| Commandline Parameter | - |
| Default value | [ "^(?<version>\d+\.\d+\.\d+.*)", "^v(?<version>\d+\.\d+\.\d+.*)" ] |
| Version Support | 0.1+ |
The Tag Patterns setting controls how versions are read from a git
repository's tags. The setting defines a list of regular expressions that
are used to extract the version from the tag name.
All regular expressions must define a version sub-expression which matches
the version. The matched value must be a valid
semantic version.
The default setting matches tag names that are semantic versions or
tags names that are semantic versions prefixed with v.
| Setting | changelog:outputPath |
| Environment Variable | CHANGELOG__OUTPUTPATH |
| Commandline Parameter | outputPath |
| Default value | changelog.md |
| Version Support | 0.1+ |
Specifies the output path for the generated change log.
When the value of the setting is a relative path, the path is interpreted to be relative to
- The repository root directory when setting the output path in the configuration file or through environment variables
- The current working directory when specifying the output path using
the
outputPathcommandline parameter
{
"changelog" : {
"outputPath" : "my-custom-output-path.md"
}
}| Setting | changelog:integrations:provider |
| Environment Variable | CHANGELOG__INTEGRATIONS__PROVIDER |
| Commandline Parameter | - |
| Default value | none |
| Allowed values |
|
| Version Support | 0.1+ |
Sets the Integration Provider to use. For details on see Integrations.
Enable the GitHub integration provider:
{
"changelog" : {
"integrations" :{
"provider" : "github"
}
}
}| Setting | changelog:integrations:github:accessToken |
| Environment Variable | CHANGELOG__INTEGRATIONS__GITHUB__ACCESSTOKEN |
| Commandline Parameter | githubAccessToken |
| Default value | - |
| Version Support | 0.1+ |
The GitHub Access Token setting configures the access token to use for accessing the GitHub API when the GitHub integration is enabled.
❌ While it is possible to set the access token in the configuration file you should use the command line parameter or environment variable options instead.
| Setting | changelog:integrations:gitlab:accessToken |
| Environment Variable | CHANGELOG__INTEGRATIONS__GITLAB__ACCESSTOKEN |
| Commandline Parameter | gitlabAccessToken |
| Default value | - |
| Version Support | 0.1+ |
The GitLab Access Token setting configures the access token to use for accessing the GitLab API when the GitLab integration is enabled.
❌ While it is possible to set the access token in the configuration file you should use the command line parameter or environment variable options instead.
| Setting | changelog:versionRange |
| Environment Variable | CHANGELOG__VERSIONRANGE |
| Commandline Parameter | versionRange |
| Default value | - |
| Version Support | 0.1+ |
By default, all versions are included in the change log. To limit the versions to include, you can specify a version range using this setting.
The value must be a valid NuGet Version Range
To only include versions newer than version 2.1 in the change log, use the
following version range:
{
"changelog" : {
"versionRange" : "[2.1, )"
}
}| Setting | changelog:currentVersion |
| Environment Variable | CHANGELOG__CURRENTVERSION |
| Commandline Parameter | currentVersion |
| Default value | - |
| Version Support | 0.1+ |
By default, versions are only read from a git repository's tags and only tagged versions are included in the change log. To include the currently checked out commit (the repository HEAD), you can specify the current version. When specified, the current version is included in the change log as well.
The value must be a valid semantic version.
| Setting | changelog:template:name |
| Environment Variable | CHANGELOG__TEMPLATE__NAME |
| Commandline Parameter | template |
| Default value | default |
| Allowed values |
|
| Version Support | 0.2+ |
Sets the template to use for generating the change log. For details see Templates.
{
"changelog" : {
"template" : {
"name": "default"
}
}
}| Setting | changelog:template:default:markdownPreset |
| Environment Variable | CHANGELOG__TEMPLATE__DEFAULT__MARKDOWNPRESET |
| Commandline Parameter | - |
| Default value | default |
| Allowed values |
|
| Version Support | 0.2+ |
The Markdown Preset (Default Template) customizes serialization of Markdown for the default template (see Template Name setting).
Note: This setting has no effect when a template other than default is used.
Supported values are:
default: Produces Markdown that should work in most environments, including GitHub and GitLabMkDocs: Produces Markdown optimized for being rendered by Python-Markdown and MkDocs
For details on the differences between the presets, see also Markdown Generator docs.
{
"changelog" : {
"template" : {
"default": {
"markdownPreset" : "MkDocs"
}
}
}
}| Setting | changelog:entryTypes |
| Environment Variable | - |
| Commandline Parameter | - |
| Default value |
[
{ "type": "feat", "DisplayName": "New Features" },
{ "type": "fix", "DisplayName": "Bug Fixes" }
]
|
| Version Support | 0.2+ |
The "Entry Types" setting controls which types of change log entries are included in the change log.
By default, all entries of type feat and fix are included.
The DisplayName property controls, the title that is used for displaying entries of this type.
feat and fix, you need to include the default value in your configuration file.
It is not possible to just add additional types.
For example, to include all changes of type feat, fix and docs, you must include all three types in the configuration file (see Example).
ℹ️ Change log entries that contain breaking changes are always included, regardless of this setting or the entry type.
The following example shows how to include changes of type feat, fix and docs in the change log:
{
"changelog" :{
"entryTypes": [
{ "type": "feat", "DisplayName": "New Features" },
{ "type": "fix", "DisplayName": "Bug Fixes" },
{ "type": "docs", "DisplayName" : "Documenation changes"}
]
}
}| Setting | changelog:parser:mode |
| Environment Variable | - |
| Commandline Parameter | - |
| Default value |
Loose
|
| Allowed values |
|
| Version Support | 0.2+ |
The "Parser Mode" setting controls how lenient the commit message parser treats commit messages.
Available options are
Loose(default)Struct
For details, see Commit Message Parser
The following example sets the parser mode to strict:
{
"changelog" : {
"parser" : {
"mode": "strict"
}
}
}