POLYBAR(5) راهنمای کاربر Polybar POLYBAR(5)
" Man page generated from reStructuredText

polybar - فایل پیکربندی برای polybar(1)

فایل پیکربندی polybar رفتار و ظاهر polybar را تعیین می‌کند. این فایل از نوعی از قالب فایل INI بهره می‌برد. ساختار دقیق آن در زیر شرح داده شده است، اما ابتدا یک قطعه کد کوچک برای آشنایی با ساختار:

[section_name]
; یک توضیح
# توضیح دیگر
background = #ff992a
width = 90%
monitor = HDMI-0
screenchange-reload = false
; در صورت تمایل به حفظ فاصله‌های اطراف، از گیومه دوتایی استفاده کنید.
text = " Some text "

هنگام اجرا، polybar فایل پیکربندی را به ترتیب زیر در یکی از چندین مکان جستجو خواهد کرد:

  • اگر آرگومان خط فرمان -c یا --config مشخص شده باشد، از مسیر ارائه‌شده استفاده می‌شود.
  • /polybar/config
  • /polybar/config.ini
  • /home/ahoura/.config/polybar/config
  • /home/ahoura/.config/polybar/config.ini
  • /polybar/config.ini
  • /etc/xdg/polybar/config.ini (تنها در صورتی که XDG_CONFIG_DIRS تنظیم نشده باشد)
  • /etc/polybar/config.ini

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

  • خالی (Empty)
  • توضیح (Comment)
  • سرآیند بخش (Section Header)
  • کلید (Key)

فاصله‌ها در ابتدا و انتهای هر خط نادیده گرفته می‌شوند.

نکته:

در این متن "فاصله‌ها" شامل نویسه فاصله معمولی و همچنین نویسه تب و هر نویسه دیگری است که isspace(3) برای آن مقدار true بازمی‌گرداند (مانند \r).

هر خطی که در یکی از این چهار نوع نگنجد، یک خطای نحوی است.

نکته:

توصیه می‌شود نام‌های سرآیند بخش و نام‌های کلید تنها از نویسه‌های حرفی-عددی و همچنین خط تیره (-)، زیرخط (_) و اسلش (/) استفاده کنند.

در عمل تمام نویسه‌ها مجاز هستند به جز فاصله‌ها و هر یک از این نویسه‌ها: "'=;#[](){}:.$\%

بخش‌ها برای گروه‌بندی گزینه‌های پیکربندی در کنار هم استفاده می‌شوند. برای نمونه هر ماژول در بخش مربوط به خود تعریف می‌شود.

یک بخش با قرار دادن نام بخش در کروشه‌ها ([ و ]) تعریف می‌شود. برای نمونه:

[module/wm]

این کار بخشی با نام module/wm تعریف می‌کند و تمام کلیدهایی که پس از این خط تعریف شوند تا زمان اعلان بخش جدید، متعلق به این بخش خواهند بود.

هشدار:

نخستین خط غیرخالی و غیرتوضیحی در فایل اصلی کانفیگ باید یک سرآیند بخش باشد. این خط نمی‌تواند یک کلید باشد، چرا که آن کلید به هیچ بخشی تعلق نخواهد داشت.

نکته:

نام‌های بخش زیر رزرو شده‌اند و نمی‌توانند درون پیکربندی استفاده شوند: self، root و BAR&.

کلیدها با تخصیص یک مقدار به یک نام تعریف می‌شوند، مانند زیر:

name = value

این دستور مقدار value را به کلید name در هر بخشی که این خط در آن قرار دارد تخصیص می‌دهد. نام‌های کلید در هر بخش باید یکتا باشند. اگر مقدار توسط گیومه دوتایی (") محصور شده باشد، گیومه‌ها نادیده گرفته می‌شوند. بنابراین مورد زیر همچنان value را به name اختصاص می‌دهد:

name = "value"

فاصله‌های اطراف علامت مساوی نادیده گرفته می‌شوند؛ موارد زیر همگی معادل هستند:

name=value
name = value
name =      value

از آنجا که فاصله‌ها در ابتدا و انتهای خط نیز نادیده گرفته می‌شوند، اگر می‌خواهید مقدار شما با یک فاصله آغاز یا پایان یابد، باید مقدار درون گیومه دوتایی قرار گیرد:

name = " value "

در اینجا مقدار کلید name دارای فاصله خالی در ابتدا و انتها است.

برای رفتار با نویسه‌های دارای معنای خاص به صورت نویسه‌های معمولی، باید پیش از آن‌ها نویسه اسکیپ بک‌اسلش (\) را قرار دهید:

name = "value\\value\\value"

مقدار این کلید name به value\value\value& منجر می‌شود.

نکته:

تنها نویسه‌ای که در حال حاضر دارای معنای خاص است، نویسه بک‌اسلش (\) می‌باشد که به عنوان نویسه اسکیپ عمل می‌کند. موارد بیشتری در آینده اضافه خواهند شد.

خطوط خالی و خطوط توضیحات هنگام خواندن فایل پیکربندی نادیده گرفته می‌شوند و بر رفتار polybar تأثیری ندارند. خطوط توضیحات با یکی از نویسه‌های ; یا # آغاز می‌شوند.

نکته:

توضیحات درون‌خطی (Inline comments) پشتیبانی نمی‌شوند. برای نمونه خط زیر با یک توضیح پایان نمی‌یابد؛ مقدار name در واقع روی value ; comment تنظیم می‌شود: 
name = value ; comment

پروژه Polybar توسط Michael Carlberg ایجاد شد و در حال حاضر توسط Patrick Ziegler نگهداری می‌شود.
فهرست مشارکت‌کنندگان در گیت‌هاب در دسترس است.

polybar(1), polybar-msg(1)

2016-2026, Michael Carlberg & contributors

September 1, 2026 3.7.2