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.
Elvis also comes with shell completions.
Optionally, download and install:
- Bash completion from https://github.com/inaka/elvis/raw/master/priv/bash_completion/elvis
- Zsh completion from https://github.com/inaka/elvis/master/priv/zsh_completion/_elvis
depending on your preferred shell.
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-hookThis 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.