Command line interface¶
luacheck
program accepts files, directories and rockspecs as arguments.
- Given a file,
luacheck
will check it. - Given
-
,luacheck
will check stdin. - Given a directory,
luacheck
will check all files with.lua
extension within it. This feature requires LuaFileSystem (installed automatically if LuaRocks was used to install Luacheck). - Given a rockspec (a file with
.rockspec
extension),luacheck
will check all files with.lua
extension mentioned in the rockspec inbuild.install.lua
,build.install.bin
andbuild.modules
tables.
The output of luacheck
consists of separate reports for each checked file and ends with a summary:
$ luacheck src
Checking src/bad_code.lua Failure
src/bad_code.lua:3:16: unused variable helper
src/bad_code.lua:3:23: unused variable length argument
src/bad_code.lua:7:10: setting non-standard global variable embrace
src/bad_code.lua:8:10: variable opt was previously defined as an argument on line 7
src/bad_code.lua:9:11: accessing undefined variable hepler
Checking src/good_code.lua OK
Checking src/python_code.lua Syntax error
spec/samples/python_code.lua:1:6: expected '=' near '__future__'
Checking src/unused_code.lua Failure
src/unused_code.lua:3:18: unused argument baz
src/unused_code.lua:4:8: unused loop variable i
src/unused_code.lua:5:13: unused variable q
src/unused_code.lua:7:11: unused loop variable a
src/unused_code.lua:7:14: unused loop variable b
src/unused_code.lua:7:17: unused loop variable c
src/unused_code.lua:13:7: value assigned to variable x is unused
src/unused_code.lua:14:1: value assigned to variable x is unused
src/unused_code.lua:22:1: value assigned to variable z is unused
Total: 14 warnings / 1 error in 4 files
luacheck
exits with 0 if no warnings or errors occured and with a positive number otherwise.
Command line options¶
Short options that do not take an argument can be combined into one, so that -qqu
is equivalent to -q -q -u
. For long options, both --option value
or --option=value
can be used.
Options taking several arguments can be used several times; --ignore foo --ignore bar
is equivalent to --ignore foo bar
.
Note that options that may take several arguments, such as --globals
, should not be used immediately before positional arguments; given --globals foo bar file.lua
, luacheck
will consider all foo
, bar
and file.lua
global and then panic as there are no file names left.
Option | Meaning |
---|---|
-g | --no-global |
Filter out warnings related to global variables. |
-u | --no-unused |
Filter out warnings related to unused variables and values. |
-r | --no-redefined |
Filter out warnings related to redefined variables. |
-a | --no-unused-args |
Filter out warnings related to unused arguments and loop variables. |
-s | --no-unused-secondaries |
Filter out warnings related to unused variables set together with used ones. |
--std <std> |
Set standard globals.
|
--globals [<global>] ... |
Add custom globals on top of standard ones. |
--read-globals [<global>] ... |
Add read-only globals. |
--new-globals [<global>] ... |
Set custom globals. Removes custom globals added previously. |
--new-read-globals [<global>] ... |
Set read-only globals. Removes read-only globals added previously. |
-c | --compat |
Equivalent to --std max . |
-d | --allow-defined |
Allow defining globals implicitly by setting them. |
-t | --allow-defined-top |
Allow defining globals implicitly by setting them in the top level scope. |
-m | --module |
Limit visibility of implicitly defined globals to their files. See Modules |
--no-unused-globals |
Filter out warnings related to set but unused global variables. |
--ignore | -i <patt> [<patt>] ... |
Filter out warnings matching patterns. |
--enable | -o <patt> [<patt>] ... |
Do not filter out warnings matching patterns. |
--only | -o <patt> [<patt>] ... |
Filter out warnings not matching patterns. |
--no-inline |
Disable inline options. |
--config <config> |
Path to custom configuration file (default: .luacheckrc ). |
--no-config |
Do not look up custom configuration file. |
--cache [<cache>] |
Path to cache file. (default: .luacheckcache ). See Caching |
--no-cache |
Do not use cache. |
-j | --jobs |
Check <jobs> files in parallel. Requires LuaLanes. |
--formatter <formatter> |
Use custom formatter.
|
-q | --quiet |
Suppress report output for files without warnings.
|
--codes |
Show warning codes. |
--no-color |
Do not colorize output. |
-v | --version |
Show version of luacheck and its dependencies and exit. |
-h | --help |
Show help and exit. |
Patterns¶
CLI options --ignore
, --enable
and --only
and corresponding config options allow filtering warnings using pattern matching on warning codes, variable names or both. If a pattern contains a slash, the part before slash matches warning code and the part after matches variable name. Otherwise, if a pattern contains a letter or underscore, it matches variable name. Otherwise, it matches warning code. E.g.:
Pattern | Matching warnings |
---|---|
4.2 | Shadowing declarations of arguments or redefining them. |
.*_ | Warnings related to variables with _ suffix. |
4.2/.*_ | Shadowing declarations of arguments with _ suffix or redefining them. |
Unless already anchored, patterns matching variable names are anchored at both sides and patterns matching warning codes are anchored at their beginnings. This allows to filter warnings by category (e.g. --only 1
focuses luacheck
on global-related warnings).
Formatters¶
CLI option --formatter
allows selecting a custom formatter for luacheck
output. A custom formatter is a Lua module returning a function with three arguments: report as returned by luacheck
module (see Report format), array of file names and table of options. Options contain values assigned to quiet
, color
, limit
, codes
and formatter
options in CLI or config. Formatter function must return a string.
Caching¶
If LuaFileSystem is available, Luacheck can cache results of checking files. On subsequent checks, only files which have changed since the last check will be rechecked, improving run time significantly. Changing options (e.g. defining additional globals) does not invalidate cache. Caching can be enabled by using --cache <cache>
option or cache
config option. Using --cache
without an argument or setting cache
config option to true
sets .luacheckcache
as the cache file. Note that --cache
must be used every time luacheck
is run, not on the first run only.