watchexec(1) General Commands Manual watchexec(1)

watchexec - اجرای دستورات هنگام تغییر فایل‌های تحت نظارت

watchexec [--bell] [-c|--clear] [--completions] [--color] [-d|--debounce] [--delay-run] [-e|--exts] [-E|--env] [--emit-events-to] [-f|--filter] [--socket] [--filter-file] [-j|--filter-prog] [--fs-events] [-i|--ignore] [-I|--interactive] [--exit-on-error] [--ignore-file] [--ignore-nothing] [--log-file] [--manual] [--map-signal] [-n ] [-N|--notify] [--no-default-ignore] [--no-discover-ignore] [--no-process-group] [--no-global-ignore] [--no-meta] [--no-project-ignore] [--no-vcs-ignore] [-o|--on-busy-update] [--only-emit-events] [--poll] [--print-events] [--project-origin] [-p|--postpone] [-q|--quiet] [-Q|--quote] [-r|--restart] [-s|--signal] [--shell] [--stdin-quit] [--stop-signal] [--stop-timeout] [--timeout] [--timings] [-v|--verbose]... [-w|--watch] [--workdir] [-W|--watch-non-recursive] [--wrap-process] [-F|--watch-file] [--no-follow-symlinks] [-h|--help] [-V|--version] [COMMAND]

اجرای دستورات هنگام تغییر فایل‌های تحت نظارت.

دایرکتوری جاری را برای تغییرات به صورت بازگشتی نظارت می‌کند و هنگام تشخیص تغییر در فایل‌سیستم (در میان سایر منابع رویداد)، دستور را اجرا می‌کند. به طور پیش‌فرض، watchexec از مکانیزم‌های کارآمد در سطح هسته (کرنل) برای نظارت بر تغییرات استفاده می‌کند.

هنگام راه‌اندازی، دستور مشخص‌شده یک بار اجرا می‌شود و watchexec نظارت بر تغییرات را آغاز می‌کند.

رویدادها به کمک مکانیزم‌های متنوعی بررسی و تثبیت (debounce) می‌شوند که می‌توانید با گزینه‌های بخش فیلتر کردن (FILTERING) آن‌ها را کنترل کنید. ترتیب اجرا به این صورت است: اولویت‌بندی داخلی (سیگنال‌ها بر همه چیز مقدم هستند و SIGINT/SIGTERM با فوریت بیشتری پردازش می‌شوند)، سپس نوع رویداد فایل (`---events`)، سپس فایل‌هایی که صراحتاً با `-w` نظارت می‌شوند، سپس موارد نادیده‌گیری (`--ignore` و موارد مشابه)، سپس فیلترها (شامل `--\xts`)، و در نهایت برنامه‌های فیلتر.

مثال‌ها:

بازسازی پروژه هنگام تغییر فایل‌های سورس:

$ watchexec make

نظارت بر تمام فایل‌های HTML، CSS و JavaScript برای تغییرات:

$ watchexec -e html,css,js make

اجرای آزمون‌ها هنگام تغییر فایل‌های سورس، همراه با پاک کردن صفحه در هر بار:

$ watchexec -c make test

راه‌اندازی و اجرای مجدد سرور node.js:

$ watchexec -r node app.js

نظارت بر دایرکتوری‌های lib و src برای تغییرات و بازسازی در هر بار:

$ watchexec -w lib -w src make

--ompletions <SHELL>
تولید اسکریپت تکمیل خودکار برای پوسته

یک اسکریپت تکمیل خودکار یا پیکربندی برای پوسته داده‌شده ارائه می‌دهد. اگر Watchexec با اسکریپت‌های تکمیل از پیش تولید شده توزیع نشده باشد، می‌توانید از این گزینه برای تولید آن‌ها استفاده کنید.

پوسته‌های پشتیبانی‌شده: bash, elvish, fish, nu, powershell, zsh.

نمایش صفحه راهنما

در صورتی که خروجی یک ترمینال باشد و برنامه 'man' در دسترس باشد، این گزینه صفحه راهنمای Watchexec را نمایش می‌دهد. در غیر این صورت، صفحه راهنما در قالب ROFF (مناسب برای نوشتن در فایل watchexec.1) در stdout چاپ می‌شود.

--ets
فقط ارسال رویدادها به stdout، بدون اجرای هیچ دستوری.

این یک گزینه کارآمد برای استفاده از Watchexec به عنوان ناظر فایل، بدون اجرای هیچ دستوری است. این عملکرد تقریباً معادل استفاده از دستور `cat` به عنوان دستور اجرایی است، با این تفاوت که برای هر رویداد پروسه جدیدی ایجاد نمی‌کند.

این گزینه به طور ضمنی `--\mit-events-to=json-stdio` را فعال می‌کند؛ همچنین می‌توانید با مشخص کردن `--\mit-events-to=stdio` از حالت متنی استفاده کنید.

چاپ راهنما (مشاهده خلاصه با '-h')
چاپ نسخه
[COMMAND]
دستور (برنامه و آرگومان‌ها) برای اجرا هنگام وقوع تغییرات

هنگامی اجرا می‌شود که رویدادها از فیلترها و دوره debounce عبور کنند (و یک بار هنگام راه‌اندازی، مگر اینکه '--ostpone'
داده شده باشد). اگر گزینه‌هایی را به دستور پاس می‌دهید، بهتر است آن را با --- جدا کنید، هرچند که این کار الزامی نیست.

مثال‌ها:

$ watchexec -w src npm run build

$ watchexec -w src --- rsync -a src dest

هنگام استفاده از الگوهای glob یا سایر بسط‌های پوسته در دستور دقت کنید. پوسته شما ممکن است آن‌ها را قبل از تحویل به Watchexec بسط دهد و نتایج مطابق انتظار نباشد. مقایسه کنید:

