Configuration file¶
luacheck
tries to load configuration from .luacheckrc
file in the current directory. If not found, it will look for it in the parent directory and so on, going up until it reaches file system root. Path to config can be set using --config
option, in which case it will be used during recursive loading. Paths within config are interpreted relatively to the directory from which it was loaded.
Config loading can be disabled using --no-config
flag.
If neither of --config
, --no-config
, and --no-default-config
options are used, luacheck
will attempt to load configuration from value of --default-config
option,
or %LOCALAPPDATA%\Luacheck\.luacheckrc
on Windows, ~/Library/Application Support/Luacheck/.luacheckrc
on OS X/macOS, and $XDG_CONFIG_HOME/luacheck/.luacheckrc
or ~/.config/luacheck/.luacheckrc
on other systems by default. Paths within default config are interpreted relatively to the current directory.
Config is simply a Lua script executed by luacheck
. It may set various options by assigning to globals or by returning a table with option names as keys.
Options loaded from config have the lowest priority: it’s possible to overwrite them with CLI options or inline options.
Config options¶
Option | Type | Default value |
---|---|---|
quiet |
Integer in range 0..3 | 0 |
color |
Boolean | true |
codes |
Boolean | false |
ranges |
Boolean | false |
formatter |
String or function | "default" |
cache |
Boolean or string | false |
jobs |
Positive integer | 1 |
exclude_files |
Array of strings | {} |
include_files |
Array of strings | (Include all files) |
global |
Boolean | true |
unused |
Boolean | true |
redefined |
Boolean | true |
unused_args |
Boolean | true |
unused_secondaries |
Boolean | true |
self |
Boolean | true |
std |
String or set of standard globals | "max" |
globals |
Array of strings or field definition map | {} |
new_globals |
Array of strings or field definition map | (Do not overwrite) |
read_globals |
Array of strings or field definition map | {} |
new_read_globals |
Array of strings or field definition map | (Do not overwrite) |
not_globals |
Array of strings | {} |
compat |
Boolean | false |
allow_defined |
Boolean | false |
allow_defined_top |
Boolean | false |
module |
Boolean | false |
max_line_length |
Number or false |
120 |
max_code_line_length |
Number or false |
120 |
max_string_line_length |
Number or false |
120 |
max_comment_line_length |
Number or false |
120 |
max_cyclomatic_complexity |
Number or false |
false |
ignore |
Array of patterns (see Patterns) | {} |
enable |
Array of patterns | {} |
only |
Array of patterns | (Do not filter) |
An example of a config which makes luacheck
ensure that only globals from the portable intersection of Lua 5.1, Lua 5.2, Lua 5.3 and LuaJIT 2.0 are used, as well as disables detection of unused arguments:
1 2 | std = "min"
ignore = {"212"}
|
Custom sets of globals¶
std
option allows setting a custom standard set of globals using a table. This table can have two fields: globals
and read_globals
.
Both of them should contain a field definition map defining some globals. The simplest way to define globals is to list their names:
1 2 3 4 | std = {
globals = {"foo", "bar"}, -- these globals can be set and accessed.
read_globals = {"baz", "quux"} -- these globals can only be accessed.
}
|
For globals defined like this Luacheck will additionally consider any fields within them defined. To define a global with a restricted set of fields, use
global name as key and a table as value. In that table, fields
subtable can contain the fields in the same format:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | std = {
read_globals = {
foo = { -- Defining read-only global `foo`...
fields = {
field1 = { -- `foo.field1` is now defined...
fields = {
nested_field = {} -- `foo.field1.nested_field` is now defined...
}
},
field2 = {} -- `foo.field2` is defined.
}
}
}
}
|
Globals and fields can be marked read-only or not using read_only
property with a boolean value.
Property other_fields
controls whether the global or field can also contain other unspecified fields:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | std = {
read_globals = {
foo = { -- `foo` and its fields are read-only by default (because they are within `read_globals` table).
fields = {
bar = {
read_only = false, -- `foo.bar` is not read-only, can be set.
other_fields = true, -- `foo.bar[anything]` is defined and can be set or mutated (inherited from `foo.bar`).
fields = {
baz = {read_only = true}, -- `foo.bar.baz` is read-only as an exception.
}
}
}
}
}
}
|
Custom sets can be given names by mutating global stds
variable, so that they can then be used in --std
CLI option
and std
inline and config option.
1 2 | stds.some_lib = {...}
std = "min+some_lib"
|
In config, globals
, new_globals
, read_globals
, and new_read_globals
can also contain definitions in same format:
1 2 3 4 5 6 7 8 9 10 | read_globals = {
server = {
fields = {
-- Allow mutating `server.sessions` with any keys...
sessions = {read_only = false, other_fields = true},
-- other fields...
}
},
--- other globals...
}
|
Per-file and per-path overrides¶
The environment in which luacheck
loads the config contains a special global files
. When checking a file <path>
, luacheck
will override options from the main config with entries from files[<glob>]
if <glob>
matches <path>
, applying entries for more general globs first. For example, the following config re-enables detection of unused arguments only for files in src/dir
, but not for files ending with _special.lua
:
1 2 3 4 | std = "min"
ignore = {"212"}
files["src/dir"] = {enable = {"212"}}
files["src/dir/**/*_special.lua"] = {ignore = {"212"}}
|
Note that files
table supports autovivification, so that
files["src/dir"].enable = {"212"}
and
files["src/dir"] = {enable = {"212"}}
are equivalent.
The configs are processed in order of increasing specificity. globals
and read_globals
will add to the set of allowed globals. not_globals
can be used to remove previously allowed globals; new_globals
and new_read_globals
can be used to override the set of globals, wiping all previously allowed globals
or read_globals
respectively, and replacing them with new entries.
Default per-path std overrides¶
luacheck
uses a set of default per-path overrides:
1 2 3 4 5 | files["**/spec/**/*_spec.lua"].std = "+busted"
files["**/test/**/*_spec.lua"].std = "+busted"
files["**/tests/**/*_spec.lua"].std = "+busted"
files["**/*.rockspec"].std = "+rockspec"
files["**/*.luacheckrc"].std = "+luacheckrc"
|
Each of these can be overriden by setting a different std
value for the corresponding key in files
.