Configuration

The Bronto refactoring tool can be configured via a .brontorc file. By default a .brontorc file will be looked for in the current working directory from which the tool is run, looking in successive parent directories until a file by that name is found.

Alternatively, one can pass --config=/path/to/my/.brontorc to choose a configuration file explicitly.

If no .brontorc file is found or specified, bronto-refactor will behave as if there were an empty .brontorc file in the current working directory.

The .brontorc file uses the TOML file format with the following schema.

Fields

project-root

The root directory of the project. The project-root is used to resolve relative paths and to strip prefixes from file paths before matching them against files constraints. This is primarily used to ensure that edits to external libraries are not generated.

If specified as a relative path, project-root is resolved relative to the directory containing the .brontorc file.

If project-root is unspecified, bronto-refactor looks for a .git directory in the ancestors of the .brontorc file. If bronto-refactor cannot find a .git directory, then it uses the .brontorc directory.

files

An ordered list of FileConstraints defining the files for which the tool generates edits. Constraints are processed sequentially, meaning that the last matching constraint is the one used. Globs are matched against paths relative to the project-root. For example:

files = [
  { include = "**" },                   # Match all files
  { exclude = "private/**" },           # ... but not the private ones
  { exclude = "hidden/**" },            # ... or the hidden
  { include = "hidden/important/**" },  # ... unless they're important.
]

If unspecified, the default of

files = [
  { include = "**" },
]

will be assumed.

clang-format

An object of type ClangFormatSpec responsible for defining how clang-format is invoked on generated edits. Below are several examples:

# Use the GNU style
[clang-format]
executable = "path/to/clang-format"
style = "gnu"

# Use my special style
[clang-format.style]
path = "path/to/my/.clang-format"

# Lookup a .clang-format in an ancestor directory of each modified file,
# or use mozilla as a fallback.
[clang-format.style]
fallback = "mozilla"

clang-format.executable

A string representing the path of a clang-format executable to be used to do the formatting. If unspecified, formatting will still occur but with an unspecified clang-format implementation.

clang-format.style

Either, a string representing a named style built in to clang-format, or an object of type PathClangFormatStyle. The options available for a named style are "chromium", "gnu", "google", "llvm", "microsoft", "mozilla", and "webkit". If no style is provided, a default PathClangFormatStyle will be assumed.

clang-format.style.path

The location of YAML file used for formatting. If unspecified, for each modified file, a file named .clang-format will be searched for in successive ancestor directories of the file being modified until such a file is found. If no such file is found, the fallback style will be used.

clang-format.style.fallback

In the event that clang-format.style.path did not describe a valid YAML file, this is the builtin named style that will be used for formatting. If not provided, an unspecified default will be chosen.

Types

ClangFormatSpec

A ClangFormatSpec has two fields that control how clang-format is executed. Both are optional.

• executable: A string representing the path of a clang-format executable to be used to do the formatting. If unspecified, formatting will still occur but with an unspecified clang-format implementation.
• style: Either, a string representing a named style built in to clang-format, or an object of type PathClangFormatStyle. The options available for a named style are "chromium", "gnu", "google", "llvm", "microsoft", "mozilla", and "webkit". If no style is provided, a default PathClangFormatStyle will be assumed (as described in that section).

PathClangFormatStyle

An object representing a clang-format style specified via a YAML style file. This object has two fields which are both optional: path and fallback.

FileConstraint

A file constraint is an object that holds exactly one of the fields include or exclude. The field is a glob determining which files should be included or excluded (respectively) from the list of edited files.

Environment Variables

Configuration can also be provided through environment variables. Any configuration key can be overridden by setting an environment variable with the prefix BRONTO_CONFIG__ and using double underscores (__) as separators for nested keys. Environment variables are case-insensitive and have the highest priority for setting configuration.

For example:

• BRONTO_CONFIG__PROJECT_ROOT=/abs/path
• BRONTO_CONFIG__CLANG_FORMAT__STYLE=mozilla
• BRONTO_CONFIG__VARIABLE_HOISTING=trivial