gitee.com/laomobk/golangci-lint.git@v1.10.1/README.tmpl.md (about) 1 # GolangCI-Lint 2 [![Build Status](https://travis-ci.com/golangci/golangci-lint.svg?branch=master)](https://travis-ci.com/golangci/golangci-lint) 3 4 GolangCI-Lint is a linters aggregator. It's fast: on average [5 times faster](#performance) than gometalinter. 5 It's [easy to integrate and use](#command-line-options), has [nice output](#quick-start) and has a minimum number of false positives. 6 7 GolangCI-Lint has [integrations](#editor-integration) with VS Code, GNU Emacs, Sublime Text. 8 9 Sponsored by [GolangCI.com](https://golangci.com): SaaS service for running linters on Github pull requests. Free for Open Source. 10 11 <a href="https://golangci.com/"><img src="docs/go.png" width="250px"></a> 12 13 * [Demo](#demo) 14 * [Install](#install) 15 * [Quick Start](#quick-start) 16 * [Editor Integration](#editor-integration) 17 * [Comparison](#comparison) 18 * [Performance](#performance) 19 * [Internals](#internals) 20 * [Trusted By](#trusted-by) 21 * [Supported Linters](#supported-linters) 22 * [Configuration](#configuration) 23 * [False Positives](#false-positives) 24 * [FAQ](#faq) 25 * [Thanks](#thanks) 26 * [Future Plans](#future-plans) 27 * [Changelog](#changelog) 28 * [Contact Information](#contact-information) 29 30 # Demo 31 <p align="center"> 32 <img src="./docs/demo.svg" width="100%"> 33 </p> 34 35 Short 1.5 min video demo of analyzing [beego](https://github.com/astaxie/beego). 36 [![asciicast](https://asciinema.org/a/183662.png)](https://asciinema.org/a/183662) 37 38 # Install 39 ## CI Installation 40 Most installations are done for CI (travis, circleci etc). It's important to have reproducible CI: 41 don't start to fail all builds at the same time. With golangci-lint this can happen if you 42 use `--enable-all` and a new linter is added or even without `--enable-all`: when one upstream linter 43 is upgraded. 44 45 It's highly recommended to install a fixed version of golangci-lint. 46 Releases are available on the [releases page](https://github.com/golangci/golangci-lint/releases). 47 48 The recommended way to install golangci-lint (replace `vX.Y.Z` with the latest 49 version from the [releases page](https://github.com/golangci/golangci-lint/releases)): 50 ```bash 51 # binary will be $GOPATH/bin/golangci-lint 52 curl -sfL https://install.goreleaser.com/github.com/golangci/golangci-lint.sh | bash -s -- -b $GOPATH/bin vX.Y.Z 53 54 # or install it into ./bin/ 55 # curl -sfL https://install.goreleaser.com/github.com/golangci/golangci-lint.sh | bash -s vX.Y.Z 56 57 # golangci-lint --version 58 ``` 59 60 Periodically update version of golangci-lint: the project is under active development 61 and is constantly being improved. But please always check for newly found issues and 62 update if needed. 63 64 ## Local Installation 65 It's a not recommended for your CI pipeline. Only install like this for your local development environment. 66 ```bash 67 go get -u github.com/golangci/golangci-lint/cmd/golangci-lint 68 ``` 69 70 You can also install it on OSX using brew: 71 ```bash 72 brew install golangci/tap/golangci-lint 73 brew upgrade golangci/tap/golangci-lint 74 ``` 75 76 # Quick Start 77 To run golangci-lint execute: 78 ```bash 79 golangci-lint run 80 ``` 81 82 It's an equivalent of executing: 83 ```bash 84 golangci-lint run ./... 85 ``` 86 87 You can choose which directories and files to analyze: 88 ```bash 89 golangci-lint run dir1 dir2/... dir3/file1.go 90 ``` 91 Directories are NOT analyzed recursively. To analyze them recursively append `/...` to their path. 92 93 GolangCI-Lint can be used with zero configuration. By default the following linters are enabled: 94 ``` 95 $ golangci-lint help linters 96 {{.LintersCommandOutputEnabledOnly}} 97 ``` 98 99 and the following linters are disabled by default: 100 ``` 101 $ golangci-lint help linters 102 ... 103 {{.LintersCommandOutputDisabledOnly}} 104 ``` 105 106 Pass `-E/--enable` to enable linter and `-D/--disable` to disable: 107 ```bash 108 $ golangci-lint run --disable-all -E errcheck 109 ``` 110 111 # Editor Integration 112 1. [Go for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go). 113 2. Sublime Text - [plugin](https://github.com/alecthomas/SublimeLinter-contrib-golang-cilint) for SublimeLinter. 114 3. GoLand 115 - Configure [File Watcher](https://www.jetbrains.com/help/go/settings-tools-file-watchers.html) with arguments `run --print-issued-lines=false $FileDir$`. 116 - Predefined File Watcher will be added in [issue](https://youtrack.jetbrains.com/issue/GO-4574). 117 4. GNU Emacs 118 - [Spacemacs](https://github.com/syl20bnr/spacemacs/blob/develop/layers/+lang/go/README.org#pre-requisites) 119 - [flycheck checker](https://github.com/weijiangan/flycheck-golangci-lint). 120 5. Vim 121 - vim-go open [issue](https://github.com/fatih/vim-go/issues/1841) 122 - syntastic [merged pull request](https://github.com/vim-syntastic/syntastic/pull/2190) with golangci-lint support 123 124 # Comparison 125 ## `golangci-lint` vs `gometalinter` 126 GolangCI-Lint was created to fix the following issues with `gometalinter`: 127 1. Slow work: `gometalinter` usually works for minutes in average projects. 128 **GolangCI-Lint works [2-7x times faster](#performance)** by [reusing work](#internals). 129 2. Huge memory consumption: parallel linters don't share the same program representation and can consume 130 `n` times more memory (`n` - concurrency). GolangCI-Lint fixes it by sharing representation and **consumes 26% less memory**. 131 3. Doesn't use real bounded concurrency: if you set it to `n` it can take up to `n*n` threads because of 132 forced threads in specific linters. `gometalinter` can't do anything about it because it runs linters as 133 black boxes in forked processes. In GolangCI-Lint we run all linters in one process and completely control 134 them. Configured concurrency will be correctly bounded. 135 This issue is important because you often want to set concurrency to the CPUs count minus one to 136 ensure you **do not freeze your PC** and be able to work on it while analyzing code. 137 4. Lack of nice output. We like how the `gcc` and `clang` compilers format their warnings: **using colors, 138 printing warning lines and showing the position in line**. 139 5. Too many issues. GolangCI-Lint cuts a lot of issues by using default exclude list of common false-positives. 140 By default, it has enabled **smart issues processing**: merge multiple issues for one line, merge issues with the 141 same text or from the same linter. All of these smart processors can be configured by the user. 142 6. Integration into large codebases. A good way to start using linters in a large project is not to fix a plethora 143 of existing issues, but to set up CI and **fix only issues in new commits**. You can use `revgrep` for it, but it's 144 yet another utility to install and configure. With `golangci-lint` it's much easier: `revgrep` is already built into 145 `golangci-lint` and you can use it with one option (`-n, --new` or `--new-from-rev`). 146 7. Installation. With `gometalinter`, you need to run a linters installation step. It's easy to forget this step and 147 end up with stale linters. It also complicates CI setup. GolangCI-Lint requires **no installation of linters**. 148 8. **Yaml or toml config**. Gometalinter's JSON isn't convenient for config files. 149 150 ## `golangci-lint` vs Running Linters Manually 151 1. It will be much slower because `golangci-lint` runs all linters in parallel and shares 50-80% of linters work. 152 2. It will have less control and more false-positives: some linters can't be properly configured without hacks. 153 3. It will take more time because of different usages and need of tracking of versions of `n` linters. 154 155 # Performance 156 Benchmarks were executed on MacBook Pro (Retina, 13-inch, Late 2013), 2,4 GHz Intel Core i5, 8 GB 1600 MHz DDR3. 157 It has 4 cores and concurrent linting as a default consuming all cores. 158 Benchmark was run (and measured) automatically, see the code 159 [here](https://github.com/golangci/golangci-lint/blob/master/test/bench_test.go) (`BenchmarkWithGometalinter`). 160 161 We measure peak memory usage (RSS) by tracking of processes RSS every 5 ms. 162 163 ## Comparison with gometalinter 164 We compare golangci-lint and gometalinter in default mode, but explicitly enable all linters because of small differences in the default configuration. 165 ```bash 166 $ golangci-lint run --no-config --issues-exit-code=0 --deadline=30m \ 167 --disable-all --enable=deadcode --enable=gocyclo --enable=golint --enable=varcheck \ 168 --enable=structcheck --enable=maligned --enable=errcheck --enable=dupl --enable=ineffassign \ 169 --enable=interfacer --enable=unconvert --enable=goconst --enable=gas --enable=megacheck 170 $ gometalinter --deadline=30m --vendor --cyclo-over=30 --dupl-threshold=150 \ 171 --exclude=<defaul golangci-lint excludes> --skip=testdata --skip=builtin \ 172 --disable-all --enable=deadcode --enable=gocyclo --enable=golint --enable=varcheck \ 173 --enable=structcheck --enable=maligned --enable=errcheck --enable=dupl --enable=ineffassign \ 174 --enable=interfacer --enable=unconvert --enable=goconst --enable=gas --enable=megacheck 175 ./... 176 ``` 177 178 | Repository | GolangCI Time | GolangCI Is Faster than Gometalinter | GolangCI Memory | GolangCI eats less memory than Gometalinter | 179 | ---------- | ------------- | ------------------------------------ | --------------- | ------------------------------------------- | 180 | gometalinter repo, 4 kLoC | 6s | **6.4x** | 0.7GB | 33% | 181 | self-repo, 4 kLoC | 12s | **7.5x** | 1.2GB | 41% | 182 | beego, 50 kLoC | 10s | **4.2x** | 1.4GB | 9% | 183 | hugo, 70 kLoC | 15s | **6.1x** | 1.6GB | 44% | 184 | consul, 127 kLoC | 58s | **4x** | 2.7GB | 41% | 185 | terraform, 190 kLoC | 2m13s | **1.6x** | 4.8GB | 0% | 186 | go-ethereum, 250 kLoC | 33s | **5x** | 3.6GB | 0% | 187 | go source (`$GOROOT/src`), 1300 kLoC | 2m45s | **2x** | 4.7GB | 0% | 188 189 190 **On average golangci-lint is 4.6 times faster** than gometalinter. Maximum difference is in the 191 self-repo: **7.5 times faster**, minimum difference is in terraform source code repo: 1.8 times faster. 192 193 On average golangci-lint consumes 26% less memory. 194 195 ## Why golangci-lint is faster 196 197 Golangci-lint directly calls linters (no forking) and reuses 80% of work by parsing program only once. 198 Read [this section](#internals) for details. 199 200 # Internals 201 202 1. Work sharing 203 The key difference with gometalinter is that golangci-lint shares work between specific linters (golint, govet, ...). 204 We don't fork to call specific linter but use its API. 205 For small and medium projects 50-90% of work between linters can be reused. 206 * load `loader.Program` once 207 208 We load program (parsing all files and type-checking) only once for all linters. For the most of linters 209 it's the most heavy operation: it takes 5 seconds on 8 kLoC repo and 11 seconds on `$GOROOT/src`. 210 * build `ssa.Program` once 211 212 Some linters (megacheck, interfacer, unparam) work on SSA representation. 213 Building of this representation takes 1.5 seconds on 8 kLoC repo and 6 seconds on `$GOROOT/src`. 214 `SSA` representation is used from a [fork of go-tools](https://github.com/dominikh/go-tools), not the official one. 215 216 * parse source code and build AST once 217 218 Parsing one source file takes 200 us on average. Parsing of all files in `$GOROOT/src` takes 2 seconds. 219 Currently we parse each file more than once because it's not the bottleneck. But we already save a lot of 220 extra parsing. We're planning to parse each file only once. 221 222 * walk files and directories once 223 224 It takes 300-1000 ms for `$GOROOT/src`. 225 2. Smart linters scheduling 226 227 We schedule linters by a special algorithm which takes estimated execution time into account. It allows 228 to save 10-30% of time when one of heavy linters (megacheck etc) is enabled. 229 230 3. Improved program loading 231 232 We smartly use setting `TypeCheckFuncBodies` in `loader.Config` to build `loader.Program`. 233 If there are no linters requiring SSA enabled we can load dependencies of analyzed code much faster 234 by not analyzing their functions: we analyze only file-level declarations. It makes program loading 235 10-30% faster in such cases. 236 4. Don't fork to run shell commands 237 238 All linters are vendored in the `/vendor` folder: their version is fixed, they are builtin 239 and you don't need to install them separately. 240 241 # Trusted By 242 243 The following great projects use golangci-lint: 244 245 * [GoogleContainerTools/skaffold](https://github.com/GoogleContainerTools/skaffold/blob/master/hack/linter.sh#L24) - Easy and Repeatable Kubernetes Development 246 * [goreleaser/goreleaser](https://github.com/goreleaser/goreleaser/blob/master/Makefile#L47) - Deliver Go binaries as fast and easily as possible 247 * [goreleaser/nfpm](https://github.com/goreleaser/nfpm/blob/master/Makefile#L43) - NFPM is Not FPM - a simple deb and rpm packager written in Go 248 * [goreleaser/godownloader](https://github.com/goreleaser/godownloader/blob/master/Makefile#L37) - Download Go binaries as fast and easily as possible 249 * [asobti/kube-monkey](https://github.com/asobti/kube-monkey/blob/master/Makefile#L12) - An implementation of Netflix's Chaos Monkey for Kubernetes clusters 250 * [nutanix/terraform-provider-nutanix](https://github.com/nutanix/terraform-provider-nutanix/blob/develop/.golangci.yml) - Terraform Nutanix Provider 251 * [getantibody/antibody](https://github.com/getantibody/antibody/blob/master/Makefile#L32) - The fastest shell plugin manager 252 * [Aptomi/aptomi](https://github.com/Aptomi/aptomi/blob/master/.golangci.yml) - Application delivery engine for k8s 253 * [status-im/status-go](https://github.com/status-im/status-go/blob/develop/.golangci.yml) - The Status module that consumes go-ethereum 254 * [ovrclk/akash](https://github.com/ovrclk/akash/blob/master/.golangci.yaml) - Blockchain-powered decentralized compute platform 255 256 257 # Supported Linters 258 To see a list of supported linters and which linters are enabled/disabled: 259 ``` 260 golangci-lint help linters 261 ``` 262 263 ## Enabled By Default Linters 264 {{.EnabledByDefaultLinters}} 265 266 ## Disabled By Default Linters (`-E/--enable`) 267 {{.DisabledByDefaultLinters}} 268 269 # Configuration 270 The config file has lower priority than command-line options. If the same bool/string/int option is provided on the command-line 271 and in the config file, the option from command-line will be used. 272 Slice options (e.g. list of enabled/disabled linters) are combined from the command-line and config file. 273 274 To see a list of enabled by your configuration linters: 275 ``` 276 golangci-lint linters 277 ``` 278 279 ## Command-Line Options 280 ``` 281 golangci-lint run -h 282 {{.RunHelpText}} 283 ``` 284 285 ## Config File 286 GolangCI-Lint looks for config files in the following paths from the current working directory: 287 - `.golangci.yml` 288 - `.golangci.toml` 289 - `.golangci.json` 290 291 GolangCI-Lint also searches for config files in all directories from the directory of the first analyzed path up to the root. 292 To see which config file is being used and where it was sourced from run golangci-lint with `-v` option. 293 294 Config options inside the file are identical to command-line options. 295 You can configure specific linters' options only within the config file (not the command-line). 296 297 There is a [`.golangci.example.yml`](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml) example 298 config file with all supported options, their description and default value: 299 ```yaml 300 {{.GolangciYamlExample}} 301 ``` 302 303 It's a [.golangci.yml](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml) config file of this repo: we enable more linters 304 than the default and have more strict settings: 305 ```yaml 306 {{.GolangciYaml}} 307 ``` 308 309 # False Positives 310 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: 311 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. 312 2. Exclude this one issue by using special comment `// nolint[:linter1,linter2,...]` on issued line. 313 Comment `// nolint` disables all issues reporting on this line. Comment e.g. `// nolint:govet` disables only govet issues for this line. 314 If you would like to completely exclude all issues for some function prepend this comment 315 above function: 316 ```go 317 //nolint 318 func f() { 319 ... 320 } 321 ``` 322 323 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. 324 325 # FAQ 326 **How do you add a custom linter?** 327 328 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. 329 330 **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** 331 332 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. 333 By doing this you won't create new issues in your code and can choose fix existing issues (or not). 334 335 **How to use `golangci-lint` in CI (Continuous Integration)?** 336 337 You have 2 choices: 338 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). 339 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. 340 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. 341 342 **Does I need to run `go install`?** 343 344 No, you don't need to do it anymore. We will run `go install -i` and `go test -i` 345 for analyzed packages ourselves. We will run them only 346 if option `govet.use-installed-packages` is `true`. 347 348 **`golangci-lint` doesn't work** 349 350 1. Update it: `go get -u github.com/golangci/golangci-lint/cmd/golangci-lint` 351 2. Run it with `-v` option and check the output. 352 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. 353 354 # Thanks 355 Thanks to [alecthomas/gometalinter](https://github.com/alecthomas/gometalinter) for inspiration and amazing work. 356 Thanks to [bradleyfalzon/revgrep](https://github.com/bradleyfalzon/revgrep) for cool diff tool. 357 358 Thanks to developers and authors of used linters: 359 {{.ThanksList}} 360 361 # Future Plans 362 1. Upstream all changes of forked linters. 363 2. Fully integrate all used linters: make a common interface and reuse 100% of what can be reused: AST traversal, packages preparation etc. 364 3. Make it easy to write own linter/checker: it should take a minimum code, have perfect documentation, debugging and testing tooling. 365 4. Speed up package loading (dig into [loader](golang.org/x/tools/go/loader)): on-disk cache and existing code profiling-optimizing. 366 5. Analyze (don't only filter) only new code: analyze only changed files and dependencies, make incremental analysis, caches. 367 6. Smart new issues detector: don't print existing issues on changed lines. 368 7. Integration with Text Editors. On-the-fly code analysis for text editors: it should be super-fast. 369 8. Minimize false-positives by fixing linters and improving testing tooling. 370 9. Automatic issues fixing (code rewrite, refactoring) where it's possible. 371 10. Documentation for every issue type. 372 373 # Changelog 374 375 There is the most valuable changes log: 376 377 ## June 2018 378 379 1. Add support of the next linters: 380 * unparam 381 * misspell 382 * prealloc 383 * nakedret 384 * lll 385 * depguard 386 2. Smart generated files detector 387 3. Full `//nolint` support 388 4. Implement `--skip-files` and `--skip-dirs` options 389 5. Checkstyle output format support 390 391 ## May 2018 392 393 1. Support GitHub Releases 394 2. Installation via Homebrew and Docker 395 396 # Contact Information 397 You can contact the [author](https://github.com/jirfag) of GolangCI-Lint 398 by [denis@golangci.com](mailto:denis@golangci.com).