Buf(1)                                                                  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-02-03 Auto generated by spf13/cobra

Auto generated by spf13/cobra     2026-02-03                            Buf(1)