Update README.md
This commit is contained in:
golangci
GitHub
parent
5b00f5bf63
commit
51d178da8e
86
README.md
86
README.md
@ -1,7 +1,7 @@
|
||||
# GolangCI-Lint
|
||||
[](https://travis-ci.com/golangci/golangci-lint)
|
||||
|
||||
GolangCI-Lint is a linters aggregator. It's fast: on average [5 times faster](#performance) than gometalinter. It's [easy to integrate and use](#issues-options), has [nice output](#quick-start) and has minimum number of false positives.
|
||||
GolangCI-Lint is a linters aggregator. It's fast: on average [5 times faster](#performance) than gometalinter. It's [easy to integrate and use](#issues-options), has [nice output](#quick-start) and has a minimum number of false positives.
|
||||
|
||||
Sponsored by [GolangCI.com](https://golangci.com): SaaS service for running linters on Github pull requests. Free for Open Source.
|
||||
|
||||
@ -45,7 +45,7 @@ To run golangci-lint execute:
|
||||
golangci-lint run
|
||||
```
|
||||
|
||||
It's and equivalent of executing:
|
||||
It's an equivalent of executing:
|
||||
```bash
|
||||
golangci-lint run ./...
|
||||
```
|
||||
@ -102,14 +102,14 @@ GolangCI-Lint was created to fix next issues with `gometalinter`:
|
||||
3. Can't set honest concurrency: if you set it to `n` it can take up to `n*n` threads because of forced threads in specific linters. `gometalinter` can't do anything about it, because it runs linters as black-boxes in forked processes. In GolangCI-Lint we run all linters in one process and fully control them. Configured concurrency will be honest.
|
||||
This issue is important because often you'd like to set concurrency to CPUs count minus one to not freeze your PC and be able to work on it while analyzing code.
|
||||
4. Lack of nice output. We like how compilers `gcc` and `clang` format their warnings: using colors, printing of warned line and showing position in line.
|
||||
5. Too many issues. GolangCI-Lint cuts a lot of issues by using default exclude list of common false-positives. Also it has enabled by default smart issues processing: merge multiple issues for one line, merge issues with the same text or from the same linter. All of these smart processors can be configured by user.
|
||||
6. Integration to large codebases. Good way to start using linters in large project is not to fix all hundreds on existing issues, but setup CI and fix only issues in new commits. You can use `revgrep` for it, but it's yet another utility to install and configure. With `golangci-lint` it's much easier: `revgrep` is already built into `golangci-lint` and you can use it with one option (`-n, --new` or `--new-from-rev`).
|
||||
7. Installation. With `gometalinter` you need to run linters installation step. It's easy to forget this step and have stale linters. It also complicates CI setup.
|
||||
5. Too many issues. GolangCI-Lint cuts a lot of issues by using default exclude list of common false-positives. Also, it has enabled by default smart issues processing: merge multiple issues for one line, merge issues with the same text or from the same linter. All of these smart processors can be configured by the user.
|
||||
6. Integration to large codebases. A good way to start using linters in a large project is not to fix all hundreds on existing issues, but setup CI and fix only issues in new commits. You can use `revgrep` for it, but it's yet another utility to install and configure. With `golangci-lint` it's much easier: `revgrep` is already built into `golangci-lint` and you can use it with one option (`-n, --new` or `--new-from-rev`).
|
||||
7. Installation. With `gometalinter`, you need to run linters installation step. It's easy to forget this step and have stale linters. It also complicates CI setup.
|
||||
8. Yaml or toml config. Gometalinter's JSON isn't convenient for configuration files.
|
||||
|
||||
## `golangci-lint` vs Run Needed 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 fewer control and more false-positives: some linters can't be properly configured without hacks.
|
||||
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
|
||||
@ -118,7 +118,7 @@ Benchmarks were executed on MacBook Pro (Retina, 13-inch, Late 2013), 2,4 GHz In
|
||||
We measure peak memory usage (RSS) by tracking of processes RSS every 5 ms.
|
||||
|
||||
## Comparison with gometalinter
|
||||
We compare golangci-lint and gometalinter in default mode, but explicitly specify all linters to enable because of small differences in default configuration.
|
||||
We compare golangci-lint and gometalinter in default mode, but explicitly specify all linters to enable 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 \
|
||||
@ -135,7 +135,7 @@ $ gometalinter --deadline=30m --vendor --cyclo-over=30 --dupl-threshold=150 \
|
||||
| Repository | GolangCI Time | GolangCI Is Faster than Gometalinter | GolangCI Memory | GolangCI eats less memory than Gometalinter |
|
||||
| ---------- | ------------- | ------------------------------------ | --------------- | ------------------------------------------- |
|
||||
| gometalinter repo, 4 kLoC | 6s | **6.4x** | 0.7GB | 1.5x |
|
||||
| self repo, 4 kLoC | 12s | **7.5x** | 1.2GB | 1.7x |
|
||||
| self-repo, 4 kLoC | 12s | **7.5x** | 1.2GB | 1.7x |
|
||||
| beego, 50 kLoC | 10s | **4.2x** | 1.4GB | 1.1x |
|
||||
| hugo, 70 kLoC | 15s | **6.1x** | 1.6GB | 1.8x |
|
||||
| consul, 127 kLoC | 58s | **4x** | 2.7GB | 1.7x |
|
||||
@ -144,13 +144,13 @@ $ gometalinter --deadline=30m --vendor --cyclo-over=30 --dupl-threshold=150 \
|
||||
| go source, 1300 kLoC | 2m45s | **2x** | 4.7GB | 1x |
|
||||
|
||||
|
||||
**On average golangci-lint is 4.6 times faster** than gometalinter. Maximum difference is in
|
||||
self repo: **7.5 times faster**, minimum difference is in terraform source code repo: 1.8 times faster.
|
||||
**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 1.35 times less memory.
|
||||
|
||||
# Supported Linters
|
||||
To see a list of supported linters and which linters are enabled/disabled by default execute command
|
||||
To see a list of supported linters and which linters are enabled/disabled by default execute a command
|
||||
```bash
|
||||
golangci-lint linters
|
||||
```
|
||||
@ -158,11 +158,11 @@ golangci-lint linters
|
||||
## Enabled By Default Linters
|
||||
- [go vet](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 go vet on steroids, applying a ton of static analysis checks
|
||||
- [unused](https://github.com/dominikh/go-tools/tree/master/cmd/unused): Checks Go code for unused constants, variables, functions and types
|
||||
- [gosimple](https://github.com/dominikh/go-tools/tree/master/cmd/gosimple): Linter for Go source code that specialises on simplifying code
|
||||
- [staticcheck](https://staticcheck.io/): Staticcheck is a go vet on steroids, applying a ton of static analysis checks
|
||||
- [unused](https://github.com/dominikh/go-tools/tree/master/cmd/unused): Checks Go code for unused constants, variables, functions, and types
|
||||
- [gosimple](https://github.com/dominikh/go-tools/tree/master/cmd/gosimple): Linter for Go source code that specializes in simplifying a code
|
||||
- [gas](https://github.com/GoASTScanner/gas): Inspects source code for security problems
|
||||
- [structcheck](https://github.com/opennota/check): Finds unused struct fields
|
||||
- [structcheck](https://github.com/opennota/check): Finds an unused struct fields
|
||||
- [varcheck](https://github.com/opennota/check): Finds unused global variables and constants
|
||||
- [ineffassign](https://github.com/gordonklaus/ineffassign): Detects when assignments to existing variables are not used
|
||||
- [deadcode](https://github.com/remyoudompheng/go-misc/tree/master/deadcode): Finds unused code
|
||||
@ -188,16 +188,16 @@ golangci-lint run -h
|
||||
|
||||
### Run Options
|
||||
- `-c, --config` - path to [config file](#configuration-file) if you don't like using default config path `.golangci.(yml|toml|json)`.
|
||||
- `-j, --concurrency` - number of threads used. By default it's a number of CPUs. Unlike `gometalinter`, it's an honest value, since we do not fork linter processes.
|
||||
- `-j, --concurrency` - the number of threads used. By default, it's a number of CPUs. Unlike `gometalinter`, it's an honest value, since we do not fork linter processes.
|
||||
- `--build-tags` - build tags to take into account.
|
||||
- `--issues-exit-code` - exit code if issues were found. Default is `1`.
|
||||
- `--issues-exit-code` - exit code if issues were found. The default is `1`.
|
||||
- `--deadline` - timeout for running golangci-lint, `1m` by default.
|
||||
- `--tests` - analyze `*_test.go` files. It's `false` by default.
|
||||
- `-v, --verbose` - enable verbose output. Use this options to see which linters were enabled, to see timings of steps and another helpful information.
|
||||
- `--print-resources-usage` - print memory usage and total time elapsed.
|
||||
|
||||
### Linters
|
||||
- `-E, --enable` - enable specific linter. You can pass option multiple times or use comma:
|
||||
- `-E, --enable` - enable specific linter. You can pass option multiple times or use a comma:
|
||||
```bash
|
||||
golangci-lint run --disable-all -E golint -E govet -E errcheck
|
||||
golangci-lint run --disable-all --enable golint,govet,errcheck
|
||||
@ -222,15 +222,15 @@ Usage example:
|
||||
$ golangci-lint run -v --disable-all -p bugs,style,complexity,format
|
||||
INFO[0000] Active linters: [govet goconst gocyclo gofmt gas dupl goimports megacheck interfacer unconvert errcheck golint]
|
||||
```
|
||||
- `--fast` - run only fast linters from enabled set of linters. To find out which linters are fast run `golangci-lint linters`.
|
||||
- `--fast` - run only fast linters from the enabled set of linters. To find out which linters are fast run `golangci-lint linters`.
|
||||
|
||||
### Linters Options
|
||||
- `--errcheck.check-type-assertions` - errcheck: check for ignored type assertion results. Disabled by default.
|
||||
- `--errcheck.check-blank` - errcheck: check for errors assigned to blank identifier: `_ = errFunc()`. Disabled by default
|
||||
- `--govet.check-shadowing` - govet: check for shadowed variables. Disabled by default.
|
||||
- `--golint.min-confidence` - golint: minimum confidence of a problem to print it. Default is `0.8`.
|
||||
- `--golint.min-confidence` - golint: minimum confidence of a problem to print it. The default is `0.8`.
|
||||
- `--gofmt.simplify` - gofmt: simplify code (`gofmt -s`), enabled by default.
|
||||
- `--gocyclo.min-complexity` - gocyclo: minimal complexity of function to report it. Default is `30` (it's very high limit).
|
||||
- `--gocyclo.min-complexity` - gocyclo: a minimal complexity of function to report it. The default is `30` (it's very high limit).
|
||||
- `--maligned.suggest-new` - Maligned: print suggested more optimal struct fields ordering. Disabled by default. Example:
|
||||
```
|
||||
crypto/tls/ticket.go:20: struct of size 64 bytes could be of size 56 bytes:
|
||||
@ -247,13 +247,13 @@ struct{
|
||||
- `--goconst.min-occurrences` - goconst: minimum occurences of constant string count to trigger issue. Default is `3`.
|
||||
|
||||
### Issues Options
|
||||
- `-n, --new` - show only new issues: if there are unstaged changes or untracked files, only those changes are analyzed, else only changes in HEAD~ are analyzed. It's a superuseful option for integration `golangci-lint` into existing large codebase. It's not practical to fix all existing issues at the moment of integration: much better don't allow issues in new code. Disabled by default.
|
||||
- `-n, --new` - show only new issues: if there are unstaged changes or untracked files, only those changes are analyzed, else only changes in HEAD~ are analyzed. It's a super-useful option for integration `golangci-lint` into existing large codebase. It's not practical to fix all existing issues at the moment of integration: much better don't allow issues in new code. Disabled by default.
|
||||
- `--new-from-rev` - show only new issues created after specified git revision.
|
||||
- `--new-from-patch` - show only new issues created in git patch with specified file path.
|
||||
- `--new-from-patch` - show only new issues created in git patch with the specified file path.
|
||||
- `-e, --exclude` - exclude issue by regexp on issue text.
|
||||
- `--exclude-use-default` - use or not use default excludes. We tested our linter on large codebases and marked common false positives. By default we ignore common false positives by next regexps:
|
||||
- `Error return value of .((os\.)?std(out|err)\..*|.*Close|os\.Remove(All)?|.*printf?|os\.(Un)?Setenv). is not checked` - ercheck: almost all programs ignore errors on these functions and in most cases it's ok.
|
||||
- `(should have comment|comment on exported method)` - golint: annoying issues about not having a comment. Rare codebase has such comments.
|
||||
- `(should have comment|comment on exported method)` - golint: annoying issues about not having a comment. The rare codebase has such comments.
|
||||
- `G103:` - gas: `Use of unsafe calls should be audited`
|
||||
- `G104:` - gas: `disable what errcheck does: it reports on Close etc`
|
||||
- `G204:` - gas: `Subprocess launching should be audited: too lot false - positives`
|
||||
@ -262,25 +262,25 @@ struct{
|
||||
- `G304:` - gas: ``Potential file inclusion via variable: `src, err := ioutil.ReadFile(filename)`.``
|
||||
|
||||
- `(possible misuse of unsafe.Pointer|should have signature)` - common false positives by govet.
|
||||
- `ineffective break statement. Did you mean to break out of the outer loop` - megacheck: developers tend to write in C-style with explicit `break` in switch, so it's ok to ignore.
|
||||
- `ineffective break statement. Did you mean to break out of the outer loop` - megacheck: developers tend to write in C-style with an explicit `break` in a switch, so it's ok to ignore.
|
||||
|
||||
Use option `--exclude-use-default=false` to disable these default exclude regexps.
|
||||
- `--max-issues-per-linter` - maximum issues count per one linter. Set to `0` to disable. Default value is `50` to not being annoying.
|
||||
- `--max-same-issues` - maximum count of issues with the same text. Set to 0 to disable. Default value is `3` to not being annoying.
|
||||
- `--max-issues-per-linter` - maximum issues count per one linter. Set to `0` to disable. The default value is `50` to not being annoying.
|
||||
- `--max-same-issues` - maximum count of issues with the same text. Set to 0 to disable. The default value is `3` to not being annoying.
|
||||
|
||||
### Output Options
|
||||
- `--out-format` - format of output: `colored-line-number|line-number|json`, default is `colored-line-number`.
|
||||
- `--print-issued-lines` - print line of source code where issue occured. Enabled by default.
|
||||
- `--print-issued-lines` - print line of source code where the issue occurred. Enabled by default.
|
||||
- `--print-linter-name` - print linter name in issue line. Enabled by default.
|
||||
- `--print-welcome` - print welcome message. Enabled by default.
|
||||
|
||||
## Configuration File
|
||||
GolangCI-Lint looks for next config paths in current directory:
|
||||
GolangCI-Lint looks for next config paths in the current directory:
|
||||
- `.golangci.yml`
|
||||
- `.golangci.toml`
|
||||
- `.golangci.json`
|
||||
|
||||
Configuration options inside file are identical to command-line options.
|
||||
Configuration options inside the file are identical to command-line options.
|
||||
There is a [`.golangci.yml`](https://github.com/golangci/golangci-lint/blob/master/.golangci.example.yml) with all supported options.
|
||||
|
||||
It's a [.golangci.yml](https://github.com/golangci/golangci-lint/blob/master/.golangci.yml) of this repo: we enable more linters than by default and make their settings more strict:
|
||||
@ -316,7 +316,7 @@ issues:
|
||||
```
|
||||
|
||||
# False Positives
|
||||
False positives are inevitable, but we did our best to reduce their count. For example, we have an enabled by default set of [exclude patterns](#issues-options). If false postive occured you have next choices:
|
||||
False positives are inevitable, but we did our best to reduce their count. For example, we have an enabled by default set of [exclude patterns](#issues-options). If false positive occurred you have next 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.
|
||||
@ -324,13 +324,13 @@ Comment `// nolint` disables all issues reporting on this line. Comment e.g. `//
|
||||
Please create [GitHub Issues here](https://github.com/golangci/golangci-lint/issues/new) about found false positives. We will add it to default exclude list if it's common or we will fix underlying linter.
|
||||
|
||||
# Internals
|
||||
Key difference with gometalinter is that golangci-lint shares work between specific linters (golint, govet, ...).
|
||||
The key difference with gometalinter is that golangci-lint shares work between specific linters (golint, govet, ...).
|
||||
For small and medium projects 50-80% of work between linters can be reused.
|
||||
Now we share `loader.Program` and `SSA` representation building. `SSA` representation is used from
|
||||
a [fork of go-tools](https://github.com/dominikh/go-tools), not the official one. Also we are going to
|
||||
a [fork of go-tools](https://github.com/dominikh/go-tools), not the official one. Also, we are going to
|
||||
reuse `AST` parsing and traversal.
|
||||
|
||||
We don't fork to call specific linter but use it's API. We forked github repos of almost all linters
|
||||
We don't fork to call specific linter but use its API. We forked GitHub repos of almost all linters
|
||||
to make API. It also allows us to be more performant and control actual count of used threads.
|
||||
|
||||
All linters are vendored in `/vendor` folder: their version is fixed, they are builtin
|
||||
@ -344,23 +344,23 @@ We use `cobra` for command-line action.
|
||||
# FAQ
|
||||
**Q: How to add custom linter?**
|
||||
|
||||
A: You can integrate it yourself, take a look at [existings linters integrations](https://github.com/golangci/golangci-lint/tree/master/pkg/golinters). Or you can create [GitHub Issue](https://github.com/golangci/golangci-lint/issues/new) and we will integrate it soon.
|
||||
A: You can integrate it yourself, take a look at [existing linters integrations](https://github.com/golangci/golangci-lint/tree/master/pkg/golinters). Or you can create [GitHub Issue](https://github.com/golangci/golangci-lint/issues/new) and we will integrate it soon.
|
||||
|
||||
**Q: It's cool to use `golangci-lint` when starting project, but what about existing projects with large codebase? It will take days to fix all found issues**
|
||||
**Q: 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**
|
||||
|
||||
A: 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=origin/master`. Also take a look at option `-n`.
|
||||
A: 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=origin/master`. Also, take a look at option `-n`.
|
||||
By doing this you won't create new issues in code and can smoothly fix existing issues (or not).
|
||||
|
||||
**Q: How to use `golangci-lint` in CI (Continuous Integration)?**
|
||||
|
||||
A: You have 2 choices:
|
||||
1. Use [GolangCI](https://golangci.com): this service is highly integrated with GitHub (issues are commented in pull request) and uses `golangci-lint` tool. For configuration use `.golangci.yml` (or toml/json).
|
||||
2. Use custom CI: just run `golangci-lint` in CI and check exit code. If it's non-zero - fail build. The main disadvantage is that you can't see found issues in pull request code and should view build log, then open needed source file to see a context.
|
||||
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 exit code. If it's non-zero - fail the build. The main disadvantage is that you can't see found issues in pull request code and should view build log, then open needed source file to see a context.
|
||||
|
||||
**Q: `golangci-lint` doesn't work**
|
||||
1. Update it: `go get -u github.com/golangci/golangci-lint/cmd/golangci-lint`
|
||||
2. Run it with `-v` option and check output.
|
||||
3. If it doesn't help create [GitHub issue](https://github.com/golangci/golangci-lint/issues/new) with output.
|
||||
2. Run it with `-v` option and check the output.
|
||||
3. If it doesn't help create [GitHub issue](https://github.com/golangci/golangci-lint/issues/new) with the output.
|
||||
|
||||
# Thanks
|
||||
Thanks to [alecthomas/gometalinter](https://github.com/alecthomas/gometalinter) for inspiration and amazing work.
|
||||
@ -387,8 +387,8 @@ Thanks to developers and authors of used linters:
|
||||
|
||||
# Future Plans
|
||||
1. Upstream all changes of forked linters.
|
||||
2. Fully integrate all used linters: make 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 minimum code, have perfect documentation, debugging and testing tooling.
|
||||
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.
|
||||
4. Speedup packages loading (dig into [loader](golang.org/x/tools/go/loader)): on-disk cache and existing code profiling-optimizing.
|
||||
5. Analyze (don't only filter) only new code: analyze only changed files and dependencies, make incremental analysis, caches.
|
||||
6. Smart new issues detector: don't print existing issues on changed lines.
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user