Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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
- Host: GitHub
- URL: https://github.com/inaka/elvis
- Owner: inaka
- License: apache-2.0
- Created: 2014-06-23T18:24:33.000Z (over 10 years ago)
- Default Branch: master
- Last Pushed: 2024-05-22T08:48:11.000Z (6 months ago)
- Last Synced: 2024-05-22T09:46:09.419Z (6 months ago)
- Topics: elvis, erlang, hacktoberfest, style-checker
- Language: Erlang
- Homepage:
- Size: 767 KB
- Stars: 416
- Watchers: 57
- Forks: 87
- Open Issues: 7
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
- awesome-linters - elvis - Configurable Erlang linter written (Linters / Erlang)
- awesome-erlang - elvis - Erlang Style Reviewer. (Codebase Maintenance)
- awesome-ccamel - inaka/elvis - Erlang Style Reviewer (Erlang)
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 fromdepending 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/).