Repository files navigation

protolint is the pluggable linting/fixing utility for Protocol Buffer files (proto2+proto3):

• Runs fast because this works without compiler.
• Easy to follow the official style guide. The rules and the style guide correspond to each other exactly.
  • Fixer automatically fixes all the possible official style guide violations.
• Allows to disable rules with a comment in a Protocol Buffer file.
  • It is useful for projects which must keep API compatibility while enforce the style guide as much as possible.
  • Some rules can be automatically disabled by inserting comments to the spotted violations.
• Loads plugins to contain your custom lint rules.
• Undergone testing for all rules.
• Many integration supports.
  • protoc plugin
  • Editor integration
  • GitHub Action
  • CI Integration

For example, vim-protolint works like the following.

protolint can be installed for Mac or Linux using Homebrew via theyoheimuta/protolint tap.

brew tap yoheimuta/protolintbrew install protolint

Sincehomebrew-core includesprotolint, you can also install it by justbrew install protolint. This is the default tap that is installed by default. It's easier, but not maintained by the same author. To keep it updated, I recommend you runbrew tap yoheimuta/protolint first.

You can also download a pre-built binary from this release page:

• https://github.com/yoheimuta/protolint/releases

In the downloads section of each release, you can find pre-built binaries in .tar.gz packages.

protolint ships a Docker imageyoheimuta/protolint that allows you to use protolint as part of your Docker workflow.

❯❯❯ docker run --volume "$(pwd):/workspace" --workdir /workspace yoheimuta/protolint lint _example/proto[_example/proto/invalidFileName.proto:1:1] File name should be lower_snake_case.proto.[_example/proto/issue_88/oneof_options.proto:11:5] Found an incorrect indentation style "    ". "  " is correct.[_example/proto/issue_88/oneof_options.proto:12:5] Found an incorrect indentation style "    ". "  " is correct.

The binary can be installed from source if Go is available.However, I recommend using one of the pre-built binaries instead because it doesn't include the version info.

go install github.com/yoheimuta/protolint/cmd/protolint@latest

You can useprotolint using your nodejs package manager likenpm oryarn.

$ npm install protolint --save-dev

This will add a reference to a development dependency to your localpackage.json.

During install, theinstall.mjs script will be called. It will download the matchingprotolint from github. Just like@electron/get, you can bypass the download using the following environment variables:

Within the remote path, the archives from thereleases page must bemirrored.

After that, you can usenpx protolint (with all supplied protolint arguments) within your dev-scripts.

{..."scripts": {"protoc":"....","preprotoc":"npx protolint"  },...}

You can add aprotolint node to yourpackage.json which may contain the content ofprotolint.yml below thelint node, i.e. the root element of the configuration will beprotolint.

If you want to get an output that matches the TSC compiler, use reportertsc.

You can useprotolint as a linter within your python projects, the wheelprotolint-bin onpypi contains the pre-compiled binaries for various platforms. Just add the desired version toyourpyproject.toml orrequirements.txt.

The wheels downloaded will contain the compiled go binaries forprotolint andprotoc-gen-protolint. Your platform mustbe compatible with the supported binary platforms.

You can add the linter configuration to thetools.protolint package inpyproject.toml.

protolint lint example.proto example2.proto# file mode, specify multiple specific filesprotolint lint.# directory mode, search for all .proto files recursivelyprotolint.# same as "protolint lint ."protolint lint -config_path=path/to/your_protolint.yaml.# use path/to/your_protolint.yamlprotolint lint -config_dir_path=path/to.# search path/to for .protolint.yamlprotolint lint -fix.# automatically fix some of the problems reported by some rulesprotolint lint -fix -auto_disable=next.# this is preferable when you want to fix problems while maintaining the compatibility. Automatically fix some problems and insert disable comments to the other problems. The available values are next and this.protolint lint -auto_disable=next.# automatically insert disable comments to the other problems.protolint lint -v.# with verbose output to investigate the parsing errorprotolint lint -no-error-on-unmatched-pattern.# exits with success code even if no file is found (file & directory mode)protolint lint -reporter junit.# output results in JUnit XML formatprotolint lint -output_file=path/to/out.txt# output results to path/to/out.txtprotolint lint -plugin ./my_custom_rule1 -plugin ./my_custom_rule2.# run custom lint rules.protolint list# list all current lint rules being usedprotolint version# print protolint version

protolint does not require configuration by default, for the majority of projects it should work out of the box.

