22
33[ ![ Go Reference] ( https://pkg.go.dev/badge/fillmore-labs.com/zerolint.svg )] ( https://pkg.go.dev/fillmore-labs.com/zerolint )
44[ ![ Test] ( https://github.com/fillmore-labs/zerolint/actions/workflows/test.yml/badge.svg?branch=main )] ( https://github.com/fillmore-labs/zerolint/actions/workflows/test.yml )
5+ [ ![ CodeQL] ( https://github.com/fillmore-labs/zerolint/actions/workflows/github-code-scanning/codeql/badge.svg?branch=main )] ( https://github.com/fillmore-labs/zerolint/actions/workflows/github-code-scanning/codeql )
56[ ![ Coverage] ( https://codecov.io/gh/fillmore-labs/zerolint/branch/main/graph/badge.svg?token=TUE1BL1QZV )] ( https://codecov.io/gh/fillmore-labs/zerolint )
67[ ![ Maintainability] ( https://api.codeclimate.com/v1/badges/baf50ad423cc30ff7790/maintainability )] ( https://codeclimate.com/github/fillmore-labs/zerolint/maintainability )
78[ ![ Go Report Card] ( https://goreportcard.com/badge/fillmore-labs.com/zerolint )] ( https://goreportcard.com/report/fillmore-labs.com/zerolint )
89[ ![ License] ( https://img.shields.io/github/license/fillmore-labs/zerolint )] ( https://www.apache.org/licenses/LICENSE-2.0 )
910
10- The ` zerolint ` linter checks usage patterns of pointers to zero-size variables in Go.
11+ ` zerolint ` is a Go static analysis tool (linter) that detects potentially wrong or unnecessary usage of pointers to
12+ zero-sized types.
13+
14+ ## Motivation
15+
16+ Go's zero-sized types, like ` struct{} ` or ` [0]byte ` , occupy no memory. While useful in certain contexts (e.g.,
17+ signaling on channels, map keys/values for set semantics), taking the address of a zero-sized variable (` &struct{}{} ` )
18+ or allocating them (` new(struct{}) ` ) is often redundant.
19+
20+ All values of a zero-sized type are indistinguishable, so pointers to them generally don't convey unique state or
21+ identity. Using pointers to zero-sized types can obscure intent, as readers might mistakenly assume the pointer implies
22+ state or identity management. Also, since pointers are not zero-sized, it introduces minor performance overhead and
23+ waste of memory.
24+
25+ ` zerolint ` helps identify these patterns, promoting cleaner and potentially more efficient code.
1126
1227## Usage
1328
1429``` console
30+ # Install the linter
1531go install fillmore-labs.com/zerolint@latest
1632```
1733
@@ -20,8 +36,70 @@ Usage: `zerolint [-flag] [package]`
2036Flags:
2137
2238- ** -c** int display offending line with this many lines of context (default -1)
23- - ** -full** full analysis
24- - ** -excluded** ` <filename> ` read excluded types from this file
25- - ** -zerotrace** trace found zero-sized types
26- - ** -fix** apply all suggested fixes
27- - ** -generated** analyze generated files and types defined in generated files
39+ - ** -level** Perform a more comprehensive analysis (Default, Extended, Full)
40+ - ** -match** Regex limiting zero-sized type detection only to matching types. Useful with ` -fix ` .
41+ - ** -excluded** ` <filename> ` Read types to be excluded from analysis from the specified file. The file should contain
42+ fully qualified type names, one per line. See Excluding Types.
43+ - ** -generated** Analyze files that contain code generation markers (e.g., ` // Code generated ... DO NOT EDIT. ` ). By
44+ default, these files are skipped.
45+ - ** -zerotrace** Enable verbose logging which types zerolint identifies as zero-sized. Useful for building a list of
46+ excluded types.
47+ - ** -fix** Apply all suggested fixes automatically. Use with caution and always review the changes made by ` -fix ` .
48+
49+ ## Examples
50+
51+ Consider the following Go code:
52+
53+ ``` go
54+ // main.go
55+ package main
56+
57+ type myError struct {}
58+
59+ func (*myError ) Error () string {
60+ return " my error"
61+ }
62+
63+ func processing () error {
64+ return &myError{}
65+ }
66+
67+ func main () {
68+ if err := processing (); err != nil {
69+ panic (err)
70+ }
71+ }
72+ ```
73+
74+ Running ` zerolint % zerolint -level 2 ./... ` would produce output similar to:
75+
76+ ``` text
77+ /path/to/your/project/main.go:6:7: error interface implemented on pointer to zero-sized type "example.com/project.myError" (zl:err)
78+ /path/to/your/project/main.go:11:9: address of zero-size variable of type "example.com/project.myError" (zl:add)
79+ ```
80+
81+ ## Excluding Types
82+
83+ If you have specific zero-sized types where pointer usage is intentional or required (e.g., due to external library
84+ constraints), you can exclude them using the ` -excluded ` flag with a file path.
85+
86+ Example ` excludes.txt ` :
87+
88+ ``` text
89+ # zerolint excludes for my project
90+ example.com/some/pkg.RequiredPointerType
91+ vendor.org/library.MarkerInterfaceImplementation
92+ ```
93+
94+ Then run: ` zerolint -excluded=excludes.txt ./... `
95+
96+ ## Integration
97+
98+ See ` zerolint-golangci-plugin `
99+
100+ ## Known Bugs
101+
102+ We are aware of a number of minor bugs in the analyzer's fixes. For example, it may sometimes cause a type not
103+ implement an interface or check a non-pointer type for nil. The known bugs are low-risk and easy to fix, as they result
104+ in a broken build or are obvious during a code review; none cause latent behavior changes. Please report any additional
105+ problems you encounter.
0 commit comments