elvis

elvis, the Erlang style reviewer, is the command-line interface for elvis_core.

What is elvis?

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.

Advantages of using it

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

Installation

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.

Shell completion

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.

Usage

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.

Options

While you can get a more complete list of options by executing elvis help, we try to keep them documented below.

--code-path <dir> (-p <dir>)

Adds <dir> to the analysis' code path.

--commands

Outputs the list of commands under stood by elvis.

git-branch <branch | commit>

Executes elvis on source files that have changed since <branch> or <commit>.

git-hook

Executes elvis (with the specific configuration file) on the pre-commit hook Git-staged files.

install git-hook

Installs elvis in your current Git repository, as a pre-commit hook.

rock [file...]

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

--config <file> (-c <file>)

Allows providing the path to the config. file (by default elvis.config is assumed).

--help (-h)

Shows help information.

--keep-rocking (-k)

Doesn't stop analysis when erroring out on a file, if given a list of files to analyse.

--output-format <plain | colors | parsable>

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

--parallel <n | auto> (-P <n | auto>)

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

--quiet (-q)

Allows suppressing all output. The exit code will still be non-0 if there are failing rules.

--verbose (-V)

Allows verbose output.

--version (-v)

Outputs the application's version.

Configuration

elvis is configured via elvis_core's elvis.config as detailed under elvis_core / Configuration.

Rules

A reference of all rules implemented in elvis can be found in elvis_core's RULES.md.

User-defined rules

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.

As a Git hook

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.

As a webhook

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"}
  ]}
].

Documentation

You can generate local documentation with rebar3 ex_doc and then access it with open doc/index.html.

Contributing

elvis is a FOSS application, and as such contributions are welcome. Be sure to read the contributing guide for more detailed information.

License

elvis is licensed under the Apache License, Version 2.0.

Inspiration

elvis got some of its inspiration from HoundCI.