Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/inaka/elvis

Erlang Style Reviewer
https://github.com/inaka/elvis

elvis erlang hacktoberfest style-checker

Last synced: 27 days ago
JSON representation

Erlang Style Reviewer

Awesome Lists containing this project

README 

        
# `elvis` [![CI][build-badge]][elvis]



[elvis]: https://github.com/inaka/elvis

[build-badge]: https://github.com/inaka/elvis/workflows/build/badge.svg



![Elvis Presley dancing](https://www.reactiongifs.com/wp-content/uploads/2013/01/elvis-dance.gif)



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

[`elvis_core`](https://github.com/inaka/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:



```console

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 

- Zsh completion from 



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 ` (`-p `)



Adds `` to the analysis' code path.



### `--commands`



Outputs the list of commands under stood by `elvis`.



#### `git-branch `



Executes `elvis` on source files that have changed since `` or ``.



#### `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 ` (`-c `)



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 `



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 ` (`-P `)



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`](https://github.com/inaka/elvis_core?tab=readme-ov-file#configuration).



### Rules



A reference of all rules implemented in `elvis` can be found in `elvis_core`'s [RULES.md](https://github.com/inaka/elvis_core/blob/main/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](https://git-scm.com/book/en/Customizing-Git-Git-Hooks#Client-Side-Hooks)

using the `git-hook` command (installable via `install git-hook`) as:



```sh

#!/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](https://developer.github.com/v3/repos/hooks/) 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.



```erlang

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:



```erlang

[

  {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](CONTRIBUTING.md) for more detailed information.



## License



`elvis` is licensed under the [Apache License, Version 2.0](LICENSE).



## Inspiration



`elvis` got some of its inspiration from [HoundCI](https://houndci.com/).