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