$ watchexec echo src/*.rs

$ watchexec echo 'src/*.rs'

$ watchexec --ell=none echo 'src/*.rs'

رفتار به مقدار '--ell' بستگی دارد: برای همه موارد به جز 'none'، تمام بخش‌های دستور با یک کاراکتر فاصله اسکی به یک رشته متصل شده و همان‌طور که در راهنمای '--ell' توضیح داده شده به پوسته تحویل داده می‌شود. برای 'none'، هر عنصر متمایز دستور مطابق با قرارداد execvp(3) ارسال می‌شود: اولین آرگومان برنامه است (به صورت مسیر یا جستجو در متغیر محیطی 'PATH')، و بقیه آرگومان‌ها هستند.

درنگ قبل از اجرای دستور

این گزینه باعث می‌شود Watchexec پس از تشخیص یک رویداد، قبل از اجرای دستور به مدت‌زمان مشخص‌شده درنگ (sleep) کند. این شبیه به استفاده از "sleep 5 && command" در یک پوسته است، اما سازگارتر و کمی کارآمدتر عمل می‌کند.

یک مقدار بدون واحد بر حسب ثانیه، یا مقداری شامل بازه زمانی مانند "2min 5s" می‌گیرد. ارائه مقدار بدون واحد منسوخ شده و هشدار می‌دهد؛ در آینده با خطا متوقف خواهد شد.

افزودن متغیرهای محیطی به دستور

این گزینه مناسبی برای تنظیم متغیرهای محیطی برای دستور است، بدون اینکه آن‌ها را برای خود پروسه Watchexec تنظیم کند.

از ساختار key=value استفاده کنید. می‌توان با تکرار این گزینه چندین متغیر را تنظیم کرد.

ارائه یک سوکت به دستور

این پروتکل ارسال سوکت systemd را همانند `systemfd` پیاده‌سازی می‌کند: سوکت‌ها از پروسه watchexec باز شده و سپس به دستوراتی که اجرا می‌کند منتقل می‌شوند. این کار به شما اجازه می‌دهد سوکت‌ها را باز نگه دارید و از مشکلات استفاده مجدد از آدرس یا از دست رفتن بسته‌ها جلوگیری کنید.

این گزینه را می‌توان چندین بار برای باز کردن چندین سوکت مشخص کرد.

مقدار می‌تواند یکی از موارد `PORT` (باز کردن سوکت شنونده TCP روی آن پورت)، `HOST:PORT` (مشخص کردن آدرس IP میزبان؛ آدرس‌های IPv6 را می‌توان در `[کروکوشه]` قرار داد)، `TYPE::PORT` یا `TYPE::HOST:PORT` (مشخص کردن نوع سوکت، `tcp` / `udp`) باشد.

این یکپارچه‌سازی فقط پشتیبانی پایه را فراهم می‌کند؛ اگر کنترل بیشتری می‌خواهید باید از ابزار `systemfd` از https://github.com/mitsuhiko/systemfd که این ویژگی بر پایه آن است استفاده کنید. ساختار دستور و رفتار ایجاد پروسه در اینجا دقیقاً مشابه `systemfd` است و هم watchexec و هم systemfd پیاده‌سازی‌های سازگار با پروتکل فعال‌سازی سوکت systemd هستند.

برنامه Watchexec متغیر `LISTEN_PID` را روی یونیکس تنظیم نمی‌کند، به این معنی که هر پروسه فرزند دستور شما ممکن است به طور تصادفی به سوکت‌ها متصل شود، مگر اینکه متغیرهای `LISTEN_*` از محیط حذف شوند.

کوتاه‌نوشت برای '--ell=none'
--0-process-group
عدم استفاده از گروه پروسه

به طور پیش‌فرض، Watchexec دستور را در یک گروه پروسه (process group) اجرا می‌کند، تا سیگنال‌ها و خاتمه‌ها به تمام پروسه‌های آن گروه ارسال شوند. گاهی اوقات این رفتار مطلوب نیست و می‌توانید با این گزینه آن را غیرفعال کنید.

منسوخ شده است، به جای آن از '--96ocess=none' استفاده کنید.

تنظیم نقل‌قول کردن یا نکردن نمادهای دستور هنگام ارسال به پوسته.

در ویندوز به طور پیش‌فرض این مقدار نادرست (false) در نظر گرفته می‌شود، زیرا CMD و PowerShell هنگامی که نمادها نقل‌قول شوند به درستی کار نمی‌کنند. برای git-bash و nushell در ویندوز، و همچنین سایر پوسته‌هایی که بدون نقل‌قول به درستی کار نمی‌کنند، با استفاده از این گزینه نقل‌قول کردن را فعال کنید.

در لینوکس و macOS این گزینه نادیده گرفته شده و همیشه درست (true) در نظر گرفته می‌شود، زیرا ارسال مقادیر خام در آن‌ها مجاز نیست.

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

اگر می‌خواهید اسکریپت‌های پوسته‌ای بنویسید که علاوه بر لینوکس/macOS، از طریق git-bash روی ویندوز نیز کار کنند، باید این گزینه را روی true قرار دهید تا رفتار در همه پلتفرم‌ها یکسان باشد. همین امر برای Nushell و احتمالاً سایر پوسته‌های جدیدتر نیز صدق می‌کند.

استفاده از یک پوسته متفاوت

به طور پیش‌فرض، Watchexec در صورت تعریف بودن از '$SHELL' یا مقدار پیش‌فرض 'sh' در سیستم‌های شبه‌یونیکس، و یکی از موارد 'pwsh'، 'powershell' یا 'cmd' (CMD.EXE) در ویندوز بسته به پوسته‌ای که Watchexec در حال اجرا تشخیص می‌دهد استفاده می‌کند.

با این گزینه می‌توانید آن را بازنویسی کرده و از پوسته متفاوتی استفاده کنید، برای مثال پوسته‌ای با امکانات بیشتر یا پوسته‌ای که نام‌های مستعار و توابع سفارشی شما را دارد.

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

دستور با فلگ '-c' اجرا می‌شود (به جز 'cmd' در ویندوز که در آن '/C' است).

مقدار ویژه 'none' می‌تواند برای غیرفعال کردن کامل استفاده از پوسته استفاده شود. در این حالت، دستور ارائه‌شده به Watchexec تجزیه شده که در آن کلمه اول فایل اجرایی و بقیه آرگومان‌ها خواهند بود و مستقیماً اجرا می‌شود. توجه داشته باشید که این تجزیه ابتدایی است و ممکن است در همه موارد طبق انتظار کار نکند.

استفاده از 'none' کمی کارآمدتر است و می‌تواند تفسیر دقیق‌تری از ورودی را فعال کند، اما همچنین به این معنی است که نمی‌توانید از قابلیت‌های پوسته مانند globbing، تغییر مسیر، جریان کنترل، منطق، یا لوله‌ها (pipes) استفاده کنید.

مثال‌ها:

استفاده بدون پوسته:

$ watchexec -n --- zsh -x -o shwordsplit scr

استفاده با powershell core:

$ watchexec --ell=pwsh --- Test-Connection localhost

استفاده با CMD.exe:

$ watchexec --ell=cmd --- dir

استفاده با یک پوسته یونیکس متفاوت:

$ watchexec --ell=bash --- 'echo $BASH_VERSION'

استفاده با یک پوسته یونیکس و گزینه‌ها:

$ watchexec --ell='zsh -x -o shwordsplit' --- scr

سیگنال ارسالی برای متوقف کردن دستور

این گزینه در حالت‌های 'restart' و 'signal' از '--gal' ارائه شده باشد). رفتار restart به این صورت است که سیگنال را ارسال می‌کند، منتظر خروج دستور می‌ماند و اگر پس از مدتی خارج نشد (به '--imeout-stop' مراجعه کنید)، آن را به اجبار خاتمه می‌دهد.

پیش‌فرض در یونیکس "SIGTERM" است.

ورودی به عنوان نام کامل سیگنال (مانند "SIGTERM")، نام کوتاه سیگنال (مانند "TERM") یا شماره سیگنال (مانند "15") تجزیه می‌شود. تمام ورودی‌ها به بزرگی و کوچکی حروف حساس نیستند.

در ویندوز این گزینه از نظر فنی پشتیبانی می‌شود اما فقط از رویداد "KILL" پشتیبانی می‌کند، زیرا Watchexec هنوز نمی‌تواند رویدادهای دیگر را تحویل دهد. ویندوز به خودی خود سیگنال ندارد؛ در عوض دارای رویدادهای خاتمه (در اینجا "KILL" یا "STOP" نامیده می‌شود) و رویدادهای "CTRL+C"، "CTRL+BREAK" و "CTRL+CLOSE" است. برای سازگاری، سیگنال‌های یونیکس "SIGKILL"، "SIGINT"، "SIGTERM" و "SIGHUP" به ترتیب به این موارد نگاشت می‌شوند.

زمان انتظار برای خروج مسالمت‌آمیز دستور

این گزینه در حالت 'restart' از '--

یک مقدار بدون واحد بر حسب ثانیه، یا مقداری شامل بازه زمانی مانند "5min 20s" می‌گیرد. ارائه مقدار بدون واحد منسوخ شده و هشدار می‌دهد؛ در آینده با خطا متوقف خواهد شد.

پیش‌فرض ۱۰ ثانیه است. برای خاتمه اجباری و فوری دستور، آن را روی ۰ تنظیم کنید.

این گزینه هیچ اثر عملی روی ویندوز ندارد زیرا دستور همیشه به اجبار خاتمه می‌یابد؛ برای دلیل آن به '--op-signal' مراجعه کنید.

خاتمه دادن به دستور در صورت اجرا بیش از این مدت‌زمان

مقداری از بازه زمانی مانند "30s"، "5min" یا "1h 30m" می‌گیرد.

هنگامی که مهلت زمانی به پایان می‌رسد، دستور با استفاده از --op-signal به صورت مسالمت‌آمیز متوقف می‌شود، سپس اگر هنوز در حال اجرا باشد پس از --op-timeout به اجبار خاتمه می‌یابد.

هر بار اجرای دستور دارای مهلت زمانی مستقل خود است.

--408
تنظیم دایرکتوری کاری

به طور پیش‌فرض، دایرکتوری کاری دستور همان دایرکتوری کاری Watchexec است. می‌توانید با این گزینه آن را تغییر دهید. توجه داشته باشید که با این کار ممکن است استفاده از مسیرها کمتر شهودی باشد.

--96ocess <MODE> [پیش‌فرض: group]
پیکربندی نحوه بسته‌بندی پروسه

به طور پیش‌فرض، Watchexec دستور را در یک نشست (session) در مک، در یک گروه پروسه در یونیکس، و در یک شیء شغلی (Job Object) در ویندوز اجرا می‌کند.

برخی از برنامه‌های یونیکس ترجیح می‌دهند در یک نشست اجرا شوند، در حالی که برخی دیگر در یک گروه پروسه کار نمی‌کنند.

از 'group' برای استفاده از گروه پروسه، از 'session' برای استفاده از نشست پروسه، و از 'none' برای اجرای مستقیم دستور استفاده کنید. در ویندوز، هر دو مورد 'group' یا 'session' از یک Job Object استفاده خواهند کرد.

اگر متوجه شدید که نیاز دارید مکرراً این گزینه را برای انواع مختلف برنامه‌ها مشخص کنید، مشکلی در https://github.com/watchexec/watchexec/issues ثبت کنید. از آنجا که خطاهای این چنینی به سختی اشکال‌زدایی می‌شوند و می‌توانند به شدت وابسته به محیط باشند، گزارش‌های ارائه‌شده از سوی *چندین فرد تحت تأثیر* با احتمال بیشتری فوراً رسیدگی می‌شوند. از دوستان و همکاران خود بخواهید!

زمان انتظار برای رویدادهای جدید قبل از انجام اقدام

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

یک کاربرد جایگزین، تنظیم یک مقدار بالا (مانند "30min" یا بیشتر) برای صرفه‌جویی در مصرف انرژی یا پهنای باند در کارهای سنگین، مانند یک اسکریپت پشتیبان‌گیری موردی است. در این موارد، توجه داشته باشید که هر رویداد انباشته‌شده در حافظه تجمع می‌یابد.

یک مقدار بدون واحد بر حسب میلی‌ثانیه، یا مقداری شامل بازه زمانی مانند "5sec 20ms" می‌گیرد. ارائه مقدار بدون واحد منسوخ شده و هشدار می‌دهد؛ در آینده با خطا مواجه خواهد شد.

پیش‌فرض ۵۰ میلی‌ثانیه است. تنظیم روی ۰ اکیداً منع می‌شود.

پیکربندی ارسال رویدادها

برنامه Watchexec می‌تواند هنگام اجرای یک دستور، اطلاعات رویداد را ارسال کند که توسط پروسه فرزند برای هدف قرار دادن فایل‌های تغییر یافته خاص قابل استفاده است.

نکته‌ای که باید مراقب آن بود این است که رفتاری را که صرفاً تصادفی رخ می‌دهد، ذاتی سیستم فرض نکنیم. به ویژه، ممکن است به نظر برسد که متغیر `RENAMED` شامل هر دو مسیر اصلی و مسیر جدید تغییر نام یافته است. در نسخه‌های قبلی، حتی در برخی پلتفرم‌ها به نظر می‌رسید که مسیر اصلی همیشه قبل از مسیر جدید می‌آید. با این حال، هیچ‌کدام از این‌ها واقعیت نداشت. دانستن این که کدام مسیر تغییر یافته قدیمی یا جدید است به طور قابل اطمینان و مستقل از پلتفرم غیرممکن است؛ تغییر نام‌های "ناقص" ممکن است رخ دهد (فقط اصلی، فقط جدید)، تغییر نام‌های "نامشخص" ممکن است ظاهر شود (تغییر یک تغییر نام بود، اما اینکه قدیمی بود یا جدید مشخص نیست)، رویدادهای تغییر نام ممکن است در دو مرز debounce تقسیم شوند، و غیره.

این گزینه کنترل می‌کند که اطلاعات در کجا ارسال شود. مقدار پیش‌فرض آن 'none' است که اصلاً اطلاعات رویداد را ارسال نمی‌کند. گزینه‌های دیگر عبارتند از 'environment' (منسوخ شده)، 'stdio'، 'file'، 'json-stdio' و 'json-file'.

حالت‌های 'stdio' و 'file' مبتنی بر متن هستند: حالت 'stdio' مسیرهای مطلق را در ورودی استاندارد (stdin) دستور می‌نویسد (یک مسیر در هر خط با یکی از پیشوندهای `create:`، `remove:`، `rename:`، `modify:` یا `other:`) و سپس هندل را می‌بندد؛ حالت 'file' همین موارد را در یک فایل موقت می‌نویسد و مسیر آن از طریق متغیر محیطی $WATCHEXEC_EVENTS_FILE داده می‌شود.

همچنین دو حالت JSON وجود دارد که مبتنی بر اشیاء JSON هستند و می‌توانند مجموعه کامل رویدادهایی را که Watchexec مدیریت می‌کند نمایش دهند. در اینجا مثالی از ایجاد یک پوشه در لینوکس آورده شده است:

{
  "tags": [
    {
      "kind": "path",
      "absolute": "/home/user/your/new-folder",
      "filetype": "dir"
    },
    {
      "kind": "fs",
      "simple": "create",
      "full": "Create(Folder)"
    },
    {
      "kind": "source",
      "source": "filesystem",
    }
  ],
  "metadata": {
    "notify-backend": "inotify"
  }
}

فیلدها به شرح زیر هستند:


- `tags`، داده‌های ساختاریافته رویداد.
- `tags[].kind`، که می‌تواند شامل موارد زیر باشد:
* 'path'، همراه با:
+ `absolute`، یک مسیر مطلق.
+ `filetype`، نوع فایل در صورت شناخته بودن ('dir', 'file', 'symlink', 'other').
* 'fs':
+ `simple`، نوع رویداد "ساده" ('access', 'create', 'modify', 'remove', یا 'other').
+ `full`، نوع رویداد "کامل"، که پیچیده‌تر از آن است که بتوان در اینجا به طور کامل توصیف کرد، اما به شکل 'General(Precise(Specific))' است.
* 'source'، همراه با:
+ `source`، منبع رویداد ('filesystem', 'keyboard', 'mouse', 'os', 'time', 'internal').
* 'keyboard'، همراه با:
+ `keycode`. در حال حاضر فقط مقدار 'eof' پشتیبانی می‌شود.
* 'process'، برای رویدادهای ناشی از پروسه‌ها:
+ `pid`، شناسه پروسه (PID).
* 'signal'، برای سیگنال‌های ارسال‌شده به Watchexec:
+ `signal`، نام سیگنال استانداردشده ('hangup', 'interrupt', 'quit', 'terminate', 'user1', 'user2').
* 'completion'، برای زمانی که یک دستور پایان می‌یابد:
+ `disposition`، وضعیت خروج ('success', 'error', 'signal', 'stop', 'exception', 'continued').
+ `code`، کد خروج، سیگنال، توقف یا استثنا.
- `metadata`، اطلاعات اضافی درباره رویداد.

حالت 'json-stdio' رویدادهای JSON را به ورودی استاندارد (stdin) دستور ارسال می‌کند (یک رویداد در هر خط) و سپس stdin را می‌بندد. حالت 'json-file' یک فایل موقت ایجاد کرده، رویدادها را در آن می‌نویسد و مسیر فایل را از طریق متغیر محیطی $WATCHEXEC_EVENTS_FILE ارائه می‌دهد.

در نهایت، حالت 'environment' تا قبل از نسخه ۲.۰ پیش‌فرض بود. این حالت متغیرهای محیطی را با مسیرهای فایل‌های تحت تأثیر برای رویدادهای فایل‌سیستم تنظیم می‌کند:

متغیر $WATCHEXEC_COMMON_PATH روی طولانی‌ترین مسیر مشترک تمام متغیرهای زیر تنظیم می‌شود و بنابراین برای به دست آوردن مسیر کامل/واقعی باید به ابتدای هر مسیر اضافه شود. سپس:


- متغیر $WATCHEXEC_CREATED_PATH هنگام ایجاد فایل‌ها/پوشه‌ها تنظیم می‌شود
- متغیر $WATCHEXEC_REMOVED_PATH هنگام حذف فایل‌ها/پوشه‌ها تنظیم می‌شود
- متغیر $WATCHEXEC_RENAMED_PATH هنگام تغییر نام فایل‌ها/پوشه‌ها تنظیم می‌شود
- متغیر $WATCHEXEC_WRITTEN_PATH هنگام تغییر فایل‌ها/پوشه‌ها تنظیم می‌شود
- متغیر $WATCHEXEC_META_CHANGED_PATH هنگام تغییر متادیتای فایل‌ها/پوشه‌ها تنظیم می‌شود
- متغیر $WATCHEXEC_OTHERWISE_CHANGED_PATH برای هر نوع رویداد دارای مسیر دیگر تنظیم می‌شود

مسیرهای متعدد با جداکننده مسیر سیستم از هم جدا می‌شوند: ';' در ویندوز و ':' در یونیکس. در هر متغیر، مسیرها یکتا شده و به ترتیب باینری مرتب می‌شوند (یعنی نه حساس به یونیکد و نه وابسته به محلی‌سازی/locale).

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

پاسخ به فشردن کلیدها برای خروج، راه‌اندازی مجدد، توقف یا مکث

در حالت تعاملی، Watchexec به فشردن کلیدها گوش داده و به آن‌ها پاسخ می‌دهد. کلیدهای پشتیبانی‌شده در حال حاضر عبارتند از: 'r' برای راه‌اندازی مجدد دستور، 's' برای متوقف کردن دستور در حال اجرا، 'p' برای تغییر وضعیت مکث نظارت، و 'q' برای خروج. این حالت نیاز به یک ترمینال (TTY) دارد و stdin را در حالت خام (raw mode) قرار می‌دهد، بنابراین پروسه فرزند ورودی stdin را دریافت نخواهد کرد.

خروج هنگام بروز خطا در دستور

به طور پیش‌فرض، Watchexec پس از پایان دستور بدون توجه به وضعیت خروج آن، به نظارت و اجرای مجدد دستور ادامه می‌دهد. با این گزینه، در صورتی که دستور با هر وضعیت خروجی غیرموفقی خاتمه یابد، خارج خواهد شد.

این گزینه هنگام اجرای Watchexec در یک مدیر پروسه یا کانتینر مفید است؛ جایی که می‌خواهید با شکست دستور کانتینر ری‌استارت شود، نه اینکه منتظر تغییرات فایل بماند.

ترجمه سیگنال‌های سیستم‌عامل به سیگنال‌های ارسالی به دستور

یک جفت نام سیگنال جداشده با دو نقطه می‌گیرد، مانند "TERM:INT" برای نگاشت SIGTERM به SIGINT. اولین سیگنال موردی است که توسط watchexec دریافت می‌شود و دومی موردی است که به دستور ارسال می‌شود. سیگنال دوم را می‌توان برای دور ریختن سیگنال اول حذف کرد، مانند "TERM:" برای انجام ندادن هیچ اقدامی هنگام دریافت SIGTERM.

اگر SIGINT یا SIGTERM نگاشت شوند، دیگر باعث خروج از Watchexec نمی‌شوند. علاوه بر سخت کردن خروج از خود Watchexec، این ویژگی برای انتقال یک کلید Ctrl-C به دستور بدون خاتمه دادن به Watchexec و برنامه زیرین آن مفید است (به عنوان مثال با "INT:INT").

این گزینه را می‌توان چندین بار برای نگاشت چندین سیگنال مشخص کرد.

ساختار نام سیگنال برای نام‌های کوتاه (مانند "TERM", "USR2") و نام‌های کامل (مانند "SIGKILL", "SIGHUP") به بزرگی و کوچکی حروف حساس نیست. شماره‌های سیگنال نیز پشتیبانی می‌شوند (مانند "15", "31"). در ویندوز، فرم‌های "STOP"، "CTRL+C" و "CTRL+BREAK" نیز برای دریافت پشتیبانی می‌شوند، اما Watchexec هنوز نمی‌تواند سیگنال‌هایی غیر از STOP را تحویل دهد.

اقدام لازم هنگام دریافت رویدادها حین اجرای دستور

پیش‌فرض 'do-nothing' است که رویدادها را در حین اجرای دستور نادیده می‌گیرد، تا تغییراتی که به دلیل اجرای خود دستور رخ می‌دهند (مانند خروجی‌های کامپایل) نادیده گرفته شوند. همچنین می‌توانید از 'queue' استفاده کنید که در صورت وقوع رویداد در حین اجرا، پس از پایان اجرای فعلی دستور را یک بار دیگر اجرا می‌کند، یا 'restart' که دستور در حال اجرا را خاتمه داده و دستور جدیدی را شروع می‌کند. در نهایت، گزینه 'signal' وجود دارد که فقط یک سیگنال ارسال می‌کند؛ این گزینه می‌تواند برای برنامه‌هایی که می‌توانند پیکربندی خود را بدون راه‌اندازی مجدد کامل بارگذاری مجدد کنند، مفید باشد.

سیگنال را می‌توان با گزینه '--gnal' مشخص کرد.

--oll
[<INTERVAL>]
نظارت دوره‌ای (polling) برای تغییرات فایل‌سیستم

به طور پیش‌فرض و در صورت امکان، Watchexec از قابلیت‌های نظارت بر فایل‌سیستم بومی سیستم‌عامل استفاده می‌کند. این گزینه آن را غیرفعال کرده و به جای آن از مکانیزم سرکشی دوره‌ای (polling) استفاده می‌کند که کارایی کمتری دارد اما می‌تواند مشکلات مربوط به برخی فایل‌سیستم‌ها (مانند اشتراک‌های شبکه) یا حالت‌های خاص را برطرف کند.

به صورت اختیاری مقداری بدون واحد بر حسب میلی‌ثانیه یا مقداری شامل بازه زمانی مانند "2s 500ms" برای استفاده به عنوان فاصله نظارت دوره‌ای می‌گیرد. در صورت عدم تعیین، پیش‌فرض ۳۰ ثانیه است. ارائه مقدار بدون واحد منسوخ شده و هشدار می‌دهد؛ در آینده با خطا مواجه خواهد شد.

دارای نام مستعار '--rce-poll' است.

انتظار تا نخستین تغییر قبل از اجرای دستور

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

راه‌اندازی مجدد پروسه در صورت در حال اجرا بودن

این یک کوتاه‌نوشت برای '--

ارسال یک سیگنال به پروسه در صورت در حال اجرا بودن

سیگنالی را برای ارسال به پروسه در صورت فعال بودن مشخص کنید. این گزینه به طور ضمنی '--gal' را فعال می‌کند؛ در غیر این صورت سیگنال مورد استفاده هنگامی که این حالت 'restart' باشد توسط '--op-signal' کنترل می‌شود.

برای ساختار نگارش به توضیحات طولانی '--op-signal' مراجعه کنید.

سیگنال‌ها در حال حاضر در ویندوز پشتیبانی نمی‌شوند و همیشه به 'kill' بازنویسی خواهند شد. برای اطلاعات بیشتر درباره "سیگنال‌های" ویندوز به '--op-signal' مراجعه کنید.

خروج هنگام بسته شدن stdin

این گزینه توصیف‌کننده فایل stdin را برای EOF نظارت می‌کند و هنگام بسته شدن آن، از Watchexec به صورت تمیز خارج می‌شود. این ویژگی توسط برخی مدیران پروسه استفاده می‌شود تا از باقی ماندن پروسه‌های زامبی جلوگیری شود.

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

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

الگوهای نام فایل برای فیلتر کردن

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

--lter-file <PATH>
فایل‌هایی برای بارگذاری فیلترها از آن‌ها

مسیری به یک فایل حاوی فیلترها (یک فیلتر در هر خط) ارائه دهید. خطوط خالی و خطوطی که با '#' شروع می‌شوند نادیده گرفته می‌شوند. از همان ساختار الگوی گزینه '--lter' استفاده می‌کند.

این ویژگی همچنین می‌تواند از طریق متغیر محیطی $WATCHEXEC_FILTER_FILES استفاده شود.

برنامه‌های فیلتر

برنامه‌های فیلتر سفارشی خود را با ساختار jaq (مشابه jq) ارائه دهید. به برنامه‌ها رویدادی با همان ساختاری که در '--\mit-events-to' توضیح داده شده داده می‌شود و باید یک مقدار بولی برگردانند. برنامه‌های نامعتبر مانع از شروع به کار watchexec می‌شوند؛ از '-v' برای مشاهده خطاهای زمان اجرای برنامه استفاده کنید.

علاوه بر کتابخانه استاندارد jaq، برنامه watchexec برخی تعاریف فیلتر سفارشی را اضافه می‌کند:

- 'path | file_meta' متادیتای فایل یا در صورت عدم وجود فایل مقدار null را برمی‌گرداند.

- 'path | file_size' اندازه فایل در مسیر یا در صورت عدم وجود مقدار null را برمی‌گرداند.

- 'path | file_read(bytes)' رشته‌ای شامل n بایت اول فایل در مسیر برمی‌گرداند. اگر فایل کوچک‌تر از n بایت باشد، کل فایل برگردانده می‌شود. برای تشویق به محدود کردن مقدار داده خوانده شده و پردازش شده، فیلتری برای خواندن کل فایل به طور یکجا وجود ندارد.

- 'string | hash' و 'path | file_hash' هش رشته یا فایل موجود در مسیر را برمی‌گردانند. هیچ تضمینی در مورد الگوریتم مورد استفاده داده نمی‌شود: با آن به عنوان یک مقدار مات (نامشخص) برخورد کنید.

- 'any | kv_store(key)'، 'kv_fetch(key)' و 'kv_clear' یک ذخیره‌ساز کلید-مقدار ساده فراهم می‌کنند. داده‌ها فقط در حافظه نگهداری می‌شوند و هیچ پایداری (persistence) وجود ندارد. یکپارچگی داده‌ها تضمین نمی‌شود.

- 'any | printout'، 'any | printerr' و 'any | log(level)' هر مقدار داده‌شده را در stdout، stderr یا لاگ چاپ یا ثبت می‌کنند (سطوح = error, warn, info, debug, trace) و مقدار را عبور می‌دهند (بنابراین '[1] | log("debug") | .[]' مقدار '1' را تولید کرده و '[1]' را لاگ می‌کند).

تمام عملیات فیلتر کردن انجام‌شده با چنین برنامه‌هایی، و به ویژه آن‌هایی که از kv یا دسترسی به فایل‌سیستم استفاده می‌کنند، بسیار کندتر از سایر روش‌های فیلتر کردن هستند. اگر فیلتر کردن بیش از حد کند باشد، رویدادها انباشته شده و watchexec متوقف می‌شود. هنگام طراحی فیلترهای خود دقت کنید.

اگر آرگومان این گزینه با یک '@' شروع شود، بقیه آرگومان به عنوان مسیر فایلی حاوی یک برنامه jaq در نظر گرفته می‌شود.

برنامه‌های jaq به ترتیب و پس از تمام فیلترهای دیگر اجرا می‌شوند و قابلیت اتصال کوتاه (short-circuit) دارند: اگر فیلتری (چه jaq و چه غیر آن) رویدادی را رد کند، اجرا در همان‌جا متوقف شده و هیچ فیلتر دیگری اجرا نمی‌شود. علاوه بر این، آن‌ها پس از خروجی دادن اولین مقدار متوقف می‌شوند، بنابراین هنگام پیمایش باید از 'any' یا 'all' استفاده کنید، در غیر این صورت فقط اولین مورد پردازش می‌شود که می‌تواند بسیار گیج‌کننده باشد!

برنامه‌های ارائه‌شده توسط کاربران را بیابید یا برنامه‌های مفید خود را در https://github.com/watchexec/watchexec/discussions/592 ارسال کنید.

مثال‌ها:

فیلتر نادیده‌گیری با عبارت منظم روی مسیرها:

'all(.tags[] | select(.kind == "path"); .absolute | test("[.]test[.]js$")) | not'

عبور دادن هر رویدادی که یک فایل ایجاد می‌کند:

'any(.tags[] | select(.kind == "fs"); .simple == "create")'

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

'any(.tags[] | select(.kind == "path" && .filetype == "file"); .absolute | metadata | .executable)'

نادیده گرفتن فایل‌هایی که با shebang شروع می‌شوند:

'any(.tags[] | select(.kind == "path" && .filetype == "file"); .absolute | read(2) == "#!") | not'

---events <EVENTS>
رویدادهای فایل‌سیستم برای فیلتر کردن

این یک فیلتر سریع برای ارسال رویدادها فقط برای انواع مشخص‌شده تغییرات فایل‌سیستم است. از میان 'access'، 'create'، 'remove'، 'rename'، 'modify'، 'metadata' انتخاب کنید. انواع متعدد را می‌توان با تکرار این گزینه یا با جدا کردن آن‌ها با کاما مشخص کرد. به طور پیش‌فرض، این گزینه شامل تمام انواع به جز 'access' است.

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

الگوهای نام فایل برای نادیده گرفتن

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

--ignore-file <PATH>
فایل‌هایی برای بارگذاری موارد نادیده‌گیری از آن‌ها

مسیری به یک فایل حاوی موارد نادیده‌گیری (یک مورد در هر خط) ارائه دهید. خطوط خالی و خطوطی که با '#' شروع می‌شوند نادیده گرفته می‌شوند. از همان ساختار الگوی گزینه '--ignore' استفاده می‌کند.

این ویژگی همچنین می‌تواند از طریق متغیر محیطی $WATCHEXEC_IGNORE_FILES استفاده شود.

--ignore-nothing
هیچ چیزی را نادیده نگیر

این یک کوتاه‌نوشت برای '--0-discover-ignore' و '--0-default-ignore' است.

توجه داشته باشید که موارد نادیده‌گیری که به صراحت از طریق سایر گزینه‌های خط فرمان بارگذاری شده‌اند، مانند '--ignore' یا '--ignore-file'، همچنان استفاده خواهند شد.

--0-default-ignore
عدم استفاده از موارد نادیده‌گیری پیش‌فرض داخلی

برنامه Watchexec دارای مجموعه‌ای از الگوهای نادیده‌گیری پیش‌فرض است، مانند فایل‌های موقت ویرایشگر (swap)، `*.pyc`, `*.pyo`, `.DS_Store`, `.bzr`, `_darcs`, `.fossil-settings`, `.git`, `.hg`, `.pijul`, `.svn` و فایل‌های لاگ Watchexec.

--0-discover-ignore
عدم کشف خودکار فایل‌های نادیده‌گیری

این یک کوتاه‌نوشت برای '--0-global-ignore', '--0-vcs-ignore', '--0-project-ignore' است، اما حتی کارآمدتر است زیرا تمام مکانیزم‌های شناسایی نادیده‌گیری را از همان ابتدا نادیده می‌گیرد.

توجه داشته باشید که نادیده‌گیری‌های پیش‌فرض همچنان بارگذاری می‌شوند؛ به '--0-default-ignore' مراجعه کنید.

--0-global-ignore
عدم بارگذاری موارد نادیده‌گیری سراسری

این گزینه بارگذاری فایل‌های نادیده‌گیری سراسری یا کاربری را غیرفعال می‌کند، مانند '~/.gitignore'، '~/.config/watchexec/ignore'، یا '%APPDATA%\Bazzar\2.0\ignore'. مقایسه شود با '--0-vcs-ignore' و '--0-project-ignore'.

فایل‌های نادیده‌گیری سراسری پشتیبانی‌شده:


- Git (در صورت تنظیم core.excludesFile): فایل موجود در آن مسیر
- Git (در غیر این صورت): اولین مورد یافت‌شده از $XDG_CONFIG_HOME/git/ignore, %APPDATA%/.gitignore, %USERPROFILE%/.gitignore, $HOME/.config/git/ignore, $HOME/.gitignore.
- Bazaar: اولین مورد یافت‌شده از %APPDATA%/Bazzar/2.0/ignore, $HOME/.bazaar/ignore.
- Watchexec: اولین مورد یافت‌شده از $XDG_CONFIG_HOME/watchexec/ignore, %APPDATA%/watchexec/ignore, %USERPROFILE%/.watchexec/ignore, $HOME/.watchexec/ignore.

همانند فایل‌های پروژه، فایل‌های سراسری Git و Bazaar فقط برای سیستم‌های کنترل نسخه مربوطه همان‌طور که در پروژه استفاده شده‌اند به کار گرفته می‌شوند.

--0-meta
عدم ارسال رویدادهای فایل‌سیستم برای تغییرات متادیتا

این یک کوتاه‌نوشت برای '---events create,remove,rename,modify' است. استفاده از آن در کنار گزینه '---events' بی‌معنی است و مجاز نیست.

--0-project-ignore
عدم بارگذاری موارد نادیده‌گیری محلی پروژه

این گزینه بارگذاری فایل‌های نادیده‌گیری محلی پروژه مانند '.gitignore' یا '.ignore' در پروژه تحت نظارت را غیرفعال می‌کند. این مورد با '--0-vcs-ignore' که بارگذاری Git و سایر فایل‌های نادیده‌گیری سیستم کنترل نسخه را غیرفعال می‌کند، و با '--0-global-ignore' که بارگذاری فایل‌های نادیده‌گیری سراسری یا کاربری مانند '~/.gitignore' یا '~/.config/watchexec/ignore' را غیرفعال می‌کند، مقایسه می‌شود.

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


- Git: فایل .gitignore در ریشه پروژه و دایرکتوری‌های فرزند، .git/info/exclude، و فایل مشخص‌شده توسط `core.excludesFile` در .git/config.
- Mercurial: فایل .hgignore در ریشه پروژه و دایرکتوری‌های فرزند.
- Bazaar: فایل .bzrignore در ریشه پروژه.
- Darcs: فایل _darcs/prefs/boring
- Fossil: فایل .fossil-settings/ignore-glob
- Ripgrep/Watchexec/generic: فایل .ignore در ریشه پروژه و دایرکتوری‌های فرزند.

فایل‌های نادیده‌گیری سیستم کنترل نسخه (شامل Git، Mercurial، Bazaar، Darcs، Fossil) فقط در صورتی استفاده می‌شوند که مشخص شود سیستم کنترل نسخه مربوطه برای پروژه/مبدأ استفاده می‌شود. به عنوان مثال، یک .bzrignore در یک مخزن Git نادیده گرفته خواهد شد.

--0-vcs-ignore
عدم بارگذاری موارد نادیده‌گیری سیستم کنترل نسخه (gitignores)

در میان سایر فایل‌های مستثنی‌سازی سیستم کنترل نسخه (VCS)، مانند Mercurial، Subversion، Bazaar، DARCS، Fossil. توجه داشته باشید که Watchexec در صورت وجود تشخیص می‌دهد کدام‌یک از این‌ها در حال استفاده هستند و فقط فایل‌های مربوطه را بارگذاری می‌کند. هر دو فایل سراسری (مانند '~/.gitignore') و محلی (مانند '.gitignore') در نظر گرفته می‌شوند.

این گزینه زمانی مفید است که می‌خواهید فایل‌هایی را که توسط Git نادیده گرفته شده‌اند نظارت کنید.

--roject-origin
<DIRECTORY>
تنظیم مبدأ پروژه

برنامه Watchexec تلاش می‌کند تا "مبدأ" (یا "ریشه") پروژه را با جستجوی نشانه‌های مختلف مانند فایل‌ها یا الگوهای دایرکتوری کشف کند. این کار را به بهترین نحو انجام می‌دهد اما گاهی اوقات اشتباه می‌کند، و شما می‌توانید با این گزینه آن را بازنویسی کنید.

مبدأ پروژه برای تعیین مسیر برخی از فایل‌های نادیده‌گیری، سیستم کنترل نسخه در حال استفاده، معنای '/' ابتدایی در الگوهای فیلتر کردن، و شاید موارد بیشتر در آینده استفاده می‌شود.

هنگامی که این گزینه تنظیم شود، Watchexec دیگر زحمت جستجو را به خود نمی‌دهد که می‌تواند به طور قابل توجهی سریع‌تر باشد.

نظارت بر یک فایل یا دایرکتوری خاص

به طور پیش‌فرض، Watchexec دایرکتوری جاری را نظارت می‌کند.

هنگام نظارت بر یک فایل منفرد، اغلب بهتر است دایرکتوری حاوی آن را نظارت کرده و روی نام فایل فیلتر اعمال کنید. برخی از ویرایشگرها ممکن است هنگام ذخیره، فایل را با یک فایل جدید جایگزین کنند، و برخی پلتفرم‌ها ممکن است این تغییر یا تغییرات بعدی را تشخیص ندهند.

پس از شروع، Watchexec یک "مبدأ پروژه" را از مسیرهای تحت نظارت تعیین می‌کند. برای اطلاعات بیشتر به راهنمای '--roject-origin'
مراجعه کنید.

این گزینه را می‌توان چندین بار برای نظارت بر چندین فایل یا دایرکتوری مشخص کرد.

مقدار ویژه '/dev/null' در صورتی که به عنوان تنها مسیر تحت نظارت ارائه شود، باعث می‌شود Watchexec هیچ مسیری را نظارت نکند. سایر منابع رویداد (مانند سیگنال‌ها یا رویدادهای کلید) همچنان ممکن است استفاده شوند.

نظارت بر یک دایرکتوری خاص، به صورت غیربازگشتی

برخلاف '-w'، پوشه‌های تحت نظارت با این گزینه به صورت بازگشتی پیمایش نمی‌شوند.

این گزینه را می‌توان چندین بار برای نظارت بر چندین دایرکتوری به صورت غیربازگشتی مشخص کرد.

نظارت بر فایل‌ها و دایرکتوری‌ها از یک فایل

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

برای کاربردهای پیچیده‌تر (مانند نظارت غیربازگشتی)، از قابلیت argfile استفاده کنید: فایلی حاوی گزینه‌های خط فرمان بسازید و آن را با `@path/to/argfile` به watchexec پاس دهید.

مقدار ویژه '-' از STDIN خواهد خواند؛ این مورد با '--din-quit' ناسازگار است.

--0-follow-symlinks
عدم دنبال کردن پیوندهای نمادین دایرکتوری هنگام نظارت

به طور پیش‌فرض، Watchexec هنگام ساخت نظارت‌های بازگشتی پیوندهای نمادین دایرکتوری را دنبال می‌کند. با این گزینه، مقصدهای آن‌ها گنجانده نمی‌شوند؛ تغییرات در خود پیوندهای نمادین همچنان ممکن است رویداد تولید کند.

ناظر بومی macOS پیوندهای نمادین دایرکتوری خارج از سلسله‌مراتب تحت نظارت را حتی بدون این گزینه نیز دنبال نمی‌کند.

--
نوشتن لاگ‌های تشخیصی در یک فایل

این گزینه لاگ‌های تشخیصی را به جای ترمینال، در قالبی از JSON در یک فایل می‌نویسد. اگر سطح لاگ قبلاً مشخص نشده باشد، این گزینه آن را روی '-vvv' تنظیم می‌کند.

اگر مسیری ارائه نشود، پیش‌فرض دایرکتوری کاری است. توجه داشته باشید که با '--ignore-nothing'، رویدادهای نوشتن در لاگ احتمالاً توسط Watchexec شناسایی می‌شوند و باعث ایجاد یک حلقه تکرار می‌گردند؛ ترجیحاً مسیری خارج از دایرکتوری تحت نظارت تنظیم کنید.

اگر مسیر ارائه‌شده یک دایرکتوری باشد، فایلی در آن دایرکتوری ایجاد خواهد شد. نام فایل تاریخ و زمان جاری با فرمت 'watchexec.YYYY-MM-DDTHH-MM-SSZ.log' خواهد بود.

--rint-events
چاپ رویدادهایی که محرک اقدامات هستند

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

در صورت نیاز به اطلاعات تشخیصی بیشتر، به جای آن از '-vvv' استفاده کنید.

تنظیم سطح لاگ تشخیصی

این گزینه ثبت لاگ‌های تشخیصی را فعال می‌کند که برای بررسی اشکالات یا به دست آوردن اطلاعات بیشتر در مورد فیلترهای معیوب یا رویدادهای "گم‌شده" مفید است. برای افزایش سطح جزئیات از آن چندین بار استفاده کنید.

تا '-vvvv' افزایش می‌یابد. هنگام ارسال گزارش‌های باگ، سطح لاگ پیش‌فرض را روی '-vvv' قرار دهید.

ممکن است بخواهید از آن همراه با '--

تنظیم متغیر محیطی $WATCHEXEC_LOG نیز کار می‌کند و اولویت دارد، اما توصیه نمی‌شود. با این حال، استفاده از $WATCHEXEC_LOG تنها راه برای دریافت لاگ‌ها از قبل از تجزیه این گزینه‌ها است.

--
به صدا درآوردن زنگ ترمینال پس از اتمام دستور
پاک کردن صفحه قبل از اجرای دستور

اگر این گزینه صفحه را به طور کامل پاک نکرد، '--lear=reset' را امتحان کنید.

--olor <MODE> [پیش‌فرض: auto]
زمان استفاده از رنگ‌های ترمینال

تنظیم متغیر محیطی `NO_COLOR` به هر مقداری معادل با `--olor=never` است.

اعلان هنگام شروع و پایان دستورات

با این گزینه، Watchexec هنگام شروع و پایان یک دستور در پلتفرم‌های پشتیبانی‌شده، یک اعلان دسکتاپ صادر می‌کند. در پلتفرم‌های پشتیبانی‌نشده، ممکن است بدون هیچ پیامی کاری انجام ندهد یا یک هشدار ثبت کند.

حالت را می‌توان به گونه‌ای مشخص کرد که فقط هنگام شروع دستور (`start`)، پایان دستور (`end`)، یا برای هر دو (`both` - که پیش‌فرض است) اعلان ارسال کند.

عدم چاپ پیام‌های شروع و توقف

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

چاپ مدت‌زمان اجرای دستور

این مقدار ممکن است کاملاً دقیق نباشد، زیرا شامل مقداری بار اضافه (overhead) از سوی خود Watchexec است. برای نتایج دقیق‌تر از ابزار `time`، تایمرهای با دقت بالا یا ابزارهای محک‌زنی (benchmarking) استفاده کنید.

از @argfile به عنوان اولین آرگومان برای بارگذاری آرگومان‌ها از فایل 'argfile' (یک آرگومان در هر خط) استفاده کنید که به جای @argfile درج خواهد شد (آرگومان‌های بعدی در خط فرمان، موارد موجود در فایل را بازنویسی کرده یا به آن‌ها اضافه می‌شوند).

انتظار این همه خروجی را نداشتید؟ از پرچم کوتاه '-h' برای دریافت راهنمای کوتاه استفاده کنید.

v2.7.2

Félix Saparelli <felix@passcod.name>, Matt Green <mattgreenrocks@gmail.com>

watchexec 2.7.2