Configuration

body

type: BodyConfig | optional

Options to customize the body prompt

changeFormat

type: string | optional | template type: Change

Template used to generate change lines in version files and changelog. Custom values are created through custom choices and can be accessible through the Custom argument.

Example

changeFormat: '* [#{{.Custom.Issue}}](https://github.com/miniscruff/changie/issues/{{.Custom.Issue}}) {{.Body}}'

changelogPath

type: string | optional

Filepath for the generated changelog file. Relative to project root. ChangelogPath is not required if you are using projects.

Example

changelogPath: CHANGELOG.md

changesDir

type: string | required

Directory for change files, header file and unreleased files. Relative to project root.

Example

changesDir: .changes

componentFormat

type: string | optional | template type: ComponentData

Template used to generate component headers. If format is empty no header will be included. If components are disabled, the format is unused.

components

type: []string | optional

Components are an additional layer of organization suited for projects that want to split change fragments by an area or tag of the project. An example could be splitting your changelogs by packages for a monorepo. If no components are listed then the component prompt will be skipped and no component header included. By default no components are configured.

Example

components:
- API
- CLI
- Frontend

custom

type: []Custom | optional

Custom choices allow you to ask for additional information when creating a new change fragment. These custom choices are included in the change custom value.

Example

# github issue and author name
custom:
- key: Issue
  type: int
  minInt: 1
- key: Author
  label: GitHub Name
  type: string
  minLength: 3

envPrefix

type: string | optional

Prefix of environment variables to load for templates. The prefix is removed from resulting key map.

Example

# if we have an environment variable like so:
# export CHANGIE_PROJECT=changie
# we can use that in our templates if we set the prefix
envPrefix: "CHANGIE_"
versionFormat: "New release for {{.Env.PROJECT}}"

footerFormat

type: string | optional | template type: BatchData

Template used to generate a version footer.

Example

# config yaml
custom:
- key: Author
  type: string
  minLength: 3
