fix markdownlint issues
This commit is contained in:
Denis Isaev
Isaev Denis
parent
21c9965f50
commit
71b940e3b2
2
.markdownlint.yaml
Normal file
2
.markdownlint.yaml
Normal file
@ -0,0 +1,2 @@
|
||||
MD013: false
|
||||
MD033: false
|
||||
136
README.md
136
README.md
@ -1,4 +1,5 @@
|
||||
# GolangCI-Lint
|
||||
|
||||
[](https://travis-ci.com/golangci/golangci-lint)
|
||||
[](https://golangci.com)
|
||||
|
||||
@ -28,7 +29,8 @@ Sponsored by [GolangCI.com](https://golangci.com): SaaS service for running lint
|
||||
* [Changelog](#changelog)
|
||||
* [Contact Information](#contact-information)
|
||||
|
||||
# Demo
|
||||
## Demo
|
||||
|
||||
<p align="center">
|
||||
<img src="./docs/demo.svg" width="100%">
|
||||
</p>
|
||||
@ -36,8 +38,10 @@ Sponsored by [GolangCI.com](https://golangci.com): SaaS service for running lint
|
||||
Short 1.5 min video demo of analyzing [beego](https://github.com/astaxie/beego).
|
||||
[](https://asciinema.org/a/183662)
|
||||
|
||||
# Install
|
||||
## CI Installation
|
||||
## Install
|
||||
|
||||
### CI Installation
|
||||
|
||||
Most installations are done for CI (travis, circleci etc). It's important to have reproducible CI:
|
||||
don't start to fail all builds at the same time. With golangci-lint this can happen if you
|
||||
use `--enable-all` and a new linter is added or even without `--enable-all`: when one upstream linter
|
||||
@ -48,6 +52,7 @@ Releases are available on the [releases page](https://github.com/golangci/golang
|
||||
|
||||
The recommended way to install golangci-lint (replace `vX.Y.Z` with the latest
|
||||
version from the [releases page](https://github.com/golangci/golangci-lint/releases)):
|
||||
|
||||
```bash
|
||||
# binary will be $GOPATH/bin/golangci-lint
|
||||
curl -sfL https://install.goreleaser.com/github.com/golangci/golangci-lint.sh | sh -s -- -b $GOPATH/bin vX.Y.Z
|
||||
@ -60,7 +65,9 @@ wget -O - -q https://install.goreleaser.com/github.com/golangci/golangci-lint.sh
|
||||
|
||||
golangci-lint --version
|
||||
```
|
||||
|
||||
As a fallback you can also use `raw.githubusercontent.com`
|
||||
|
||||
```bash
|
||||
# binary will be $GOPATH/bin/golangci-lint
|
||||
curl -sfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh| sh -s -- -b $GOPATH/bin vX.Y.Z
|
||||
@ -78,8 +85,10 @@ Periodically update version of golangci-lint: the project is under active develo
|
||||
and is constantly being improved. But please always check for newly found issues and
|
||||
update if needed.
|
||||
|
||||
## Local Installation
|
||||
### Local Installation
|
||||
|
||||
It's a not recommended for your CI pipeline. Only install like this for your local development environment.
|
||||
|
||||
```bash
|
||||
go get -u github.com/golangci/golangci-lint
|
||||
cd $GOPATH/src/github.com/golangci/golangci-lint/cmd/golangci-lint
|
||||
@ -87,12 +96,13 @@ go install -ldflags "-X 'main.version=$(git rev-parse --abbrev-ref HEAD)' -X 'ma
|
||||
```
|
||||
|
||||
You can also install it on OSX using brew:
|
||||
|
||||
```bash
|
||||
brew install golangci/tap/golangci-lint
|
||||
brew upgrade golangci/tap/golangci-lint
|
||||
```
|
||||
|
||||
# Trusted By
|
||||
## Trusted By
|
||||
|
||||
The following companies/products use golangci-lint:
|
||||
|
||||
@ -127,26 +137,31 @@ The following great projects use golangci-lint:
|
||||
* [posener/complete](https://github.com/posener/complete)
|
||||
* [y0ssar1an/q](https://github.com/y0ssar1an/q)
|
||||
|
||||
## Quick Start
|
||||
|
||||
# Quick Start
|
||||
To run golangci-lint execute:
|
||||
|
||||
```bash
|
||||
golangci-lint run
|
||||
```
|
||||
|
||||
It's an equivalent of executing:
|
||||
|
||||
```bash
|
||||
golangci-lint run ./...
|
||||
```
|
||||
|
||||
You can choose which directories and files to analyze:
|
||||
|
||||
```bash
|
||||
golangci-lint run dir1 dir2/... dir3/file1.go
|
||||
```
|
||||
|
||||
Directories are NOT analyzed recursively. To analyze them recursively append `/...` to their path.
|
||||
|
||||
GolangCI-Lint can be used with zero configuration. By default the following linters are enabled:
|
||||
```
|
||||
|
||||
```bash
|
||||
$ golangci-lint help linters
|
||||
Enabled by default linters:
|
||||
govet: Vet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string [fast: true]
|
||||
@ -162,7 +177,8 @@ typecheck: Like the front-end of a Go compiler, parses and type-checks Go code [
|
||||
```
|
||||
|
||||
and the following linters are disabled by default:
|
||||
```
|
||||
|
||||
```bash
|
||||
$ golangci-lint help linters
|
||||
...
|
||||
Disabled by default linters:
|
||||
@ -186,38 +202,44 @@ prealloc: Finds slice declarations that could potentially be preallocated [fast:
|
||||
```
|
||||
|
||||
Pass `-E/--enable` to enable linter and `-D/--disable` to disable:
|
||||
|
||||
```bash
|
||||
$ golangci-lint run --disable-all -E errcheck
|
||||
golangci-lint run --disable-all -E errcheck
|
||||
```
|
||||
|
||||
# Editor Integration
|
||||
## Editor Integration
|
||||
|
||||
1. [Go for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go).
|
||||
Recommended settings for VS Code are:
|
||||
|
||||
```json
|
||||
"go.lintTool":"golangci-lint",
|
||||
"go.lintFlags": [
|
||||
"--fast"
|
||||
]
|
||||
```
|
||||
|
||||
Using it in an editor without `--fast` can freeze your editor.
|
||||
Golangci-lint automatically discovers `.golangci.yml` config for edited file: you don't need to configure it in VS Code settings.
|
||||
|
||||
2. Sublime Text - [plugin](https://github.com/alecthomas/SublimeLinter-contrib-golang-cilint) for SublimeLinter.
|
||||
3. GoLand
|
||||
- Configure [File Watcher](https://www.jetbrains.com/help/go/settings-tools-file-watchers.html) with arguments `run --print-issued-lines=false $FileDir$`.
|
||||
- Predefined File Watcher will be added in [issue](https://youtrack.jetbrains.com/issue/GO-4574).
|
||||
* Configure [File Watcher](https://www.jetbrains.com/help/go/settings-tools-file-watchers.html) with arguments `run --print-issued-lines=false $FileDir$`.
|
||||
* Predefined File Watcher will be added in [issue](https://youtrack.jetbrains.com/issue/GO-4574).
|
||||
4. GNU Emacs
|
||||
- [Spacemacs](https://github.com/syl20bnr/spacemacs/blob/develop/layers/+lang/go/README.org#pre-requisites)
|
||||
- [flycheck checker](https://github.com/weijiangan/flycheck-golangci-lint).
|
||||
* [Spacemacs](https://github.com/syl20bnr/spacemacs/blob/develop/layers/+lang/go/README.org#pre-requisites)
|
||||
* [flycheck checker](https://github.com/weijiangan/flycheck-golangci-lint).
|
||||
5. Vim
|
||||
- vim-go open [issue](https://github.com/fatih/vim-go/issues/1841)
|
||||
- syntastic [merged pull request](https://github.com/vim-syntastic/syntastic/pull/2190) with golangci-lint support
|
||||
- ale [merged pull request](https://github.com/w0rp/ale/pull/1890) with golangci-lint support
|
||||
* vim-go open [issue](https://github.com/fatih/vim-go/issues/1841)
|
||||
* syntastic [merged pull request](https://github.com/vim-syntastic/syntastic/pull/2190) with golangci-lint support
|
||||
* ale [merged pull request](https://github.com/w0rp/ale/pull/1890) with golangci-lint support
|
||||
6. Atom - the [issue](https://github.com/joefitzgerald/go-plus/issues/819) for a go-plus.
|
||||
|
||||
# Comparison
|
||||
## `golangci-lint` vs `gometalinter`
|
||||
## Comparison
|
||||
|
||||
### `golangci-lint` vs `gometalinter`
|
||||
|
||||
GolangCI-Lint was created to fix the following issues with `gometalinter`:
|
||||
|
||||
1. Slow work: `gometalinter` usually works for minutes in average projects.
|
||||
**GolangCI-Lint works [2-7x times faster](#performance)** by [reusing work](#internals).
|
||||
2. Huge memory consumption: parallel linters don't share the same program representation and can consume
|
||||
@ -241,12 +263,14 @@ yet another utility to install and configure. With `golangci-lint` it's much eas
|
||||
end up with stale linters. It also complicates CI setup. GolangCI-Lint requires **no installation of linters**.
|
||||
8. **Yaml or toml config**. Gometalinter's JSON isn't convenient for config files.
|
||||
|
||||
## `golangci-lint` vs Running Linters Manually
|
||||
### `golangci-lint` vs Running Linters Manually
|
||||
|
||||
1. It will be much slower because `golangci-lint` runs all linters in parallel and shares 50-80% of linters work.
|
||||
2. It will have less control and more false-positives: some linters can't be properly configured without hacks.
|
||||
3. It will take more time because of different usages and need of tracking of versions of `n` linters.
|
||||
|
||||
# Performance
|
||||
## Performance
|
||||
|
||||
Benchmarks were executed on MacBook Pro (Retina, 13-inch, Late 2013), 2,4 GHz Intel Core i5, 8 GB 1600 MHz DDR3.
|
||||
It has 4 cores and concurrent linting as a default consuming all cores.
|
||||
Benchmark was run (and measured) automatically, see the code
|
||||
@ -254,8 +278,10 @@ Benchmark was run (and measured) automatically, see the code
|
||||
|
||||
We measure peak memory usage (RSS) by tracking of processes RSS every 5 ms.
|
||||
|
||||
## Comparison with gometalinter
|
||||
### Comparison with gometalinter
|
||||
|
||||
We compare golangci-lint and gometalinter in default mode, but explicitly enable all linters because of small differences in the default configuration.
|
||||
|
||||
```bash
|
||||
$ golangci-lint run --no-config --issues-exit-code=0 --deadline=30m \
|
||||
--disable-all --enable=deadcode --enable=gocyclo --enable=golint --enable=varcheck \
|
||||
@ -280,23 +306,23 @@ $ gometalinter --deadline=30m --vendor --cyclo-over=30 --dupl-threshold=150 \
|
||||
| go-ethereum, 250 kLoC | 33s | **5x** | 3.6GB | 0% |
|
||||
| go source (`$GOROOT/src`), 1300 kLoC | 2m45s | **2x** | 4.7GB | 0% |
|
||||
|
||||
|
||||
**On average golangci-lint is 4.6 times faster** than gometalinter. Maximum difference is in the
|
||||
self-repo: **7.5 times faster**, minimum difference is in terraform source code repo: 1.8 times faster.
|
||||
|
||||
On average golangci-lint consumes 26% less memory.
|
||||
|
||||
## Why golangci-lint is faster
|
||||
### Why golangci-lint is faster
|
||||
|
||||
Golangci-lint directly calls linters (no forking) and reuses 80% of work by parsing program only once.
|
||||
Read [this section](#internals) for details.
|
||||
|
||||
# Internals
|
||||
## Internals
|
||||
|
||||
1. Work sharing
|
||||
The key difference with gometalinter is that golangci-lint shares work between specific linters (golint, govet, ...).
|
||||
We don't fork to call specific linter but use its API.
|
||||
For small and medium projects 50-90% of work between linters can be reused.
|
||||
|
||||
* load `loader.Program` once
|
||||
|
||||
We load program (parsing all files and type-checking) only once for all linters. For the most of linters
|
||||
@ -332,14 +358,16 @@ Read [this section](#internals) for details.
|
||||
All linters are vendored in the `/vendor` folder: their version is fixed, they are builtin
|
||||
and you don't need to install them separately.
|
||||
|
||||
## Supported Linters
|
||||
|
||||
# Supported Linters
|
||||
To see a list of supported linters and which linters are enabled/disabled:
|
||||
```
|
||||
|
||||
```bash
|
||||
golangci-lint help linters
|
||||
```
|
||||
|
||||
## Enabled By Default Linters
|
||||
### Enabled By Default Linters
|
||||
|
||||
- [govet](https://golang.org/cmd/vet/) - Vet examines Go source code and reports suspicious constructs, such as Printf calls whose arguments do not align with the format string
|
||||
- [errcheck](https://github.com/kisielk/errcheck) - Errcheck is a program for checking for unchecked errors in go programs. These unchecked errors can be critical bugs in some cases
|
||||
- [staticcheck](https://staticcheck.io/) - Staticcheck is a go vet on steroids, applying a ton of static analysis checks
|
||||
@ -351,7 +379,8 @@ golangci-lint help linters
|
||||
- [deadcode](https://github.com/remyoudompheng/go-misc/tree/master/deadcode) - Finds unused code
|
||||
- typecheck - Like the front-end of a Go compiler, parses and type-checks Go code
|
||||
|
||||
## Disabled By Default Linters (`-E/--enable`)
|
||||
### Disabled By Default Linters (`-E/--enable`)
|
||||
|
||||
- [golint](https://github.com/golang/lint) - Golint differs from gofmt. Gofmt reformats Go source code, whereas golint prints out style mistakes
|
||||
- [gosec](https://github.com/securego/gosec) - Inspects source code for security problems
|
||||
- [interfacer](https://github.com/mvdan/interfacer) - Linter that suggests narrower interface types
|
||||
@ -370,18 +399,21 @@ golangci-lint help linters
|
||||
- [nakedret](https://github.com/alexkohler/nakedret) - Finds naked returns in functions greater than a specified function length
|
||||
- [prealloc](https://github.com/alexkohler/prealloc) - Finds slice declarations that could potentially be preallocated
|
||||
|
||||
# Configuration
|
||||
## Configuration
|
||||
|
||||
The config file has lower priority than command-line options. If the same bool/string/int option is provided on the command-line
|
||||
and in the config file, the option from command-line will be used.
|
||||
Slice options (e.g. list of enabled/disabled linters) are combined from the command-line and config file.
|
||||
|
||||
To see a list of enabled by your configuration linters:
|
||||
```
|
||||
|
||||
```bash
|
||||
golangci-lint linters
|
||||
```
|
||||
|
||||
## Command-Line Options
|
||||
```
|
||||
### Command-Line Options
|
||||
|
||||
```bash
|
||||
golangci-lint run -h
|
||||
Usage:
|
||||
golangci-lint run [flags]
|
||||
@ -455,11 +487,13 @@ Global Flags:
|
||||
|
||||
```
|
||||
|
||||
## Config File
|
||||
### Config File
|
||||
|
||||
GolangCI-Lint looks for config files in the following paths from the current working directory:
|
||||
- `.golangci.yml`
|
||||
- `.golangci.toml`
|
||||
- `.golangci.json`
|
||||
|
||||
* `.golangci.yml`
|
||||
* `.golangci.toml`
|
||||
* `.golangci.json`
|
||||
|
||||
GolangCI-Lint also searches for config files in all directories from the directory of the first analyzed path up to the root.
|
||||
To see which config file is being used and where it was sourced from run golangci-lint with `-v` option.
|
||||
@ -469,6 +503,7 @@ You can configure specific linters' options only within the config file (not the
|
||||
|
||||
There is a [`.golangci.example.yml`](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml) example
|
||||
config file with all supported options, their description and default value:
|
||||
|
||||
```yaml
|
||||
# This file contains all available configuration options
|
||||
# with their default values.
|
||||
@ -656,6 +691,7 @@ issues:
|
||||
|
||||
It's a [.golangci.yml](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml) config file of this repo: we enable more linters
|
||||
than the default and have more strict settings:
|
||||
|
||||
```yaml
|
||||
linters-settings:
|
||||
govet:
|
||||
@ -692,13 +728,16 @@ linters:
|
||||
- gosec
|
||||
```
|
||||
|
||||
# False Positives
|
||||
## False Positives
|
||||
|
||||
False positives are inevitable, but we did our best to reduce their count. For example, we have a default enabled set of [exclude patterns](#command-line-options). If a false positive occurred you have the following choices:
|
||||
|
||||
1. Exclude issue by text using command-line option `-e` or config option `issues.exclude`. It's helpful when you decided to ignore all issues of this type.
|
||||
2. Exclude this one issue by using special comment `//nolint[:linter1,linter2,...]` on issued line.
|
||||
Comment `//nolint` disables all issues reporting on this line. Comment e.g. `//nolint:govet` disables only govet issues for this line.
|
||||
If you would like to completely exclude all issues for some function prepend this comment
|
||||
above function:
|
||||
|
||||
```go
|
||||
//nolint
|
||||
func f() {
|
||||
@ -708,7 +747,8 @@ func f() {
|
||||
|
||||
Please create [GitHub Issues here](https://github.com/golangci/golangci-lint/issues/new) if you find any false positives. We will add it to the default exclude list if it's common or we will fix underlying linter.
|
||||
|
||||
# FAQ
|
||||
## FAQ
|
||||
|
||||
**How do you add a custom linter?**
|
||||
|
||||
You can integrate it yourself, see this [wiki page](https://github.com/golangci/golangci-lint/wiki/How-to-add-a-custom-linter) with documentation. Or you can create a [GitHub Issue](https://github.com/golangci/golangci-lint/issues/new) and we will integrate when time permits.
|
||||
@ -721,8 +761,10 @@ By doing this you won't create new issues in your code and can choose fix existi
|
||||
**How to use `golangci-lint` in CI (Continuous Integration)?**
|
||||
|
||||
You have 2 choices:
|
||||
|
||||
1. Use [GolangCI](https://golangci.com): this service is highly integrated with GitHub (issues are commented in the pull request) and uses a `golangci-lint` tool. For configuration use `.golangci.yml` (or toml/json).
|
||||
2. Use custom CI: just run `golangci-lint` in CI and check the exit code. If it's non-zero - fail the build. The main disadvantage is that you can't see issues in pull request code and would need to view the build log, then open the referenced source file to see the context.
|
||||
|
||||
We don't recommend vendoring `golangci-lint` in your repo: you will get troubles updating `golangci-lint`. Please, use recommended way to install with the shell script: it's very fast.
|
||||
|
||||
**Does I need to run `go install`?**
|
||||
@ -743,7 +785,7 @@ Golangci-lint versions <= v1.10.2 supported Go 1.9, 1.10, 1.11.
|
||||
Because the first run caches type information. All subsequent runs will be fast.
|
||||
Usually this options is used during development on local machine and compilation was already performed.
|
||||
|
||||
# Thanks
|
||||
## Thanks
|
||||
|
||||
Thanks to [alecthomas/gometalinter](https://github.com/alecthomas/gometalinter) for inspiration and amazing work.
|
||||
Thanks to [bradleyfalzon/revgrep](https://github.com/bradleyfalzon/revgrep) for cool diff tool.
|
||||
@ -766,7 +808,8 @@ Thanks to developers and authors of used linters:
|
||||
- [walle](https://github.com/walle)
|
||||
- [alexkohler](https://github.com/alexkohler)
|
||||
|
||||
# Future Plans
|
||||
## Future Plans
|
||||
|
||||
1. Upstream all changes of forked linters.
|
||||
2. Fully integrate all used linters: make a common interface and reuse 100% of what can be reused: AST traversal, packages preparation etc.
|
||||
3. Make it easy to write own linter/checker: it should take a minimum code, have perfect documentation, debugging and testing tooling.
|
||||
@ -778,11 +821,11 @@ Thanks to developers and authors of used linters:
|
||||
9. Automatic issues fixing (code rewrite, refactoring) where it's possible.
|
||||
10. Documentation for every issue type.
|
||||
|
||||
# Changelog
|
||||
## Changelog
|
||||
|
||||
There is the most valuable changes log:
|
||||
|
||||
## June 2018
|
||||
### June 2018
|
||||
|
||||
1. Add support of the next linters:
|
||||
* unparam
|
||||
@ -796,11 +839,12 @@ There is the most valuable changes log:
|
||||
4. Implement `--skip-files` and `--skip-dirs` options
|
||||
5. Checkstyle output format support
|
||||
|
||||
## May 2018
|
||||
### May 2018
|
||||
|
||||
1. Support GitHub Releases
|
||||
2. Installation via Homebrew and Docker
|
||||
|
||||
# Contact Information
|
||||
## Contact Information
|
||||
|
||||
You can contact the [author](https://github.com/jirfag) of GolangCI-Lint
|
||||
by [denis@golangci.com](mailto:denis@golangci.com).
|
||||
|
||||
136
README.tmpl.md
136
README.tmpl.md
@ -1,4 +1,5 @@
|
||||
# GolangCI-Lint
|
||||
|
||||
[](https://travis-ci.com/golangci/golangci-lint)
|
||||
[](https://golangci.com)
|
||||
|
||||
@ -28,7 +29,8 @@ Sponsored by [GolangCI.com](https://golangci.com): SaaS service for running lint
|
||||
* [Changelog](#changelog)
|
||||
* [Contact Information](#contact-information)
|
||||
|
||||
# Demo
|
||||
## Demo
|
||||
|
||||
<p align="center">
|
||||
<img src="./docs/demo.svg" width="100%">
|
||||
</p>
|
||||
@ -36,8 +38,10 @@ Sponsored by [GolangCI.com](https://golangci.com): SaaS service for running lint
|
||||
Short 1.5 min video demo of analyzing [beego](https://github.com/astaxie/beego).
|
||||
[](https://asciinema.org/a/183662)
|
||||
|
||||
# Install
|
||||
## CI Installation
|
||||
## Install
|
||||
|
||||
### CI Installation
|
||||
|
||||
Most installations are done for CI (travis, circleci etc). It's important to have reproducible CI:
|
||||
don't start to fail all builds at the same time. With golangci-lint this can happen if you
|
||||
use `--enable-all` and a new linter is added or even without `--enable-all`: when one upstream linter
|
||||
@ -48,6 +52,7 @@ Releases are available on the [releases page](https://github.com/golangci/golang
|
||||
|
||||
The recommended way to install golangci-lint (replace `vX.Y.Z` with the latest
|
||||
version from the [releases page](https://github.com/golangci/golangci-lint/releases)):
|
||||
|
||||
```bash
|
||||
# binary will be $GOPATH/bin/golangci-lint
|
||||
curl -sfL https://install.goreleaser.com/github.com/golangci/golangci-lint.sh | sh -s -- -b $GOPATH/bin vX.Y.Z
|
||||
@ -60,7 +65,9 @@ wget -O - -q https://install.goreleaser.com/github.com/golangci/golangci-lint.sh
|
||||
|
||||
golangci-lint --version
|
||||
```
|
||||
|
||||
As a fallback you can also use `raw.githubusercontent.com`
|
||||
|
||||
```bash
|
||||
# binary will be $GOPATH/bin/golangci-lint
|
||||
curl -sfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh| sh -s -- -b $GOPATH/bin vX.Y.Z
|
||||
@ -78,8 +85,10 @@ Periodically update version of golangci-lint: the project is under active develo
|
||||
and is constantly being improved. But please always check for newly found issues and
|
||||
update if needed.
|
||||
|
||||
## Local Installation
|
||||
### Local Installation
|
||||
|
||||
It's a not recommended for your CI pipeline. Only install like this for your local development environment.
|
||||
|
||||
```bash
|
||||
go get -u github.com/golangci/golangci-lint
|
||||
cd $GOPATH/src/github.com/golangci/golangci-lint/cmd/golangci-lint
|
||||
@ -87,12 +96,13 @@ go install -ldflags "-X 'main.version=$(git rev-parse --abbrev-ref HEAD)' -X 'ma
|
||||
```
|
||||
|
||||
You can also install it on OSX using brew:
|
||||
|
||||
```bash
|
||||
brew install golangci/tap/golangci-lint
|
||||
brew upgrade golangci/tap/golangci-lint
|
||||
```
|
||||
|
||||
# Trusted By
|
||||
## Trusted By
|
||||
|
||||
The following companies/products use golangci-lint:
|
||||
|
||||
@ -127,70 +137,82 @@ The following great projects use golangci-lint:
|
||||
* [posener/complete](https://github.com/posener/complete)
|
||||
* [y0ssar1an/q](https://github.com/y0ssar1an/q)
|
||||
|
||||
## Quick Start
|
||||
|
||||
# Quick Start
|
||||
To run golangci-lint execute:
|
||||
|
||||
```bash
|
||||
golangci-lint run
|
||||
```
|
||||
|
||||
It's an equivalent of executing:
|
||||
|
||||
```bash
|
||||
golangci-lint run ./...
|
||||
```
|
||||
|
||||
You can choose which directories and files to analyze:
|
||||
|
||||
```bash
|
||||
golangci-lint run dir1 dir2/... dir3/file1.go
|
||||
```
|
||||
|
||||
Directories are NOT analyzed recursively. To analyze them recursively append `/...` to their path.
|
||||
|
||||
GolangCI-Lint can be used with zero configuration. By default the following linters are enabled:
|
||||
```
|
||||
|
||||
```bash
|
||||
$ golangci-lint help linters
|
||||
{{.LintersCommandOutputEnabledOnly}}
|
||||
```
|
||||
|
||||
and the following linters are disabled by default:
|
||||
```
|
||||
|
||||
```bash
|
||||
$ golangci-lint help linters
|
||||
...
|
||||
{{.LintersCommandOutputDisabledOnly}}
|
||||
```
|
||||
|
||||
Pass `-E/--enable` to enable linter and `-D/--disable` to disable:
|
||||
|
||||
```bash
|
||||
$ golangci-lint run --disable-all -E errcheck
|
||||
golangci-lint run --disable-all -E errcheck
|
||||
```
|
||||
|
||||
# Editor Integration
|
||||
## Editor Integration
|
||||
|
||||
1. [Go for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go).
|
||||
Recommended settings for VS Code are:
|
||||
|
||||
```json
|
||||
"go.lintTool":"golangci-lint",
|
||||
"go.lintFlags": [
|
||||
"--fast"
|
||||
]
|
||||
```
|
||||
|
||||
Using it in an editor without `--fast` can freeze your editor.
|
||||
Golangci-lint automatically discovers `.golangci.yml` config for edited file: you don't need to configure it in VS Code settings.
|
||||
|
||||
2. Sublime Text - [plugin](https://github.com/alecthomas/SublimeLinter-contrib-golang-cilint) for SublimeLinter.
|
||||
3. GoLand
|
||||
- Configure [File Watcher](https://www.jetbrains.com/help/go/settings-tools-file-watchers.html) with arguments `run --print-issued-lines=false $FileDir$`.
|
||||
- Predefined File Watcher will be added in [issue](https://youtrack.jetbrains.com/issue/GO-4574).
|
||||
* Configure [File Watcher](https://www.jetbrains.com/help/go/settings-tools-file-watchers.html) with arguments `run --print-issued-lines=false $FileDir$`.
|
||||
* Predefined File Watcher will be added in [issue](https://youtrack.jetbrains.com/issue/GO-4574).
|
||||
4. GNU Emacs
|
||||
- [Spacemacs](https://github.com/syl20bnr/spacemacs/blob/develop/layers/+lang/go/README.org#pre-requisites)
|
||||
- [flycheck checker](https://github.com/weijiangan/flycheck-golangci-lint).
|
||||
* [Spacemacs](https://github.com/syl20bnr/spacemacs/blob/develop/layers/+lang/go/README.org#pre-requisites)
|
||||
* [flycheck checker](https://github.com/weijiangan/flycheck-golangci-lint).
|
||||
5. Vim
|
||||
- vim-go open [issue](https://github.com/fatih/vim-go/issues/1841)
|
||||
- syntastic [merged pull request](https://github.com/vim-syntastic/syntastic/pull/2190) with golangci-lint support
|
||||
- ale [merged pull request](https://github.com/w0rp/ale/pull/1890) with golangci-lint support
|
||||
* vim-go open [issue](https://github.com/fatih/vim-go/issues/1841)
|
||||
* syntastic [merged pull request](https://github.com/vim-syntastic/syntastic/pull/2190) with golangci-lint support
|
||||
* ale [merged pull request](https://github.com/w0rp/ale/pull/1890) with golangci-lint support
|
||||
6. Atom - the [issue](https://github.com/joefitzgerald/go-plus/issues/819) for a go-plus.
|
||||
|
||||
# Comparison
|
||||
## `golangci-lint` vs `gometalinter`
|
||||
## Comparison
|
||||
|
||||
### `golangci-lint` vs `gometalinter`
|
||||
|
||||
GolangCI-Lint was created to fix the following issues with `gometalinter`:
|
||||
|
||||
1. Slow work: `gometalinter` usually works for minutes in average projects.
|
||||
**GolangCI-Lint works [2-7x times faster](#performance)** by [reusing work](#internals).
|
||||
2. Huge memory consumption: parallel linters don't share the same program representation and can consume
|
||||
@ -214,12 +236,14 @@ yet another utility to install and configure. With `golangci-lint` it's much eas
|
||||
end up with stale linters. It also complicates CI setup. GolangCI-Lint requires **no installation of linters**.
|
||||
8. **Yaml or toml config**. Gometalinter's JSON isn't convenient for config files.
|
||||
|
||||
## `golangci-lint` vs Running Linters Manually
|
||||
### `golangci-lint` vs Running Linters Manually
|
||||
|
||||
1. It will be much slower because `golangci-lint` runs all linters in parallel and shares 50-80% of linters work.
|
||||
2. It will have less control and more false-positives: some linters can't be properly configured without hacks.
|
||||
3. It will take more time because of different usages and need of tracking of versions of `n` linters.
|
||||
|
||||
# Performance
|
||||
## Performance
|
||||
|
||||
Benchmarks were executed on MacBook Pro (Retina, 13-inch, Late 2013), 2,4 GHz Intel Core i5, 8 GB 1600 MHz DDR3.
|
||||
It has 4 cores and concurrent linting as a default consuming all cores.
|
||||
Benchmark was run (and measured) automatically, see the code
|
||||
@ -227,8 +251,10 @@ Benchmark was run (and measured) automatically, see the code
|
||||
|
||||
We measure peak memory usage (RSS) by tracking of processes RSS every 5 ms.
|
||||
|
||||
## Comparison with gometalinter
|
||||
### Comparison with gometalinter
|
||||
|
||||
We compare golangci-lint and gometalinter in default mode, but explicitly enable all linters because of small differences in the default configuration.
|
||||
|
||||
```bash
|
||||
$ golangci-lint run --no-config --issues-exit-code=0 --deadline=30m \
|
||||
--disable-all --enable=deadcode --enable=gocyclo --enable=golint --enable=varcheck \
|
||||
@ -253,23 +279,23 @@ $ gometalinter --deadline=30m --vendor --cyclo-over=30 --dupl-threshold=150 \
|
||||
| go-ethereum, 250 kLoC | 33s | **5x** | 3.6GB | 0% |
|
||||
| go source (`$GOROOT/src`), 1300 kLoC | 2m45s | **2x** | 4.7GB | 0% |
|
||||
|
||||
|
||||
**On average golangci-lint is 4.6 times faster** than gometalinter. Maximum difference is in the
|
||||
self-repo: **7.5 times faster**, minimum difference is in terraform source code repo: 1.8 times faster.
|
||||
|
||||
On average golangci-lint consumes 26% less memory.
|
||||
|
||||
## Why golangci-lint is faster
|
||||
### Why golangci-lint is faster
|
||||
|
||||
Golangci-lint directly calls linters (no forking) and reuses 80% of work by parsing program only once.
|
||||
Read [this section](#internals) for details.
|
||||
|
||||
# Internals
|
||||
## Internals
|
||||
|
||||
1. Work sharing
|
||||
The key difference with gometalinter is that golangci-lint shares work between specific linters (golint, govet, ...).
|
||||
We don't fork to call specific linter but use its API.
|
||||
For small and medium projects 50-90% of work between linters can be reused.
|
||||
|
||||
* load `loader.Program` once
|
||||
|
||||
We load program (parsing all files and type-checking) only once for all linters. For the most of linters
|
||||
@ -305,40 +331,48 @@ Read [this section](#internals) for details.
|
||||
All linters are vendored in the `/vendor` folder: their version is fixed, they are builtin
|
||||
and you don't need to install them separately.
|
||||
|
||||
## Supported Linters
|
||||
|
||||
# Supported Linters
|
||||
To see a list of supported linters and which linters are enabled/disabled:
|
||||
```
|
||||
|
||||
```bash
|
||||
golangci-lint help linters
|
||||
```
|
||||
|
||||
## Enabled By Default Linters
|
||||
### Enabled By Default Linters
|
||||
|
||||
{{.EnabledByDefaultLinters}}
|
||||
|
||||
## Disabled By Default Linters (`-E/--enable`)
|
||||
### Disabled By Default Linters (`-E/--enable`)
|
||||
|
||||
{{.DisabledByDefaultLinters}}
|
||||
|
||||
# Configuration
|
||||
## Configuration
|
||||
|
||||
The config file has lower priority than command-line options. If the same bool/string/int option is provided on the command-line
|
||||
and in the config file, the option from command-line will be used.
|
||||
Slice options (e.g. list of enabled/disabled linters) are combined from the command-line and config file.
|
||||
|
||||
To see a list of enabled by your configuration linters:
|
||||
```
|
||||
|
||||
```bash
|
||||
golangci-lint linters
|
||||
```
|
||||
|
||||
## Command-Line Options
|
||||
```
|
||||
### Command-Line Options
|
||||
|
||||
```bash
|
||||
golangci-lint run -h
|
||||
{{.RunHelpText}}
|
||||
```
|
||||
|
||||
## Config File
|
||||
### Config File
|
||||
|
||||
GolangCI-Lint looks for config files in the following paths from the current working directory:
|
||||
- `.golangci.yml`
|
||||
- `.golangci.toml`
|
||||
- `.golangci.json`
|
||||
|
||||
* `.golangci.yml`
|
||||
* `.golangci.toml`
|
||||
* `.golangci.json`
|
||||
|
||||
GolangCI-Lint also searches for config files in all directories from the directory of the first analyzed path up to the root.
|
||||
To see which config file is being used and where it was sourced from run golangci-lint with `-v` option.
|
||||
@ -348,23 +382,28 @@ You can configure specific linters' options only within the config file (not the
|
||||
|
||||
There is a [`.golangci.example.yml`](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml) example
|
||||
config file with all supported options, their description and default value:
|
||||
|
||||
```yaml
|
||||
{{.GolangciYamlExample}}
|
||||
```
|
||||
|
||||
It's a [.golangci.yml](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml) config file of this repo: we enable more linters
|
||||
than the default and have more strict settings:
|
||||
|
||||
```yaml
|
||||
{{.GolangciYaml}}
|
||||
```
|
||||
|
||||
# False Positives
|
||||
## False Positives
|
||||
|
||||
False positives are inevitable, but we did our best to reduce their count. For example, we have a default enabled set of [exclude patterns](#command-line-options). If a false positive occurred you have the following choices:
|
||||
|
||||
1. Exclude issue by text using command-line option `-e` or config option `issues.exclude`. It's helpful when you decided to ignore all issues of this type.
|
||||
2. Exclude this one issue by using special comment `//nolint[:linter1,linter2,...]` on issued line.
|
||||
Comment `//nolint` disables all issues reporting on this line. Comment e.g. `//nolint:govet` disables only govet issues for this line.
|
||||
If you would like to completely exclude all issues for some function prepend this comment
|
||||
above function:
|
||||
|
||||
```go
|
||||
//nolint
|
||||
func f() {
|
||||
@ -374,7 +413,8 @@ func f() {
|
||||
|
||||
Please create [GitHub Issues here](https://github.com/golangci/golangci-lint/issues/new) if you find any false positives. We will add it to the default exclude list if it's common or we will fix underlying linter.
|
||||
|
||||
# FAQ
|
||||
## FAQ
|
||||
|
||||
**How do you add a custom linter?**
|
||||
|
||||
You can integrate it yourself, see this [wiki page](https://github.com/golangci/golangci-lint/wiki/How-to-add-a-custom-linter) with documentation. Or you can create a [GitHub Issue](https://github.com/golangci/golangci-lint/issues/new) and we will integrate when time permits.
|
||||
@ -387,8 +427,10 @@ By doing this you won't create new issues in your code and can choose fix existi
|
||||
**How to use `golangci-lint` in CI (Continuous Integration)?**
|
||||
|
||||
You have 2 choices:
|
||||
|
||||
1. Use [GolangCI](https://golangci.com): this service is highly integrated with GitHub (issues are commented in the pull request) and uses a `golangci-lint` tool. For configuration use `.golangci.yml` (or toml/json).
|
||||
2. Use custom CI: just run `golangci-lint` in CI and check the exit code. If it's non-zero - fail the build. The main disadvantage is that you can't see issues in pull request code and would need to view the build log, then open the referenced source file to see the context.
|
||||
|
||||
We don't recommend vendoring `golangci-lint` in your repo: you will get troubles updating `golangci-lint`. Please, use recommended way to install with the shell script: it's very fast.
|
||||
|
||||
**Does I need to run `go install`?**
|
||||
@ -409,7 +451,7 @@ Golangci-lint versions <= v1.10.2 supported Go 1.9, 1.10, 1.11.
|
||||
Because the first run caches type information. All subsequent runs will be fast.
|
||||
Usually this options is used during development on local machine and compilation was already performed.
|
||||
|
||||
# Thanks
|
||||
## Thanks
|
||||
|
||||
Thanks to [alecthomas/gometalinter](https://github.com/alecthomas/gometalinter) for inspiration and amazing work.
|
||||
Thanks to [bradleyfalzon/revgrep](https://github.com/bradleyfalzon/revgrep) for cool diff tool.
|
||||
@ -417,7 +459,8 @@ Thanks to [bradleyfalzon/revgrep](https://github.com/bradleyfalzon/revgrep) for
|
||||
Thanks to developers and authors of used linters:
|
||||
{{.ThanksList}}
|
||||
|
||||
# Future Plans
|
||||
## Future Plans
|
||||
|
||||
1. Upstream all changes of forked linters.
|
||||
2. Fully integrate all used linters: make a common interface and reuse 100% of what can be reused: AST traversal, packages preparation etc.
|
||||
3. Make it easy to write own linter/checker: it should take a minimum code, have perfect documentation, debugging and testing tooling.
|
||||
@ -429,11 +472,11 @@ Thanks to developers and authors of used linters:
|
||||
9. Automatic issues fixing (code rewrite, refactoring) where it's possible.
|
||||
10. Documentation for every issue type.
|
||||
|
||||
# Changelog
|
||||
## Changelog
|
||||
|
||||
There is the most valuable changes log:
|
||||
|
||||
## June 2018
|
||||
### June 2018
|
||||
|
||||
1. Add support of the next linters:
|
||||
* unparam
|
||||
@ -447,11 +490,12 @@ There is the most valuable changes log:
|
||||
4. Implement `--skip-files` and `--skip-dirs` options
|
||||
5. Checkstyle output format support
|
||||
|
||||
## May 2018
|
||||
### May 2018
|
||||
|
||||
1. Support GitHub Releases
|
||||
2. Installation via Homebrew and Docker
|
||||
|
||||
# Contact Information
|
||||
## Contact Information
|
||||
|
||||
You can contact the [author](https://github.com/jirfag) of GolangCI-Lint
|
||||
by [denis@golangci.com](mailto:denis@golangci.com).
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user