+++ /dev/null
-<!--(
- "Title": "Staticcheck"
-)-->
-
-
-<h2 id="overview">Overview</h2>
-
-<p>
- Staticcheck is a static analysis toolset for the <a href="https://golang.org">Go programming language.</a>
- It comes with a large number of checks,
- integrates with various Go build systems
- and offers enough customizability to fit into your workflows.
-</p>
-
-<h2 id="installation">Installation</h2>
-
-<p>
- There are various ways in which you can install staticcheck,
- but they all boil down to obtaining the command located at <code>honnef.co/go/tools/cmd/staticcheck</code>
-</p>
-
-<p>
- If you use Go modules, you can simply run <code>go get honnef.co/go/tools/cmd/staticcheck</code> to obtain the latest released version.
- If you're still using a GOPATH-based workflow, then the above command will instead fetch the master branch.
- It is suggested that you explicitly check out the latest release branch instead, which is currently <code>2020.1.5</code>.
- One way of doing so would be as follows:
-</p>
-
-<pre><code>cd $GOPATH/src/honnef.co/go/tools/cmd/staticcheck
-git checkout 2020.1.4
-go get
-go install
-</code></pre>
-
-<p>
- Alternatively, you can <a href="https://github.com/dominikh/go-tools/releases">download pre-compiled binaries from GitHub.</a>
-</p>
-
-<p>
- If you'd like to be notified of new releases, you can use GitHub's
- <a href="https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository"><em>Releases only</em> watches</a>.
-</p>
-
-<h2 id="running-the-tools">Running staticcheck</h2>
-
-<p>
- Staticcheck can be run on code in several ways,
- mimicking the way the official Go tools work.
- At the core, it expects to be run on well-formed Go packages.
- The most common way of specifying packages is via their import paths.
- One or more packages can be specified in a single command,
- and the <code>...</code> glob operator is supported.
- All of the following examples are valid invocations:
-
- <pre><code>staticcheck github.com/example/foo
-staticcheck github.com/example/foo github.com/example/bar
-staticcheck github.com/example/...</code></pre>
-</p>
-
-<p>
- In addition, a single package can be specified as a list of files:
-
- <pre><code>staticcheck file1.go file2.go file3.go</code></pre>
-
- Note that <strong>all</strong> files of the package need to be specified,
- similar to how <code>go build</code> works.
-</p>
-
-<h2 id="configuration">Configuration</h2>
-
-<p>
- Various aspects of staticcheck can be customized with configuration files.
-</p>
-
-<p>
- These files are placed in Go packages and apply recursively to the package tree rooted at the containing package.
- For example, configuration placed in <code>pkg</code> will apply to <code>pkg</code>, <code>pkg/subpkg</code>, <code>pkg/subpkg/subsubpkg</code> and so on.
-</p>
-
-<p>
- Configuration files in subpackages can override or inherit from settings of configuration files higher up the package tree.
- Staticcheck's default configuration is represented as the virtual root of the configuration tree and can be inherited from.
-</p>
-
-<h3>Configuration format</h3>
-
-<p>
- Staticcheck configuration files are named <code>staticcheck.conf</code> and contain <a href="https://github.com/toml-lang/toml">TOML</a>.
-</p>
-
-<p>
- Any set option will override the same option from further up the package tree,
- whereas unset options will inherit their values.
- Additionally, the special value <code>"inherit"</code> can be used to inherit values.
- This is especially useful for array values, as it allows adding and removing values to the inherited option.
-</p>
-
-<p>
- The special value <code>"all"</code> matches all possible values.
- Currently, this is only used when enabling checks.
-</p>
-
-<p>
- Values prefixed with a minus sign,
- such as <code>"-S1000"</code>
- will exclude values from a list.
- This can be used in combination with <code>"all"</code> to express "all but",
- or in combination with <code>"inherit"</code> to remove values from the inherited option.
-</p>
-
-<h3>Options</h3>
-
-<p>
- A list of all options and their explanations can be found on the <a href="/docs/options">Options</a> page.
-</p>
-
-<h3>Example configuration</h3>
-
-<p>
- The following example configuration is the textual representation of staticcheck's default configuration.
-</p>
-
-<pre><code>{{ option "checks" }} = ["all", "-{{ check "ST1000" }}", "-{{ check "ST1003" }}", "-{{ check "ST1016" }}"]
-{{ option "initialisms" }} = ["ACL", "API", "ASCII", "CPU", "CSS", "DNS",
- "EOF", "GUID", "HTML", "HTTP", "HTTPS", "ID",
- "IP", "JSON", "QPS", "RAM", "RPC", "SLA",
- "SMTP", "SQL", "SSH", "TCP", "TLS", "TTL",
- "UDP", "UI", "GID", "UID", "UUID", "URI",
- "URL", "UTF8", "VM", "XML", "XMPP", "XSRF",
- "XSS"]
-{{ option "dot_import_whitelist" }} = []
-{{ option "http_status_code_whitelist" }} = ["200", "400", "404", "500"]</code></pre>
-
-<h2 id="cli">Command-line flags</h2>
-
-<p>
- In addition to configuration files, some aspects of staticcheck can be controlled via command-line flags.
- These are settings that can vary between individual invocations or environments (CI, editors, ...) and shouldn't be stored in configuration files.
-</p>
-
-<table class="table">
- <tr>
- <th>Flag</th>
- <th>Description</th>
- </tr>
- <tr>
- <td>-checks</td>
- <td>
- Allows overriding the list of checks to run.
- Has the same syntax as the <a href="/docs/options#checks"><code>checks</code></a> setting
- in configuration files.
- </td>
- </tr>
- <tr>
- <td>-explain</td>
- <td>
- Print the description of a check.
- </td>
- </tr>
- <tr>
- <td>-f</td>
- <td>
- Select between the different <a href="/docs/formatters">output formats</a>.
- </td>
- </tr>
- <tr>
- <td>-fail</td>
- <td>
- Specify the list of checks which,
- if they find any issues in your code,
- should cause staticcheck to exit with a non-zero status.
- This can be used, for example, to not fail your CI
- pipeline because of possible code simplifications.
- </td>
- </tr>
- <tr>
- <td>-go</td>
- <td>
- Select the Go version to target.
- See
- <a href="#targeting-go-versions">Targeting Go versions</a>
- for more details.
- </td>
- </tr>
- <tr>
- <td style="white-space: nowrap">-show-ignored</td>
- <td>
- Show all problems found,
- even those that were ignored by linter directives.
- </td>
- </tr>
- <tr>
- <td>-tags</td>
- <td>
- Similar to <code>go build -tags</code>,
- allows specifying the build tags to use.
- </td>
- </tr>
- <tr>
- <td>-tests</td>
- <td>
- Include tests in the analysis.
- </td>
- </tr>
- <tr>
- <td>-unused.whole-program</td>
- <td>
- Run unused in whole program mode.
- </td>
- </tr>
- <tr>
- <td>-version</td>
- <td>
- Display the version of staticcheck and exit.
- </td>
- </tr>
-</table>
-
-<h2 id="targeting-go-versions">Targeting Go versions</h2>
-
-<p>
- By default, staticcheck will make suggestions that are correct for the current version of Go.
- If you're wishing to support older versions of Go,
- not all suggestions are applicable –
- some simplifications are only valid for newer versions of Go
- and deprecated functions may not have had viable alternatives in older versions.
-</p>
-
-<p>
- To target a specific Go version you can use the <code>-go</code> command line flag.
- For example, with <code>-go 1.6</code>, only suggestions that are valid for Go 1.6 will be made.
-</p>
-
-<h2 id="ignoring-problems">Ignoring problems</h2>
-
-<p>
- In general, you shouldn't have to ignore problems reported by staticcheck.
- Great care is taken to minimize the number of false positives and subjective suggestions.
- Dubious code should be rewritten and genuine false positives should be reported so that they can be fixed.
-</p>
-
-<p>
- The reality of things, however, is that not all corner cases can be taken into consideration.
- Sometimes code just has to look weird enough to confuse tools,
- and sometimes suggestions, though well-meant, just aren't applicable.
- For those rare cases, there are several ways of ignoring unwanted problems.
-</p>
-
-<h3 id="line-based-linter-directives">Line-based linter directives</h3>
-
-<p>
- The most fine-grained way of ignoring reported problems is to annotate the offending lines of code with linter directives.
-</p>
-
-<p>
- The <code>//lint:ignore Check1[,Check2,...,CheckN] reason</code> directive
- ignores one or more checks on the following line of code.
- The <code>reason</code> is a required field
- that must describe why the checks should be ignored for that line of code.
- This field acts as documentation for other people (including future you) reading the code.
-</p>
-
-<p>
- Let's consider the following example,
- which intentionally checks that the results of two identical function calls are not equal:
-
- <pre><code>func TestNewEqual(t *testing.T) {
- if errors.New("abc") == errors.New("abc") {
- t.Errorf(`New("abc") == New("abc")`)
- }
-}</code></pre>
-</p>
-
-<p>
- {{ check "SA4000" }} of staticcheck
- will flag this code,
- pointing out that the left and right side of <code>==</code> are identical –
- usually indicative of a typo and a bug.
-</p>
-
-<p>
- To silence this problem, we can use a linter directive:
-
- <pre><code>func TestNewEqual(t *testing.T) {
- //lint:ignore SA4000 we want to make sure that no two results of errors.New are ever the same
- if errors.New("abc") == errors.New("abc") {
- t.Errorf(`New("abc") == New("abc")`)
- }
-}</code></pre>
-</p>
-
-<h4>Maintenance of linter directives</h4>
-
-<p>
- It is crucial to update or remove outdated linter directives when code has been changed.
- Staticcheck helps you with this by making unnecessary directives a problem of its own.
- For example, for this (admittedly contrived) snippet of code
-
- <pre><code>//lint:ignore SA1000 we love invalid regular expressions!
-regexp.Compile(".+")</code></pre>
-
- staticcheck will report the following:
-
- <pre><code>tmp.go:1:2: this linter directive didn't match anything; should it be removed?</code></pre>
-</p>
-
-<p>
- Checks that have been disabled via configuration files
- will not cause directives to be considered unnecessary.
-</p>
-
-<h3 id="file-based-linter-directives">File-based linter directives</h3>
-
-<p>
- In some cases, you may want to disable checks for an entire file.
- For example, code generation may leave behind a lot of unused code,
- as it simplifies the generation process.
- Instead of manually annotating every instance of unused code,
- the code generator can inject a single, file-wide ignore directive to ignore the problem.
-</p>
-
-<p>
- File-based linter directives look a lot like line-based ones:
-
- <pre><code>//lint:file-ignore U1000 Ignore all unused code, it's generated</code></pre>
-</p>
-
-<p>
- The only difference is that these comments aren't associated with any specific line of code.
- Conventionally, these comments should be placed near the top of the file.
-</p>
-
-<p>
- Unlike line-based directives, file-based ones will not be flagged for being unnecessary.
-</p>
-
-<h2 id="resource-usage">Resource usage</h2>
-
-<p>
- Static analysis is a rather resource intensive process,
- having to apply expensive algorithms to a lot of data.
- Depending on the complexity of the checked code,
- this can result in many gigabytes of memory usage and minutes (if not hours) of CPU time.
-</p>
-
-<p>
- To combat the time complexity of static analysis, staticcheck makes use of caching.
- It reuses Go's build cache as well as its own facts cache to avoid analysing dependencies whenever possible.
- In development environments, there is usually nothing to do to benefit from these caches.
- In CI, however, you have to ensure that the caches persist across successive runs of CI.
- The build cache and fact cache are stored beneath the <code>os.UserCacheDir()</code> directory, in <code>go-build</code> and <code>staticcheck</code> respectively.
- On Linux, by default, these directories can be found in <code>~/.cache/go-build</code> and <code>~/.cache/staticcheck</code>.
-</p>
-
-<p>
- The overall memory consumption of staticcheck is controlled by the degree of parallelism.
- The more CPU cores a system has available, the more packages will be checked in parallel, increasing the total amount of memory needed.
- Staticcheck respects the <code>GOMAXPROCS</code> environment variable to control the degree of parallelism.
-</p>
-
-<p>
- Note that reducing <code>GOMAXPROCS</code> only benefits systems with a lot of cores and code bases with a lot of packages.
- As <code>GOMAXPROCS</code> approaches 1, peak memory usage will be dominated by the most complex package in the code base.
- Additionally, smaller code bases may have such interconnected dependencies that peak parallelism is never reached, or there may simply be fewer packages than cores.
- For example, when checking 10 packages it makes no difference if GOMAXPROCS is set to 32 or 16, at most 10 packages can be processed in parallel.
-</p>
-
-<p>
- Furthermore, a certain amount of type information per package needs to be retained until the end of the process,
- which means that overall memory usage grows with the number of checked packages.
- You can reduce this effect by disabling the U1000 and U1001 checks via the <code>-checks</code> command line flag (e.g. via <code>staticcheck -checks="inherit,-U1000,-U1001"</code>).
-</p>
-
-<p>
- Finally, you can trade execution time for memory usage by setting the <code>GOGC</code> environment variable to a value less than 100.
- This will run more frequent garbage collection, potentially lowering peak memory usage, at the cost of spending more CPU.
-</p>
-
-
-<h2>Checks</h2>
-
-A list of all checks can be found on the <a href="/docs/checks">Checks</a> page.
projects / dotfiles / .git / blobdiff