shfmt(1) General Commands Manual shfmt(1)

shfmt - قالب‌بندی برنامه‌های شل

shfmt [flags] [path...]

دستور shfmt برنامه‌های شل را قالب‌بندی می‌کند. اگر تنها آرگومان یک خط تیره (-) باشد یا هیچ آرگومانی داده نشود، ورودی استاندارد استفاده خواهد شد. اگر مسیر داده‌شده یک دایرکتوری باشد، تمام اسکریپت‌های شلِ پیدا شده در آن دایرکتوری استفاده خواهند شد.

اگر هرگونه فایل EditorConfig یافت شود، از آن‌ها برای اعمال گزینه‌های قالب‌بندی استفاده خواهد شد. اگر هرگونه پرچم تجزیه‌کننده یا چاپگر به ابزار داده شود، هیچ گزینه قالب‌بندی EditorConfig اعمال نخواهد شد. یک مقدار پیش‌فرض مانند -i=0 می‌تواند برای این منظور استفاده شود.

قالب‌بندی پیش‌فرض شل در shfmt به گونه‌ای انتخاب شده است که سازگار، معمول و قابل پیش‌بینی باشد. برخی از جنبه‌های قالب‌بندی را می‌توان از طریق پرچم‌های چاپگر پیکربندی کرد.

--version

نمایش نسخه و خروج.

-l[=0], --list[=0]

خروج با وضعیت خطا به همراه فهرستی از فایل‌هایی که قالب‌بندی آن‌ها با shfmt تفاوت دارد؛ مسیرها با خط جدید، یا در صورت تعیین -l=0 با یک نویسه نال (null)، از یکدیگر جدا می‌شوند.

-w, --write

نوشتن نتیجه در فایل به جای stdout.

-d, --diff

خروج با وضعیت خطا به همراه نمایش یک diff در صورتی که قالب‌بندی تفاوت داشته باشد.

اگر خروجی یک ترمینال باشد، diff رنگی خواهد بود. برای عدم استفاده همیشگی از رنگ، متغیر غیرخالی NO_COLOR یا TERM=dumb را تنظیم کنید. برای استفاده همیشگی از رنگ، متغیر غیرخالی FORCE_COLOR را تنظیم کنید.

--apply-ignore

همیشه قواعد نادیده‌گیری (ignore) فایل EditorConfig اعمال شوند.

هنگام قالب‌بندی مستقیم فایل‌ها، بدون این پرچم از قواعد نادیده‌گیری صرف‌نظر می‌شود. این پرچم برای هر ابزار یا ویرایشگری که stdin یا یک تک‌فایل را قالب‌بندی می‌کند، مفید خواهد بود. هنگام چاپ نتایج در stdout، یک فایل نادیده‌گرفته‌شده منجر به هیچ خروجی‌ای نمی‌شود.

--filename str

ارائه یک نام برای فایل ورودی استاندارد.

استفاده از این پرچم برای کارکرد پشتیبانی EditorConfig با stdin ضروری است، زیرا فایل‌های EditorConfig نسبت به مکان یک اسکریپت پیدا می‌شوند.

-ln, --language-dialect <str>

گویش زبان (bash/posix/mksh/bats/zsh، پیش‌فرض auto).

هنگامی که روی auto تنظیم شود، تا زمانی که نام فایل ورودی دارای یک پسوند شل مانند foo.mksh باشد، زبان از روی آن تشخیص داده می‌شود. در غیر این صورت، اگر ورودی با یک shebang شل مانند #!/bin/sh آغاز شود، به جای آن استفاده می‌شود. اگر هیچ‌کدام نتیجه‌ای نداشته باشند، از bash به عنوان جایگزین پشتیبان (fallback) استفاده می‌شود.

پسوند نام فایل .sh یک حالت ویژه است: نشان‌دهنده posix است، اما ممکن است توسط یک shebang معتبر شل بازنویسی شود.

-p, --posix

کوتاه‌نوشتی برای -ln=posix.

-s, --simplify

ساده‌سازی کد.

-i, --indent <uint>

دندانه‌گذاری: 0 برای تب‌ها (پیش‌فرض)، و >0 برای تعداد فاصله‌ها.

-bn, --binary-next-line

عملگرهای دودویی مانند && و | می‌توانند یک خط را آغاز کنند.

