Checkers¶

check-config uses checkers which define the desired state of the configuration files. There are several checker types (and more to come):

checker type	description	fixable	templating
file_absent	the file must be absent	yes	no
file_present	the file must be present, indifferent the content	yes	no
key_absent	a specified key must be absent in a toml / yaml / json file	yes	no
key_value_present	a specified key with a specified value must be present in a toml / yaml / json file	yes	no
key_value_regex_matched	the value of a specified key must be match the specified regex in a toml / yaml / json file	no (unless placeholder is given)	no
entry_absent	a specified entry must be absent in the array of a toml / yaml / json file	yes	no
entry_present	a specified entry must be present in the of a toml / yaml / json file	yes	no
lines_absent	the specified lines must be absent	yes	yes
lines_present	the specified lines must be present	yes	yes
file_unpacked	the file must be unpacked	yes	no
file_copied	the file must be copied	yes	yes
dir_copied	the dir must be copied	yes	no
dir_present	the dir must be present	yes	no
dir_absent	the dir must be absent	yes	no
git_fetched	the git repo must be present and fetched	yes	no
package_present	the package is installed	yes	no
package_absent	the package is not installed	yes	no

check-config.toml¶

The check-config.toml is the default entrypoint to define all checkers and configure check-config:

include = [  # optional list of toml files with additional checks
    "/home/me/.checkers/check.toml",  # absolute path
    "~/.checkers/check.toml",  # relative to home dir of current user
    "config:check.toml", # relative to the parent dir of this toml
    "py://my_package:checkers/python.toml", # path to file in python package
    "https//example.com/check.toml", # path on webserver
 ]

Note: When using a path to a Python package to include checkers, the activated Python (virtual) environment will be used.

And one or more checkers

[[<checker_name>]]
<checker specific key/values>

Note the double square brackets. We use an array of tables to define the checkers, so multiple checkers of the same type may exist in the same toml file. If you use only one checker for a certain type in toml file, you can also use single square brackets. However, to be consistent and extensible, we advice to always use double brackets.

The syntax is slightly different per checker type. See the next sections for help about the checker definitions.

Tags¶

All checkers can have a tags key to make it possible to exclude or include this checker from the execution.

See cli tags options for more information about the usage.

[[lines_present]]
file = ".gitignore"
tags = ["linux"]
lines = ".cache"

Check-Only¶

When --fix is given on the cli, check-config will try to fix the checkers. However, sometimes you do not want a fix a violation, but just check if a previous fix is performed correct. For example: you unzip a file in one checker and want to check whether a file is unpacked from the zip. In that case you do not want to create an empty file by the checker which checks for the unpacked file. To do so, add check_only = true to your checker, like:

[[file_present]]
file = "path/to/unpacked_file"
check_only = true

Templating¶

Some checkers support templating. When a checker supports templating, variables are substitued by their values. Variables are defined in the top level variables key in the toml files.

[variables]
date = "2025-10-10"

Beside adding the variables to the config, you can add all environment variables via the --env cli option:

check-config --env

In your content, the variables within ${} are replaced when is_template is set to true:

[[lines_present]]
file = "test.txt"
lines = "date: ${date}"
is_template = true

You can escape variable substitution by adding a \ ie \${date}. During execution the unescaped variant ${date} will replace the escaped one.

Notes:

order is important. If variables are inserted after the de definition of a checker, they will not be available.
variables names are case sensitive.
the values of the variables must be strings.

File Absent¶

file_absent will check if the file is absent.

The next example will check that test/absent_file will be absent.

[[file_absent]]
file = "test/absent_file"

File Present¶

file_present will check if the file is present.

The next example will check that test/present_file will be present. It will not check the contents.

[[file_present]]
file = "test/present_file"

When the file does not exists, running with fix will create the file. At default an empty file will be created.

This checker type can handle any text file.

This checker has some options:

placeholder
regex
permissions

Placeholder¶

When a file will be created when run with --fix, the created file will be created with the placeholder as content.

[[file_present]]
file = "test/present_file"
placeholder = "sample content"

Regex Match¶

Checks whether the contents of the file matches the regex expression.

[[file_present]]
file = ".bashrc"
regex = 'export KEY=.*'

Note: specify the regex as a raw toml string (single quotes) to prevent escaping.

Permissions¶

On Unix systems, you can check for the permissions:

[[file_present]]
file = ".bashrc"
permissions = "644"

The permissions need to be defined in the octal representation. See chmod calculator an explanation.

Combinations¶

These options can of course be combined in one definition:

[[file_present]]
file = ".bashrc"
regex = 'export KEY=.*'
placeholder = "export KEY=hi"
permissions = "644"

File Copied¶

file_copied will check that the file is copied from a file on your system or from https.

[[file_copied]]
source = "url or path to file"
destination_dir = "dir on local filesystem"
destination = "path (including filename) on local filesystem"

Only on destination and destination_dir`` needs to be specified. Whendestination_diris given, thedestinationis created by appending the filename from the source to thedestination. Whendestinationis given,destination_dir` is ignored.

When the parent dir of the destination does not exists, the dir is created.

Templating¶

This checker supports templating.

[[file_copied]]
source = "url or path to file"
destination = "path (including filename) on local filesystem"
is_template = true

Dir Copied¶

dir_copied will check that the dir including all contents is copied.

[[dir_copied]]
source = "path to dir"
destination_dir = "dir on local filesystem in which the contents are copied"
destination = "dir on local filesystem in which the source directory is copied"
always_copy_on_fix = false # optional, defaults to false

Only on destination and destination_dir`` needs to be specified. Whendestination_diris given, thedestinationis created by appending the filename from the source to thedestination. Whendestinationis given,destination_dir` is ignored.

When the parent dir of the destination does not exists, the dir is created.

When the destination exists, the directory will not be copied. This is overridable with always_copy_on_fix. When that key is true, the directory will be copied regardless whether it exists or not.

Dir Present¶

dir_present will check if the dir including the parent directories is present. When permissions are given, it will also check the permissions.

[[dir_present]]
dir = "path to dir"
permissions = "755" # optional

Dir Absent¶

dir_absent will check if the dir including the contents is absent.

[[dir_absent]]
dir = "path to dir"

File Unpacked¶

file_unpacked will check that the file is unpacked. It can unpack zip, tar.gz and tar files.

[[file_unpacked]]
source = " path to packed file"
destination_dir = "path to destination directory"
unpacker = "optional override extension"

The unpack method is selected based on the extension of the source. When the extension is the correct one, you can override it via unpacker.

Git Fetched¶

git_fetched will check that the git repo is cloned and fetched.

[[git_fetched]]
repo = "git url"
destination_dir = "path to destination directory"

# one of the next
branch = "main"
commit_hash = "a1872"
tag = " v1.1"

Key Absent¶

key_absent will check if the key is not present in the file.

The next example will check that test/file.toml has no key named key_to_be_absent.

[[key_absent]]
file = "test/file.toml"
key.key_to_be_absent = {}

The value of the key is not important; any value will do.

The key can be nested. In the next case it is sufficient that key_to_be_absent is not present. super_key will not be removed if it contains also other keys.

[[key_absent]]
file = "test/present.toml"
key.super_key.key_to_be_absent = {}