footerFormat: |
  ### Contributors
  {{- range (customs .Changes "Author" | uniq) }}
  * [{{.}}](https://github.com/{{.}})
  {{- end}}

fragmentFileFormat

type: string | optional | template type: Change

Customize the file name generated for new fragments. The default uses the component and kind only if configured for your project. The file is placed in the unreleased directory, so the full path is:

{{.ChangesDir}}/{{.UnreleasedDir}}/{{.FragmentFileFormat}}.yaml

Example

fragmentFileFormat: "{{.Kind}}-{{.Custom.Issue}}"

headerFormat

type: string | optional | template type: BatchData

Template used to generate a version header.

headerPath

type: string | optional

Header content included at the top of the merged changelog. A default header file is created when initializing that follows "Keep a Changelog".

Filepath for your changelog header file. Relative to changesDir.

Example

headerPath: header.tpl.md

kindFormat

type: string | optional | template type: KindData

Template used to generate kind headers. If format is empty no header will be included. If kinds are disabled, the format is unused.

kinds

type: []KindConfig | optional

Kinds are another optional layer of changelogs suited for specifying what type of change we are making. If configured, developers will be prompted to select a kind.

The default list comes from keep a changelog and includes; added, changed, removed, deprecated, fixed, and security.

Example

kinds:
- label: Added
- label: Changed
- label: Deprecated
- label: Removed
- label: Fixed
- label: Security

newlines

type: NewlinesConfig | optional

Newline options allow you to add extra lines between elements written by changie.

post

type: []PostProcessConfig | optional

Post process options when saving a new change fragment.

Example

# build a GitHub link from author choice
post:
- key: AuthorLink
  value: "https://github.com/{{.Custom.Author}}
changeFormat: "* {{.Body}} by [{{.Custom.Author}}]({{.Custom.AuthorLink}})"

projects

type: []ProjectConfig | optional

Projects allow you to specify child projects as part of a monorepo setup.

Example

projects:
  - label: UI
    key: ui
    changelog: ui/CHANGELOG.md
  - label: Email Sender
    key: email_sender
    changelog: services/email/CHANGELOG.md

projectsVersionSeparator

type: string | optional

ProjectsVersionSeparator is used to determine the final version when using projects. The result is: project key + projectVersionSeparator + latest/next version.

Example

projectsVersionSeparator: "_"

replacements

type: []Replacement | optional

Replacements to run when merging a changelog.

Example

# nodejs package.json replacement
replacements:
- path: package.json
  find: '  "version": ".*",'
  replace: '  "version": "{{.VersionNoPrefix}}",'

unreleasedDir

type: string | required

Directory for all unreleased change files. Relative to changesDir.

Example

unreleasedDir: unreleased

versionExt

type: string | required

File extension for generated version files. This should probably match your changelog path file. Must not include the period.

Example

# for markdown changelogs
versionExt: md

versionFooterPath

type: string | optional

Filepath for your version footer file relative to unreleasedDir. It is also possible to use the '--footer-path' parameter when using the batch command.

versionFormat

type: string | optional | template type: BatchData

Template used to generate version headers.

versionHeaderPath

type: string | optional

Filepath for your version header file relative to unreleasedDir. It is also possible to use the '--header-path' parameter when using the batch command.

---

BatchData

Batch data is a common structure for templates when generating change fragments.

Changes

type: []Change | optional

Changes included in the batch

Env

type: map [ string ] string | optional

Env vars configured by the system. See envPrefix for configuration.

Major

type: int | optional

Major value of the version

Metadata

type: string | optional

Metadata value of the version

Minor

type: int | optional

Minor value of the version

Patch

type: int | optional

Patch value of the version

Prerelease

type: string | optional

Prerelease value of the version

PreviousVersion

type: string | optional

Previous released version

Time

type: Time | optional

Time of the change

Version

type: string | optional

Version of the change, will include "v" prefix if used

VersionNoPrefix

type: string | optional

Version of the release without the "v" prefix if used

---

BodyConfig

Body config allows you to customize the default body prompt

maxLength

type: int64 | optional

Max length specifies the maximum body length

minLength

type: int64 | optional

Min length specifies the minimum body length

block

type: bool | optional

Block allows multiline text inputs for body messages

---

Change

Change represents an atomic change to a project.

body

type: string | optional

Body message of our change, if one was provided.

component

type: string | optional

Component of our change, if one was provided.

custom

type: map [ string ] string | optional

Custom values corresponding to our options where each key-value pair is the key of the custom option and value the one provided in the change.

Example

custom:
- key: Issue
  type: int
changeFormat: "{{.Body}} from #{{.Custom.Issue}}"

env

type: map [ string ] string | optional

Env vars configured by the system. This is not written in change fragments but instead loaded by the system and accessible for templates. For example if you want to use an env var in change format you can, but env vars configured when executing changie new will not be saved. See envPrefix for configuration.

filename

type: string | optional

Filename the change was saved to.

kind

type: string | optional

Kind key of our change, if one was provided. Backwards compatible alias for KindKey.

kindKey

type: string | optional

Kind key of our change, if one was provided.

kindLabel

type: string | optional

Kind label of our change, if one was provided.

project

type: string | optional

Project of our change, if one was provided.

time

type: Time | required

When our change was made.

---

ComponentData

Component data stores data related to writing component headers.

Component

type: string | required

Name of the component

Env

type: map [ string ] string | optional

Env vars configured by the system. See envPrefix for configuration.

---

Custom

Custom defines a custom choice that is asked when using 'changie new'. The result is an additional custom value in the change file for including in the change line.

A simple one could be the issue number or authors github name.

Example

- key: Author
    label: GitHub Name
    type: string
    minLength: 3

enumOptions

type: []string | optional

When using the enum type, you must also specify what possible options to allow. Users will be given a selection list to select the value they want.

key

type: string | required

Value used as the key in the custom map for the change format. This should only contain alpha numeric characters, usually starting with a capital.

Example

key: Issue

label

type: string | optional

Description used in the prompt when asking for the choice. If empty key is used instead.

Example

label: GitHub Username

maxInt

type: int64 | optional

If specified the input value must be less than or equal to maxInt.

maxLength

type: int64 | optional

If specified string input must be no more than this long

minInt

type: int64 | optional

If specified the input value must be greater than or equal to minInt.

minLength

type: int64 | optional

If specified the string input must be at least this long

optional

type: bool | optional

If true, an empty value will not fail validation. The optional check is handled before min so you can specify that the value is optional but if it is used it must have a minimum length or value depending on type.

When building templates that allow for optional values you can compare the custom choice to an empty string to check for a value or empty.

Example

custom:
- key: TicketNumber
  type: int
  optional: true
changeFormat: >-
{{- if not (eq .Custom.TicketNumber "")}}
PROJ-{{.Custom.TicketNumber}}
{{- end}}
{{.Body}}

type

type: CustomType | required

Specifies the type of choice which changes the prompt.

value	description	options
string	Freeform text	minLength and maxLength
block	Multiline text	minLength and maxLength
int	Whole numbers	minInt and maxInt
enum	Limited set of strings	enumOptions is used to specify values

---

CustomType

CustomType determines the possible custom choice types. Current values are: string, block, int and enum.

---

KindConfig

Kind config allows you to customize the options depending on what kind was selected.

additionalChoices

type: []Custom | optional

Additional choices allows adding choices per kind

auto

type: string | optional

Auto determines what value to bump when using batch auto or next auto. Possible values are major, minor, patch or none and the highest one is used if multiple changes are found. none will not bump the version. Only none changes is not a valid bump and will fail to batch.

Example

auto: minor

changeFormat

type: string | optional

Change format will override the root change format when building changes specific to this kind.

Example

changeFormat: 'Breaking: {{.Custom.Body}}

format

type: string | optional

Format will override the root kind format when building the kind header.

Example

format: '### {{.Kind}} **Breaking Changes**'

key

type: string | optional

Key is the value used for lookups and file names for kinds. By default it will use label if no key is provided.

Example

key: feature

label

type: string | required

Label is the value used in the prompt when selecting a kind.

Example

label: Feature

post

type: []PostProcessConfig | optional

Post process options when saving a new change fragment specific to this kind.

skipBody

type: bool | optional

Skip body allows skipping the parent body prompt.

skipGlobalChoices

type: bool | optional

Skip global choices allows skipping the parent choices options.

skipGlobalPost

type: bool | optional

Skip global post allows skipping the parent post processing.

---

KindData

Kind data stores data related to writing kind headers.

Env

type: map [ string ] string | optional

Env vars configured by the system. See envPrefix for configuration.

Kind

type: string | required

Name of the kind

---

NewlinesConfig

Configuration options for newlines before and after different elements.

afterChange

type: int | optional

Add newlines after change fragment

afterChangelogHeader

type: int | optional

Add newlines after the header file in the merged changelog

afterChangelogVersion

type: int | optional

Add newlines after adding a version to the changelog

afterComponent

type: int | optional

Add newlines after component

afterFooterFile

type: int | optional

Add newlines after footer file

afterFooter

type: int | optional

Add newlines after footer template

afterHeaderFile

type: int | optional

Add newlines after header file

afterHeaderTemplate

type: int | optional

Add newlines after header template

afterKind

type: int | optional

Add newlines after kind

afterVersion

type: int | optional

Add newlines after version

beforeChange

type: int | optional

Add newlines before change fragment

beforeChangelogVersion

type: int | optional

Add newlines before adding a version to the changelog

beforeComponent

type: int | optional

Add newlines before component

beforeFooterFile

type: int | optional

Add newlines before footer file

beforeFooterTemplate

type: int | optional

Add newlines before footer template

beforeHeaderFile

type: int | optional

Add newlines before header file

beforeHeaderTemplate

type: int | optional

Add newlines before header template

beforeKind

type: int | optional

Add newlines before kind

beforeVersion

type: int | optional

Add newlines before version

endOfVersion

type: int | optional

Add newlines at the end of the version file

---

PostProcessConfig

PostProcessConfig allows adding additional custom values to a change fragment after all the other inputs are complete. This will add additional keys to the custom section of the fragment. If the key already exists as part of a custom choice the value will be overridden.

key

type: string | optional

Key to save the custom value with

value

type: string | optional | template type: Change

Value of the custom value as a go template

---

ProjectConfig

ProjectConfig extends changie to support multiple changelog files for different projects inside one repository.

Example

projects:
  - label: UI
    key: ui
    changelog: ui/CHANGELOG.md
  - label: Email Sender
    key: email_sender
    changelog: services/email/CHANGELOG.md

changelog

type: string | optional

ChangelogPath is the path to the changelog for this project.

Example

changelog: src/frontend/CHANGELOG.md

key

type: string | optional

Key is the value used for unreleased and version output paths.

Example

key: frontend

label

type: string | optional

Label is the value used in the prompt when selecting a project.

Example

label: Frontend

replacements

type: []Replacement | optional

Replacements to run when merging a changelog for our project.

Example

# nodejs package.json replacement
replacements:
- path: ui/package.json
  find: '  "version": ".*",'
  replace: '  "version": "{{.VersionNoPrefix}}",'

---

ReplaceData

Template data used for replacing version values.

Major

type: int | optional

Major value of the version

Metadata

type: string | optional

Metadata value of the version

Minor

type: int | optional

Minor value of the version

Patch

type: int | optional

Patch value of the version

Prerelease

type: string | optional

Prerelease value of the version

Version

type: string | optional

Version of the release, will include "v" prefix if used

VersionNoPrefix

type: string | optional

Version of the release without the "v" prefix if used

---

Replacement

Replacement handles the finding and replacing values when merging the changelog. This can be used to keep version strings in-sync when preparing a release without having to manually update them. This works similar to the find and replace from IDE tools but also includes the file path of the file.

Example

# NodeJS package.json
replacements:
  - path: package.json
    find: '  "version": ".*",'
    replace: '  "version": "{{.VersionNoPrefix}}",'

find

type: string | required

Regular expression to search for in the file. Capture groups are supported and can be used in the replace value.

flags

type: string | optional

Optional regular expression mode flags. Defaults to the m flag for multiline such that ^ and $ will match the start and end of each line and not just the start and end of the string.

For more details on regular expression flags in Go view the regexp/syntax.

path

type: string | required

Path of the file to find and replace in. Also supports Go filepath globs.

Example

# Will match any .json file in the current directory
replacements:
  - path: *.json
    find: '  "version": ".*",'
    replace: '  "version": "{{.VersionNoPrefix}}",'

replace

type: string | required | template type: ReplaceData

Template string to replace the line with.

---

TemplateCache

Template cache handles running all the templates for change fragments. Included options include the default go template and sprig functions for formatting. Additionally, custom template functions are listed below for working with changes.

Example

format: |
### Contributors
{{- range (customs .Changes "Author" | uniq) }}
* [{{.}}](https://github.com/{{.}})
{{- end}}

bodies

Bodies will return all the bodies from the provided changes.

Example

format: "{{ bodies .Changes }} bodies"

components

Components will return all the components from the provided changes.

Example

format: "{{components .Changes }} components"

count

Count will return the number of occurrences of a string in a slice.

Example

format: "{{ kinds .Changes | count \"added\" }} kinds"

customs

Customs will return all the values from the custom map by a key. If a key is missing from a change, it will be an empty string.

Example

format: "{{ customs .Changes \"Author\" }} authors"

kinds

Kinds will return all the kindsi from the provided changes.

Example

format: "{{ kinds .Changes }} kinds"

times

Times will return all the times from the provided changes.

Example

format: "{{ times .Changes }} times"

---