github.com/ekalinin/errcheck@v1.2.1-0.20190917115355-d3315f128aa5/README.md (about)

     1  # errcheck
     2  
     3  errcheck is a program for checking for unchecked errors in go programs.
     4  
     5  [![Build Status](https://travis-ci.org/kisielk/errcheck.png?branch=master)](https://travis-ci.org/kisielk/errcheck)
     6  
     7  ## Install
     8  
     9      go get -u github.com/kisielk/errcheck
    10  
    11  errcheck requires Go 1.9 or newer and depends on the package go/packages from the golang.org/x/tools repository.
    12  
    13  ## Use
    14  
    15  For basic usage, just give the package path of interest as the first argument:
    16  
    17      errcheck github.com/kisielk/errcheck/testdata
    18  
    19  To check all packages beneath the current directory:
    20  
    21      errcheck ./...
    22  
    23  Or check all packages in your $GOPATH and $GOROOT:
    24  
    25      errcheck all
    26  
    27  errcheck also recognizes the following command-line options:
    28  
    29  The `-tags` flag takes a space-separated list of build tags, just like `go
    30  build`. If you are using any custom build tags in your code base, you may need
    31  to specify the relevant tags here.
    32  
    33  The `-asserts` flag enables checking for ignored type assertion results. It
    34  takes no arguments.
    35  
    36  The `-blank` flag enables checking for assignments of errors to the
    37  blank identifier. It takes no arguments.
    38  
    39  
    40  ## Excluding functions
    41  
    42  Use the `-exclude` flag to specify a path to a file containing a list of functions to
    43  be excluded.
    44  
    45      errcheck -exclude errcheck_excludes.txt path/to/package
    46  
    47  The 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
    49  and `(*package.Receiver).MethodName` for pointer receivers. If the function name is followed by string of form `(TYPE)`, then
    50  the 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  
    53  An 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  
    60  The exclude list is combined with an internal list for functions in the Go standard library that
    61  have an error return type but are documented to never return an error.
    62  
    63  
    64  ### The deprecated method
    65  
    66  The `-ignore` flag takes a comma-separated list of pairs of the form package:regex.
    67  For each package, the regex describes which functions to ignore within that package.
    68  The package may be omitted to have the regex apply to all packages.
    69  
    70  For example, you may wish to ignore common operations like Read and Write:
    71  
    72      errcheck -ignore '[rR]ead|[wW]rite' path/to/package
    73  
    74  or 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  
    78  The `-ignorepkg` flag takes a comma-separated list of package import paths
    79  to ignore:
    80  
    81      errcheck -ignorepkg 'fmt,encoding/binary' path/to/package
    82  
    83  Note that this is equivalent to:
    84  
    85      errcheck -ignore 'fmt:.*,encoding/binary:.*' path/to/package
    86  
    87  If a regex is provided for a package `pkg` via `-ignore`, and `pkg` also appears
    88  in the list of packages passed to `-ignorepkg`, the latter takes precedence;
    89  that is, all functions within `pkg` will be ignored.
    90  
    91  Note that by default the `fmt` package is ignored entirely, unless a regex is
    92  specified for it. To disable this, specify a regex that matches nothing:
    93  
    94      errcheck -ignore 'fmt:a^' path/to/package
    95  
    96  The `-ignoretests` flag disables checking of `_test.go` files. It takes
    97  no arguments.
    98  
    99  ## Cgo
   100  
   101  Currently 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  
   103  However, 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  
   105  See https://github.com/kisielk/errcheck/issues/16 for more details.
   106  
   107  ## Exit Codes
   108  
   109  errcheck returns 1 if any problems were found in the checked files.
   110  It 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)
   117  integrates errcheck with Emacs by providing a `go-errcheck` command
   118  and 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`
   123  and `:GoMetaLinter` commands.