bronto-refactor

This document contains the help content for the bronto-refactor command-line program.

bronto-refactor

Usage: bronto-refactor <COMMAND>

Subcommands:

• run — Runs the tool, generating edits in the .fossil format
• merge — Takes one or more .fossil files and merges them into a single file
• format — Converts edit-describing files between supported formats
• apply — Takes one or more .fossil files and applies the changes
• count — Reports the number of lines modifiable by the tool
• compiler-explorer — Version of the tool designed to interact with Compiler Explorer
• explain — Provides detailed information about error messages
• show — Display information from subcommands

bronto-refactor run

Runs the tool, generating edits in the .fossil format

Usage: bronto-refactor run [OPTIONS] --output <OUTPUT> [CLANG]...

Arguments:

• <CLANG> — Arguments to be passed to Clang. Exactly one of --db, --compile-flags, or clang arguments must be specified

Options:

• -o, --output <OUTPUT> — The location to write the .fossil file

• --config <CONFIG> — The location of a TOML configuration file controlling this tool

• --clang-path <CLANG_PATH> — The path to an instance of Clang installed on this machine from which we can detect the system include directories

• --compile-flags <COMPILE_FLAGS> — Location of a compile_flags.txt file specifying the translation unit to be processed. Exactly one of --db, --compile-flags, or clang arguments must be specified

• --db <DB> — Location of a compilations database JSON file. Exactly one of --db, --compile-flags, or clang arguments must be specified

• --include <INCLUDE> — Paths to header files to be included in every translation unit while processing. Typically this is used to include refactoring recipes that don't otherwise have a reasonable existing header to live in

• -j, --jobs <JOBS> — Number of threads on which to process input. If not provided, a reasonable default will be chosen. There are no guarantees about the specific value chosen, but a reasonable effort is made to detect an appropriate number for the host system

• --retain <RETAIN> [alias: filter] — A glob that filters translation units by the key in --db. Only entries in the compilation database that match the glob will be processed. Paths are considered relative to the project root, not necessarily the file and directory specified in the compilations database

  Default value: **

• --volatile — If true, processing will happen whether or not a cached result already exists. Caching is keyed on the compilation command, not the content of the files being processed

• --interactive — Indicates whether the tool is being run interactively. Defaults to true. Can use --no-interactive for false

  Default value: true

bronto-refactor merge

Takes one or more .fossil files and merges them into a single file

Usage: bronto-refactor merge [OPTIONS] --output <OUTPUT> <--manifest <MANIFEST>|FILES>

Arguments:

• <FILES> — A sequence of directories or .tar files containing output artifacts from prior tool executions

Options:

• --output <OUTPUT> — The location the merged .fossil file should be written to
• --config <CONFIG> — The location of a TOML configuration file controlling this tool
• --log-to-stderr
• --manifest <MANIFEST> — A file containing a newline-separated list of directories or .tar files containing output artifacts from prior tool executions

bronto-refactor format

Converts edit-describing files between supported formats

Usage: bronto-refactor format [OPTIONS] --input <INPUT> --output <OUTPUT>

Options:

• --config <CONFIG> — The location of a TOML configuration file controlling this tool

• -i, --input <INPUT> — The input file to be reformatted

• -o, --output <OUTPUT> — The location the output file should be written to

• -f, --from <FROM> — The format of the input file. If left unspeficied, the format will be inferred from the input file extension

  Possible values: fossil, patch

• -t, --to <TO> — The format into which the file should be converted. If left unspeficied, the format will be inferred from the output file extension

  Possible values: fossil, patch

• --log-to-stderr

• --on-missing-file <ON_MISSING_FILE> — The action to be taken if a file referenced in a record is not present

  Default value: error

  Possible values:

  • error: Stop processing entirely and return an error
  • discard: Skip processing the record containing the missing file, continuing with other records
  • partial: Process the record as if the missing file were not part of that record. Note that this can have unexpected behavior, as records are generally designed to be applied entirely, or not at all

bronto-refactor apply

Takes one or more .fossil files and applies the changes