-ci, --case-indent

بندهای case دندانه‌گذاری می‌شوند.

-sr, --space-redirects

به دنبال عملگرهای تغییر مسیر یک فاصله قرار می‌گیرد.

-kp, --keep-padding

حفظ فاصله‌گذاری‌های تراز ستونی.

این پرچم منسوخ شده است (DEPRECATED) و در نسخه اصلی بعدی حذف خواهد شد. برای اطلاعات بیشتر، ببینید: https://github.com/mvdan/sh/issues/658

-fn, --func-next-line

کروشه‌های بازکننده تابع در یک خط جداگانه قرار می‌گیرند.

-mn, --minify

کوچک‌سازی کد برای کاهش اندازه آن (شامل -s نیز می‌شود).

-f[=0], --find[=0]

یافتن بازگشتی تمام فایل‌های شل و چاپ مسیر آن‌ها؛ مسیرها با خط جدید، یا در صورت تعیین -f=0 با یک نویسه نال (null)، از یکدیگر جدا می‌شوند.

--to-json

چاپ درخت نحو در stdout به صورت JSON نوع‌دار.

--from-json

خواندن درخت نحو از stdin به صورت JSON نوع‌دار.

قالب‌بندی تمام اسکریپت‌های موجود در دایرکتوری جاری و چاپ مواردی که تغییر یافته‌اند:

shfmt -l -w .

برای یکپارچه‌سازی مداوم (CI)، می‌توان از حالتی استفاده کرد که تغییرات قالب‌بندی صرفاً به صورت diff نشان داده شوند:

shfmt -d .

پرچم‌های قالب‌بندی زیر شباهت زیادی به سبک شل گوگل (Google) تعریف‌شده در https://google.github.io/styleguide/shellguide.html دارند:

shfmt -i 2 -ci -bn

در ادامه یک نمونه فایل EditorConfig تعریف‌شده بر اساس https://editorconfig.org آمده است که نحوه تنظیم گزینه‌های پشتیبانی‌شده را نشان می‌دهد:

[*.sh]
# مانند -i=4
indent_style = space
indent_size = 4
# --language-dialect
shell_variant      = posix
simplify           = true
binary_next_line   = true
# --case-indent
switch_case_indent = true
space_redirects    = true
keep_padding       = true
# --func-next-line
function_next_line = true
minify             = true
# نادیده‌گرفتن کل دایرکتوری "third_party" هنگام فراخوانی shfmt روی دایرکتوری‌ها،
# مانند "shfmt -l -w .". هنگام قالب‌بندی مستقیم فایل‌ها،
# مانند "shfmt -w third_party/foo.sh" یا "shfmt --filename=third_party/foo.sh"،
# منطق نادیده‌گیری تنها در صورتی اعمال می‌شود که پرچم --apply-ignore داده شده باشد.
[third_party/**]
ignore = true

بخش‌های EditorConfig همچنین می‌توانند از `[[shell]]`، `[[bash]]`، یا `[[zsh]]` برای تطبیق با اسکریپت‌های شل استفاده کنند، که به‌ویژه زمانی مفید است که اسکریپت‌ها از shebang استفاده کرده اما پسوندی ندارند. توجه داشته باشید که این ویژگی خارج از مشخصات رسمی EditorConfig است و ممکن است در آینده تغییر کند.

دستور shfmt همچنین می‌تواند جایگزین bash -n برای بررسی خطاهای نحوی اسکریپت‌های شل شود. این ابزار جامع‌تر است، زیرا تمام نحو را به صورت ایستا تجزیه کرده و به UTF-8 معتبر نیاز دارد:

$ echo '${foo:1 2}' | bash -n
$ echo '${foo:1 2}' | shfmt >/dev/null
1:9: not a valid arithmetic operator: 2
$ echo 'foo=(1 2)' | bash --posix -n
$ echo 'foo=(1 2)' | shfmt -p >/dev/null
1:5: arrays are a bash feature

نگهداری توسط Daniel Martí <mvdan@mvdan.cc>، با همراهی سایر مشارکت‌کنندگان متن‌باز انجام می‌شود. برای اطلاعات بیشتر و توسعه، ببینید: https://github.com/mvdan/sh.

2026-04-07