Advanced Topics

Relevant source files

• .github/instructions/go.instructions.md
• DEVELOPING.md
• README.md
• RULES_DESCRIPTIONS.md
• config/config.go
• config/config_test.go
• lint/file.go
• lint/linter.go
• lint/linter_test.go
• lint/package.go
• logging/logger.go
• logging/logger_test.go
• test/file_filter_test.go
• test/golint_test.go
• test/utils_test.go

This page covers specialized features and advanced integration patterns in revive. These topics are essential for users who need fine-grained control over linting behavior, want to understand revive's internal mechanisms, or need to integrate revive into complex development workflows.

For information about creating custom rules, see Creating Custom Rules. For basic configuration, see Configuration System. For information about specific rules, see Rule System.

---

In-Code Directives

Revive supports inline directives that allow developers to selectively enable or disable linting rules within source files using specially-formatted comments. This mechanism provides granular control over rule application without modifying configuration files.

Directive Syntax

The directive parser uses a regular expression to match comment patterns:

//revive:(enable|disable)(?:-(line|next-line))?(?::([^\s]+))?[\s]*(?: (.+))?$

This pattern supports:

• Action: enable or disable
• Modifier: -line (current line only) or -next-line (following line only)
• Rule Names: Optional comma-separated list after :
• Reason: Optional trailing text explaining why the rule was disabled

Sources: lint/file.go164

Directive Types and Scope

Directive Pattern	Scope	Example
//revive:disable	From this line to end of file or next enable	//revive:disable
//revive:enable	Re-enables previously disabled rules	//revive:enable
//revive:disable-line	Current line only	x := 1 //revive:disable-line:var-naming
//revive:disable-next-line	Following line only	//revive:disable-next-line:exported
//revive:disable:rule-name	Specific rule(s), comma-separated	//revive:disable:cyclomatic,cognitive-complexity

DisabledInterval Calculation

The directive processing system converts comments into DisabledInterval structures that represent line ranges where specific rules are inactive:

Sources: lint/file.go166-274 lint/file.go276-302

Mandatory Disable Reasons

Revive can enforce that all disable directives include an explanation. This is configured via the specify-disable-reason directive in the configuration file:

When enabled, any //revive:disable comment without a trailing reason text will generate a linting failure with the rule name specify-disable-reason.

Implementation Details:

• The reason text is extracted at position 4 in the regex match: match[reasonPos]
• The check occurs during directive parsing in handleComment function
• Failures are sent directly to the failures channel when reasons are missing

Sources: lint/file.go115 lint/file.go246-256 README.md315-326

Directive Processing Algorithm

Sources: lint/file.go166-274

---

File Filtering and Exclusions

Revive provides multiple mechanisms for excluding files from linting, both at the global level and per-rule. This system uses pattern matching with support for literal paths, glob patterns, and regular expressions.

Exclude Pattern Types

The RuleConfig.Exclude field accepts an array of strings that can be:

Pattern Type	Syntax	Example	Description
Full Path	Literal string	src/pkg/mypkg/some.go	Exact file path match
Glob Pattern	** and * wildcards	src/**/*.pb.go	Pattern matching with wildcards
Regex	Prefix with ~	~\.(pb|auto|generated)\.go$	Regular expression match
Special: TEST	Keyword TEST	TEST	Matches all **/*_test.go files
Special: Wildcard	* or ~ alone	*	Excludes all files (effectively disables rule)
Special: Empty	""	""	Excludes nothing (no-op)

Sources: README.md490-499

RuleConfig.MustExclude Implementation

The exclusion logic is implemented in the RuleConfig structure:

Sources: lint/rule.go (inferred from README documentation and test files)

Configuration Example

Per-rule exclusions are configured in the TOML file:

The exclusion patterns are evaluated during the linting phase in File.lint():

Sources: lint/file.go117-148 README.md471-500

Global vs Rule-Level Exclusions

Exclusion Level	Configuration	Scope	Processed By
Global	CLI flag -exclude	All rules, all files	dots.ResolvePackages
Rule-Level	[rule.name] Exclude = [...]	Specific rule only	RuleConfig.MustExclude

Global exclusions prevent files from being parsed entirely, while rule-level exclusions skip specific rules for matched files but allow other rules to run.

Sources: README.md248-251 lint/file.go121-125

---

Go Version Detection

Revive automatically detects the Go version requirement for each package by traversing the directory tree to locate go.mod files and parsing the go directive. This version information is used by version-specific rules to adjust their behavior.

Version Detection Algorithm

Sources: lint/linter.go61-123 lint/linter.go159-202 lint/linter.go183-202

Module Version Caching

The linter maintains two caching structures:

1. perModVersions: map[string]*goversion.Version - Maps module root directories to their Go versions
2. perPkgVersions: []*goversion.Version - Parallel array storing the resolved version for each package

This caching strategy avoids redundant file system traversal and go.mod parsing when multiple packages belong to the same module.

Sources: lint/linter.go64-100

Version Constants

The lint package defines several Go version constants used by rules:

Constant	Version	Usage
Go115	1.15	Reserved for version-specific behavior
Go121	1.21	Used by rules checking 1.21+ features
Go122	1.22	Used by rules checking 1.22+ features (e.g., range over integers)
Go124	1.24	Used by rules checking 1.24+ features
Go125	1.25	Used by rules checking 1.25+ features (e.g., WaitGroup.Go)

Sources: lint/package.go37-46

Package.IsAtLeastGoVersion

Rules query the detected version using the Package.IsAtLeastGoVersion method:

This method performs thread-safe comparison: p.goVersion.GreaterThanOrEqual(v)

Sources: lint/package.go219-224

---

Type Checking and AST Analysis

Revive leverages Go's type checker (go/types package) to perform advanced static analysis. Type checking is performed on-demand when rules require type information, such as checking whether an expression has a specific type or resolving method receivers.

Type Checking Workflow

Sources: lint/package.go102-157

types.Info Structure

The types.Info structure populated by type checking provides four key maps:

Map	Type	Purpose
Types	map[ast.Expr]types.TypeAndValue	Maps expressions to their types and constant values
Defs	map[*ast.Ident]types.Object	Maps identifiers to the objects they define
Uses	map[*ast.Ident]types.Object	Maps identifiers to the objects they reference
Scopes	map[ast.Node]*types.Scope	Maps AST nodes to their lexical scopes

Sources: lint/package.go117-122

Error Handling Strategy

Type checking uses a no-op error reporter to maximize partial results:

Additionally, the check helper function wraps config.Check() with panic recovery to prevent crashes from type checker issues (see issue #59).

Sources: lint/package.go112-116 lint/package.go145-157

Sortable Interface Detection

Before linting, packages scan for types implementing sort.Interface by looking for methods:

• Len() int
• Less(int, int) bool
• Swap(int, int)

Rules can then query pkg.Sortable() to check if a type implements the sorting interface.

Sources: lint/package.go180-204 lint/package.go226-237

Type-Aware Rules

Rules that require type checking are marked with "Typed: yes" in the documentation. Examples include:

• context-keys-type: Checks basic types in context.WithValue
• errorf: Detects errors.New(fmt.Sprintf()) patterns
• string-of-int: Warns on string(intValue) conversions
• time-equal: Suggests using time.Time.Equal instead of ==
• unchecked-type-assertion: Requires checked type assertions

Sources: README.md506-608

---

Integration with Other Tools

Revive integrates seamlessly into diverse development environments through multiple mechanisms: direct editor integration, meta-linter bundling, CI/CD pipelines, and programmatic library usage.

Editor Integrations

Sources: README.md162-189

golangci-lint Integration

golangci-lint bundles revive as one of its linters, allowing centralized configuration:

Configuration example:

Sources: README.md205-241 .golangci.yml

CI/CD Pipeline Integration

Revive integrates into CI/CD through three primary patterns:

Pattern	Implementation	Output Format	Use Case
Dedicated Action	mgechev/revive-action	GitHub annotations	GitHub-specific workflows
Docker Container	ghcr.io/mgechev/revive:latest	Configurable formatter	Generic CI systems
golangci-lint Action	Includes revive by default	SARIF, checkstyle	Multi-linter setup

Sources: README.md191-201 Dockerfile

Programmatic Library Usage

Revive exposes the revivelib package for embedding linting functionality into custom applications:

Example usage:

Sources: README.md689-760 revivelib/core.go

Output Format Selection for Integrations

Different integrations require different output formats:

Integration	Recommended Format	Rationale
Human CLI	friendly, stylish	Rich formatting with colors and tables
VSCode	json	Structured data for diagnostic parsing
Jenkins/GitLab	checkstyle	Standard XML format for CI plugins
GitHub Actions	sarif	Native GitHub code scanning format
Log aggregation	ndjson	Streamable newline-delimited JSON
golangci-lint	Internal format	Handled automatically

Sources: README.md252-260 README.md626-674