Usage: bronto-refactor apply [OPTIONS] <--manifest <MANIFEST>|FILES>

Arguments:

• <FILES> — A sequence of directories or .tar files containing output artifacts from prior tool executions

Options:

• --config <CONFIG> — The location of a TOML configuration file controlling this tool

• --manifest <MANIFEST> — A file containing a newline-separated list of directories or .tar files containing output artifacts from prior tool executions

• --interactive — Indicates whether the tool is being run interactively. Defaults to true. Can use --no-interactive for false

  Default value: true

bronto-refactor count

Reports the number of lines modifiable by the tool

Usage: bronto-refactor count [OPTIONS] [CLANG]...

Arguments:

• <CLANG> — Arguments to be passed to Clang. Exactly one of --db, --compile-flags, or clang arguments must be specified

Options:

• --config <CONFIG> — The location of a TOML configuration file controlling this tool

• --depth <DEPTH> — Display line counts totals for directories up to this depth

  Default value: 1

• --clang-path <CLANG_PATH> — The path to an instance of Clang installed on this machine from which we can detect the system include directories

• --compile-flags <COMPILE_FLAGS> — Location of a compile_flags.txt file specifying the translation unit to be processed. Exactly one of --db, --compile-flags, or clang arguments must be specified

• --db <DB> — Location of a compilations database JSON file. Exactly one of --db, --compile-flags, or clang arguments must be specified

• --include <INCLUDE> — Paths to header files to be included in every translation unit while processing. Typically this is used to include refactoring recipes that don't otherwise have a reasonable existing header to live in

• -j, --jobs <JOBS> — Number of threads on which to process input. If not provided, a reasonable default will be chosen. There are no guarantees about the specific value chosen, but a reasonable effort is made to detect an appropriate number for the host system

• --retain <RETAIN> [alias: filter] — A glob that filters translation units by the key in --db. Only entries in the compilation database that match the glob will be processed. Paths are considered relative to the project root, not necessarily the file and directory specified in the compilations database

  Default value: **

• --volatile — If true, processing will happen whether or not a cached result already exists. Caching is keyed on the compilation command, not the content of the files being processed

• --interactive — Indicates whether the tool is being run interactively. Defaults to true. Can use --no-interactive for false

  Default value: true

bronto-refactor compiler-explorer

Version of the tool designed to interact with Compiler Explorer

Usage: bronto-refactor compiler-explorer [OPTIONS] <FILE> [CLANG]...

Arguments:

• <FILE> — The file whose modified contents should be displayed
• <CLANG> — Arguments to be passed to Clang

Options:

• -c, --clang-path <CLANG_PATH> — The path to an instance of Clang installed on this machine from which we can detect the system include directories

• --clang-format-path <CLANG_FORMAT_PATH> — The path to an instance of clang-format installed on this machine

• -o, --output <OUTPUT> — The location to write the modified file contents, or stdout if not provided

• --include <INCLUDE> — Paths to header files to be included in every translation unit while processing. Typically this is used to include refactoring recipes that don't otherwise have a reasonable existing header to live in

• --log-to-stderr

  Default value: true

• --config <CONFIG> — The location of a TOML configuration file controlling this tool

bronto-refactor explain

Provides detailed information about error messages

Usage: bronto-refactor explain [OPTIONS] [ERROR_CODE]

Arguments:

• <ERROR_CODE>

Options:

• --list

bronto-refactor show

Display information from subcommands

Usage: bronto-refactor show <COMMAND>

Subcommands:

• config — Runs the tool, printing the resolved brontorc to stdout
• output — Opens the TUI showing the results of a prior run or merge command

bronto-refactor show config

Runs the tool, printing the resolved brontorc to stdout

Usage: bronto-refactor show config [OPTIONS]

Options:

• --config <CONFIG> — The location of a TOML configuration file controlling this tool

• --format <FORMAT>

  Default value: toml

  Possible values: toml, json

bronto-refactor show output

Opens the TUI showing the results of a prior run or merge command

Usage: bronto-refactor show output <DIRECTORY>

Arguments:

• <DIRECTORY> — An output directory from a prior run or merge command to display in the UI