Buf(1)

✨ Buf(1) — buf-format ✨

Okay so bestie, this is the Buf(1) manual page for buf-format — the command that formats Protobuf files. It’s giving “glow-up for your .proto files,” and honestly? Obsessed. 💅

---

🌸 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. No cap.

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
...

🚨 Heads up: the -w and -o flags cannot be used together in a single invocation.

Format a single file read from stdin with --stdin-filepath, writing the result to stdout. The path is not read from disk, only used to report parse errors and diffs. This flag can be useful for editor integrations that format unsaved buffers:

$ cat simple/simple.proto | buf format --stdin-filepath simple/simple.proto

🚨 Also important: the --stdin-filepath flag cannot be used with an input, or with the -w, -o, --path, --exclude-path, or --config flags.

👑 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
• --stdin-filepath="" — The path to pretend the stdin input comes from. Reads a single .proto file from stdin and writes the formatted result to stdout. Cannot be used with an input, or with the --write, --output, --path, --exclude-path, or --config flags
• -w, --write[=false] — Rewrite files in-place

🌈 OPTIONS INHERITED FROM PARENT COMMANDS 🌈

• --debug[=false] — Turn on debug logging (env BUF_DEBUG)
• --log-format="color" — The log format text,color,json ⟨env BUF_LOG_FORMAT⟩
• --timeout=0s — The duration until timing out, setting it to 0 means no timeout (env BUF_TIMEOUT)

🫶 SEE ALSO 🫶

buf(1)

📜 HISTORY 📜

2026-10-22 Auto generated by spf13/cobra

---

💖 okay that’s the whole page, bestie: this Buf(1) manual is auto generated by spf13/cobra, dated 2026-10-22. Slay, bye! 🎀