Usage#

When using glob-linters as a command line tool, you can use both command line options and configuration file to control the parameters for linting.

Command line options#

Note

The command line options will be overwritten by configuration file . All given arguments will ignored if you use configuration file.

You can use glob-linters as a command line tool if you want to lint your codes or test your GitHub action workflow in local terminals.

-d [TARGET_DIR], --target-dirs [TARGET_DIR ...]#

Specify the directory to be scanned for files to be linted, could be multiple values separated by space.

Default: ., the current working directory when glob-linters is called.

Keyword in configuration file: target.dirs.

-s [TARGET_SUFFIX ...], --target-suffixes [TARGET_SUFFIX ...]#

Extensions of files to be linted, e.g., .cpp, .py, and can be given more than one, separated by comma or space.

Default: all supported language extensions.

Keyword in configuration file: target.suffixes.

-E [ENABLED_LINTER ...], --enable-linters [ENABLED_LINTER ...]#

Enable specified linters to run. Only enabled linters will be run. The format of the argument is {suffix}:{linter_name}, e.g., .cpp:clang_format and .py:mypy. Multiple arguments can be given.

Default: None

Keyword in configuration: {suffix}.enabled_linters such as .cpp.enabled_linters.

-D [DISABLED_LINTER ...], --disable-linters [DISABLED_LINTER ...]#

Disable specified linters to run. Only enabled linters will be run. The format of the argument is the same as glob-linters --enable-linters

Default: None

Keyword in configuration: {suffix}.disabled_linters such as .cpp.disabled_linters.

-c [LINTER_SETTING ...], --linter-settings [LINTER_SETTING ...]#

Configure linters via command line arguments. Format is {suffix}:{linter_name}.{arg}={value} where arg can be one of the following

  • executable, the path of linter executable

  • config_file, the path of linter configuration file

  • options, additional arguments feeded to linter

For example, .cpp:cpplint.executable=/home/bowentan/.local/bin/cpplint.

Default: None.

Keyword in configuration file: {suffix}:{linter_name}.{arg}.

-x [EXTRA_PYTHON_PACKAGE_REQUIREMENTS ...], --extra-python-package-requirements [EXTRA_PYTHON_PACKAGE_REQUIREMENTS ...]#

Specify extra python packages which may be used in linting such as as Numpy extension. The same format of general requirements.txt. Multiple files supported.

Default: None

Keyword in configuration: env.extra_python_package_requirements.

-C [CONFIG_FILE], --config-file [CONFIG_FILE]#

glob-linters configuration file (glob-linters.ini) path.

Default: .github/glob-linters.ini.

No keyword for this in configuration file.

-g, --enable-debug#

Enable debug mode. Debugging information will be outputed.

Default: disabled.

Keyword in configuration file: env.debug.

Examples#

By issuing glob-linters in a directory like following:

$ glob-linters

without any options, glob-linters will recursively scan the directory to find files with all supported extensions using all default linters.

To change the target directory to src/ and only lint .py files, add options:

$ glob-linters --target-dirs src --target-suffixes .py

and if you also want to diasble flake8 and mypy linters with debugging information, do this:

$ glob-linters --target-dir src --target-suffix .py --disable-linters flake8 mypy

Configuration file#

The configuration file format follows configparse structure. The configuration file is generally used in GitHub actions. You can also use it to test your workflow in local terminals.

[target]#

dirs = <TARGET_DIR>

Work as the same with glob-linters --target-dirs. Directories to be scanned.

Default: .

suffixes = <TARGET_SUFFIX ...>

Work as the same with glob-linters --target-suffixes. File suffixes to be scanned.

Default: all supported file suffixes.

[{suffix}]#

enabled_linters = <...>

Specify the linters to be run for files with {suffix} suffix. Separate multiple values by comma or space.

Default: all supported linters.

disabled_linters = <...>

Disable the linters that will not be run for files with {suffix} suffix. Separate multiple values by comma or space.

Default: None.

[{suffix}:{linter_name}]#

executable = <path>

Specify the path of executable of the linter {suffix}:linter_name.

Default: the basename of the linter.

config_file = <path>

Specify the path of configuration file of the linter {suffix}:linter_name.

Default: None.

[env]#

debug = <True | False>

Set glob-linters to debugging mode.

Default: False.

extra_python_package_requirements

Specify additional Python package requirements. Separate multiple files by comma or space.

Default: None.

Example#

A direct example is given as:

[target]
dirs = src scripts
suffixes = .cpp .py

[.cpp]
enabled_linters = cpplint clang_format

[.cpp:cpplint]
config_file = .github/linter-configs/CPPLINT.cfg

[.cpp.clang_format]
config_file = .github/linter-configs/.clang-format

[.py]
disabled_linters = flake8 mypy

[.py:pylint]
config_file = .github/linter-configs/.pylintrc

[.py:black]
config_file = .github/linter-configs/.black

[.py:isort]
config_file = .github/linter-configs/.isort.cfg

[env]
debug = True

The above example will lint .cpp and .py files in the src and scripts directories with cpplint and clang_format for .cpp files, pylint, black and isort linters for .py files as well as degugging mode enabled. Also custom configuration files for all enabled linters are given, which are generally cases when used in GitHub Action.

Linter configurations#

Example configuration files for linters are given in LINTER_CONFIGS of GitHub repository as templates. You can modify them as you need.

Run as a Docker container#

You can also use glob-linters as a local Docker container by pulling the image and expose your workspace to the container, so as to test it as the GitHub action.

$ docker pull ghcr.io/bowentan/glob-linters:v0
$ docker run --name glob-linters-test --workdir /github/workspace --rm -v "<your workspace to be run against>":"/github/workspace" ghcr.io/bowentan/glob-linters:v0