.\"
.\" Copyright (c) 2012 Eric Radman <ericshane@eradman.com>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.Dd March 2, 2026
.Dt ENTR 1
.Os
.Sh "نام (NAME)"
.Nm entr
.Nd اجرای دستورهای دلخواه به هنگام تغییر فایل‌ها
.Sh "خلاصه دستور (SYNOPSIS)"
.Nm
.Op Fl acdnprsxz
.Ar utility
.Op Ar argument /_ ...
.Sh "توضیحات (DESCRIPTION)"
فهرستی از فایل‌ها از طریق ورودی استاندارد فراهم می‌شود، و در صورت تغییر هر یک از آن‌ها،
.Ar utility
با آرگومان‌های ارائه‌شده اجرا می‌گردد.
.Nm
پیش از پاسخ به رویدادهای بعدی سامانه فایل، منتظر پایان فرآیند فرزند می‌ماند.
همچنین پیش از ورود به حلقهٔ پایش، یک TTY باز می‌شود تا از ابزارهای تعاملی پشتیبانی به عمل آید.
.Pp
آرگومان‌ها به شرح زیر هستند:
.Bl -tag -width Ds
.It Fl a
پاسخ به تمامی رویدادهایی که هنگام اجرای
.Ar utility
رخ می‌دهند.
بدون این گزینه،
.Nm
رویدادها را یکپارچه می‌کند تا از افتادن در حلقه جلوگیری کند.
این گزینه در ترکیب با پرچم
.Fl r
بی‌اثر است.
.It Fl c
پاک کردن صفحه پیش از فراخوانی
.Ar utility
مشخص‌شده در خط فرمان.
مشخص کردن دو بارهٔ آن موجب پاک شدن بافر پیمایش (scrollback) می‌شود.
.It Fl d
ردیابی دایرکتوری والد فایل‌های عادیِ ارائه‌شده به عنوان ورودی.
اگر دو بار مشخص شود، تمام ورودی‌های جدید به یک دایرکتوری شناسایی می‌شوند، در غیر این صورت فایل‌هایی که نامشان با
.Ql \&.
آغاز می‌شود نادیده گرفته خواهند شد.
.It Fl n
اجرا در حالت غیرتعاملی.
در این حالت
.Nm entr
تلاشی برای خواندن از TTY یا تغییر ویژگی‌های آن نمی‌کند.
.It Fl p
به تعویق انداختن نخستین اجرای
.Ar utility
تا زمانی که فایلی تغییر یابد.
.It Fl r
بارگذاری مجدد (reload) یک فرآیند فرزند ماندگار.
همانند حالت استاندارد عملکرد، یک
.Ar utility
که پایان می‌یابد تا زمان پردازش یک رویداد سامانه فایل یا صفحه‌کلید، دوباره اجرا نخواهد شد.
یک گروه فرآیند (process group) ایجاد می‌شود تا از پوشانده شدن سیگنال‌ها توسط اسکریپت‌های شل جلوگیری شود.
.Nm
منتظر خروج
.Ar utility
می‌ماند تا از بسته شدن منابعی مانند سوکت‌ها اطمینان حاصل شود.
کنترل TTY به فرآیند فرزند منتقل نمی‌شود.
.It Fl s
ارزیابی نخستین آرگومان با استفاده از مفسر مشخص‌شده توسط متغیر محیطی
.Ev SHELL .
.It Fl x
قالب‌بندی پیام‌های وضعیت خروج سفارشی با استفاده از یک فرآیند ماندگار
.Xr awk 1 .
مسیر اسکریپت وضعیت توسط متغیر محیطی
.Ev ENTR_STATUS_SCRIPT
تعیین می‌شود.
اگر اسکریپت وضعیت وجود نداشته باشد،
.Nm
یک نمونه ایجاد خواهد کرد.
دستورهای شل و تغییر مسیر فایل به طور پیش‌فرض مجاز نیستند، اما می‌توان با دو بار مشخص کردن
.Fl x
آن‌ها را فعال کرد.
.It Fl z
خروج پس از تکمیل کار
.Ar utility .
هنگام ترکیب با
.Fl r ،
ابزار
.Ar utility
تنها در پاسخ به دستورها یا رویدادهای سامانه فایل مجدداً راه‌اندازی خواهد شد.
.El
.Pp
نخستین آرگومان با نام
.Ar /_
با مسیر مطلق نخستین فایلی که رویداد را برانگیخته است جایگزین می‌شود.
نخستین فایل تحت پایش به عنوان پیش‌فرض استفاده می‌شود.
اگر گزینهٔ
.Fl s
استفاده شود، نام نخستین فایلی که رویداد را برانگیخته است را می‌توان از
.Va $0
خواند.
.Sh "دستورها (COMMANDS)"
.Nm
به ورودی صفحه‌کلید گوش فرا می‌دهد و به دستورهای زیر پاسخ می‌دهد:
.Bl -tag -width <space>
.It Aq Cm space
اجرای فوری ابزار.
اگر گزینهٔ
.Fl Cm r
تنظیم شده باشد، این کار فرآیند فرزند را متوقف کرده و مجدداً راه‌اندازی می‌کند، گویی یک رویداد تغییر فایل رخ داده است.
.It Cm q
خروج؛ معادل فشردن
.Aq Cm control-C .
.El
.Sh "محیط (ENVIRONMENT)"
.Bl -tag -width "ENTR_ENVIRON"
.It Ev ENTR_STATUS_SCRIPT
مسیر اسکریپت وضعیت خروج که توسط گزینهٔ
.Fl x
فعال می‌شود.
به طور پیش‌فرض
.Pa $HOME/.entr/status.awk
ارزیابی می‌شود.
.It Ev ENTR_RESTART_SIGNAL
سیگنال مورد استفاده برای پایان دادن به
.Ar utility .
نام‌های سیگنال پشتیبانی‌شده عبارتند از
.Dv HUP ،
.Dv INT ،
.Dv QUIT ،
.Dv TERM ،
.Dv USR1
و
.Dv USR2 .
پیش‌فرض
.Dv SIGTERM
است.
.It Ev EV_TRACE
چاپ پیام‌های رویدادهای سامانه فایل.
.It Ev PAGER
به طور پیش‌فرض روی
.Pa /bin/cat
تنظیم شده تا در صورتی که خروجی در صفحه جا نشود، از منتظر ماندن ابزارهای تعاملی برای دریافت ورودی صفحه‌کلید جلوگیری کند.
.It Ev SHELL
مشخص کردن شل مورد استفاده همراه با پرچم
.Fl s .
پیش‌فرض
.Pa /bin/sh
است.
.El
.Sh "وضعیت خروج (EXIT STATUS)"
اگر پرچم
.Fl z
تنظیم شده باشد و
.Ar utility
با موفقیت اجرا شود، وضعیت فرآیند فرزند بازگردانده می‌شود.
اگر فرآیند فرزند توسط یک سیگنال متوقف شده باشد، وضعیت خروج برابر با شماره سیگنال به علاوهٔ ۱۲۸ خواهد بود.
.Pp
.Nm
به طور معمول یکی از مقادیر زیر را بازمی‌گرداند:
.Pp
.Bl -tag -width Ds -offset indent -compact
.It 0
خاتمهٔ عادی پس از دریافت
.Dv SIGINT
.It 1
هیچ فایل عادی در ورودی ارائه نشد یا خطایی رخ داد
.It 2
فایل‌هایی به یک دایرکتوری اضافه یا از آن حذف شدند
.El
.Sh "مثال‌ها (EXAMPLES)"
بازسازی یک پروژه در صورت تغییر فایل‌های مبدأ، با محدود کردن خروجی به ۲۰ خط نخست:
.Pp
.Dl $ find src/ | entr -s 'make | head -n 20'
.Pp
اجرا و بارگذاری مجدد خودکار یک سرور node.js:
.Pp
.Dl $ ls *.js | entr -r node app.js
.Pp
پاک کردن صفحه و اجرای یک پرس‌وجو پس از به‌روزرسانی اسکریپت SQL:
.Pp
.Dl $ echo my.sql | entr -cp psql -f /_
.Pp
بازسازی پروژه در صورت ویرایش یک فایل مبدأ یا اضافه شدن فایلی به دایرکتوری src/:
.Pp
.Dl $ while sleep 0.1; do ls -d src src/*.rb | entr make; done
.Pp
بارگذاری مجدد خودکار یک وب‌سرور، یا خاتمه یافتن برنامه در صورت خروج سرور:
.Pp
.Dl $ ls * | entr -rz ./httpd