Global_variables_(1xx)">Global_variables_(1xx)">Global variables (1xx)

For each file, Luacheck builds list of defined globals and fields which can be used there. By default only globals from Lua standard library are defined; custom globals can be added using --globals CLI option or globals config option, and version of standard library can be selected using --std CLI option or std config option. When an undefined global or field is set, mutated or accessed, Luacheck produces a warning.

Read-only globals

By default, most standard globals and fields are marked as read-only, so that setting them produces a warning. Custom read-only globals and fields can be added using --read-globals CLI option or read_globals config option, or using a custom set of globals. See Custom sets of globals

Globals and fields that are not read-only by default:

Implicitly defined globals

Luacheck can be configured to consider globals assigned under some conditions to be defined implicitly. When -d/--allow_defined CLI option or allow_defined config option is used, all assignments to globals define them; when -t/--allow_defined_top CLI option or allow_defined_top config option is used, assignments to globals in the top level function scope (also known as main chunk) define them. A warning is produced when an implicitly defined global is not accessed anywhere.

Modules

Files can be marked as modules using -m/--module CLI option or module config option to simulate semantics of the deprecated module function. Globals implicitly defined inside a module are considired part of its interface, are not visible outside and are not reported as unused. Assignments to other globals are not allowed, even to defined ones.

Unused_variables_(2xx)_and_values_(3xx)">Unused_variables_(2xx)_and_values_(3xx)">Unused variables (2xx) and values (3xx)

Luacheck generates warnings for all unused local variables except one named _. It also detects variables which are set but never accessed or accessed but never set.

"Unused hint" (214)

If a function argument starts with an underscore _, it recevies an "unused hint", meaning that it's intended to be left unused. If it is used, a 214 warning is generated.

Unused values and uninitialized variables