protolint is available as apre-commit hook. Add this to your.pre-commit-config.yaml in your repository to run protolint with Go:

repos:  -repo:https://github.com/yoheimuta/protolintrev:<version># Select a release here like v0.44.0hooks:      -id:protolint

or alternatively use this to run protolint with Docker:

repos:  -repo:https://github.com/yoheimuta/protolintrev:<version># Select a release here like v0.44.0hooks:      -id:protolint-docker

Visual Studio Code

• vscode-protolint

JetBrains IntelliJ IDEA, GoLand, WebStorm, PHPStorm, PyCharm...

• intellij-protolint

Vim(ALE engine)

• ale'sbuilt-in support

Vim(Syntastic)

• vim-protolint

AGitHub Action to run protolint in your workflows

• github/super-linter
• plexsystems/protolint-action
• yoheimuta/action-protolint - Integrated withreviewdog

Jenkins Plugins

• warnings-ng and any that useviolatons-lib

It is possible to format your linting according to the formatting of the CI/CD environment. The environment must be set using the output format. Currently, the following output is realized:

You can also use the genericci formatter, which will create a generic problem matcher.

With theci-env value, you can specify the template from the following environment variables:

The resulting line-feed must not be added, as it will be added automatically.

The following fields are available:

Severity: The severity as string (either note, warning or error)

File: Path to the file containing the error

Line: Line within thefile containing the error (starting position)

Column: Column within thefile containing the error (starting position)

Rule: The name of the rule that is faulting

Message: The error message that descibes the error

You can create a specific output matching your CI/CD environment and also create an output file, e.g. for your static code analysis tools like github CodeQL or SonarQube.

This can be done by adding the--add-reporter flag.Please note, that the value must be formatted<reporter-name>:<output-file-path> (omitting< and>).

