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.