Debian Codegraph @

website/content/docs/configuration/_index.md

raw
1 ---
2 title: "Configuration"
3 description: "Tweak Staticcheck to your requirements"
4 weight: 3
5 ---
6
7 Staticcheck tries to provide a good out-of-the-box experience, but it also offers a number of options to fine-tune it to your specific needs.
8
9 ## Command-line flags {#cli-flags}
10
11 Staticcheck uses command-line flags for settings that are specific to single invocations and that may change depending on the context (local development, continuous integration etc).
12 This includes which build tags to set and which output format to use.
13 All of the CLI flags are explained in the [Command-line interface]({{< relref "/docs/running-staticcheck/cli" >}}) article.
14
15 ## Configuration files {#configuration-files}
16
17 Staticcheck uses configuration files for settings that apply to all users of Staticcheck on a given project.
18 Configuration files can choose which checks to run as well as tweak the behavior of individual checks.
19
20 Configuration files are named `staticcheck.conf` and apply to subtrees of packages. Consider the following tree of Go packages and configuration files:
21
22 ```plain
23 .
24 ├── net
25 │ ├── cgi
26 │ ├── http
27 │ │ ├── parser
28 │ │ └── staticcheck.conf // config 3
29 │ └── staticcheck.conf // config 2
30 ├── staticcheck.conf // config 1
31 └── strconv
32 ```
33
34 Config 1 will apply to all packages, config 2 will apply to `./net/...` and config 3 will apply to `./net/http/...`.
35 When multiple configuration files apply to a package (for example, all three configs will apply to `./net/http`) they will be merged, with settings in files deeper in the package tree overriding rules higher up the tree.
36
37 ### Configuration format {#configuration-format}
38
39 Staticcheck configuration files are named `staticcheck.conf` and contain [TOML](https://github.com/toml-lang/toml).
40
41 Any set option will override the same option from further up the package tree,
42 whereas unset options will inherit their values.
43 Additionally, the special value `"inherit"` can be used to inherit values.
44 This is especially useful for array values, as it allows adding and removing values to the inherited option.
45 For example, the option `checks = ["inherit", "ST1000"]` will inherit the enabled checks and additionally enable ST1000.
46
47 The special value `"all"` matches all possible values.
48 this is used when enabling or disabling checks.
49
50 Values prefixed with a minus sign, such as `"-S1000"` will exclude values from a list.
51 This can be used in combination with `"all"` to express "all but",
52 or in combination with `"inherit"` to remove values from the inherited option.
53
54 ### Configuration options {#configuration-options}
55
56 A list of all options and their explanations can be found on the [Options]({{< relref "/docs/configuration/options" >}}) page.
57
58 ### Example configuration {#example-configuration}
59
60 The following example configuration is the textual representation of Staticcheck's default configuration.
61
62 {{% content "default_config.md" %}}
63
64 ## Ignoring problems with linter directives {#ignoring-problems}
65
66 In general, you shouldn't have to ignore problems reported by Staticcheck.
67 Great care is taken to minimize the number of false positives and subjective suggestions.
68 Dubious code should be rewritten and genuine false positives should be reported so that they can be fixed.
69
70 The reality of things, however, is that not all corner cases can be taken into consideration.
71 Sometimes code just has to look weird enough to confuse tools,
72 and sometimes suggestions, though well-meant, just aren't applicable.
73 For those rare cases, there are several ways of ignoring unwanted problems.
74
75 ### Line-based linter directives {#line-based-linter-directives}
76
77 The most fine-grained way of ignoring reported problems is to annotate the offending lines of code with linter directives.
78
79 The `//lint:ignore Check1[,Check2,...,CheckN] reason` directive
80 ignores one or more checks on the following line of code.
81 The `reason` is a required field
82 that must describe why the checks should be ignored for that line of code.
83 This field acts as documentation for other people (including future you) reading the code.
84
85 Let's consider the following example,
86 which intentionally checks that the results of two identical function calls are not equal:
87
88 ```go
89 func TestNewEqual(t *testing.T) {
90 if errors.New("abc") == errors.New("abc") {
91 t.Errorf(`New("abc") == New("abc")`)
92 }
93 }
94 ```
95
96 {{< check "SA4000" >}} will flag this code,
97 pointing out that the left and right side of `==` are identical –
98 usually indicative of a typo and a bug.
99
100 To silence this problem, we can use a linter directive:
101
102 ```go
103 func TestNewEqual(t *testing.T) {
104 //lint:ignore SA4000 we want to make sure that no two results of errors.New are ever the same
105 if errors.New("abc") == errors.New("abc") {
106 t.Errorf(`New("abc") == New("abc")`)
107 }
108 }
109 ```
110
111 ### Maintenance of linter directives {#maintenance-of-linter-directives}
112
113 It is crucial to update or remove outdated linter directives when code has been changed.
114 Staticcheck helps you with this by making unnecessary directives a problem of its own.
115 For example, for this (admittedly contrived) snippet of code
116
117 ```go
118 //lint:ignore SA1000 we love invalid regular expressions!
119 regexp.Compile(".+")
120 ```
121
122 Staticcheck will report the following:
123
124 ```plain
125 tmp.go:1:2: this linter directive didn't match anything; should it be removed?
126 ```
127
128 Checks that have been disabled via configuration files will not cause directives to be considered unnecessary.
129
130 ### File-based linter directives {#file-based-linter-directives}
131
132 In some cases, you may want to disable checks for an entire file.
133 For example, code generation may leave behind a lot of unused code,
134 as it simplifies the generation process.
135 Instead of manually annotating every instance of unused code,
136 the code generator can inject a single, file-wide ignore directive to ignore the problem.
137
138 File-based linter directives look a lot like line-based ones:
139
140 ```go
141 //lint:file-ignore U1000 Ignore all unused code, it's generated
142 ```
143
144 The only difference is that these comments aren't associated with any specific line of code.
145 Conventionally, these comments should be placed near the top of the file.
146
147 Unlike line-based directives, file-based ones will not be flagged for being unnecessary.