.nh
.TH "Buf" "1" "2026-02-03" "Auto generated by spf13/cobra" ""

.SH NAME
buf-format - Format Protobuf files


.SH SYNOPSIS
\fBbuf format  [flags]\fP


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

.PP
Examples:

.PP
Write the current directory's formatted content to stdout:

.EX
$ buf format
.EE

.PP
Most people will want to rewrite the files defined in the current directory in-place with -w:

.EX
$ buf format -w
.EE

.PP
Display a diff between the original and formatted content with -d
Write a diff instead of the formatted file:

.EX
$ 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;
}
.EE

.PP
Use the --exit-code flag to exit with a non-zero exit code if there is a diff:

.EX
$ buf format --exit-code
$ buf format -w --exit-code
$ buf format -d --exit-code
.EE

.PP
Format a file, directory, or module reference by specifying a source e.g.
Write the formatted file to stdout:

.EX
$ buf format simple/simple.proto

syntax = "proto3";

package simple;

message Object {
  string key = 1;
  bytes value = 2;
}
.EE

.PP
Write the formatted directory to stdout:

.EX
$ buf format simple
\&...
.EE

.PP
Write the formatted module reference to stdout:

.EX
$ buf format buf.build/acme/petapis
\&...
.EE

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

.PP
Write the formatted file to another file:

.EX
$ buf format simple/simple.proto -o simple/simple.formatted.proto
.EE

.PP
Write the formatted directory to another directory, creating it if it doesn't exist:

.EX
$ buf format proto -o formatted
.EE

.PP
This also works with module references:

.EX
$ buf format buf.build/acme/weather -o formatted
.EE

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

.PP
Rewrite a single file in-place:

.EX
$ buf format simple.proto -w
.EE

.PP
Rewrite an entire directory in-place:

.EX
$ buf format proto -w
.EE

.PP
Write a diff and rewrite the file(s) in-place:

.EX
$ buf format simple -d -w

$ diff -u simple/simple.proto.orig simple/simple.proto
\&...
.EE

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


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

.PP
\fB-d\fP, \fB--diff\fP[=false]
	Display diffs instead of rewriting files

.PP
\fB--disable-symlinks\fP[=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

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

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

.PP
\fB--exit-code\fP[=false]
	Exit with a non-zero exit code if files were not already formatted

.PP
\fB-h\fP, \fB--help\fP[=false]
	help for format

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

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

.PP
\fB-w\fP, \fB--write\fP[=false]
	Rewrite files in-place


.SH OPTIONS INHERITED FROM PARENT COMMANDS
\fB--debug\fP[=false]
	Turn on debug logging

.PP
\fB--log-format\fP="color"
	The log format [text,color,json]

.PP
\fB--timeout\fP=0s
	The duration until timing out, setting it to 0 means no timeout


.SH SEE ALSO
\fBbuf(1)\fP


.SH HISTORY
2026-02-03 Auto generated by spf13/cobra