Buf(1)

NAME
buf-format - Format Protobuf files

SYNOPSIS
buf format [flags]

DESCRIPTION
By default, the source is the current directory and the formatted content is written to stdout.

Examples:

Write the current directory's formatted content to stdout:
    $ buf format

Most people will want to rewrite the files defined in the current directory in-place with -w:
    $ buf format -w

Display a diff between the original and formatted content with -d Write a diff instead of the formatted file:
    $ buf format simple/simple.proto -d
    $ diff -u simple/simple.proto.orig simple/simple.proto
    --- simple/simple.proto.orig	2022-03-24 09:44:10.000000000 -0700
    +++ simple/simple.proto	2022-03-24 09:44:10.000000000 -0700
    @@ -2,8 +2,7 @@
    package simple;
    -
    message Object {
    -    string key = 1;
    -   bytes value = 2;
    +  string key = 1;
    +  bytes value = 2;
    }

Use the --exit-code flag to exit with a non-zero exit code if there is a diff:
    $ buf format --exit-code
    $ buf format -w --exit-code
    $ buf format -d --exit-code

Format a file, directory, or module reference by specifying a source e.g. Write the formatted file to stdout:
    $ buf format simple/simple.proto
    syntax = "proto3";
    package simple;
    message Object {
      string key = 1;
      bytes value = 2;
    }

Write the formatted directory to stdout:
    $ buf format simple
    ...

Write the formatted module reference to stdout:
    $ buf format buf.build/acme/petapis
    ...

Write the result to a specified output file or directory with -o e.g.

Write the formatted file to another file:
    $ buf format simple/simple.proto -o simple/simple.formatted.proto

Write the formatted directory to another directory, creating it if it doesn't exist:
    $ buf format proto -o formatted

This also works with module references:
    $ buf format buf.build/acme/weather -o formatted

Rewrite the file(s) in-place with -w. e.g.

Rewrite a single file in-place:
    $ buf format simple.proto -w

Rewrite an entire directory in-place:
    $ buf format proto -w

Write a diff and rewrite the file(s) in-place:
    $ buf format simple -d -w
    $ diff -u simple/simple.proto.orig simple/simple.proto
    ...

The -w and -o flags cannot be used together in a single invocation.

OPTIONS
--config=""
    The buf.yaml file or data to use for configuration

-d, --diff[=false]
    Display diffs instead of rewriting files

--disable-symlinks[=false]
    Do not follow symlinks when reading sources or configuration from the local filesystem By default, symlinks are followed in this CLI, but never followed on the Buf Schema Registry

--error-format="text"
    The format for build errors printed to stderr. Must be one of [text,json,msvs,junit,github-actions,gitlab-code-quality]

--exclude-path=[]
    Exclude specific files or directories, e.g. "proto/a/a.proto", "proto/a" If specified multiple times, the union is taken

--exit-code[=false]
    Exit with a non-zero exit code if files were not already formatted

-h, --help[=false]
    help for format

-o, --output="-"
    The output location for the formatted files. Must be one of format [dir,protofile]. If omitted, the result is written to stdout

--path=[]
    Limit to specific files or directories, e.g. "proto/a/a.proto", "proto/a" If specified multiple times, the union is taken

-w, --write[=false]
    Rewrite files in-place

OPTIONS INHERITED FROM PARENT COMMANDS
--debug[=false]
    Turn on debug logging

--log-format="color"
    The log format [text,color,json]

--timeout=0s
    The duration until timing out, setting it to 0 means no timeout

SEE ALSO
buf(1)

HISTORY
2026-04-29 Auto generated by spf13/cobra