project-config CLI

Validate the configuration of your project against the configured styles.

project-config [-h] [-v] [-T] [-c CONFIG] [--root ROOTDIR] [-r NAME[:FORMAT];OPTION=VALUE]
               [--no-color] [--no-cache] [--only-hints]
               {check,fix,show,clean,init}

project-config positional arguments

  • command - Command to execute. (default: None)

project-config options

  • -h, --help - Show project-config’s help and exit.

  • -v, --version - Show project-config’s version number and exit.

  • -T, --traceback - Display the full traceback when a exception is found. Useful for debugging purposes.

  • -c CONFIG, --config CONFIG - Custom configuration file path. (default: None)

  • --root ROOTDIR, --rootdir ROOTDIR - Root directory of the project. Useful if you want to execute project-config for another project rather than the current working directory. (default: {cwd})

  • -r NAME[:FORMAT];OPTION=VALUE, --reporter NAME[:FORMAT];OPTION=VALUE - Reporter for generated output when failed. Possible values are shown executing project-config show reporters.Additionally, options can be passed to the reporter appending ';' to the end of the reporter id with the syntax '<OPTION>=<JSON VALUE>'. Console reporters can take an argument 'color' which accepts a JSON object to customize the colors for parts of the report like files, for example: table:simple;colors=”file”:”blue”. (default: {})

  • --no-color, --nocolor - Disable colored output. You can also set a value in the environment variable NO_COLOR.

  • --no-cache, --nocache - Disable cache for the current execution. You can also set the value 'false' in the environment variable PROJECT_CONFIG_USE_CACHE.

  • --only-hints - Only show the hint messages rather than complete errors.

Commands

  • project-config check - Check the styles of the current project.

  • project-config fix - Fix the files of the current project.

  • project-config init - Initialize a minimal style for the current project.

  • project-config show config - Show the configuration.

  • project-config show style - Show the collected styles merged into the final one.

  • project-config show plugins - Show all available plugins with their actions.

  • project-config show cache - Show cache directory location.

  • project-config show file <resource> - Print JSON-serialized version of the file or URL passed as argument.

  • project-config show reporters - Show all available reporters.

  • project-config clean cache - Clean the persistent cache of remote collected sources.

Tip

project-config CLI sets the environment variable PROJECT_CONFIG while is running.

Reporting

project-config supports multiple formats for reporting. Currently, the following reporters are supported:

  • default - The default reporter, based on YAML but simplified.

  • yaml - YAML reporter with flow style format.

  • json - JSON reporter.

  • toml - TOML reporter.

  • table - Table reporters using tabulate.

When you pass a reporter with the project-config --reporter option, you can specify the variant of the format with reporter:format syntax, for example table:html will output the errors in an HTML table.

Additional third party reporters can be implemented as plugins, see Writing third party reporters for more information.

The reporter output affects the output of the next commands:

  • project-config check

  • project-config fix

  • project-config show config

  • project-config show style

  • project-config show plugins

Note

Keep in mind that errors shown by check and fix commands are redirected to STDERR.

Colorized output can’t be serialized, so if you want to postprocess the report in the command line use always the project-config --no-color flag or set the environment variable NO_COLOR.

Examples of usage

Check the styles of the current project reporting in TOML format without color and making all requests to remote sources:

project-config check -r toml --no-color --no-cache

The installation of project-config from Python sources comes with the jmespath Python library, which includes the CLI tool jp.py that can be used to apply JMESPath queries to JSON reports produced by project-config.

For example, to show the number of incorrect files detected by the check command (Unix only):

project-config check -r json --no-color 2>&1 | jp.py 'length(keys(@))'

Show the number of rules defined in your styles after collecting all:

project-config show style -r json --no-color 2>&1 | jp.py 'length(rules)'

Show the number of actions currently available:

project-config show plugins -r json --no-color 2>&1 | jp.py 'length(*[])'

Show your styles after collecting all in YAML format:

project-config show style -r yaml

Fix the styles for the current project:

project-config fix

Print the content of a file converted to JSON:

project-config -r json:pretty show file .project-config.yml

You can also pass a URL to the show file command and indent the JSON with 4 spaces using the json:pretty4 reporter:

src/project_config/__main__.py -r json:pretty4 \
  show file gh://mondeja/project-config/pyproject.toml

Print the result of a JMESPath query works against a file (accept paths or URLs):

project-config show file .pre-commit-config.yaml \
  | jp.py "repos[?repo=='https://github.com/mondeja/project-config']"

Initialize a minimal configuration:

project-config init

Initialize a minimal configuration storing the configuration inside a pyproject.toml file:

project-config init --config pyproject.toml

Initialize a minimal configuration storing the configuration in a custom file located in a relative project root directory:

project-config init --config styles-configuration.toml --rootdir my/subdir