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