revive/README.md

revive

Fast, configurable, extensible, flexible, and beautiful linter for Go.

Here's how revive is different from golint:

• Allows you to enable or disable rules using a configuration file.
• Allows you to configure the linting rules with a TOML file.
• Provides functionality to disable a specific rule or the entire linter for a file or a range of lines.
• Provides more rules compared to golint.
• Provides multiple formatters which let you customize the output.
• Allows you to customize the return code for the entire linter or based on the failure of only some rules.
• Open for addition of new rules or formatters.
• Faster. It runs the rules over each file in a separate goroutine.

Usage

Revive is configurable linter which you can fit your needs. By default you can use revive with the default configuration options. This way the linter will work the same way golint does.

Command Line Flags

Revive accepts three command line parameters:

• config - path to config file in TOML format.
• exclude - pattern for files/directories/packages to be excluded for linting. You can specify the files you want to exclude for linting either as package name (i.e. github.com/mgechev/revive), list them as individual files (i.e. file.go file2.go), directories (i.e. ./foo/...), or any combination of the three.
• formatter - formatter to be used for the output. The currently available formatters are:
  • default - will output the warnings the same way that golint does.
  • json - outputs the warnings in JSON format.
  • stylish - formats the warnings in a table.

Configuration

Revive can be configured with a TOML file

Default Configuration

The default configuration of revive can be found at defaults.toml. This will enable all rules available in golint and use their default configuration (i.e. the way they are hardcoded in golint).

revive -config defaults.toml github.com/mgechev/revive

This will use the configuration file defaults.toml, the default formatter, and will run linting over the github.com/mgechev/revive package.

Recommended Configuration

revive -config config.toml -formatter stylish github.com/mgechev/revive

This will use config.toml, the stylish formatter, and will run linting over the github.com/mgechev/revive package. Keep in mind that the stylish formatter performs aggregation and grouping of the discovered problems in your code. This means that the output will be buffered and printed at once. If you want a streaming output use default.

Available Rules

Name	Configuration	Description
cyclomatic	int (for instance, 9)	Sets restriction ot maximum Cyclomatic complexity.
context-key-type	Not configurable	Disallows the usage of basic types in context.WithValue.
dot-imports	Not configurable	Forbids . imports.
blank-imports	Not configurable	Disallows blank imports
context-arguments	Not configurable	context.Context should be the first argument of a function.
argument-limit	int (for instance, 4)	Specifies the maximum number of arguments a function can receive

Available Formatters

This section lists all the available formatters and provides a screenshot for each one.

Stylish

Extension

The tool can be extended with custom rules or formatters. This section contains additional information on how to implement such.

To extend the linter with a custom rule or a formatter you'll have to push it to this repository. This is due to the limited -buildmode=plugin support which works only on Linux (with known issues).

Custom Rule

Each rule needs to implement the lint.Rule interface:

type Rule interface {
	Name() string
	Apply(*File, Arguments) []Failure
}

The Arguments type is an alias of the type []interface{}. The arguments of the rule are passed from the configuration file.

Example

Let's suppose we have developed a rule called BanStructNameRule which disallow us to name a structure with given identifier. We can set the banned identifier by using the TOML configuration file:

[rule.ban-struct-name]
  arguments = ["Foo"]

With the snippet above we:

• Enable the rule with name ban-struct-name. The Name() method of our rule should return a string which matches ban-struct-name.
• Configure the rule with the argument Foo. The list of arguments will be passed to Apply(*File, Arguments) together with the target file we're linting currently.

A sample rule implementation can be found here.

Custom Formatter

Each formatter needs to implement the following interface:

type Formatter interface {
	Format(<-chan Failure, RulesConfig) (string, error)
	Name() string
}

The Format method accepts a channel of Failure instances and the configuration of the enabled rules. The Name() method should return a string different from the names of the already existing rules. This string is used when specifying the formatter when invoking the revive CLI tool.

For a sample formatter, take a look at this file.

License

MIT