نام (NAME)

buf-format - قالب‌بندی و مرتب‌سازی فایل‌های پروتوباف با buf

خلاصه دستور (SYNOPSIS)

buf format [flags]

توضیحات (DESCRIPTION)

به‌طور پیش‌فرض، منبع دایرکتوری جاری است و محتوای قالب‌بندی‌شده در خروجی استاندارد (stdout) نوشته می‌شود.

مثال‌ها:

نوشتن محتوای قالب‌بندی‌شده دایرکتوری جاری در خروجی استاندارد (stdout):

$ buf format

بیشتر افراد ترجیح می‌دهند فایل‌های تعریف‌شده در دایرکتوری جاری را مستقیماً در جای خود با گزینه -w بازنویسی کنند:

$ buf format -w

نمایش یک diff بین محتوای اصلی و قالب‌بندی‌شده با گزینه -d: نوشتن یک diff به جای فایل قالب‌بندی‌شده:

$ 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;
}

استفاده از فلگ --exit-code برای خروج با یک کد خروج غیرصفر در صورت وجود diff:

$ buf format --exit-code
$ buf format -w --exit-code
$ buf format -d --exit-code

قالب‌بندی یک فایل، دایرکتوری یا ارجاع ماژول با تعیین یک منبع؛ برای مثال نوشتن فایل قالب‌بندی‌شده در خروجی استاندارد (stdout):

$ buf format simple/simple.proto
syntax = "proto3";
package simple;
message Object {
  string key = 1;
  bytes value = 2;
}

نوشتن دایرکتوری قالب‌بندی‌شده در خروجی استاندارد (stdout):

$ buf format simple
...

نوشتن ارجاع ماژول قالب‌بندی‌شده در خروجی استاندارد (stdout):

$ buf format buf.build/acme/petapis
...

نوشتن نتیجه در یک فایل یا دایرکتوری خروجی مشخص با گزینه -o برای مثال:

نوشتن فایل قالب‌بندی‌شده در فایلی دیگر:

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

نوشتن دایرکتوری قالب‌بندی‌شده در دایرکتوری دیگر، و ایجاد آن در صورت عدم وجود:

$ buf format proto -o formatted

این قابلیت با ارجاعات ماژول نیز کار می‌کند:

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

بازنویسی فایل(ها) در جای خود با گزینه -w برای مثال:

بازنویسی یک فایل تکی در جای خود:

$ buf format simple.proto -w

بازنویسی یک دایرکتوری کامل در جای خود:

$ buf format proto -w

نوشتن diff و بازنویسی فایل(ها) در جای خود:

$ buf format simple -d -w
$ diff -u simple/simple.proto.orig simple/simple.proto
...

فلگ‌های -w و -o نمی‌توانند به‌طور هم‌زمان در یک فراخوانی استفاده شوند.

گزینه‌ها (OPTIONS)

--config="" فایل buf.yaml یا داده‌های مورد استفاده برای پیکربندی

-d, --diff[=false] نمایش تفاوت‌ها (diff) به جای بازنویسی فایل‌ها

--disable-symlinks[=false] عدم دنبال کردن پیوندهای نمادین هنگام خواندن منابع یا پیکربندی از سیستم فایل محلی به‌طور پیش‌فرض، پیوندهای نمادین در این رابط خط فرمان دنبال می‌شوند، اما هرگز در Buf Schema Registry دنبال نمی‌شوند

--error-format="text" قالب خطاهای ساخت چاپ‌شده در خروجی استاندارد خطا (stderr). باید یکی از موارد [text,json,msvs,junit,github-actions,gitlab-code-quality] باشد

--exclude-path=[] مستثنی کردن فایل‌ها یا دایرکتوری‌های خاص، مثلاً "proto/a/a.proto"، "proto/a" در صورت تعیین چندباره، اجتماع آن‌ها در نظر گرفته می‌شود

--exit-code[=false] خروج با یک کد خروج غیرصفر در صورتی که فایل‌ها قبلاً قالب‌بندی نشده باشند

-h, --help[=false] راهنما برای format

-o, --output="-" محل خروجی برای فایل‌های قالب‌بندی‌شده. باید یکی از قالب‌های [dir,protofile] باشد. در صورت حذف، نتیجه در خروجی استاندارد (stdout) نوشته می‌شود

--path=[] محدود کردن به فایل‌ها یا دایرکتوری‌های خاص، مثلاً "proto/a/a.proto"، "proto/a" در صورت تعیین چندباره، اجتماع آن‌ها در نظر گرفته می‌شود

-w, --write[=false] بازنویسی فایل‌ها در جای خود

گزینه‌های به ارث رسیده از دستورات والد (OPTIONS INHERITED FROM PARENT COMMANDS)

--debug[=false] فعال‌سازی ثبت وقایع خطایابی

--log-format="color" قالب ثبت وقایع [text,color,json]

--timeout=0s مدت زمان تا پایان مهلت زمانی؛ تعیین 0s به معنی عدم محدودیت زمانی است

همچنین ببینید (SEE ALSO)

buf(1)

تاریخچه (HISTORY)

2026-07-17 تولید خودکار توسط spf13/cobra