github.com/getkalido/errcheck@v1.7.0-alpha/README.md (about) 1 # errcheck 2 3 errcheck is a program for checking for unchecked errors in Go code. 4 5 ![Go](https://github.com/getkalido/errcheck/workflows/Go/badge.svg) 6 7 It is forked from https://github.com/kisielk/errcheck but unlike the original 8 allows you to write `defer foo.Close()`. 9 10 ## Why a fork 11 12 `defer h.Close()` is idiomatic Go, which appears regularly in the standard library and text books. 13 If h is a read only descriptor, then nothing useful can be done if the Close fails. 14 15 This has been raised a number [of](https://github.com/kisielk/errcheck/issues/55) [times](https://github.com/kisielk/errcheck/issues/101) 16 upstream, but these issues have been closed, as the author 17 believes that these errors should always be checked, and if necessary deferred calls to Close 18 should be wrapped in a lambda. 19 20 This [unecessarily complicates code](https://github.com/Marethyu12/gotube/pull/4/commits/8552c52ca02b81fd0a307784916bfe6393fcaa1e), 21 and means that the Go standard library will fail errcheck. 22 23 The Author is, of course, entitled to his opinion. But those who disagree with him have the right to fork and do otherwise. 24 25 ## Install 26 27 go install github.com/getkalido/errcheck@latest 28 29 errcheck requires Go 1.18 or newer. 30 31 ## Use 32 33 For basic usage, just give the package path of interest as the first argument: 34 35 errcheck github.com/kisielk/errcheck/testdata 36 37 To check all packages beneath the current directory: 38 39 errcheck ./... 40 41 Or check all packages in your `$GOPATH` and `$GOROOT`: 42 43 errcheck all 44 45 errcheck also recognizes the following command-line options: 46 47 The `-tags` flag takes a space-separated list of build tags, just like `go 48 build`. If you are using any custom build tags in your code base, you may need 49 to specify the relevant tags here. 50 51 The `-asserts` flag enables checking for ignored type assertion results. It 52 takes no arguments. 53 54 The `-blank` flag enables checking for assignments of errors to the 55 blank identifier. It takes no arguments. 56 57 The `-abspath` flag prints the absolute paths to files with unchecked errors. 58 59 The `-mod` flag sets the module download mode to use: `readonly` or `vendor`. 60 61 ### go/analysis 62 63 The package provides `Analyzer` instance that can be used with 64 [go/analysis](https://pkg.go.dev/golang.org/x/tools/go/analysis) API. 65 66 Currently supported flags are `blank`, `assert`, `exclude`, and `excludeonly`. 67 Just as the API itself, the analyzer is experimental and may change in the 68 future. 69 70 ## Excluding functions 71 72 Use the `-exclude` flag to specify a path to a file containing a list of functions to 73 be excluded. 74 75 errcheck -exclude errcheck_excludes.txt path/to/package 76 77 The file should contain one function signature per line. The format for function signatures is 78 `package.FunctionName` while for methods it's `(package.Receiver).MethodName` for value receivers 79 and `(*package.Receiver).MethodName` for pointer receivers. If the function name is followed by string of form `(TYPE)`, then 80 the the function call is excluded only if the type of the first argument is `TYPE`. It also accepts a special suffix 81 `(os.Stdout)` and `(os.Stderr)`, which excludes the function only when the first argument is a literal `os.Stdout` or `os.Stderr`. 82 83 An example of an exclude file is: 84 85 io.Copy(*bytes.Buffer) 86 io.Copy(os.Stdout) 87 os.ReadFile 88 89 // Sometimes we don't care if a HTTP request fails. 90 (*net/http.Client).Do 91 92 By default, the exclude list is combined with an internal list for functions in 93 the Go standard library that have an error return type but are documented to never 94 return an error. To disable the built-in exclude list, pass the `-excludeonly` flag. 95 96 Run errcheck in `-verbose` mode to see the resulting list of added excludes. 97 98 When using vendored dependencies, specify the full import path. For example: 99 * Your project's import path is `example.com/yourpkg` 100 * You've vendored `example.net/fmt2` as `vendor/example.net/fmt2` 101 * You want to exclude `fmt2.Println` from error checking 102 103 In this case, add this line to your exclude file: 104 ``` 105 example.com/yourpkg/vendor/example.net/fmt2.Println 106 ``` 107 108 Empty lines and lines starting with `//` are ignored. 109 110 ### The deprecated method 111 112 The `-ignore` flag takes a comma-separated list of pairs of the form package:regex. 113 For each package, the regex describes which functions to ignore within that package. 114 The package may be omitted to have the regex apply to all packages. 115 116 For example, you may wish to ignore common operations like Read and Write: 117 118 errcheck -ignore '[rR]ead|[wW]rite' path/to/package 119 120 or you may wish to ignore common functions like the `print` variants in `fmt`: 121 122 errcheck -ignore 'fmt:[FS]?[Pp]rint*' path/to/package 123 124 The `-ignorepkg` flag takes a comma-separated list of package import paths 125 to ignore: 126 127 errcheck -ignorepkg 'fmt,encoding/binary' path/to/package 128 129 Note that this is equivalent to: 130 131 errcheck -ignore 'fmt:.*,encoding/binary:.*' path/to/package 132 133 If a regex is provided for a package `pkg` via `-ignore`, and `pkg` also appears 134 in the list of packages passed to `-ignorepkg`, the latter takes precedence; 135 that is, all functions within `pkg` will be ignored. 136 137 Note that by default the `fmt` package is ignored entirely, unless a regex is 138 specified for it. To disable this, specify a regex that matches nothing: 139 140 errcheck -ignore 'fmt:a^' path/to/package 141 142 The `-ignoretests` flag disables checking of `_test.go` files. It takes 143 no arguments. 144 145 The `-ignoregenerated` flag disables checking of generated source code. It takes no arguments. 146 147 ## Exit Codes 148 149 errcheck returns 1 if any problems were found in the checked files. 150 It returns 2 if there were any other failures. 151 152 # Editor Integration 153 154 ## Emacs 155 156 [go-errcheck.el](https://github.com/dominikh/go-errcheck.el) 157 integrates errcheck with Emacs by providing a `go-errcheck` command 158 and customizable variables to automatically pass flags to errcheck. 159 160 ## Vim 161 162 [vim-go](https://github.com/fatih/vim-go) can run errcheck via both its `:GoErrCheck` 163 and `:GoMetaLinter` commands.