$ protolint --reporter ci-gh --add-reporter sarif:/path/to/my/output.sarif.json proto/*.proto

protolint also maintains a binaryprotoc-gen-protolint that performs the lint functionality as a protoc plugin.Seecmd/protoc-gen-protolint/README.md in detail.

This is useful in situations where you already have a protoc plugin workflow.

You can also use protolint from Go code.SeeGo Documentation andlib/lint_test.go in detail.

args:= []string{"-config_path","path/to/your_protolint.yaml","."}varstdout bytes.Buffervarstderr bytes.Buffererr:=lib.Lint(test.inputArgs,&stdout,&stderr)

Seeinternal/addon/rules in detail.

The rule set follows:

• Official Style Guide. This is enabled by default. Basically, these rules can fix the violations by appending-fix option.
• Unofficial Style Guide. This is disabled by default. You can enable each rule with.protolint.yaml.

The-fix option on the command line can automatically fix all the problems reported by fixable rules.See Fixable columns below.

The-auto_disable option on the command line can automatically disable all the problems reported by auto-disable rules.This feature is helpful when fixing the existing violations breaks the compatibility.See AutoDisable columns below.

• *1: These rules are not supposed to support AutoDisable because the fixes don't break their compatibilities. You should run the protolint with-fix.

I recommend that you addall_default: true in.protolint.yaml, because all linters above are automatically enabled so that you can always enjoy maximum benefits whenever protolint is updated.

Here are some examples that show good style enabled by default.- is a bad style,+ is a good style:

ENUM_FIELD_NAMES_PREFIX

enum FooBar {-  UNSPECIFIED = 0;+  FOO_BAR_UNSPECIFIED = 0;}

ENUM_FIELD_NAMES_UPPER_SNAKE_CASE

enum Foo {-  firstValue = 0;+  FIRST_VALUE = 0;-  second_value = 1;+  SECOND_VALUE = 1;}

ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH

enum Foo {-  FOO_FIRST = 0;+  FOO_UNSPECIFIED = 0;}

ENUM_NAMES_UPPER_CAMEL_CASE

- enum foobar {+ enum FooBar {  FIRST_VALUE = 0;  SECOND_VALUE = 1;}

FIELD_NAMES_LOWER_SNAKE_CASE

message SongServerRequest {-  required string SongName = 1;+  required string song_name = 1;}

IMPORTS_SORTED

- import public "new.proto";+ import "myproject/other_protos.proto";- import "myproject/other_protos.proto";+ import public "new.proto";import "google/protobuf/empty.proto";import "google/protobuf/timestamp.proto";

MESSAGE_NAMES_UPPER_CAMEL_CASE

- message song_server_request {+ message SongServerRequest {  required string SongName = 1;  required string song_name = 1;}

ORDER

- option java_package = "com.example.foo";- syntax = "proto3";- package examplePb;- message song_server_request { }- import "other.proto";+ syntax = "proto3";+ package examplePb;+ import "other.proto";+ option java_package = "com.example.foo";+ message song_server_request { }

PACKAGE_NAME_LOWER_CASE

- package myPackage+ package my.package

RPC_NAMES_UPPER_CAMEL_CASE

service FooService {-  rpc get_something(FooRequest) returns (FooResponse);+  rpc GetSomething(FooRequest) returns (FooResponse);}

RPC_NAMES_UPPER_CAMEL_CASE

- service foo_service {+ service FooService {  rpc get_something(FooRequest) returns (FooResponse);  rpc GetSomething(FooRequest) returns (FooResponse);}

REPEATED_FIELD_NAMES_PLURALIZED

-  repeated string song_name = 1;+  repeated string song_names = 1;

INDENT

 enum enumAllowingAlias {   UNKNOWN = 0;-        option allow_alias = true;+  option allow_alias = true;   STARTED = 1;-     RUNNING = 2 [(custom_option) = "hello world"];+  RUNNING = 2 [(custom_option) = "hello world"];- }+}

-   message TestMessage { string test_field = 1; }+ message TestMessage {+  string test_field = 1;+}

QUOTE_CONSISTENT

 option java_package = "com.example.foo";- option go_package = 'example';+ option go_package = "example";

protolint is the pluggable linter so that you can freely create custom lint rules.

A complete sample project (aka plugin) is included in this repo under the_example/plugin directory.

protolint comes with several built-in reporters(aka. formatters) to control the appearance of the linting results.

You can specify a reporter using the -reporter flag on the command line. For example,-reporter junit uses the junit reporter.

The built-in reporter options are:

• plain (default)
• junit
• json
• sarif
• sonar (SonarQube generic issue format)
• unix
• tsc (compatible to TypeScript compiler)

Disable rules in a Protocol Buffer file

Rules can be disabled with a comment inside a Protocol Buffer file with the following format.The rules will be disabled until the end of the file or until the linter sees a matching enable comment:

// protolint:disable <ruleID1> [<ruleID2> <ruleID3>...]...// protolint:enable <ruleID1> [<ruleID2> <ruleID3>...]

It's also possible to modify a disable command by appending :next or :this for only applying the command to this(current) or the next line respectively.

For example:

enumFoo {// protolint:disable:next ENUM_FIELD_NAMES_UPPER_SNAKE_CASEfirstValue=0;// no errorsecond_value=1;// protolint:disable:this ENUM_FIELD_NAMES_UPPER_SNAKE_CASETHIRD_VALUE=2;// spits out an error}

Setting the command-line option-auto_disable tonext orthis inserts disable commands whenever spotting problems.

You can specify-fix option together. The rules supporting auto_disable suppress the violations instead of fixing them that cause a schema incompatibility.

Config file

protolint can operate using a config file named.protolint.yaml.

Refer to_example/config/.protolint.yaml for the config file specification.

protolint will automatically search a current working directory for the config file by defaultand successive parent directories all the way up to the root directory of the filesystem.And it can search the specified directory with-config_dir_path flag.It can also search the specified file with--config_path flag.

When linting files, protolint will exit with one of the following exit codes:

• 0: Linting was successful and there are no linting errors.
• 1: Linting was successful and there is at least one linting error.
• 2: Linting was unsuccessful due to all other errors, such as parsing, internal, and runtime errors.

There exists the similar protobuf linters as of 2018/12/20.

One is a plug-in for Google's Protocol Buffers compiler.

• When you just want to lint the files, it may be tedious to create the compilation environment.
• And it generally takes a lot of time to compile the files than to parse the files.

Other is a command line tool which also lints Protocol Buffer files.

• While it has a lot of features other than lint, it seems cumbersome for users who just want the linter.
• The lint rule slants towards to be opinionated.
• Further more, the rule set and the official style guide don't correspond to each other exactly. It requires to understand both rules and the guide in detail, and then to combine the rules accurately.

I wrote an article comparing various Protocol Buffer Linters, including protolint, on 2019/12/17.

• https://qiita.com/yoheimuta/items/da7678fcd046b93a2637
  • NOTE: This one is written in Japanese.

• go-protoparser

The MIT License (MIT)