github.com/nakabonne/golangci-lint@v1.26.1/README.tmpl.md (about) 1 # GolangCI-Lint 2 3 [![Build Status](https://travis-ci.com/golangci/golangci-lint.svg?branch=master)](https://travis-ci.com/golangci/golangci-lint) 4 [![GolangCI](https://golangci.com/badges/github.com/golangci/golangci-lint.svg)](https://golangci.com) 5 [![License](https://img.shields.io/github/license/golangci/golangci-lint)](/LICENSE) 6 [![Release](https://img.shields.io/github/release/golangci/golangci-lint.svg)](https://github.com/golangci/golangci-lint/releases/latest) 7 [![Docker](https://img.shields.io/docker/pulls/golangci/golangci-lint)](https://hub.docker.com/r/golangci/golangci-lint) 8 9 GolangCI-Lint is a linters aggregator. It's fast: on average [5 times faster](#performance) than gometalinter. 10 It's [easy to integrate and use](#command-line-options), has [nice output](#quick-start) and has a minimum number of false positives. It supports go modules. 11 12 GolangCI-Lint has [integrations](#editor-integration) with VS Code, GNU Emacs, Sublime Text. 13 14 Follow the news and releases on our [twitter](https://twitter.com/golangci) and our [blog](https://medium.com/golangci). 15 16 Sponsored by [GolangCI.com](https://golangci.com): SaaS service for running linters on GitHub pull requests. Free for Open Source. 17 18 <a href="https://golangci.com/"><img src="docs/go.png" width="250px"></a> 19 20 - [GolangCI-Lint](#golangci-lint) 21 - [Demo](#demo) 22 - [Install](#install) 23 - [Binary](#binary) 24 - [macOS](#macos) 25 - [Docker](#docker) 26 - [Go](#go) 27 - [Trusted By](#trusted-by) 28 - [Quick Start](#quick-start) 29 - [Editor Integration](#editor-integration) 30 - [Shell Completion](#shell-completion) 31 - [macOS](#macos-1) 32 - [Linux](#linux) 33 - [Comparison](#comparison) 34 - [`golangci-lint` vs `gometalinter`](#golangci-lint-vs-gometalinter) 35 - [`golangci-lint` vs Running Linters Manually](#golangci-lint-vs-running-linters-manually) 36 - [Performance](#performance) 37 - [Comparison with gometalinter](#comparison-with-gometalinter) 38 - [Why golangci-lint is faster](#why-golangci-lint-is-faster) 39 - [Memory Usage of Golangci-lint](#memory-usage-of-golangci-lint) 40 - [Internals](#internals) 41 - [Supported Linters](#supported-linters) 42 - [Enabled By Default Linters](#enabled-by-default-linters) 43 - [Disabled By Default Linters (`-E/--enable`)](#disabled-by-default-linters--e--enable) 44 - [Configuration](#configuration) 45 - [Command-Line Options](#command-line-options) 46 - [Config File](#config-file) 47 - [False Positives](#false-positives) 48 - [Nolint](#nolint) 49 - [FAQ](#faq) 50 - [Thanks](#thanks) 51 - [Changelog](#changelog) 52 - [Debug](#debug) 53 - [Future Plans](#future-plans) 54 - [Contact Information](#contact-information) 55 - [License Scan](#license-scan) 56 57 ## Demo 58 59 <p align="center"> 60 <img src="./docs/demo.svg" width="100%"> 61 </p> 62 63 Short 1.5 min video demo of analyzing [beego](https://github.com/astaxie/beego). 64 [![asciicast](https://asciinema.org/a/183662.png)](https://asciinema.org/a/183662) 65 66 ## Install 67 68 ### Binary 69 70 Most installations are done for CI (e.g. Travis CI, CircleCI). It's important to have reproducible CI: 71 don't start to fail all builds at the same time. With golangci-lint this can happen if you 72 use deprecated option `--enable-all` and a new linter is added or even without `--enable-all`: when one upstream linter is upgraded. 73 74 It's highly recommended to install a specific version of golangci-lint available on the [releases page](https://github.com/golangci/golangci-lint/releases). 75 76 Here is the recommended way to install golangci-lint {{.LatestVersion}}: 77 78 ```bash 79 # binary will be $(go env GOPATH)/bin/golangci-lint 80 curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s -- -b $(go env GOPATH)/bin {{.LatestVersion}} 81 82 # or install it into ./bin/ 83 curl -sSfL https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s {{.LatestVersion}} 84 85 # In alpine linux (as it does not come with curl by default) 86 wget -O- -nv https://raw.githubusercontent.com/golangci/golangci-lint/master/install.sh | sh -s {{.LatestVersion}} 87 88 golangci-lint --version 89 ``` 90 91 It is advised that you periodically update version of golangci-lint as the project is under active development 92 and is constantly being improved. For any problems with golangci-lint, check out recent [GitHub issues](https://github.com/golangci/golangci-lint/issues) and update if needed. 93 94 ### macOS 95 96 You can also install a binary release on macOS using [brew](https://brew.sh/): 97 98 ```bash 99 brew install golangci/tap/golangci-lint 100 brew upgrade golangci/tap/golangci-lint 101 ``` 102 103 ### Docker 104 105 ```bash 106 docker run --rm -v $(pwd):/app -w /app golangci/golangci-lint:{{.LatestVersion}} golangci-lint run -v 107 ``` 108 109 ### Go 110 111 Go source installations are supported for the two most recent Go releases. 112 113 ```bash 114 GO111MODULE=on go get github.com/golangci/golangci-lint/cmd/golangci-lint@{{.LatestVersion}} 115 ``` 116 117 ## Trusted By 118 119 The following companies/products use golangci-lint: 120 121 * [Google](https://github.com/GoogleContainerTools/skaffold) 122 * [Facebook](https://github.com/facebookincubator/fbender) 123 * [Red Hat OpenShift](https://github.com/openshift/telemeter) 124 * [Yahoo](https://github.com/yahoo/yfuzz) 125 * [IBM](https://github.com/ibm-developer/ibm-cloud-env-golang) 126 * [Intuit](https://github.com/intuit) 127 * [Xiaomi](https://github.com/XiaoMi/soar) 128 * [Baidu](https://github.com/baidu/bfe) 129 * [Samsung](https://github.com/samsung-cnct/cluster-api-provider-ssh) 130 * [Arduino](https://github.com/arduino/arduino-cli) 131 * [Eclipse Foundation](https://github.com/eclipse/che-go-jsonrpc) 132 * [WooCart](https://github.com/woocart/gsutil) 133 * [Percona](https://github.com/percona/pmm-managed) 134 * [Serverless](https://github.com/serverless/event-gateway) 135 * [ScyllaDB](https://github.com/scylladb/gocqlx) 136 * [NixOS](https://github.com/NixOS/nixpkgs-channels) 137 * [The New York Times](https://github.com/NYTimes/encoding-wrapper) 138 * [Istio](https://github.com/istio/istio) 139 * [SoundCloud](https://github.com/soundcloud/periskop) 140 * [Mattermost](https://github.com/mattermost/mattermost-server) 141 142 The following great projects use golangci-lint: 143 144 * [alecthomas/participle](https://github.com/alecthomas/participle) 145 * [asobti/kube-monkey](https://github.com/asobti/kube-monkey) 146 * [banzaicloud/pipeline](https://github.com/banzaicloud/pipeline) 147 * [caicloud/cyclone](https://github.com/caicloud/cyclone) 148 * [getantibody/antibody](https://github.com/getantibody/antibody) 149 * [goreleaser/goreleaser](https://github.com/goreleaser/goreleaser) 150 * [go-swagger/go-swagger](https://github.com/go-swagger/go-swagger) 151 * [kubeedge/kubeedge](https://github.com/kubeedge/kubeedge) 152 * [kubernetes-sigs/kustomize](https://github.com/kubernetes-sigs/kustomize) 153 * [dunglas/mercure](https://github.com/dunglas/mercure) 154 * [posener/complete](https://github.com/posener/complete) 155 * [segmentio/terraform-docs](https://github.com/segmentio/terraform-docs) 156 * [tsuru/tsuru](https://github.com/tsuru/tsuru) 157 * [twpayne/chezmoi](https://github.com/twpayne/chezmoi) 158 * [virtual-kubelet/virtual-kubelet](https://github.com/virtual-kubelet/virtual-kubelet) 159 * [xenolf/lego](https://github.com/xenolf/lego) 160 * [y0ssar1an/q](https://github.com/y0ssar1an/q) 161 162 ## Quick Start 163 164 To run golangci-lint execute: 165 166 ```bash 167 golangci-lint run 168 ``` 169 170 It's an equivalent of executing: 171 172 ```bash 173 golangci-lint run ./... 174 ``` 175 176 You can choose which directories and files to analyze: 177 178 ```bash 179 golangci-lint run dir1 dir2/... dir3/file1.go 180 ``` 181 182 Directories are NOT analyzed recursively. To analyze them recursively append `/...` to their path. 183 184 GolangCI-Lint can be used with zero configuration. By default the following linters are enabled: 185 186 ```bash 187 $ golangci-lint help linters 188 {{.LintersCommandOutputEnabledOnly}} 189 ``` 190 191 and the following linters are disabled by default: 192 193 ```bash 194 $ golangci-lint help linters 195 ... 196 {{.LintersCommandOutputDisabledOnly}} 197 ``` 198 199 Pass `-E/--enable` to enable linter and `-D/--disable` to disable: 200 201 ```bash 202 golangci-lint run --disable-all -E errcheck 203 ``` 204 205 ## Editor Integration 206 207 1. [Go for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go). 208 Recommended settings for VS Code are: 209 210 ```json 211 "go.lintTool":"golangci-lint", 212 "go.lintFlags": [ 213 "--fast" 214 ] 215 ``` 216 217 Using it in an editor without `--fast` can freeze your editor. 218 Golangci-lint automatically discovers `.golangci.yml` config for edited file: you don't need to configure it in VS Code settings. 219 2. Sublime Text - [plugin](https://github.com/alecthomas/SublimeLinter-contrib-golang-cilint) for SublimeLinter. 220 3. GoLand 221 * Add [File Watcher](https://www.jetbrains.com/help/go/settings-tools-file-watchers.html) using existing `golangci-lint` template. 222 * If your version of GoLand does not have the `golangci-lint` [File Watcher](https://www.jetbrains.com/help/go/settings-tools-file-watchers.html) template you can configure your own and use arguments `run --disable=typecheck $FileDir$`. 223 4. GNU Emacs 224 * [Spacemacs](https://github.com/syl20bnr/spacemacs/blob/develop/layers/+lang/go/README.org#pre-requisites) 225 * [flycheck checker](https://github.com/weijiangan/flycheck-golangci-lint). 226 5. Vim 227 * [vim-go](https://github.com/fatih/vim-go) 228 * syntastic [merged pull request](https://github.com/vim-syntastic/syntastic/pull/2190) with golangci-lint support 229 * ale [merged pull request](https://github.com/w0rp/ale/pull/1890) with golangci-lint support 230 6. Atom - [go-plus](https://atom.io/packages/go-plus) supports golangci-lint. 231 232 ## Shell Completion 233 234 `golangci-lint` can generate bash completion file. 235 236 ### macOS 237 238 There are two versions of `bash-completion`, v1 and v2. V1 is for Bash 3.2 (which is the default on macOS), and v2 is for Bash 4.1+. The `golangci-lint` completion script doesn’t work correctly with bash-completion v1 and Bash 3.2. It requires bash-completion v2 and Bash 4.1+. Thus, to be able to correctly use `golangci-lint` completion on macOS, you have to install and use Bash 4.1+ ([instructions](https://itnext.io/upgrading-bash-on-macos-7138bd1066ba)). The following instructions assume that you use Bash 4.1+ (that is, any Bash version of 4.1 or newer). 239 240 Install `bash-completion v2`: 241 242 ```bash 243 brew install bash-completion@2 244 echo 'export BASH_COMPLETION_COMPAT_DIR="/usr/local/etc/bash_completion.d"' >>~/.bashrc 245 echo '[[ -r "/usr/local/etc/profile.d/bash_completion.sh" ]] && . "/usr/local/etc/profile.d/bash_completion.sh"' >>~/.bashrc 246 exec bash # reload and replace (if it was updated) shell 247 type _init_completion && echo "completion is OK" # verify that bash-completion v2 is correctly installed 248 ``` 249 250 Add `golangci-lint` bash completion: 251 252 ```bash 253 echo 'source <(golangci-lint completion bash)' >>~/.bashrc 254 source ~/.bashrc 255 ``` 256 257 ### Linux 258 259 See [kubectl instructions](https://kubernetes.io/docs/tasks/tools/install-kubectl/#enabling-shell-autocompletion) and don't forget to replace `kubectl` with `golangci-lint`. 260 261 ## Comparison 262 263 ### `golangci-lint` vs `gometalinter` 264 265 GolangCI-Lint was created to fix the following issues with `gometalinter`: 266 267 1. Slow work: `gometalinter` usually works for minutes in average projects. 268 **GolangCI-Lint works [2-7x times faster](#performance)** by [reusing work](#internals). 269 2. Huge memory consumption: parallel linters don't share the same program representation and can consume 270 `n` times more memory (`n` - concurrency). GolangCI-Lint fixes it by sharing representation and **consumes 26% less memory**. 271 3. Doesn't use real bounded concurrency: if you set it to `n` it can take up to `n*n` threads because of 272 forced threads in specific linters. `gometalinter` can't do anything about it because it runs linters as 273 black boxes in forked processes. In GolangCI-Lint we run all linters in one process and completely control 274 them. Configured concurrency will be correctly bounded. 275 This issue is important because you often want to set concurrency to the CPUs count minus one to 276 ensure you **do not freeze your PC** and be able to work on it while analyzing code. 277 4. Lack of nice output. We like how the `gcc` and `clang` compilers format their warnings: **using colors, 278 printing warning lines and showing the position in line**. 279 5. Too many issues. GolangCI-Lint cuts a lot of issues by using default exclude list of common false-positives. 280 By default, it has enabled **smart issues processing**: merge multiple issues for one line, merge issues with the 281 same text or from the same linter. All of these smart processors can be configured by the user. 282 6. Integration into large codebases. A good way to start using linters in a large project is not to fix a plethora 283 of existing issues, but to set up CI and **fix only issues in new commits**. You can use `revgrep` for it, but it's 284 yet another utility to install and configure. With `golangci-lint` it's much easier: `revgrep` is already built into 285 `golangci-lint` and you can use it with one option (`-n, --new` or `--new-from-rev`). 286 7. Installation. With `gometalinter`, you need to run a linters installation step. It's easy to forget this step and 287 end up with stale linters. It also complicates CI setup. GolangCI-Lint requires **no installation of linters**. 288 8. **Yaml or toml config**. Gometalinter's JSON isn't convenient for config files. 289 290 ### `golangci-lint` vs Running Linters Manually 291 292 1. It will be much slower because `golangci-lint` runs all linters in parallel and shares 50-80% of linters work. 293 2. It will have less control and more false-positives: some linters can't be properly configured without hacks. 294 3. It will take more time because of different usages and need of tracking of versions of `n` linters. 295 296 ## Performance 297 298 Benchmarks were executed on MacBook Pro (Retina, 13-inch, Late 2013), 2,4 GHz Intel Core i5, 8 GB 1600 MHz DDR3. 299 It has 4 cores and concurrent linting as a default consuming all cores. 300 Benchmark was run (and measured) automatically, see the code 301 [here](https://github.com/golangci/golangci-lint/blob/master/test/bench/bench_test.go) (`BenchmarkWithGometalinter`). 302 303 We measure peak memory usage (RSS) by tracking of processes RSS every 5 ms. 304 305 ### Comparison with gometalinter 306 307 We compare golangci-lint and gometalinter in default mode, but explicitly enable all linters because of small differences in the default configuration. 308 309 ```bash 310 $ golangci-lint run --no-config --issues-exit-code=0 --timeout=30m \ 311 --disable-all --enable=deadcode --enable=gocyclo --enable=golint --enable=varcheck \ 312 --enable=structcheck --enable=maligned --enable=errcheck --enable=dupl --enable=ineffassign \ 313 --enable=interfacer --enable=unconvert --enable=goconst --enable=gosec --enable=megacheck 314 $ gometalinter --deadline=30m --vendor --cyclo-over=30 --dupl-threshold=150 \ 315 --exclude=<default golangci-lint excludes> --skip=testdata --skip=builtin \ 316 --disable-all --enable=deadcode --enable=gocyclo --enable=golint --enable=varcheck \ 317 --enable=structcheck --enable=maligned --enable=errcheck --enable=dupl --enable=ineffassign \ 318 --enable=interfacer --enable=unconvert --enable=goconst --enable=gosec --enable=megacheck 319 ./... 320 ``` 321 322 | Repository | GolangCI Time | GolangCI Is Faster than Gometalinter | GolangCI Memory | GolangCI eats less memory than Gometalinter | 323 | ---------- | ------------- | ------------------------------------ | --------------- | ------------------------------------------- | 324 | gometalinter repo, 4 kLoC | 6s | **6.4x** | 0.7GB | 33% | 325 | self-repo, 4 kLoC | 12s | **7.5x** | 1.2GB | 41% | 326 | beego, 50 kLoC | 10s | **4.2x** | 1.4GB | 9% | 327 | hugo, 70 kLoC | 15s | **6.1x** | 1.6GB | 44% | 328 | consul, 127 kLoC | 58s | **4x** | 2.7GB | 41% | 329 | terraform, 190 kLoC | 2m13s | **1.6x** | 4.8GB | 0% | 330 | go-ethereum, 250 kLoC | 33s | **5x** | 3.6GB | 0% | 331 | go source (`$GOROOT/src`), 1300 kLoC | 2m45s | **2x** | 4.7GB | 0% | 332 333 **On average golangci-lint is 4.6 times faster** than gometalinter. Maximum difference is in the 334 self-repo: **7.5 times faster**, minimum difference is in terraform source code repo: 1.8 times faster. 335 336 On average golangci-lint consumes 26% less memory. 337 338 ### Why golangci-lint is faster 339 340 Golangci-lint directly calls linters (no forking) and reuses 80% of work by parsing program only once. 341 Read [this section](#internals) for details. 342 343 ### Memory Usage of Golangci-lint 344 345 A trade-off between memory usage and execution time can be controlled by [`GOGC`](https://golang.org/pkg/runtime/#hdr-Environment_Variables) environment variable. 346 Less `GOGC` values trigger garbage collection more frequently and golangci-lint consumes less memory and more CPU. Below is the trade-off table for running on this repo: 347 348 |`GOGC`|Peak Memory, GB|Executon Time, s| 349 |------|---------------|----------------| 350 |`5` |1.1 |60 | 351 |`10` |1.1 |34 | 352 |`20` |1.3 |25 | 353 |`30` |1.6 |20.2 | 354 |`50` |2.0 |17.1 | 355 |`80` |2.2 |14.1 | 356 |`100` (default)|2.2 |13.8 | 357 |`off` |3.2 |9.3 | 358 359 ## Internals 360 361 1. Work sharing 362 The key difference with gometalinter is that golangci-lint shares work between specific linters (golint, govet, ...). 363 We don't fork to call specific linter but use its API. 364 For small and medium projects 50-90% of work between linters can be reused. 365 366 * load `[]*packages.Package` by `go/packages` once 367 368 We load program (parsing all files and type-checking) only once for all linters. For the most of linters 369 it's the most heavy operation: it takes 5 seconds on 8 kLoC repo and 11 seconds on `$GOROOT/src`. 370 * build `ssa.Program` once 371 372 Some linters (megacheck, interfacer, unparam) work on SSA representation. 373 Building of this representation takes 1.5 seconds on 8 kLoC repo and 6 seconds on `$GOROOT/src`. 374 375 * parse source code and build AST once 376 377 Parsing one source file takes 200 us on average. Parsing of all files in `$GOROOT/src` takes 2 seconds. 378 Currently we parse each file more than once because it's not the bottleneck. But we already save a lot of 379 extra parsing. We're planning to parse each file only once. 380 381 * walk files and directories once 382 383 It takes 300-1000 ms for `$GOROOT/src`. 384 2. Smart linters scheduling 385 386 We schedule linters by a special algorithm which takes estimated execution time into account. It allows 387 to save 10-30% of time when one of heavy linters (megacheck etc) is enabled. 388 389 3. Don't fork to run shell commands 390 391 All linters has their version fixed with go modules, they are builtin 392 and you don't need to install them separately. 393 394 ## Supported Linters 395 396 To see a list of supported linters and which linters are enabled/disabled: 397 398 ```bash 399 golangci-lint help linters 400 ``` 401 402 ### Enabled By Default Linters 403 404 {{.EnabledByDefaultLinters}} 405 406 ### Disabled By Default Linters (`-E/--enable`) 407 408 {{.DisabledByDefaultLinters}} 409 410 ## Configuration 411 412 The config file has lower priority than command-line options. If the same bool/string/int option is provided on the command-line 413 and in the config file, the option from command-line will be used. 414 Slice options (e.g. list of enabled/disabled linters) are combined from the command-line and config file. 415 416 To see a list of enabled by your configuration linters: 417 418 ```bash 419 golangci-lint linters 420 ``` 421 422 ### Command-Line Options 423 424 ```bash 425 golangci-lint run -h 426 {{.RunHelpText}} 427 ``` 428 429 ### Config File 430 431 GolangCI-Lint looks for config files in the following paths from the current working directory: 432 433 * `.golangci.yml` 434 * `.golangci.toml` 435 * `.golangci.json` 436 437 GolangCI-Lint also searches for config files in all directories from the directory of the first analyzed path up to the root. 438 To see which config file is being used and where it was sourced from run golangci-lint with `-v` option. 439 440 Config options inside the file are identical to command-line options. 441 You can configure specific linters' options only within the config file (not the command-line). 442 443 There is a [`.golangci.example.yml`](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml) example 444 config file with all supported options, their description and default value: 445 446 ```yaml 447 {{.GolangciYamlExample}} 448 ``` 449 450 It's a [.golangci.yml](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml) config file of this repo: we enable more linters 451 than the default and have more strict settings: 452 453 ```yaml 454 {{.GolangciYaml}} 455 ``` 456 457 ## Custom Linters 458 Some people and organizations may choose to have custom made linters run as a part of golangci-lint. That functionality 459 is supported through go's plugin library. 460 461 ### Create a Copy of `golangci-lint` that Can Run with Plugins 462 In order to use plugins, you'll need a golangci-lint executable that can run them. The normal version of this project 463 is built with the vendors option, which breaks plugins that have overlapping dependencies. 464 465 1. Download [golangci-lint](https://github.com/golangci/golangci-lint) source code 466 2. From the projects root directory, run `make vendor_free_build` 467 3. Copy the `golangci-lint` executable that was created to your path, project, or other location 468 469 ### Configure Your Project for Linting 470 If you already have a linter plugin available, you can follow these steps to define it's usage in a projects 471 `.golangci.yml` file. An example linter can be found at [here](https://github.com/golangci/example-plugin-linter). If you're looking for 472 instructions on how to configure your own custom linter, they can be found further down. 473 474 1. If the project you want to lint does not have one already, copy the [.golangci.yml](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml) to the root directory. 475 2. Adjust the yaml to appropriate `linters-settings:custom` entries as so: 476 ``` 477 linters-settings: 478 custom: 479 example: 480 path: /example.so 481 description: The description of the linter 482 original-url: github.com/golangci/example-linter 483 ``` 484 485 That is all the configuration that is required to run a custom linter in your project. Custom linters are enabled by default, 486 but abide by the same rules as other linters. If the disable all option is specified either on command line or in 487 `.golangci.yml` files `linters:disable-all: true`, custom linters will be disabled; they can be re-enabled by adding them 488 to the `linters:enable` list, or providing the enabled option on the command line, `golangci-lint run -Eexample`. 489 490 ### To Create Your Own Custom Linter 491 492 Your linter must implement one or more `golang.org/x/tools/go/analysis.Analyzer` structs. 493 Your project should also use `go.mod`. All versions of libraries that overlap `golangci-lint` (including replaced 494 libraries) MUST be set to the same version as `golangci-lint`. You can see the versions by running `go version -m golangci-lint`. 495 496 You'll also need to create a go file like `plugin/example.go`. This MUST be in the package `main`, and define a 497 variable of name `AnalyzerPlugin`. The `AnalyzerPlugin` instance MUST implement the following interface: 498 ``` 499 type AnalyzerPlugin interface { 500 GetAnalyzers() []*analysis.Analyzer 501 } 502 ``` 503 The type of `AnalyzerPlugin` is not important, but is by convention `type analyzerPlugin struct {}`. See 504 [plugin/example.go](https://github.com/golangci/example-plugin-linter/plugin/example.go) for more info. 505 506 To build the plugin, from the root project directory, run `go build -buildmode=plugin plugin/example.go`. This will create a plugin `*.so` 507 file that can be copied into your project or another well known location for usage in golangci-lint. 508 509 ## False Positives 510 511 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: 512 513 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. Also, you can use `issues.exclude-rules` config option for per-path or per-linter configuration. 514 2. Exclude this one issue by using special comment `//nolint` (see [the section](#nolint) below). 515 3. Exclude issues in path by `run.skip-dirs`, `run.skip-files` or `issues.exclude-rules` config options. 516 517 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. 518 519 ### Nolint 520 521 To exclude issues from all linters use `//nolint`. For example, if it's used inline (not from the beginning of the line) it excludes issues only for this line. 522 523 ```go 524 var bad_name int //nolint 525 ``` 526 527 To exclude issues from specific linters only: 528 529 ```go 530 var bad_name int //nolint:golint,unused 531 ``` 532 533 To exclude issues for the block of code use this directive on the beginning of a line: 534 535 ```go 536 //nolint 537 func allIssuesInThisFunctionAreExcluded() *string { 538 // ... 539 } 540 541 //nolint:govet 542 var ( 543 a int 544 b int 545 ) 546 ``` 547 548 Also, you can exclude all issues in a file by: 549 550 ```go 551 //nolint:unparam 552 package pkg 553 ``` 554 555 You may add a comment explaining or justifying why `//nolint` is being used on the same line as the flag itself: 556 557 ```go 558 //nolint:gocyclo // This legacy function is complex but the team too busy to simplify it 559 func someLegacyFunction() *string { 560 // ... 561 } 562 ``` 563 564 You can see more examples of using `//nolint` in [our tests](https://github.com/golangci/golangci-lint/tree/master/pkg/result/processors/testdata) for it. 565 566 Use `//nolint` instead of `// nolint` because machine-readable comments should have no space by Go convention. 567 568 ## FAQ 569 570 **How do you add a custom linter?** 571 572 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. 573 574 **It's cool to use `golangci-lint` when starting a project, but what about existing projects with large codebase? It will take days to fix all found issues** 575 576 We are sure that every project can easily integrate `golangci-lint`, even the large one. The idea is to not fix all existing issues. Fix only newly added issue: issues in new code. To do this setup CI (or better use [GolangCI](https://golangci.com)) to run `golangci-lint` with option `--new-from-rev=HEAD~1`. Also, take a look at option `--new`, but consider that CI scripts that generate unstaged files will make `--new` only point out issues in those files and not in the last commit. In that regard `--new-from-rev=HEAD~1` is safer. 577 By doing this you won't create new issues in your code and can choose fix existing issues (or not). 578 579 **How to use `golangci-lint` in CI (Continuous Integration)?** 580 581 You have 2 choices: 582 583 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). 584 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. 585 586 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. 587 588 **Do I need to run `go install`?** 589 590 No, you don't need to do it anymore. 591 592 **Which go versions are supported** 593 Short answer: go 1.12 and newer are officially supported. 594 595 Long answer: 596 597 1. go < 1.9 isn't supported 598 2. go1.9 is officially supported by golangci-lint <= v1.10.2 599 3. go1.10 is officially supported by golangci-lint <= 1.15.0. 600 4. go1.11 is officially supported by golangci-lint <= 1.17.1. 601 5. go1.12+ are officially supported by the latest version of golangci-lint (>= 1.18.0). 602 603 **`golangci-lint` doesn't work** 604 605 1. Please, ensure you are using the latest binary release. 606 2. Run it with `-v` option and check the output. 607 3. If it doesn't help create a [GitHub issue](https://github.com/golangci/golangci-lint/issues/new) with the output from the error and #2 above. 608 609 **Why running with `--fast` is slow on the first run?** 610 Because the first run caches type information. All subsequent runs will be fast. 611 Usually this options is used during development on local machine and compilation was already performed. 612 613 ## Thanks 614 615 Thanks to all [contributors](https://github.com/golangci/golangci-lint/graphs/contributors)! 616 Thanks to [alecthomas/gometalinter](https://github.com/alecthomas/gometalinter) for inspiration and amazing work. 617 Thanks to [bradleyfalzon/revgrep](https://github.com/bradleyfalzon/revgrep) for cool diff tool. 618 619 Thanks to developers and authors of used linters: 620 {{.ThanksList}} 621 622 ## Changelog 623 624 {{.ChangeLog}} 625 626 ## Debug 627 628 You can see a verbose output of linter by using `-v` option. 629 630 If you would like to see more detailed logs you can set environment variable `GL_DEBUG` to debug `golangci-lint`. 631 It's value is a list of debug tags. For example, `GL_DEBUG=loader,gocritic golangci-lint run`. 632 Existing debug tags: 633 634 1. `gocritic` - debug `go-critic` linter; 635 2. `env` - debug `go env` command; 636 3. `loader` - debug packages loading (including `go/packages` internal debugging); 637 4. `autogen_exclude` - debug a filter excluding autogenerated source code; 638 5. `nolint` - debug a filter excluding issues by `//nolint` comments. 639 640 ## Future Plans 641 642 1. Upstream all changes of forked linters. 643 2. Make it easy to write own linter/checker: it should take a minimum code, have perfect documentation, debugging and testing tooling. 644 3. Speed up SSA loading: on-disk cache and existing code profiling-optimizing. 645 4. Analyze (don't only filter) only new code: analyze only changed files and dependencies, make incremental analysis, caches. 646 5. Smart new issues detector: don't print existing issues on changed lines. 647 6. Minimize false-positives by fixing linters and improving testing tooling. 648 7. Automatic issues fixing (code rewrite, refactoring) where it's possible. 649 8. Documentation for every issue type. 650 651 ## Contact Information 652 653 Slack channel: [#golangci-lint](https://slack.com/share/IS0TDK8RG/TEKQWjTZXxfK9Ta2G5HrnsMY/enQtODg0OTMxNjU0ODY2LWUyMTQ3NDc2MmNlNGU3NTNhYWE0Nzc3MjUyZjkxZWI3YjI5ODMwNDA1NTU3MmM2Yzc5ZjQyYTFkNThlODllN2Y). 654 655 You can contact the [author](https://github.com/jirfag) of GolangCI-Lint 656 by [denis@golangci.com](mailto:denis@golangci.com). Follow the news and releases on our [twitter](https://twitter.com/golangci) and our [blog](https://medium.com/golangci). 657 658 ## License Scan 659 660 [![FOSSA Status](https://app.fossa.io/api/projects/git%2Bgithub.com%2Fgolangci%2Fgolangci-lint.svg?type=large)](https://app.fossa.io/projects/git%2Bgithub.com%2Fgolangci%2Fgolangci-lint?ref=badge_large)