For each value assigned to a local variable, Luacheck computes set of expressions where it could be used. Warnings are produced for unused values (when a value can't be used anywhere) and for accessing uninitialized variables (when no values can reach an expression). E.g. in the following snippet value assigned to foo on line 1 is unused, and variable bar is uninitialized on line 9:

local foo = expr1()
local bar
if condition() then


   foo = expr2()


   bar = expr3()
else


   foo = expr4()


   print(bar)
end
return foo, bar

Secondary values and variables

Unused value assigned to a local variable is secondary if its origin is the last item on the RHS of assignment, and another value from that item is used. Secondary values typically appear when result of a function call is put into locals, and only some of them are later used. For example, here value assigned to b is secondary, value assigned to c is used, and value assigned to a is simply unused:

local a, b, c = f(), g()
return c

A variable is secondary if all values assigned to it are secondary. In the snippet above, b is a secondary variable.

Warnings related to unused secondary values and variables can be removed using -s/--no-unused-secondaries CLI option or unused_secondaries config option.

Shadowing_declarations_(4xx)">Shadowing_declarations_(4xx)">Shadowing declarations (4xx)

Luacheck detects declarations of local variables shadowing previous declarations, unless the variable is named _. If the previous declaration is in the same scope as the new one, it is called redefining.

Note that it is not necessary to define a new local variable when overwriting an argument:

local function f(x)


   local x = x or "default" -- bad
end
local function f(x)


   x = x or "default" -- good
end

Control_flow_and_data_flow_issues_(5xx)">Control_flow_and_data_flow_issues_(5xx)">Control flow and data flow issues (5xx)

Unreachable code

Luacheck detects unreachable code. It also detects it if end of a loop block is unreachable, which means that the loop can be executed at most once:

for i = 1, 100 do


   -- Break statement is outside the `if` block,


   -- so that the loop always stops after the first iteration.


   if cond(i) then f() end break
end

Unused labels

Labels that are not used by any goto statements are reported as unused.

Unbalanced assignments

If an assignment has left side and right side with different lengths, the assignment is unbalanced and Luacheck warns about it.

An exception is initializing several local variables in a single statement while leaving some uninitialized:

local a, b, c = nil -- Effectively sets `a`, `b`, and `c` to nil, no warning.

Empty blocks

Luacheck warns about empty do end blocks and empty if branches (then else, then elseif, and then end).

Empty statements

In Lua 5.2+ semicolons are considered statements and can appear even when not following normal statements. Such semicolons produce Luacheck warnings as they are completely useless.

Cyclomatic complexity

If a limit is set using --max-cyclomatic-complexity CLI option or corresponding config or inline options, Luacheck warns about functions with too high cyclomatic complexity.

Reversed numeric for loops

Iterating a table in reverse using a numeric for loop going from #t to 1 requires a negative loop step. Luacheck warns about loops going from #(some expression) to 1 or a smaller constant when the loop step is not negative:

-- Warning for this loop:
-- numeric for loop goes from #(expr) down to 1 but loop step is not negative
for i = #t, 1 do


   print(t[i])
end
-- This loop is okay.
for i = #t, 1, -1 do


   print(t[i])
end

Error-prone and Unnecessary Negations

Negation has a higher priority than relational operators; (not x == 3) is interpreted as (not x) == 3, rather than not (x == 3).

Negating the output of a relational operator is unnecessary; each one has another operator that can be used directly:

not (x == y) => x ~= y not (x ~= y) => x == y not (x > y) => x <= y not (x >= y) => x < y not (x < y) => x >= y not (x <= y) => x > y

These replacements work for all numbers, but can fail with metatables or NaN's.

Formatting_issues_(6xx)">Formatting_issues_(6xx)">Formatting issues (6xx)

Whitespace issues

Luacheck warns about trailing whitespace and inconsistent indentation (SPACE followed by TAB).

Some examples of trailing whitespace Luacheck finds:

-- Whitespace example.
print("Hello")
print("World")

Here:

Trailing whitespace in any of these forms is useless, can be a nuisance to developers navigating around a file, and is forbidden in many formatting styles.

Line length limits

Luacheck warns about lines that are longer then some limit. Default limit is 120 characters. It's possible to change this limit using --max-line-length CLI option or disable the check completely with --no-max-line-length; there are similar config and inline options.

Additionally, separate limits can be set for three different type of lines:

These types of lines are limited using CLI options named --[no-]max-string-line-length, --[no-]max-comment-line-length, and --[no-]max-code-line-length, with similar config and inline options.

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.

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.:

Unless already anchored, patterns matching variable names are anchored at both sides and patterns matching warning codes are anchored at their beginnings. This allows one to filter warnings by category (e.g. --only 1 focuses luacheck on global-related warnings).

Defining extra globals and fields

CLI options --globals, --new-globals, --read-globals, --new-read-globals, and corresponding config options add new allowed globals or fields. E.g. --read-globals foo --globals foo.bar allows accessing foo global and mutating its bar field. --not-globals also operates on globals and fields and removes definitions of both standard and custom globals.

Sets of standard globals

CLI option --stds allows combining built-in sets described above using +. For example, --std max is equivalent to --std=lua51c+lua52c+lua53c+luajit. Leading plus sign adds new sets to current one instead of replacing it. For instance, --std +love is suitable for checking files using LÖVE framework. Custom sets of globals can be defined by mutating global variable stds in config. See Custom sets of globals

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, ranges 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.

Stable interface for editor plugins and tools

Command-line interface of Luacheck can change between minor releases. Starting from 0.11.0 version, the following interface is guaranteed at least till 1.0.0 version, and should be used by tools using Luacheck output, e.g. editor plugins.

If compatibility with older Luacheck version is desired, output of luacheck --help can be used to get its version. If it contains string 0.<minor>.<patch>, where <minor> is at least 11 and patch is any number, interface described above should be used.

Config options

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:

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:

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:

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:

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.

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:

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:

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:

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"
files["**/config.ld"].std = "+ldoc"

Each of these can be overriden by setting a different std value for the corresponding key in files.

Report format

A final report is an array of file reports plus fields warnings, errors and fatals containing total number of warnings, errors and fatal errors, correspondingly.

A file report is an array of issues (warnings or errors). If a fatal error occurred while checking a file, its report will have fatal field containing error type and msg field containing error message.

An issue is a table with field code indicating its type (see List of warnings), and fields line, column and end_column pointing to the source of the warning. name field may contain name of related variable. Issues of some types can also have additional fields:

Other fields may be present for internal reasons.

This is documentation for version 1.1.0 of Luacheck, a linter for Lua.