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.

FieldsCopy Anchor Link

project-rootCopy Anchor Link

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, it is resolved relative to the directory containing the .brontorc file.

If unspecified, bronto-refactor looks for a .git directory in the ancestors of the .brontorc file. If it cannot find one, it uses the .brontorc directory. If no .brontorc file is used, such as when none is found or --config /dev/null is passed explicitly, the current working directory takes the place of the .brontorc directory in this search.

filesCopy Anchor Link

An ordered list of FileConstraints defining the files for which the tool generates edits. Constraints are processed sequentially, so the last matching constraint is the one used. Globs are matched against paths relative to the project root. A glob written as an absolute path is matched against the absolute path instead.

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

If unspecified, files = [{ include = "**" }] is assumed.

clang-formatCopy Anchor Link

A ClangFormatSpec defining how clang-format is invoked on generated edits.

clang-format.executableCopy Anchor Link

The path of a clang-format executable used to do the formatting. If unspecified, formatting still occurs but with an unspecified clang-format implementation. If specified but the executable cannot be run, loading the configuration fails rather than falling back.

clang-format.styleCopy Anchor Link

Either a string naming a style built in to clang-format, or a PathClangFormatStyle object. If no style is provided, a default PathClangFormatStyle is assumed. For a named style, one of the following strings is used.

The available values are "chromium", "gnu", "google", "llvm", "microsoft", "mozilla", and "webkit".

clang-format.style.pathCopy Anchor Link

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

clang-format.style.fallbackCopy Anchor Link

In the event that path did not describe a valid YAML file, this is the builtin named style used for formatting. If not provided, "google" is used.

The available values are "chromium", "gnu", "google", "llvm", "microsoft", "mozilla", and "webkit".

compilationCopy Anchor Link

Where to find a compilation database when none was named on the command line. If not present, one must be supplied on the command line.

compilation.manualCopy Anchor Link

Uses a compilation database that is maintained outside of Bronto. Bronto reads it but never regenerates it.

compilation.manual.pathCopy Anchor Link

The location of the compilation database, relative to the project root. If unspecified, defaults to "compile_commands.json".

compilation.bazelCopy Anchor Link

Generates the compilation database by running a bazel target with bazel run.

compilation.bazel.targetCopy Anchor Link

The bazel target which generates the compile_commands.json file. If left unspecified, defaults to "//:refresh_compile_commands"

compilation.bazel.argumentsCopy Anchor Link

Additional arguments to be passed when running the target to generate a compile_commands.json file.

compilation.cmakeCopy Anchor Link

Generates the compilation database by configuring a cmake build.

compilation.cmake.build-directoryCopy Anchor Link

The directory cmake configures into, which is also where it writes the compilation database. If unspecified, defaults to "build" in the project root.

compilation.commandCopy Anchor Link

Generates the compilation database by running an arbitrary command.

compilation.command.commandCopy Anchor Link

The program to run followed by its arguments.

compilation.command.outputCopy Anchor Link

The location, relative to the project root, of the compilation database that the command writes.

TypesCopy Anchor Link

FileConstraintCopy Anchor Link

An object holding exactly one of the fields include or exclude. The field is a glob determining which files are included in, or excluded from, the list of edited files.

• include: Items matching this glob are included.
• exclude: Items matching this glob are excluded.

ClangFormatSpecCopy Anchor Link

Controls how clang-format is invoked on generated edits. Both fields are optional.

# 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"

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

PathClangFormatStyleCopy Anchor Link

An object representing a clang-format style specified through a YAML style file. Both path and fallback are optional.

CompileCommandsGeneratorCopy Anchor Link

An object holding exactly one of the fields manual, bazel, cmake, or command. The field selects how the compilation database is obtained.

• manual: Uses an existing compilation database, which is never regenerated.
• bazel: Generates the compilation database by running a bazel target.
• cmake: Generates the compilation database by configuring a cmake build.
• command: Generates the compilation database by running an arbitrary command.

Environment VariablesCopy Anchor Link

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