nitpick

Find Go hygiene problems that a compiler and most linters let through. Report only the lines that a change touched, with a measured precision for each rule.

tuios.dev/nitpick finds Go hygiene problems: errors that are dropped, development defaults read from the environment, comments that say what the next line says, deep nesting and code kept in comments. Each rule is a plain go/analysis analyzer. The nitpick command runs the rules and can report only the lines that a change touched.

Each rule has a precision. The precision is the share of its findings that a labeller judged worth a change, on a labelled sample of real Go code. Each finding shows it, and --gate uses it.

Install

go install tuios.dev/nitpick/cmd/nitpick@latest

The command needs Go 1.26 or later. The library requires only golang.org/x/tools. The API reference is on pkg.go.dev.

Check a change

nitpick diff                        # findings on the lines changed since HEAD
nitpick diff --base origin/main     # findings on the lines this branch changed
nitpick diff --staged --gate 90%    # exit 1 when a staged finding has a precision of 90% or more

nitpick diff reads git diff. Without --staged, it uses the working tree, and an untracked Go file counts as new. With --base REF, it starts at the merge base of REF and HEAD. Without packages, it checks the packages of the changed files.

Each finding shows the precision of its rule:

store/load.go:42:3: error_to_empty_success: the err != nil branch returns empty values and a nil error, so the caller sees a success (precision 55%)

Check packages

nitpick check ./...                 # every finding in the packages
nitpick rules                       # the rules and their precision

nitpick check checks ./... when you give no packages.

Rules

RuleDefaultPrecisionWhat it reports
swallowed_erroroff10%_ = f() that drops an error in a function that returns an error, and an empty if err != nil {}
error_to_empty_successon55%if err != nil { return nil, nil } and other empty returns with a nil error
config_fallbackoff0%An environment variable that falls back to a development value, such as localhost
narrator_commenton85%A comment that says what the next line says
deep_nestingon65%Control nesting of 5 or more in one function
elision_commentoff75%A comment that stands in for missing code, such as "rest of implementation"
junk_identifieroff33%A name such as foo, stuff or data2
commented_out_codeon61%Go code kept in a comment
nolint_without_reasonoff20%A //nolint directive with no reason

A rule is on by default when its precision is 50% or more on a sample of 10 or more. A sample under 20 gives a wide interval, so read those numbers as a first estimate. PRECISION.md gives the method, the sample sizes and the intervals.

A comment with a reason silences most rules. Write why the error is dropped, and the finding goes away.

Flags

FlagMeaning
--jsonWrite JSON: findings (file, line, column, rule, message, precision), errors, gate_failed.
--gate PExit with 1 when a finding has a precision of P or more. P is 0.9 or 90%.
--enable LISTTurn on more rules. LIST is rule names with commas, or all.
--disable LISTTurn off rules.
--tests=falseDo not check _test.go files.
--base REFCompare with REF. The default is HEAD. Only nitpick diff reads it.
--stagedUse the staged changes only. Only nitpick diff reads it.

In JSON, precision is a fraction from 0 to 1. The exit status is 0 when the gate passes, 1 when it fails, and 2 on an error, such as a package that does not compile.

{
  "findings": [
    {
      "file": "store/load.go",
      "line": 42,
      "column": 3,
      "rule": "error_to_empty_success",
      "message": "the err != nil branch returns empty values and a nil error, so the caller sees a success",
      "precision": 0.5454545454545454
    }
  ],
  "gate": 0.5,
  "gate_failed": true
}

A pre-commit hook or a CI step can use the gate. This step fails when the branch adds a finding with a precision of 60% or more:

nitpick diff --base origin/main --gate 60%

Use the analyzers in your own driver

nitpick.Analyzers() returns the analyzers of the default rules. Any go/analysis driver can run them. This program is a vet tool with the default rules:

package main

import (
	"golang.org/x/tools/go/analysis/multichecker"
	"tuios.dev/nitpick"
)

func main() {
	multichecker.Main(nitpick.Analyzers()...)
}

Each analyzer is also a variable of its own, such as nitpick.SwallowedError or nitpick.DeepNesting. Add one to the list to turn on a rule that is off by default. nitpick.Rules lists every rule with its default, precision and sample size:

for _, r := range nitpick.Rules {
	fmt.Println(r.Name(), r.Default, r.Precision, r.Sample)
}

A driver reports every finding in the packages. Only the nitpick command limits the report to changed lines.

API overview

NameDoes
AnalyzersThe analyzers of the default rules.
Rules, RuleEvery rule with its analyzer, default, precision and sample size.
LookupThe rule with a given name.

Versions

The module is at v0 and has no tag yet. The rules, their precision and their defaults can change before v1. Its tags will have the folder name as a prefix, such as nitpick/v0.1.0. The source is in the nitpick folder of the tuios repository, under the MIT licence.

The idea of a diff-scoped hygiene check with a measured precision comes from nits. nitpick shares no code with it.

tuios lives only at tuios.dev and github.com/Gaurav-Gosain/tuios. tuios has no X or Twitter account. An account that offers a tuios token or presale is not this project.

On this page