github.com/dvyukov/gometalinter@v2.0.12-0.20181028185006-9777a28a8438+incompatible/README.md (about) 1 # Go Meta Linter 2 [![Build Status](https://travis-ci.org/alecthomas/gometalinter.svg)](https://travis-ci.org/alecthomas/gometalinter) [![Gitter chat](https://badges.gitter.im/alecthomas.svg)](https://gitter.im/alecthomas/Lobby) 3 4 <!-- MarkdownTOC --> 5 6 - [Installing](#installing) 7 - [Binary Releases](#binary-releases) 8 - [Homebrew](#homebrew) 9 - [Editor integration](#editor-integration) 10 - [Supported linters](#supported-linters) 11 - [Configuration file](#configuration-file) 12 - [`Format` key](#format-key) 13 - [Format Methods](#format-methods) 14 - [Adding Custom linters](#adding-custom-linters) 15 - [Comment directives](#comment-directives) 16 - [Quickstart](#quickstart) 17 - [FAQ](#faq) 18 - [Exit status](#exit-status) 19 - [What's the best way to use `gometalinter` in CI?](#whats-the-best-way-to-use-gometalinter-in-ci) 20 - [How do I make `gometalinter` work with Go 1.5 vendoring?](#how-do-i-make-gometalinter-work-with-go-15-vendoring) 21 - [Why does `gometalinter --install` install a fork of gocyclo?](#why-does-gometalinter---install-install-a-fork-of-gocyclo) 22 - [Many unexpected errors are being reported](#many-unexpected-errors-are-being-reported) 23 - [Gometalinter is not working](#gometalinter-is-not-working) 24 - [1. Update to the latest build of gometalinter and all linters](#1-update-to-the-latest-build-of-gometalinter-and-all-linters) 25 - [2. Analyse the debug output](#2-analyse-the-debug-output) 26 - [3. Report an issue.](#3-report-an-issue) 27 - [How do I filter issues between two git refs?](#how-do-i-filter-issues-between-two-git-refs) 28 - [Checkstyle XML format](#checkstyle-xml-format) 29 30 <!-- /MarkdownTOC --> 31 32 33 The number of tools for statically checking Go source for errors and warnings 34 is impressive. 35 36 This is a tool that concurrently runs a whole bunch of those linters and 37 normalises their output to a standard format: 38 39 <file>:<line>:[<column>]: <message> (<linter>) 40 41 eg. 42 43 stutter.go:9::warning: unused global variable unusedGlobal (varcheck) 44 stutter.go:12:6:warning: exported type MyStruct should have comment or be unexported (golint) 45 46 It is intended for use with editor/IDE integration. 47 48 ## Installing 49 50 ### Binary Releases 51 52 To install the latest stable release: 53 54 curl -L https://git.io/vp6lP | sh 55 56 Alternatively you can install a specific version from the [releases](https://github.com/alecthomas/gometalinter/releases) list. 57 58 ### Homebrew 59 60 ```sh 61 brew tap alecthomas/homebrew-tap 62 brew install gometalinter 63 ``` 64 65 ## Editor integration 66 67 - [SublimeLinter plugin](https://github.com/alecthomas/SublimeLinter-contrib-gometalinter). 68 - [Atom go-plus package](https://atom.io/packages/go-plus). 69 - [Emacs Flycheck checker](https://github.com/favadi/flycheck-gometalinter). 70 - [Go for Visual Studio Code](https://marketplace.visualstudio.com/items?itemName=lukehoban.Go). 71 - Vim/Neovim 72 - [Neomake](https://github.com/neomake/neomake). 73 - [Syntastic](https://github.com/scrooloose/syntastic/wiki/Go:---gometalinter) `let g:syntastic_go_checkers = ['gometalinter']`. 74 - [ale](https://github.com/w0rp/ale) `let g:ale_linters = {'go': ['gometalinter']}` 75 - [vim-go](https://github.com/fatih/vim-go) with the `:GoMetaLinter` command. 76 77 ## Supported linters 78 79 - [go vet](https://golang.org/cmd/vet/) - Reports potential errors that otherwise compile. 80 - [go tool vet --shadow](https://golang.org/cmd/vet/#hdr-Shadowed_variables) - Reports variables that may have been unintentionally shadowed. 81 - [gotype](https://golang.org/x/tools/cmd/gotype) - Syntactic and semantic analysis similar to the Go compiler. 82 - [gotype -x](https://golang.org/x/tools/cmd/gotype) - Syntactic and semantic analysis in external test packages (similar to the Go compiler). 83 - [deadcode](https://github.com/tsenart/deadcode) - Finds unused code. 84 - [gocyclo](https://github.com/alecthomas/gocyclo) - Computes the cyclomatic complexity of functions. 85 - [golint](https://github.com/golang/lint) - Google's (mostly stylistic) linter. 86 - [varcheck](https://github.com/opennota/check) - Find unused global variables and constants. 87 - [structcheck](https://github.com/opennota/check) - Find unused struct fields. 88 - [maligned](https://github.com/mdempsky/maligned) - Detect structs that would take less memory if their fields were sorted. 89 - [errcheck](https://github.com/kisielk/errcheck) - Check that error return values are used. 90 - [megacheck](https://github.com/dominikh/go-tools/tree/master/cmd/megacheck) - Run staticcheck, gosimple and unused, sharing work. 91 - [dupl](https://github.com/mibk/dupl) - Reports potentially duplicated code. 92 - [ineffassign](https://github.com/gordonklaus/ineffassign) - Detect when assignments to *existing* variables are not used. 93 - [interfacer](https://github.com/mvdan/interfacer) - Suggest narrower interfaces that can be used. 94 - [unconvert](https://github.com/mdempsky/unconvert) - Detect redundant type conversions. 95 - [goconst](https://github.com/jgautheron/goconst) - Finds repeated strings that could be replaced by a constant. 96 - [gosec](https://github.com/securego/gosec) - Inspects source code for security problems by scanning the Go AST. 97 98 Disabled by default (enable with `--enable=<linter>`): 99 100 - [testify](https://github.com/stretchr/testify) - Show location of failed testify assertions. 101 - [test](http://golang.org/pkg/testing/) - Show location of test failures from the stdlib testing module. 102 - [gofmt -s](https://golang.org/cmd/gofmt/) - Checks if the code is properly formatted and could not be further simplified. 103 - [goimports](https://godoc.org/golang.org/x/tools/cmd/goimports) - Checks missing or unreferenced package imports. 104 - [gosimple](https://github.com/dominikh/go-tools/tree/master/cmd/gosimple) - Report simplifications in code. 105 - [gochecknoinits](https://4d63.com/gochecknoinits) - Report init functions, to reduce side effects in code. 106 - [gochecknoglobals](https://4d63.com/gochecknoglobals) - Report global vars, to reduce side effects in code. 107 - [lll](https://github.com/walle/lll) - Report long lines (see `--line-length=N`). 108 - [misspell](https://github.com/client9/misspell) - Finds commonly misspelled English words. 109 - [nakedret](https://github.com/alexkohler/nakedret) - Finds naked returns. 110 - [unparam](https://github.com/mvdan/unparam) - Find unused function parameters. 111 - [unused](https://github.com/dominikh/go-tools/tree/master/cmd/unused) - Find unused variables. 112 - [safesql](https://github.com/stripe/safesql) - Finds potential SQL injection vulnerabilities. 113 - [staticcheck](https://github.com/dominikh/go-tools/tree/master/cmd/staticcheck) - Statically detect bugs, both obvious and subtle ones. 114 115 Additional linters can be added through the command line with `--linter=NAME:COMMAND:PATTERN` (see [below](#details)). 116 117 ## Configuration file 118 119 gometalinter now supports a JSON configuration file called `.gometalinter.json` that can 120 be placed at the root of your project. The configuration file will be automatically loaded 121 from the working directory or any parent directory and can be overridden by passing 122 `--config=<file>` or ignored with `--no-config`. The format of this file is determined by 123 the `Config` struct in [config.go](https://github.com/alecthomas/gometalinter/blob/master/config.go). 124 125 The configuration file mostly corresponds to command-line flags, with the following exceptions: 126 127 - Linters defined in the configuration file will overlay existing definitions, not replace them. 128 - "Enable" defines the exact set of linters that will be enabled (default 129 linters are disabled). `--help` displays the list of default linters with the exact names 130 you must use. 131 132 Here is an example configuration file: 133 134 ```json 135 { 136 "Enable": ["deadcode", "unconvert"] 137 } 138 ``` 139 140 If a `.gometalinter.json` file is loaded, individual options can still be overridden by 141 passing command-line flags. All flags are parsed in order, meaning configuration passed 142 with the `--config` flag will override any command-line flags passed before and be 143 overridden by flags passed after. 144 145 146 #### `Format` key 147 148 The default `Format` key places the different fields of an `Issue` into a template. this 149 corresponds to the `--format` option command-line flag. 150 151 Default `Format`: 152 ``` 153 Format: "{{.Path}}:{{.Line}}:{{if .Col}}{{.Col}}{{end}}:{{.Severity}}: {{.Message}} ({{.Linter}})" 154 ``` 155 156 #### Format Methods 157 158 * `{{.Path.Relative}}` - equivalent to `{{.Path}}` which outputs a relative path to the file 159 * `{{.Path.Abs}}` - outputs an absolute path to the file 160 161 ### Adding Custom linters 162 163 Linters can be added and customized from the config file using the `Linters` field. 164 Linters supports the following fields: 165 166 * `Command` - the path to the linter binary and any default arguments 167 * `Pattern` - a regular expression used to parse the linter output 168 * `IsFast` - if the linter should be run when the `--fast` flag is used 169 * `PartitionStrategy` - how paths args should be passed to the linter command: 170 * `directories` - call the linter once with a list of all the directories 171 * `files` - call the linter once with a list of all the files 172 * `packages` - call the linter once with a list of all the package paths 173 * `files-by-package` - call the linter once per package with a list of the 174 files in the package. 175 * `single-directory` - call the linter once per directory 176 177 The config for default linters can be overridden by using the name of the 178 linter. 179 180 Additional linters can be configured via the command line using the format 181 `NAME:COMMAND:PATTERN`. 182 183 Example: 184 185 ``` 186 $ gometalinter --linter='vet:go tool vet -printfuncs=Infof,Debugf,Warningf,Errorf:PATH:LINE:MESSAGE' . 187 ``` 188 189 ## Comment directives 190 191 gometalinter supports suppression of linter messages via comment directives. The 192 form of the directive is: 193 194 ``` 195 // nolint[: <linter>[, <linter>, ...]] 196 ``` 197 198 Suppression works in the following way: 199 200 1. Line-level suppression 201 202 A comment directive suppresses any linter messages on that line. 203 204 eg. In this example any messages for `a := 10` will be suppressed and errcheck 205 messages for `defer r.Close()` will also be suppressed. 206 207 ```go 208 a := 10 // nolint 209 a = 2 210 defer r.Close() // nolint: errcheck 211 ``` 212 213 2. Statement-level suppression 214 215 A comment directive at the same indentation level as a statement it 216 immediately precedes will also suppress any linter messages in that entire 217 statement. 218 219 eg. In this example all messages for `SomeFunc()` will be suppressed. 220 221 ```go 222 // nolint 223 func SomeFunc() { 224 } 225 ``` 226 227 Implementation details: gometalinter now performs parsing of Go source code, 228 to extract linter directives and associate them with line ranges. To avoid 229 unnecessary processing, parsing is on-demand: the first time a linter emits a 230 message for a file, that file is parsed for directives. 231 232 ## Quickstart 233 234 Install gometalinter (see above). 235 236 Run it: 237 238 ``` 239 $ cd example 240 $ gometalinter ./... 241 stutter.go:13::warning: unused struct field MyStruct.Unused (structcheck) 242 stutter.go:9::warning: unused global variable unusedGlobal (varcheck) 243 stutter.go:12:6:warning: exported type MyStruct should have comment or be unexported (golint) 244 stutter.go:16:6:warning: exported type PublicUndocumented should have comment or be unexported (golint) 245 stutter.go:8:1:warning: unusedGlobal is unused (deadcode) 246 stutter.go:12:1:warning: MyStruct is unused (deadcode) 247 stutter.go:16:1:warning: PublicUndocumented is unused (deadcode) 248 stutter.go:20:1:warning: duplicateDefer is unused (deadcode) 249 stutter.go:21:15:warning: error return value not checked (defer a.Close()) (errcheck) 250 stutter.go:22:15:warning: error return value not checked (defer a.Close()) (errcheck) 251 stutter.go:27:6:warning: error return value not checked (doit() // test for errcheck) (errcheck) 252 stutter.go:29::error: unreachable code (vet) 253 stutter.go:26::error: missing argument for Printf("%d"): format reads arg 1, have only 0 args (vet) 254 ``` 255 256 Gometalinter also supports the commonly seen `<path>/...` recursive path 257 format. Note that this can be *very* slow, and you may need to increase the linter `--deadline` to allow linters to complete. 258 259 ## FAQ 260 261 ### Exit status 262 263 gometalinter sets two bits of the exit status to indicate different issues: 264 265 | Bit | Meaning 266 |-----|---------- 267 | 0 | A linter generated an issue. 268 | 1 | An underlying error occurred; eg. a linter failed to execute. In this situation a warning will also be displayed. 269 270 eg. linter only = 1, underlying only = 2, linter + underlying = 3 271 272 ### What's the best way to use `gometalinter` in CI? 273 274 There are two main problems running in a CI: 275 276 1. <s>Linters break, causing `gometalinter --install --update` to error</s> (this is no longer an issue as all linters are vendored). 277 2. `gometalinter` adds a new linter. 278 279 I have solved 1 by vendoring the linters. 280 281 For 2, the best option is to disable all linters, then explicitly enable the 282 ones you want: 283 284 gometalinter --disable-all --enable=errcheck --enable=vet --enable=vetshadow ... 285 286 ### How do I make `gometalinter` work with Go 1.5 vendoring? 287 288 `gometalinter` has a `--vendor` flag that just sets `GO15VENDOREXPERIMENT=1`, however the 289 underlying tools must support it. Ensure that all of the linters are up to date and built with Go 1.5 290 (`gometalinter --install --force`) then run `gometalinter --vendor .`. That should be it. 291 292 ### Why does `gometalinter --install` install a fork of gocyclo? 293 294 I forked `gocyclo` because the upstream behaviour is to recursively check all 295 subdirectories even when just a single directory is specified. This made it 296 unusably slow when vendoring. The recursive behaviour can be achieved with 297 gometalinter by explicitly specifying `<path>/...`. There is a 298 [pull request](https://github.com/fzipp/gocyclo/pull/1) open. 299 300 ### Many unexpected errors are being reported 301 302 If you see a whole bunch of errors being reported that you wouldn't expect, 303 such as compile errors, this typically means that something is wrong with your 304 Go environment. Try `go install` and fix any issues with your go installation, 305 then try gometalinter again. 306 307 ### Gometalinter is not working 308 309 That's more of a statement than a question, but okay. 310 311 Sometimes gometalinter will not report issues that you think it should. There 312 are three things to try in that case: 313 314 #### 1. Update to the latest build of gometalinter and all linters 315 316 curl -L https://git.io/vp6lP | sh 317 318 If you're lucky, this will fix the problem. 319 320 #### 2. Analyse the debug output 321 322 If that doesn't help, the problem may be elsewhere (in no particular order): 323 324 1. Upstream linter has changed its output or semantics. 325 2. gometalinter is not invoking the tool correctly. 326 3. gometalinter regular expression matches are not correct for a linter. 327 4. Linter is exceeding the deadline. 328 329 To find out what's going on run in debug mode: 330 331 gometalinter --debug 332 333 This will show all output from the linters and should indicate why it is 334 failing. 335 336 #### 3. Report an issue. 337 338 Failing all else, if the problem looks like a bug please file an issue and 339 include the output of `gometalinter --debug`. 340 341 ### How do I filter issues between two git refs? 342 343 [revgrep](https://github.com/bradleyfalzon/revgrep) can be used to filter the output of `gometalinter` 344 to show issues on lines that have changed between two git refs, such as unstaged changes, changes in 345 `HEAD` vs `master` and between `master` and `origin/master`. See the project's documentation and `-help` 346 usage for more information. 347 348 ``` 349 go get -u github.com/bradleyfalzon/revgrep/... 350 gometalinter |& revgrep # If unstaged changes or untracked files, those issues are shown. 351 gometalinter |& revgrep # Else show issues in the last commit. 352 gometalinter |& revgrep master # Show issues between master and HEAD (or any other reference). 353 gometalinter |& revgrep origin/master # Show issues that haven't been pushed. 354 ``` 355 356 ## Checkstyle XML format 357 358 `gometalinter` supports [checkstyle](http://checkstyle.sourceforge.net/) 359 compatible XML output format. It is triggered with `--checkstyle` flag: 360 361 gometalinter --checkstyle 362 363 Checkstyle format can be used to integrate gometalinter with Jenkins CI with the 364 help of [Checkstyle Plugin](https://wiki.jenkins-ci.org/display/JENKINS/Checkstyle+Plugin).