Configuration

Most of the options that let you configure Braulio’s behavior, are available through the command line tool or a Config file with a few exceptions.

The options provided through the CLI have precedence over those specified in the configuration file.

Config file

Currently, only the file setup.cfg can be used to configure the application. All the options must be under the section [braulio]. There is a special section: [braulio.stages] which is used solely to configure the stages of the project.

A config file would look like this:

[braulio]
commit = False
Tag = False
confirm = True

[braulio.stages]
alpha = {major}.{minor}.{patch}a{n}
beta  = {major}.{minor}.{patch}b{n}
final = {major}.{minor}.{patch}

Options

Next, we have a table with all the options for the release subcommand. If an option is not available through an input method, the cell will be empty.

CLI config file Descriptions
–major   Major version bump.
–minor   Minor version bump.
–patch   Patch version bump.
–bump   Bump to a given version arbitrarily.
–commit / –no-commit commit Enable/disable release commit
–message message Customizes commit message.
–tag / –no-tag tag Enable/disable version tagging.
–changelog-file changelog_file Specify the changelog file.
–label-position label_position Where the label is located in the commit message.
–label-pattern label_pattern Pattern to identify labels in commit messages.
–tag-pattern tag_pattern Pattern for Git tags that represent versions
–current-version current_version Manually specify the curren version.
–stage   Select a stage where to bump
–merge-pre   Merge pre-release changelogs.
-y confirm Don’t ask for confirmation
files (argument) files Don’t ask for confirmation
–help   Show this message and exit.

bump

CLI Config File Default
--bump    

Takes a valid version string and bump the project version.

major

CLI Config File Default
--major    

Perform a major release bumping the major part of the current version.

minor

CLI Config File Default
--minor    

Perform a major release bumping the major part of the current version.

patch

CLI Config File Default
--patch    

Perform a major release bumping the major part of the current version.

current_version

CLI Config File Default
--current-version current_version  

Determines the current version of the project. If this option is present in the configuration file, it will be updated on each new release.

tag_pattern

CLI Config File Default
--tag--patern tag_pattern v{version}

Parse and render Git tag names.

It is used to find Git tags that mark a release, as well as to render tag name for new releases.

The pattern string must have the placeholder {version}, which determines where a version string is located in a tag name.

Examples:

The tag pattern version{version} would match version1.0.0. The tag pattern release-{version} would match release-1.0.0.

As stated above, any time a new version is released, the same pattern will be used to render the new Git tag name.

label_position

CLI Config File Default
--label-position label_position footer

Determines where the commit analyzer must look for commit labels. The available values are header and footer.

label_pattern

CLI Config File Default
--label-pattern label_pattern !{type}:{scope}

The format of label inside commit messages. This uses the next placeholders to extract metadata information.:

  • {type}: The type of the commit (fix, feat, chore, etc). Required.
  • {scope}: The scope where a commit belong. Optional.
  • {subject}: The subject of the message. Required when the label is located in the header.

commit

CLI Config File Default
--commit/--no-commit commit True

Enable/disable commit of the changes produced by a version bump. If this is enabled, it will commit only the changelog file and the files provided through the files option.

tag

CLI Config File Default
--tag/--no-tag tag True

Enable/disable a release tag after a version bump.

message

CLI Config File Default
--message message “Release version {new_version}”

If the release commit is enabled, this is used for the message.

This is a template string containing replacement fields. The available fields are {new_version} and {current_version}. {new_version} is mandatory, while {current_version} is optional.

changelog_file

CLI Config File Default
--changelog-file changelog_file  

Path to the changelog file.

files

CLI Config File Default
files (argument) files  

List of files to update with a new version string.

Note that in the case of the CLI this is a positional argument and must be place at the end of the command.

$ brau release --bump=4.0.0 file1.py file2.py folder/file3.py

Each file path must be separated by an space.

Through a configuration file, each file path must be in a new line like the example belog.

[braulio]
files =
    file1.py
    file2.py
    folder/file3.py

stage

CLI Config File Default
--stage    

Determines in what stage a new release must be made.

stages

CLI Config File Default
  [braulio.stages] final = {major}.{minor}.{patch}

Only available through a configuration file, this determines the stages of a project development cycle.

By default the only stage defined is final, which must always present:

[braulio.stages]
final = {major}.{minor}.{patch}

For more information, read the Setting up pre-releases section.