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