README.md
1# errcheck
2
3errcheck is a program for checking for unchecked errors in go programs.
4
5[](https://travis-ci.org/kisielk/errcheck)
6
7## Install
8
9 go get -u github.com/kisielk/errcheck
10
11errcheck requires Go 1.9 or newer and depends on the package go/packages from the golang.org/x/tools repository.
12
13## Use
14
15For basic usage, just give the package path of interest as the first argument:
16
17 errcheck github.com/kisielk/errcheck/testdata
18
19To check all packages beneath the current directory:
20
21 errcheck ./...
22
23Or check all packages in your $GOPATH and $GOROOT:
24
25 errcheck all
26
27errcheck also recognizes the following command-line options:
28
29The `-tags` flag takes a space-separated list of build tags, just like `go
30build`. If you are using any custom build tags in your code base, you may need
31to specify the relevant tags here.
32
33The `-asserts` flag enables checking for ignored type assertion results. It
34takes no arguments.
35
36The `-blank` flag enables checking for assignments of errors to the
37blank identifier. It takes no arguments.
38
39
40## Excluding functions
41
42Use the `-exclude` flag to specify a path to a file containing a list of functions to
43be excluded.
44
45 errcheck -exclude errcheck_excludes.txt path/to/package
46
47The file should contain one function signature per line. The format for function signatures is
48`package.FunctionName` while for methods it's `(package.Receiver).MethodName` for value receivers
49and `(*package.Receiver).MethodName` for pointer receivers. If the function name is followed by string of form `(TYPE)`, then
50the the function call is excluded only if the type of the first argument is `TYPE`. It also accepts a special suffix
51`(os.Stdout)` and `(os.Stderr)`, which excludes the function only when the first argument is a literal `os.Stdout` or `os.Stderr`.
52
53An example of an exclude file is:
54
55 io/ioutil.ReadFile
56 io.Copy(*bytes.Buffer)
57 io.Copy(os.Stdout)
58 (*net/http.Client).Do
59
60The exclude list is combined with an internal list for functions in the Go standard library that
61have an error return type but are documented to never return an error.
62
63
64### The deprecated method
65
66The `-ignore` flag takes a comma-separated list of pairs of the form package:regex.
67For each package, the regex describes which functions to ignore within that package.
68The package may be omitted to have the regex apply to all packages.
69
70For example, you may wish to ignore common operations like Read and Write:
71
72 errcheck -ignore '[rR]ead|[wW]rite' path/to/package
73
74or you may wish to ignore common functions like the `print` variants in `fmt`:
75
76 errcheck -ignore 'fmt:[FS]?[Pp]rint*' path/to/package
77
78The `-ignorepkg` flag takes a comma-separated list of package import paths
79to ignore:
80
81 errcheck -ignorepkg 'fmt,encoding/binary' path/to/package
82
83Note that this is equivalent to:
84
85 errcheck -ignore 'fmt:.*,encoding/binary:.*' path/to/package
86
87If a regex is provided for a package `pkg` via `-ignore`, and `pkg` also appears
88in the list of packages passed to `-ignorepkg`, the latter takes precedence;
89that is, all functions within `pkg` will be ignored.
90
91Note that by default the `fmt` package is ignored entirely, unless a regex is
92specified for it. To disable this, specify a regex that matches nothing:
93
94 errcheck -ignore 'fmt:a^' path/to/package
95
96The `-ignoretests` flag disables checking of `_test.go` files. It takes
97no arguments.
98
99## Cgo
100
101Currently errcheck is unable to check packages that import "C" due to limitations in the importer when used with versions earlier than Go 1.11.
102
103However, you can use errcheck on packages that depend on those which use cgo. In order for this to work you need to go install the cgo dependencies before running errcheck on the dependent packages.
104
105See https://github.com/kisielk/errcheck/issues/16 for more details.
106
107## Exit Codes
108
109errcheck returns 1 if any problems were found in the checked files.
110It returns 2 if there were any other failures.
111
112# Editor Integration
113
114## Emacs
115
116[go-errcheck.el](https://github.com/dominikh/go-errcheck.el)
117integrates errcheck with Emacs by providing a `go-errcheck` command
118and customizable variables to automatically pass flags to errcheck.
119
120## Vim
121
122[vim-go](https://github.com/fatih/vim-go) can run errcheck via both its `:GoErrCheck`
123and `:GoMetaLinter` commands.
124
){kind=link}