gersemi

A formatter to make your CMake code the real treasure.

Installation

You can install gersemi from PyPI:

pip3 install gersemi

Usage

usage: gersemi [-c] [-i] [--diff] [--print-config {minimal,verbose,default}] [--version]
               [-h] [-l INTEGER] [--indent (INTEGER | tabs)] [--unsafe]
               [--definitions src [src ...]]
               [--list-expansion {favour-inlining,favour-expansion}]
               [--warn-about-unknown-commands] [--disable-formatting]
               [--extensions extension-name-or-path [extension-name-or-path ...]]
               [--sort-order {case-sensitive,case-insensitive}] [-q] [--color]
               [-w (INTEGER | max)] [--cache] [--cache-dir CACHE_DIR]
               [--config CONFIGURATION_FILE] [--warnings-as-errors]
               [--line-ranges LINE_RANGES] [--respect-ignore-files]
               [src ...]

A formatter to make your CMake code the real treasure.

positional arguments:
  src                   File or directory to format. When directory is provided then
                        CMakeLists.txt, CMakeLists.txt.in and files with
                        .cmake/.cmake.in extension are automatically discovered. If only
                        `-` is provided, input is taken from stdin instead.

modes:
  -c, --check           Check if files require reformatting. Return 0 when there's
                        nothing to reformat. Return 1 when some files would be
                        reformatted. It can be used together with --diff.
  -i, --in-place        Format files in-place.
  --diff                Show diff on stdout for each formatted file instead. It can be
                        used together with --check.
  --print-config {minimal,verbose,default}
                        Print configuration for files. With "minimal" prints source of
                        outcome configuration (configuration file or defaults) and the
                        options that differ from defaults. With "verbose" prints source
                        of outcome configuration (configuration file or defaults), files
                        for which this configuration is applicable and complete listing
                        of options. With "default" prints outcome configuration with
                        default values. Command line arguments are taken into
                        consideration just as they would be for formatting. When
                        configuration file is found values in "definitions" are printed
                        as relative paths, otherwise absolute paths are printed. Output
                        can be placed in .gersemirc file verbatim.
  --version             Show version.
  -h, --help            Show this help message and exit.

outcome configuration:
  These arguments control how gersemi formats source code. Values for these arguments
  can be stored in .gersemirc file which can be placed in directory next to the source
  file or any parent directory. The highest priority has file provided through
  --config, then file closest to the source file, then file in parent directory etc.
  until root of file system is reached. Arguments from command line can be used to
  override parts of that stored configuration or supply them in absence of
  configuration file. Precedence: (command line arguments) > (configuration file) >
  (defaults)

  -l, --line-length INTEGER
                        Maximum line length in characters. [default: 80]
  --indent (INTEGER | tabs)
                        Number of spaces used to indent or 'tabs' for indenting with
                        tabs [default: 4]
  --unsafe              Skip default sanity checks.
  --definitions src [src ...]
                        Files or directories containing custom command definitions
                        (functions or macros). If only - is provided custom definitions,
                        if there are any, are taken from stdin instead. Commands from
                        not deprecated CMake native modules don't have to be provided.
                        See: https://cmake.org/cmake/help/latest/manual/cmake-
                        modules.7.html
  --list-expansion {favour-inlining,favour-expansion}
                        Switch controls how code is expanded into multiple lines when
                        it's not possible to keep it formatted in one line. With
                        "favour-inlining" the list of entities will be formatted in such
                        way that sublists might still be formatted into single line as
                        long as it's possible or as long as it doesn't break the "more
                        than four standalone arguments" heuristic that's mostly focused
                        on commands like `set` or `list(APPEND)`. With "favour-
                        expansion" the list of entities will be formatted in such way
                        that sublists will be completely expanded once expansion becomes
                        necessary at all. [default: favour-inlining]
  --warn-about-unknown-commands, --no-warn-about-unknown-commands
                        When enabled file which has unknown custom commands will have
                        warnings issued about that and result won't be cached. See:
                        "Let's make a deal" section in README. [default: warnings
                        enabled, same as --warn-about-unknown-commands]
  --disable-formatting, --enable-formatting
                        Completely disable formatting. [default: formatting enabled]
  --extensions extension-name-or-path [extension-name-or-path ...]
                        Names of extension modules or paths to extension files. See:
                        "Extensions" section in README.
  --sort-order {case-sensitive,case-insensitive}
                        Defines sorting order for values after the keyword which
                        supports sorting due to either keyword hint or extension
                        definition. With "case-sensitive" arguments that are sorted in
                        case sensitive order also known as code point order. With "case-
                        insensitive" arguments are sorted in case insensitive order.
                        [default: case-sensitive]

control configuration:
  These arguments control how gersemi operates rather than how it formats source code.
  Values for these options are not read from configuration file. Default values are
  used when the arguments aren't supplied. Precedence: (command line arguments) >
  (defaults)

  -q, --quiet, --no-quiet
                        Skip printing non-error messages to stderr.
                        [default: don't skip, same as --no-quiet]
  --color, --no-color   If --diff is selected showed diff is colorized. Colorama has to
                        be installed for this option to work.
                        [default: don't colorize diff, same as --no-color]
  -w, --workers (INTEGER | max)
                        Explicit number of workers or 'max' for maximum possible number
                        of workers on given machine used to format multiple files in
                        parallel. [default: max]
  --cache, --no-cache   Enables cache with data about files that are known to be
                        formatted to speed up execution.
                        [default: cache enabled, same as --cache]
  --cache-dir CACHE_DIR
                        Directory used to store cache file when cache is enabled. When
                        omitted platform specific default cache directory will be used
                        instead.
                        [default: omitted]
  --config CONFIGURATION_FILE
                        Path to configuration file. When present this configuration file
                        will be used for determining configuration for all sources
                        instead of automatically found configuration files closest to
                        each of the sources. [default: omitted]
  --warnings-as-errors  Treat warnings as errors so that status code becomes 1 when at
                        least one warning would be issued. This option is not inhibited
                        by --quiet.
  --line-ranges LINE_RANGES
                        Try to format code only in specified line ranges. This option
                        works only with one input file. Range is specified as pairs of
                        integers indicating line numbers (1-based) joined with `-`
                        (dash) and each pair must be separated by comma. Examples of
                        valid values of this option: a) single line range: 13-21 b)
                        multiple line ranges: 10-49,51-100,111-123 c) single line: 7-7.
                        This option can be specified multiple times and union of ranges
                        will be considered, example: `--line-ranges 10-49 --line-ranges
                        51-100` is the same as `--line-ranges 10-49,51-100`
  --respect-ignore-files, --no-respect-ignore-files
                        When directory is passed as a source argument gersemi will
                        automatically discover relevant CMake files while respecting
                        rules in the following ignore files: .ignore, .gitignore,
                        .git/info/exclude and global gitignore globs. See:
                        https://docs.rs/ignore/latest/ignore/index.html