Configuration

Configuration is normally read from //.config/mfgames-conventional-commit.json, where // means the Git root of a project. The configuration can also be supplied explicitly from the command line.

Command-line configuration

Use --config to provide a JSON configuration file:

mfgames-conventional-commit --config ./config/base.json version

The option is global and can be repeated. Files are merged in the order given, with later files overriding earlier values:

mfgames-conventional-commit \
  --config ./config/base.json \
  --config ./config/ci-overrides.json \
  version --all

When at least one --config path is supplied, those paths are authoritative and the repository configuration is not loaded automatically. When no --config is supplied, the tool loads .config/mfgames-conventional-commit.json from the discovered Git root. A missing repository configuration uses the built-in defaults.

Every merged configuration is validated before a command runs. Errors identify the invalid package or field, including malformed globs, empty tag prefixes, empty update scripts, and unknown JSON properties.

Schema

This system uses the schema to determine the version of the file. Right now, there is only a v0 version

{
    "$schema": "https://mfgames.com/mfgames-conventional-commit-rs/schemas/v0.json"
}

Package

The core of the configuration is how to deal with a single package. This is a specification that is used in multiple places, but generally looks like this:

{
    "tag_prefix": "v",
    "directories": { "include": ["."] },
    "files": { "include": ["**/*"] },
    "updates": [{ "script": "echo first task" }]
}

All of these properties are optional.

tag_prefix

The tag prefix is a prefix to any Git tag to determine the version. The default is “v” which would mean version 1.0.0 would have a Git tag of v1.0.0.

directories.include

This is used to determine what package a user is referencing to when they don't use --all or --package package-name in the parameters. This is relative to the project root. If multiple packages match a given path, then there will be an error. The same if no package matches the current working directory.

files.include

This is a list of globs (uses ** for any matching across directories and * for a single file) that the system uses to determine if a file is in a specific module. This can overlap with other packages and it can contain multiple matches.

The glob was used so you could only match even specific files (**/*.rs) if you want.

files.exclude

This is the list of exclusions to the files.include configuration above.

updates

Updates is a list of commands to use with the update command. Every property except script is optional and each entry looks like this:

{
    "always_run": false,
    "script": "echo this is a script"
}

update.script

The shell script to run on the update. The following will be substituted with dynamic values.

• {package} will be replaced with the name of the package
• {flatten_version} will be replaced with the flattened version
• {detail_version} will be replaced with the detail version

update.always_run

If this is true, then the update will run every time with the mfgames-conventional-commit update command is run for that package. This defaults to false.

Substitutions

In all of these properties, {package} will be substituted with the name of the package (see below). So, { "directories": { "include": [ "src/{package}/**/*" ]}} will replace {package} with the name of the package.

Packages

The packages property is a dictionary/map of package names to package details above.

{
  "$schema": "https://mfgames.com/mfgames-conventional-commit-rs/schemas/v0.json",
  "packages": {
    {
      "MfGames.IO": {
      "tag_prefix": "{package}-",
      "directories": { "include": ["src/{package}"] },
      "files": { "include": ["src/{package}/**/*"] }
    },
      "MfGames.Nitride": {
      "tag_prefix": "{package}-",
      "directories": { "include": ["src/{package}"] },
      "files": { "include": ["src/{package}/**/*"] }
    }
  }
}

Defaults

If you notice that the two packages in the above example have the same values (they originally didn't before {package} became a thing). The defaults property can be used to set them and simplify the configuration.

{
    "$schema": "https://mfgames.com/mfgames-conventional-commit-rs/schemas/v0.json",
    "defaults": {
        "tag_prefix": "{package}-",
        "directories": { "include": ["src/{package}"] },
        "files": { "include": ["src/{package}/**/*"] }
    },
    "packages": {
        "MfGames.IO": {},
        "MfGames.Nitride": {}
    }
}

If a package contains a value, it will override the defaults.

{
    "$schema": "https://mfgames.com/mfgames-conventional-commit-rs/schemas/v0.json",
    "defaults": {
        "tag_prefix": "{package}-",
        "directories": { "include": ["src/{package}"] },
        "files": { "include": ["src/{package}/**/*"] }
    },
    "packages": {
        "MfGames.IO": { "tag_prefix": "mfgames-io-" },
        "MfGames.Nitride": { "tag_prefix": "mfgames-nitride-" }
    }
}

Missing Defaults

If there are no defaults, the following is used:

{
    "tag_prefix": "v",
    "directories": { "include": "." },
    "files": { "include": "**/*" }
}

Missing Entries

If the configuration file is missing, then the following is used:

{
    "$schema": "https://mfgames.com/mfgames-conventional-commit-rs/schemas/v0.json",
    "defaults": {
        "tag_prefix": "v",
        "directories": { "include": "." },
        "files": { "include": "**/*" }
    },
    "packages": {
        "default": {}
    }
}