Protobuf files

A file with the .proto extension is formatted as a proto3 file, with the protobuf section of commands.format: every declaration gets a canonical layout, nested declarations are indented, and imports, options, declarations, fields, enum values and methods are sorted as sort says. No comment is lost.

Layout

The formatter:

• writes every declaration in a canonical layout: one statement per line, normalized spacing, blank lines between top-level declarations and around nested messages, enums and extends
• indents nested declarations by the configured number of spaces
• optionally sorts imports, options and declarations

No comment is lost. Comments are written as // line comments and stay with their declarations when declarations are sorted. Comments that protoc ignores, such as those inside a declaration (int32 /* type */ id = 1;), are written as /* */ comments directly before the end of their declaration (int32 id = 1 /* type */;).

Files that are syntactically correct but break proto3 rules, for example with duplicate field numbers, are formatted. Files with syntax errors are reported with the position of each error and left untouched. Editions and proto2 files are not supported.

Settings

Key	Values	Recommended	Description
indent	1 to 8	2	Number of spaces for one level of nesting.
sort.imports	original, sorted	sorted	Sorts imports by path.
sort.options	original, sorted	sorted	Sorts option statements and the options in brackets ([deprecated = true, json_name = "x"]) by name.
sort.declarations	original, grouped, sorted	original	grouped puts top-level declarations in this order: package, imports, options, services, messages, enums, extends. sorted also sorts services, messages, enums and extends by name within their groups.
sort.fields	original, number, name	original	Sorts the fields of messages, oneofs and extends. A oneof is placed by its lowest field number (or its name), and its fields are sorted too.
sort.enum_values	original, number, name	original	Sorts enum values. A first value of zero stays first, as proto3 requires.
sort.nested_types	original, sorted	original	Sorts the messages, enums and extends nested in a message by name.

Without a configuration file, the recommended settings are used. With extends: [original], nothing is sorted.

Each kind of declaration is sorted among the positions that declarations of that kind take in its body, so sorting fields, for example, does not move options, reserved statements or nested messages. Only the grouped and sorted values of sort.declarations move top-level declarations between kinds.

Changing the order of fields, enum values or methods does not change the wire format, but it changes the order of declarations in generated code and descriptors. For this reason, the recommended configuration sorts only imports and options.

Example - Recommended settings with 4-space indentation, and fields sorted by number

commands:
  format:
    extends:
      - recommended
    protobuf:
      indent: 4
      sort:
        declarations: grouped
        fields: number
        enum_values: number

apigenie format api/store/v1/*.proto --config api-style-guide.yaml