| 1 |
--- |
| 2 |
title: Command-line interface |
| 3 |
description: How to use the `staticcheck` command |
| 4 |
--- |
| 5 |
The `staticcheck` command is the primary way of running Staticcheck. |
| 6 |
|
| 7 |
At its core, the `staticcheck` command works a lot like `go vet` or `go build`. |
| 8 |
It accepts the same package patterns (see `go help packages` for details), |
| 9 |
it outputs problems in the same format, |
| 10 |
it supports a `-tags` flag for specifying which build tags to use, and so on. |
| 11 |
Overall, it is meant to feel like another `go` command. |
| 12 |
|
| 13 |
However, it also comes with several of its own flags to support some of its unique functionality. |
| 14 |
This article will focus on explaining that unique functionality. |
| 15 |
|
| 16 |
<!-- TODO --> |
| 17 |
<!-- ## Specifying which checks to run {#checks} --> |
| 18 |
|
| 19 |
## Explaining checks {#explain} |
| 20 |
|
| 21 |
You can use `staticcheck -explain <check>` to get a helpful description of a check. |
| 22 |
|
| 23 |
Every diagnostic that staticcheck reports is annotated with the identifier of the specific check that found the issue. For example, in |
| 24 |
|
| 25 |
```text |
| 26 |
foo.go:1248:4: unnecessary use of fmt.Sprintf (S1039) |
| 27 |
``` |
| 28 |
|
| 29 |
the check's identifier is S1039. Running `staticcheck -explain S1039` will output the following: |
| 30 |
|
| 31 |
```text |
| 32 |
Unnecessary use of fmt.Sprint |
| 33 |
|
| 34 |
Calling fmt.Sprint with a single string argument is unnecessary and identical to using the string directly. |
| 35 |
|
| 36 |
Available since |
| 37 |
2020.1 |
| 38 |
|
| 39 |
Online documentation |
| 40 |
https://staticcheck.dev/docs/checks#S1039 |
| 41 |
``` |
| 42 |
|
| 43 |
The output includes a one-line summary, one or more paragraphs of helpful text, the first version of Staticcheck that the check appeared in, and a link to online documentation, which contains the same information as the output of `staticcheck -explain`. |
| 44 |
|
| 45 |
## Selecting an output format {#format} |
| 46 |
|
| 47 |
Staticcheck can format its output in a number of ways, by using the `-f` flag. |
| 48 |
See this [list of formatters]({{< relref "/docs/running-staticcheck/cli/formatters" >}}) for a list of all formatters. |
| 49 |
|
| 50 |
<!-- TODO --> |
| 51 |
<!-- ## Controlling the exit status {#fail} --> |
| 52 |
|
| 53 |
## Targeting Go versions {#go} |
| 54 |
|
| 55 |
Some of Staticcheck's analyses adjust their behavior based on the targeted Go version. |
| 56 |
For example, the suggestion that one use `for range xs` instead of `for _ = range xs` only applies to Go 1.4 and later, as it won't compile with versions of Go older than that. |
| 57 |
|
| 58 |
By default, Staticcheck targets the Go version declared in `go.mod` via the `go` directive. |
| 59 |
For Go 1.21 and newer, that directive specifies the minimum required version of Go. |
| 60 |
|
| 61 |
For older versions of Go, the directive technically specifies the maximum version of language features that the module |
| 62 |
can use, which means it might be higher than the minimum required version. In those cases, you can manually overwrite |
| 63 |
the targeted Go version by using the `-go` command line flag. For example, `staticcheck -go 1.0 ./...` will only make |
| 64 |
suggestions that work with Go 1.0. |
| 65 |
|
| 66 |
The targeted Go version limits both language features and parts of the standard library that will be recommended. |
| 67 |
|
| 68 |
## Excluding tests {#tests} |
| 69 |
|
| 70 |
By default, Staticcheck analyses packages as well as their tests. |
| 71 |
By passing `-tests=false`, one can skip the analysis of tests. |
| 72 |
This is primarily useful for the {{< check "U1000" >}} check, as it allows finding code that is only used by tests and would otherwise be unused. |