6 <h2 id="overview">Overview</h2>
9 Staticcheck is a static analysis toolset for the <a href="https://golang.org">Go programming language.</a>
10 It comes with a large number of checks,
11 integrates with various Go build systems
12 and offers enough customizability to fit into your workflows.
15 <h2 id="installation">Installation</h2>
18 There are various ways in which you can install staticcheck,
19 but they all boil down to obtaining the command located at <code>honnef.co/go/tools/cmd/staticcheck</code>
23 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.
24 If you're still using a GOPATH-based workflow, then the above command will instead fetch the master branch.
25 It is suggested that you explicitly check out the latest release tag instead, which is currently <code>2020.2.1</code>.
26 One way of doing so would be as follows:
29 <pre><code>cd $GOPATH/src/honnef.co/go/tools/cmd/staticcheck
36 Alternatively, you can <a href="https://github.com/dominikh/go-tools/releases">download pre-compiled binaries from GitHub.</a>
40 If you'd like to be notified of new releases, you can use GitHub's
41 <a href="https://help.github.com/en/articles/watching-and-unwatching-releases-for-a-repository"><em>Releases only</em> watches</a>.
44 <h2 id="running-the-tools">Running staticcheck</h2>
47 Staticcheck can be run on code in several ways,
48 mimicking the way the official Go tools work.
49 At the core, it expects to be run on well-formed Go packages.
50 The most common way of specifying packages is via their import paths.
51 One or more packages can be specified in a single command,
52 and the <code>...</code> glob operator is supported.
53 All of the following examples are valid invocations:
55 <pre><code>staticcheck github.com/example/foo
56 staticcheck github.com/example/foo github.com/example/bar
57 staticcheck github.com/example/...</code></pre>
61 In addition, a single package can be specified as a list of files:
63 <pre><code>staticcheck file1.go file2.go file3.go</code></pre>
65 Note that <strong>all</strong> files of the package need to be specified,
66 similar to how <code>go build</code> works.
69 <h2 id="configuration">Configuration</h2>
72 Various aspects of staticcheck can be customized with configuration files.
76 These files are placed in Go packages and apply recursively to the package tree rooted at the containing package.
77 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.
81 Configuration files in subpackages can override or inherit from settings of configuration files higher up the package tree.
82 Staticcheck's default configuration is represented as the virtual root of the configuration tree and can be inherited from.
85 <h3>Configuration format</h3>
88 Staticcheck configuration files are named <code>staticcheck.conf</code> and contain <a href="https://github.com/toml-lang/toml">TOML</a>.
92 Any set option will override the same option from further up the package tree,
93 whereas unset options will inherit their values.
94 Additionally, the special value <code>"inherit"</code> can be used to inherit values.
95 This is especially useful for array values, as it allows adding and removing values to the inherited option.
99 The special value <code>"all"</code> matches all possible values.
100 Currently, this is only used when enabling checks.
104 Values prefixed with a minus sign,
105 such as <code>"-S1000"</code>
106 will exclude values from a list.
107 This can be used in combination with <code>"all"</code> to express "all but",
108 or in combination with <code>"inherit"</code> to remove values from the inherited option.
114 A list of all options and their explanations can be found on the <a href="/docs/options">Options</a> page.
117 <h3>Example configuration</h3>
120 The following example configuration is the textual representation of staticcheck's default configuration.
123 <pre><code>{{ option "checks" }} = ["all", "-{{ check "ST1000" }}", "-{{ check "ST1003" }}", "-{{ check "ST1016" }}"]
124 {{ option "initialisms" }} = ["ACL", "API", "ASCII", "CPU", "CSS", "DNS",
125 "EOF", "GUID", "HTML", "HTTP", "HTTPS", "ID",
126 "IP", "JSON", "QPS", "RAM", "RPC", "SLA",
127 "SMTP", "SQL", "SSH", "TCP", "TLS", "TTL",
128 "UDP", "UI", "GID", "UID", "UUID", "URI",
129 "URL", "UTF8", "VM", "XML", "XMPP", "XSRF",
131 {{ option "dot_import_whitelist" }} = []
132 {{ option "http_status_code_whitelist" }} = ["200", "400", "404", "500"]</code></pre>
134 <h2 id="cli">Command-line flags</h2>
137 In addition to configuration files, some aspects of staticcheck can be controlled via command-line flags.
138 These are settings that can vary between individual invocations or environments (CI, editors, ...) and shouldn't be stored in configuration files.
141 <table class="table">
149 Allows overriding the list of checks to run.
150 Has the same syntax as the <a href="/docs/options#checks"><code>checks</code></a> setting
151 in configuration files.
157 Print the description of a check.
163 Select between the different <a href="/docs/formatters">output formats</a>.
169 Specify the list of checks which,
170 if they find any issues in your code,
171 should cause staticcheck to exit with a non-zero status.
172 This can be used, for example, to not fail your CI
173 pipeline because of possible code simplifications.
179 Select the Go version to target.
181 <a href="#targeting-go-versions">Targeting Go versions</a>
186 <td style="white-space: nowrap">-show-ignored</td>
188 Show all problems found,
189 even those that were ignored by linter directives.
195 Similar to <code>go build -tags</code>,
196 allows specifying the build tags to use.
202 Include tests in the analysis.
208 Display the version of staticcheck and exit.
213 <h2 id="targeting-go-versions">Targeting Go versions</h2>
216 By default, staticcheck will make suggestions that are correct for the current version of Go.
217 If you're wishing to support older versions of Go,
218 not all suggestions are applicable –
219 some simplifications are only valid for newer versions of Go
220 and deprecated functions may not have had viable alternatives in older versions.
224 To target a specific Go version you can use the <code>-go</code> command line flag.
225 For example, with <code>-go 1.6</code>, only suggestions that are valid for Go 1.6 will be made.
228 <h2 id="ignoring-problems">Ignoring problems</h2>
231 In general, you shouldn't have to ignore problems reported by staticcheck.
232 Great care is taken to minimize the number of false positives and subjective suggestions.
233 Dubious code should be rewritten and genuine false positives should be reported so that they can be fixed.
237 The reality of things, however, is that not all corner cases can be taken into consideration.
238 Sometimes code just has to look weird enough to confuse tools,
239 and sometimes suggestions, though well-meant, just aren't applicable.
240 For those rare cases, there are several ways of ignoring unwanted problems.
243 <h3 id="line-based-linter-directives">Line-based linter directives</h3>
246 The most fine-grained way of ignoring reported problems is to annotate the offending lines of code with linter directives.
250 The <code>//lint:ignore Check1[,Check2,...,CheckN] reason</code> directive
251 ignores one or more checks on the following line of code.
252 The <code>reason</code> is a required field
253 that must describe why the checks should be ignored for that line of code.
254 This field acts as documentation for other people (including future you) reading the code.
258 Let's consider the following example,
259 which intentionally checks that the results of two identical function calls are not equal:
261 <pre><code>func TestNewEqual(t *testing.T) {
262 if errors.New("abc") == errors.New("abc") {
263 t.Errorf(`New("abc") == New("abc")`)
269 {{ check "SA4000" }} of staticcheck
271 pointing out that the left and right side of <code>==</code> are identical –
272 usually indicative of a typo and a bug.
276 To silence this problem, we can use a linter directive:
278 <pre><code>func TestNewEqual(t *testing.T) {
279 //lint:ignore SA4000 we want to make sure that no two results of errors.New are ever the same
280 if errors.New("abc") == errors.New("abc") {
281 t.Errorf(`New("abc") == New("abc")`)
286 <h4>Maintenance of linter directives</h4>
289 It is crucial to update or remove outdated linter directives when code has been changed.
290 Staticcheck helps you with this by making unnecessary directives a problem of its own.
291 For example, for this (admittedly contrived) snippet of code
293 <pre><code>//lint:ignore SA1000 we love invalid regular expressions!
294 regexp.Compile(".+")</code></pre>
296 staticcheck will report the following:
298 <pre><code>tmp.go:1:2: this linter directive didn't match anything; should it be removed?</code></pre>
302 Checks that have been disabled via configuration files
303 will not cause directives to be considered unnecessary.
306 <h3 id="file-based-linter-directives">File-based linter directives</h3>
309 In some cases, you may want to disable checks for an entire file.
310 For example, code generation may leave behind a lot of unused code,
311 as it simplifies the generation process.
312 Instead of manually annotating every instance of unused code,
313 the code generator can inject a single, file-wide ignore directive to ignore the problem.
317 File-based linter directives look a lot like line-based ones:
319 <pre><code>//lint:file-ignore U1000 Ignore all unused code, it's generated</code></pre>
323 The only difference is that these comments aren't associated with any specific line of code.
324 Conventionally, these comments should be placed near the top of the file.
328 Unlike line-based directives, file-based ones will not be flagged for being unnecessary.
331 <h2 id="resource-usage">Resource usage</h2>
334 Static analysis is a rather resource intensive process,
335 having to apply expensive algorithms to a lot of data.
336 Depending on the complexity of the checked code,
337 this can result in many gigabytes of memory usage and minutes (if not hours) of CPU time.
341 To combat the time complexity of static analysis, staticcheck makes use of caching.
342 It reuses Go's build cache as well as its own facts cache to avoid analysing dependencies whenever possible.
343 In development environments, there is usually nothing to do to benefit from these caches.
344 In CI, however, you have to ensure that the caches persist across successive runs of CI.
345 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.
346 On Linux, by default, these directories can be found in <code>~/.cache/go-build</code> and <code>~/.cache/staticcheck</code>.
350 The overall memory consumption of staticcheck is controlled by the degree of parallelism.
351 The more CPU cores a system has available, the more packages will be checked in parallel, increasing the total amount of memory needed.
352 Staticcheck respects the <code>GOMAXPROCS</code> environment variable to control the degree of parallelism.
356 Note that reducing <code>GOMAXPROCS</code> only benefits systems with a lot of cores and code bases with a lot of packages.
357 As <code>GOMAXPROCS</code> approaches 1, peak memory usage will be dominated by the most complex package in the code base.
358 Additionally, smaller code bases may have such interconnected dependencies that peak parallelism is never reached, or there may simply be fewer packages than cores.
359 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.
363 Finally, you can trade execution time for memory usage by setting the <code>GOGC</code> environment variable to a value less than 100.
364 This will run more frequent garbage collection, potentially lowering peak memory usage, at the cost of spending more CPU.
370 A list of all checks can be found on the <a href="/docs/checks">Checks</a> page.