- Editor integration
- Supported linters
- Configuration file
- Installing
- Comment directives
- Quickstart
- FAQ
- Checkstyle XML format
The number of tools for statically checking Go source for errors and warnings is impressive.
This is a tool that concurrently runs a whole bunch of those linters and normalises their output to a standard format:
<file>:<line>:[<column>]: <message> (<linter>)
eg.
stutter.go:9::warning: unused global variable unusedGlobal (varcheck)
stutter.go:12:6:warning: exported type MyStruct should have comment or be unexported (golint)
It is intended for use with editor/IDE integration.
- SublimeLinter plugin.
- Atom go-plus package.
- Emacs Flycheck checker.
- Go for Visual Studio Code.
- Vim/Neovim
- go vet - Reports potential errors that otherwise compile.
- go tool vet --shadow - Reports variables that may have been unintentionally shadowed.
- gotype - Syntactic and semantic analysis similar to the Go compiler.
- gotype -x - Syntactic and semantic analysis in external test packages (similar to the Go compiler).
- deadcode - Finds unused code.
- gocyclo - Computes the cyclomatic complexity of functions.
- golint - Google's (mostly stylistic) linter.
- varcheck - Find unused global variables and constants.
- structcheck - Find unused struct fields.
- maligned - Detect structs that would take less memory if their fields were sorted.
- errcheck - Check that error return values are used.
- megacheck - Run staticcheck, gosimple and unused, sharing work.
- dupl - Reports potentially duplicated code.
- ineffassign - Detect when assignments to existing variables are not used.
- interfacer - Suggest narrower interfaces that can be used.
- unconvert - Detect redundant type conversions.
- goconst - Finds repeated strings that could be replaced by a constant.
- gas - Inspects source code for security problems by scanning the Go AST.
Disabled by default (enable with --enable=<linter>
):
- testify - Show location of failed testify assertions.
- test - Show location of test failures from the stdlib testing module.
- gofmt -s - Checks if the code is properly formatted and could not be further simplified.
- goimports - Checks missing or unreferenced package imports.
- gosimple - Report simplifications in code.
- lll - Report long lines (see
--line-length=N
). - misspell - Finds commonly misspelled English words.
- nakedret - Finds naked returns.
- unparam - Find unused function parameters.
- unused - Find unused variables.
- safesql - Finds potential SQL injection vulnerabilities.
- staticcheck - Statically detect bugs, both obvious and subtle ones.
Additional linters can be added through the command line with --linter=NAME:COMMAND:PATTERN
(see below).
gometalinter now supports a JSON configuration file which can be loaded via
--config=<file>
. The format of this file is determined by the Config
struct
in config.go.
The configuration file mostly corresponds to command-line flags, with the following exceptions:
- Linters defined in the configuration file will overlay existing definitions, not replace them.
- "Enable" defines the exact set of linters that will be enabled (default
linters are disabled).
--help
displays the list of default linters with the exact names you must use.
Here is an example configuration file:
{
"Enable": ["deadcode", "unconvert"]
}
Linters can be added and customized from the config file using the Linters
field.
Linters supports the following fields:
Command
- the path to the linter binary and any default argumentsPattern
- a regular expression used to parse the linter outputIsFast
- if the linter should be run when the--fast
flag is usedPartitionStrategy
- how paths args should be passed to the linter command:directories
- call the linter once with a list of all the directoriesfiles
- call the linter once with a list of all the filespackages
- call the linter once with a list of all the package pathsfiles-by-package
- call the linter once per package with a list of the files in the package.single-directory
- call the linter once per directory
The config for default linters can be overridden by using the name of the linter.
Additional linters can be configured via the command line using the format
NAME:COMMAND:PATTERN
.
Example:
$ gometalinter --linter='vet:go tool vet -printfuncs=Infof,Debugf,Warningf,Errorf:PATH:LINE:MESSAGE' .
There are two options for installing gometalinter.
- Install a stable version, eg.
go get -u gopkg.in/alecthomas/gometalinter.v1
. I will generally only tag a new stable version when it has passed the Travis regression tests. The downside is that the binary will be calledgometalinter.v1
. - Install from HEAD with:
go get -u github.com/alecthomas/gometalinter
. This has the downside that changes to gometalinter may break.
gometalinter supports suppression of linter messages via comment directives. The form of the directive is:
// nolint[: <linter>[, <linter>, ...]]
Suppression works in the following way:
-
Line-level suppression
A comment directive suppresses any linter messages on that line.
eg. In this example any messages for
a := 10
will be suppressed and errcheck messages fordefer r.Close()
will also be suppressed.a := 10 // nolint a = 2 defer r.Close() // nolint: errcheck
-
Statement-level suppression
A comment directive at the same indentation level as a statement it immediately precedes will also suppress any linter messages in that entire statement.
eg. In this example all messages for
SomeFunc()
will be suppressed.// nolint func SomeFunc() { }
Implementation details: gometalinter now performs parsing of Go source code, to extract linter directives and associate them with line ranges. To avoid unnecessary processing, parsing is on-demand: the first time a linter emits a message for a file, that file is parsed for directives.
Install gometalinter (see above).
Install all known linters:
$ gometalinter --install
Installing:
structcheck
maligned
deadcode
gocyclo
ineffassign
dupl
golint
gotype
goimports
errcheck
varcheck
interfacer
goconst
gosimple
staticcheck
unparam
unused
misspell
lll
gas
safesql
Run it:
$ cd example
$ gometalinter ./...
stutter.go:13::warning: unused struct field MyStruct.Unused (structcheck)
stutter.go:9::warning: unused global variable unusedGlobal (varcheck)
stutter.go:12:6:warning: exported type MyStruct should have comment or be unexported (golint)
stutter.go:16:6:warning: exported type PublicUndocumented should have comment or be unexported (golint)
stutter.go:8:1:warning: unusedGlobal is unused (deadcode)
stutter.go:12:1:warning: MyStruct is unused (deadcode)
stutter.go:16:1:warning: PublicUndocumented is unused (deadcode)
stutter.go:20:1:warning: duplicateDefer is unused (deadcode)
stutter.go:21:15:warning: error return value not checked (defer a.Close()) (errcheck)
stutter.go:22:15:warning: error return value not checked (defer a.Close()) (errcheck)
stutter.go:27:6:warning: error return value not checked (doit() // test for errcheck) (errcheck)
stutter.go:29::error: unreachable code (vet)
stutter.go:26::error: missing argument for Printf("%d"): format reads arg 1, have only 0 args (vet)
Gometalinter also supports the commonly seen <path>/...
recursive path
format. Note that this can be very slow, and you may need to increase the linter --deadline
to allow linters to complete.
gometalinter sets two bits of the exit status to indicate different issues:
Bit | Meaning |
---|---|
0 | A linter generated an issue. |
1 | An underlying error occurred; eg. a linter failed to execute. In this situation a warning will also be displayed. |
eg. linter only = 1, underlying only = 2, linter + underlying = 3
There are two main problems running in a CI:
Linters break, causing(this is no longer an issue as all linters are vendored).gometalinter --install --update
to errorgometalinter
adds a new linter.
I have solved 1 by vendoring the linters.
For 2, the best option is to disable all linters, then explicitly enable the ones you want:
gometalinter --disable-all --enable=errcheck --enable=vet --enable=vetshadow ...
gometalinter
has a --vendor
flag that just sets GO15VENDOREXPERIMENT=1
, however the
underlying tools must support it. Ensure that all of the linters are up to date and built with Go 1.5
(gometalinter --install --force
) then run gometalinter --vendor .
. That should be it.
I forked gocyclo
because the upstream behaviour is to recursively check all
subdirectories even when just a single directory is specified. This made it
unusably slow when vendoring. The recursive behaviour can be achieved with
gometalinter by explicitly specifying <path>/...
. There is a
pull request open.
That's more of a statement than a question, but okay.
Sometimes gometalinter will not report issues that you think it should. There are three things to try in that case:
go get -u github.com/alecthomas/gometalinter
gometalinter --install
If you're lucky, this will fix the problem.
If that doesn't help, the problem may be elsewhere (in no particular order):
- Upstream linter has changed its output or semantics.
- gometalinter is not invoking the tool correctly.
- gometalinter regular expression matches are not correct for a linter.
- Linter is exceeding the deadline.
To find out what's going on run in debug mode:
gometalinter --debug
This will show all output from the linters and should indicate why it is failing.
Failing all else, if the problem looks like a bug please file an issue and
include the output of gometalinter --debug
.
revgrep can be used to filter the output of gometalinter
to show issues on lines that have changed between two git refs, such as unstaged changes, changes in
HEAD
vs master
and between master
and origin/master
. See the project's documentation and -help
usage for more information.
go get -u github.com/bradleyfalzon/revgrep/...
gometalinter |& revgrep # If unstaged changes or untracked files, those issues are shown.
gometalinter |& revgrep # Else show issues in the last commit.
gometalinter |& revgrep master # Show issues between master and HEAD (or any other reference).
gometalinter |& revgrep origin/master # Show issues that haven't been pushed.
gometalinter
supports checkstyle
compatible XML output format. It is triggered with --checkstyle
flag:
gometalinter --checkstyle
Checkstyle format can be used to integrate gometalinter with Jenkins CI with the help of Checkstyle Plugin.