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