Configuration

In this wiki page we first list the available flags with their meanings, then we list the driver-specific flags, and finally show how the flags are passed for each linter driver.

General Flags

include-pkgs

Default "" (all packages are included)

A comma-separated list of package prefixes to include for analysis.

By default all packages (including standard and 3rd party libraries) will be loaded by the driver and passed to the linters for analysis. This may not be desirable in practice: the errors reported on them cannot be fixed locally, and the overhead for analyzing them is pointless. Hence this flag can be set to include packages that have certain prefixes (e.g., go.uber.org), such that only first-party code is analyzed. If a package is excluded from analysis, default nilabilities will be assumed (e.g., functions will be assumed to always return nonnil pointers).

Warning

Please note that even if a package is excluded from analysis, errors might still be reported on them if the nilness flows happens within the analyzed package, but it includes using a struct from the excluded package. For example, if the analyzed package constructs a struct from the excluded package, assigns a nil to a field, and then immediately dereferences the field. In this case, NilAway will report an error for this flow, but the location will be on the field (that resides in the excluded package). To only report errors on the desired packages, please use the error suppression mechanisms specified in the driver (golangci-lint, nogo).

Added in v0.1.0

exclude-pkgs

Default "" (no packages are excluded)

A comma-separated list of package prefixes to exclude for analysis. This takes precedence over include-pkgs.

Added in v0.1.0

exclude-file-docstrings

Default "" (no files are excluded)

A comma-separated list of strings to search for in a file's docstrings to exclude a file from analysis.

Added in v0.1.0

pretty-print

Default false

A boolean flag indicating if NilAway should pretty print the errors (with ANSI color codes to highlight different components in the errors).

Added in v0.1.0

Driver-Specific Flags

Standalone Checker

Since the standalone linter driver does not support error suppression, which may be required for some deployments (see Include Package for a detailed discussion), we add two more flags to this specific checker for such functionality:

include-errors-in-files

Default is the current working directory, meaning we only report errors for files within the current working directory.

A comma-separated list of file prefixes to report errors.

Added in v0.1.0

exclude-errors-in-files

Default "", meaning no errors are suppressed.

A comma-separated list of file prefixes to exclude from error reporting. This takes precedence over include-errors-in-files.

Added in v0.1.0

json

Default false

A boolean flag indicating if the NilAway errors should be printed in JSON format for further post-processing.

Added in v0.1.0

Passing Configurations

NilAway adopts the standard flag passing mechanism in the go/analysis framework. However, the multi-analyzer architecture of NilAway (see wiki/Architecture) makes it slightly difficult to pass flags to NilAway. If we simply set the Flags fields to the top-level nilaway.Analyzer, by the time it is executed, the sub-analyzers have already done the work, making the flags meaningless (i.e., it can no long alter their behaviors).

To address this problem, we have defined a separate "nilaway_config" analyzer which is only responsible for defining the Flags field and expose the configs through its return value. All other sub-analyzers will depend on the config.Analyzer and use the values there to execute different logic.

This inevitably makes the configurations for NilAway slightly confusing: you will have to pass flags to the separate "nilaway_config" analyzer, while any error suppressions must be set for the top-level "nilaway" analyzer (since it is the one that eventually reports the errors).

Standalone Checker

For better UX, we lift the flags from "nilaway_config" to the top-level standalone driver, so they can be just specified by

nilaway -flag1 <VALUE> -flag2 <VALUE> ./...

nogo

Due to the architecture explained above, flags must be passed to NilAway via the nilaway_config analyzer, and the suppression must be passed directly to nilaway analyzer. Therefore, in your nogo's config.json file (see nogo's documentation on configurations on how to pass this file to the nogo driver), you have to specify configurations for two analyzers. For example:

{
  "nilaway_config": {
    "analyzer_flags": {
      "include-pkgs": "go.uber.org",
      "exclude-pkgs": "vendor/",
      "exclude-file-docstrings": "@generated,Code generated by,Autogenerated by"
    }
  },
  "nilaway": {
    "exclude_files": {
      "bazel-out": "this prevents nilaway from outputting diagnostics on intermediate test files"
    },
    "only_files": {
      "my/code/path": "This is the comment for why we want to enable NilAway on this code path"
    }
  },
}

golangci-lint

See our README on why we currently cannot support golangci-lint (help wanted!)