elvis
, the Erlang style reviewer, is the command-line interface for
elvis_core
.
elvis
is an Erlang generic style reviewer that focuses on code and configuration consistency,
as well as readability, across your whole code base. By the very nature of the rules applied from
elvis_core
it can also be considered a learning tool, by trying to generalize good practices and
allowing teams to adapt it to their own specific needs, while fostering discussions around code
conventions.
Some of the advantages of using elvis
are:
- enabling consistency in style across all your code base
- encouraging the development team to sit down and talk about code conventions
- allowing continuous monitoring of code quality
- helping developers avoid repeated mistakes that can be automatically detected
- providing homogenisation among different projects in a company, therefore facilitating project switching for developers, as well as allowing easier code sharing between projects
- learning, since some of the conventions it proposes are themselves the distilled result of working in very large code bases
To use elvis
as a standalone tool, you need to:
git clone https://github.com/inaka/elvis
cd elvis
rebar3 escriptize
export PATH=${PWD}/_build/default/bin:${PATH}
(to make the env. variable export more permanent add it to your shell's configuration file,
i.e. .bashrc
, .zshrc
, ...)
Now run it by calling elvis
(or elvis help
), and you should get to the Usage: elvis
instructions.
The most common use case is to cd
into a folder containing an elvis.config
file
and executing elvis rock
.
If you just execute elvis
with no arguments or options you'll get to the usage instructions
outlined in this README.
While you can get a more complete list of options by executing elvis help
, we try to keep them
documented below.
Adds <dir>
to the analysis' code path.
Outputs the list of commands under stood by elvis
.
Executes elvis
on source files that have changed since <branch>
or <commit>
.
Executes elvis
(with the specific configuration file) on the pre-commit hook Git-staged files.
Installs elvis
in your current Git repository, as a pre-commit hook.
Executes elvis
analysis on identified files. It will, by default, consider all the files
in the configuration (i.e. either elvis.config
or the path set by option --config
).
Allows providing the path to the config. file (by default elvis.config
is assumed).
Shows help information.
Doesn't stop analysis when erroring out on a file, if given a list of files to analyse.
Allows controlling the output format of the analysis' results.
The default value is colors
.
plain
will output results without colors.
parsable
will allow for consumption by systems (it's less readable for humans).
Allows analyzing files concurrently.
Use n
to set the desired number of parallel workers, or auto
to have the application choose
an appropriate value (based on the number of schedulers).
Allows suppressing all output. The exit code will still be non-0
if there are failing rules.
Allows verbose output.
Outputs the application's version.
elvis
is configured via elvis_core
's elvis.config
as detailed under
elvis_core / Configuration
.
A reference of all rules implemented in elvis
can be found in elvis_core
's RULES.md.
If you have implemented elvis
rule that are in your local repository or in one of
your dependencies, you can add these rule to your elvis.config
file and
tell elvis
where to find the .beam
that contains the compiled rule using
the --code-path
option.
For example, if the rule is in one of your dependencies, you can run elvis rock -p deps/elvis_rules/ebin -c elvis.config
.
elvis
can be used as a git
pre-commit hook
using the git-hook
command (installable via install git-hook
) as:
#!/bin/sh
elvis git-hook
This will have elvis
execute on staged files, as per its configuration.
If any rule fails, elvis
exits with a non-zero code, which signals to git
that the commit
shouldn't be made.
Note: your pre-commit hook script should be executable (i.e. by running
chmod +x .git/hooks/pre-commit
), otherwise git
won't be able to execute it.
elvis
can be used as a GitHub webhook for
pull request
(PR) events, by calling the elvis_webhook:event/1
function. This will add
a comment in each file and rule that is broken, analyzing only the files associated with the PR.
Since GitHub's API needs a valid username and password to allow the creation of
reviews on PRs, parameters github_user
and github_password
need to be
added to elvis
's configuration file (mind you that the credentials used
must be from an admin. of the repo or someone with permissions for requesting changes
to PRs).
The elvis_webhook:event/1
function takes a map containing the keys headers
and body
,
whose values should be the map of headers and the body from the GitHub's event
request.
Headers = #{<<"X-GitHub-Event">>, <<"pull_request">>},
Body = <<"{}">>, %% JSON data from GitHub's event.
Request = #{headers => Headers, body => Body},
elvis:webhook(Request).
The extension to the configuration is as follows:
[
{elvis, [
{config, [...]},
%% webhook configuration parameters
{github_user, "user"},
{github_password, "password"}
]}
].
You can generate local documentation with rebar3 ex_doc
and then access it with open doc/index.html
.
elvis
is a FOSS application, and as such contributions are welcome. Be sure to read
the contributing guide for more detailed information.
elvis
is licensed under the Apache License, Version 2.0.
elvis
got some of its inspiration from HoundCI.