Rules

In this document, we present links to the rules supported by elvis and the available configuration options for each one. At the end of this document, we share an example elvis.config file you can copy-paste (in your project's root) and then tweak to your liking.

Rules and other significant changes, like new options (starting from version 0.4.0), are identified with for convenience purposes.

Avoid, prefer, quick fix

Most, if not all, of the rules will present (opinionated) documentation sections titled "Avoid" and "Prefer". We aim to provide a "Rationale" with them and, in some cases, "Exceptions" or "Quick fix", if applicable.

Style rules

Always Shortcircuit
Atom Naming Convention
Behaviour Spelling
Don't Repeat Yourself
Export Used Types
Function Naming Convention
Generic Type
Guard Operators
Include ms_transform for ets:fun2ms/1
Line Length
Macro Module Names - deprecated
Macro Naming Convention
Max Anonymous Function Arity
Max Function Arity
Max Function Clause Length
Max Function Length
Max Module Length
Module Naming Convention

No $

No Author
No Behavior Info
No Block Expressions
No Boolean In Comparison
No Call
No Catch Expressions
No Common Caveats
No Debug Call
No Deep Nesting
No God Modules
No If Expression
No Import
No Invalid Dynamic Calls
No Init Lists
No Macros
No Match In Condition
No Includes
No Nested try...catch Blocks
No Operator With Same Values
No Redundant Blank Lines
No receive Without Timeout
No Single-Clause Case Expressions
No Single-Match Maybe Blocks
No Space After #
No Space
No Spec With Records
No Specs
No Successive Maps
No Tabs
No Throw
No Trailing Whitespace
No Types
No Used Ignored Variables
Numeric Format
Operator Spaces
Param Pattern-Matching
Prefer Include
Prefer Unquoted Atoms
Private Data Types
Simplify Anonymous Functions
State Record And Type
Variable Casing
Variable Naming Convention

`.gitignore` rules

.gitignore Forbidden Patterns
.gitignore Required Patterns

Project rules

No Deps master erlang.mk - deprecated
No Deps master rebar.config - deprecated
No Deps With Branches
Old Configuration Format - deprecated
Protocol For Deps erlang.mk - deprecated
Protocol For Deps rebar.config - deprecated
Protocol For Deps

Rulesets

Rulesets in elvis are used to group individual rules together and can save a lot of duplication. elvis currently has five pre-defined rulesets, but gives you the ability to specify custom rulesets in the configuration file.

The six pre-defined rulesets are:

erl_files, for Erlang source files (pre-defined ruleset).
erl_files_test, for Erlang test files (pre-defined ruleset).
erl_files_strict, for Erlang source files (all applicable rules).
gitignore, for .gitignore files.
hrl_files, for Erlang header files (pre-defined ruleset).
hrl_files_strict, for Erlang header files (all applicable rules).
rebar_config, for rebar configuration files.

Custom rulesets are defined in a {RuleNamespace, #{}} tuple in elvis' configuration. Each key in the map represents the ruleset name and is mapped to a list of rules as otherwise defined in a standard ruleset.

Example configuration with a custom ruleset (named my_ruleset):

[{elvis, [
    {rulesets,
        #{ my_ruleset => [{elvis_style, max_module_length, #{}}
                        , {elvis_style, no_common_caveats_call, #{}}
                         ]
         }
    }
  , {config,
        [#{ dirs => ["src/**" , "test/**"]
          , filter => "*.erl"
          , ruleset => my_ruleset
          }
        ]
    }
]}].

The `-elvis` attribute

Per-module rules can also be configured using attribute -elvis(_)., with the same content as is expected in elvis.config's rules option, e.g.:

-elvis([{elvis_style, no_behavior_info, #{}}]).
-elvis([{elvis_style, no_nested_try_catch}]).

Note: a single attribute with a list of rules is the same as multiple attributes with a list of rules each - the rules are "merged" - as in:

-elvis([{elvis_style, no_behavior_info, #{}}, {elvis_style, no_nested_try_catch}]).

In this case, the ignore attribute has limited value since it'll be ignored for "other" modules. You can always play with the following, but results may not be surprising.

-module(mymodule).
-elvis([{elvis_style, no_deep_nesting, #{ level => 4, ignore => [mymodule] }}]).
...

Disabling rules

Rules (as used by you, in elvis.config) come in 3-element tuples (if you use options) or 2-element tuples (if you don't). To disable a rule, you need to use the 3-element form, and the reserved word disable: let's consider you want to disable rule elvis_text_style:no_tabs; you do {elvis_text_style, no_tabs, disable}, and you're done!

The `ignore` option

Module-level rules implement a generic ignore mechanism that allows skipping analysis in elements of your choice. It suffices to add the ignore list to your rules, as per the example below.

-elvis([{elvis_style, no_invalid_dynamic_calls, #{ ignore => [elvis_core]}}]).
-elvis([{elvis_style, no_debug_call, #{ ignore => [elvis_result, elvis_utils]}}]).

You can add the exceptions using the following syntax:

whole module: ignore => [mod]
functions (by name only): ignore => [{mod, fun}] (available for elvis_style-based rules only)
module, function and arity: ignore => [{mod, fun, arity}] (available for elvis_style-based rules only)

BEAM files

Specific rules (signaled with ) allow you to perform analysis directly on beam files (instead of source code).

To target these, specifiy beam_files (or beam_files_strict), instead of erl_files (or erl_files_strict), as the target ruleset.

Though this analysis may be useful for pin-pointing certain elements, beware that, e.g., reported line numbers will most surely not correspond with those in the source file.

HRL files

Specific rules (signaled with ) are reserved for .hrl files.

Example `elvis.config`

[{elvis, [
    {config, [
        #{ dirs => ["src/**", "test/**"]
         , filter => "*.erl"
         , ruleset => erl_files
         % these are not enforced by default, so are added here for completeness
         , rules => [{elvis_style, max_module_length, #{}}
                   , {elvis_style, no_common_caveats_call, #{}}
                    ]
         }
      , #{ dirs => ["include/**"]
         , filter => "*.hrl"
         , ruleset => hrl_files
         }
      , #{ dirs => ["."]
         , filter => "Makefile"
         , ruleset => makefiles
         , rules => [] }
      , #{ dirs => ["."]
         , filter => "rebar.config"
         , ruleset => rebar_config
         , rules => [] }
      , #{ dirs => ["."]
         , filter => ".gitignore"
         , ruleset => gitignore }
    ]}
  , {verbose, true}
]}].

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!