نام (NAME)

cargo-watch - بر کدهای منبع پروژه Cargo شما نظارت می‌کند

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

cargo watch [--version	-V]
cargo watch [--help	-h]

توضیحات (DESCRIPTION)

بر کدهای منبع پروژه شما برای تشخیص تغییرات نظارت می‌کند و هنگام رخ دادن آن‌ها، دستورات Cargo را اجرا می‌نماید.

دستورات (COMMANDS)

cargo subcommand: زیردستور Cargo که هنگام تغییر فایل‌های تحت نظارت و در زمان راه‌اندازی اجرا می‌شود، مگر اینکه گزینه --postpone مشخص شده باشد.

این در واقع همانند <command> است اما با پیشوند cargo، با این تفاوت که علاوه بر آن، گزینه‌های مختص cargo مانند --features نیز اعمال می‌شوند.

command: دستوری که هنگام تغییر فایل‌های تحت نظارت و در زمان راه‌اندازی اجرا می‌شود، مگر اینکه گزینه --postpone مشخص شده باشد.

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

دستورات Cargo (گزینه -x) همیشه پیش از دستورات پوسته (گزینه -s) اجرا می‌شوند.

اگر یک دستور انتهایی با -- <command> مشخص شود، جایگزین تمام دستورات دیگر خواهد شد.

گزینه‌ها (OPTIONS)

-h, --help: نمایش این پیام راهنما.
-V, --version: نمایش اطلاعات نسخه.
--debug: نمایش خروجی اشکال‌زدایی (دیباگ).
--why: نمایش مسیرهایی که دچار تغییر شده‌اند.
-q, --quiet: عدم نمایش خروجی‌های خود cargo-watch.
--skip-local-deps: از یافتن وابستگی‌های محلی کریت فعلی و نظارت بر دایرکتوری‌های کاری آن‌ها صرف‌نظر می‌کند. فقط بر دایرکتوری جاری نظارت خواهد شد.
-w, --watch watch...: نظارت بر فایل(ها) یا پوشه(های) خاص. جستجو و نظارت بر وابستگی‌های محلی را غیرفعال می‌کند.

به‌طور پیش‌فرض، دایرکتوری‌های فضای‌کاری (workspace) پروژه شما و تمام وابستگی‌های محلی به جز پوشه‌های target/ و .git/ تحت نظارت قرار می‌گیرند. فایل‌های .ignore و .gitignore شما برای فیلتر کردن مسیرها استفاده می‌شوند.

-i, --ignore pattern...: نادیده گرفتن یک الگوی منطبق بر سبک glob/gitignore.

در ویندوز، اسلش‌های مستقیم (/) در الگوهای ارائه‌شده به -i به‌طور خودکار به بک‌اسلش تبدیل می‌شوند تا قابلیت حمل دستورات آسان‌تر شود.

--no-vcs-ignores: از فایل‌های .gitignore استفاده نکن.
--no-dot-ignores: از فایل‌های .ignore استفاده نکن.
--ignore-nothing: هیچ چیزی را نادیده نگیر، حتی target/ و .git/.
-c, --clear: پاک کردن صفحه قبل از هر بار اجرا.
-E, --env-var key=value: تزریق یک متغیر محیطی.
--env-file path: تزریق متغیرهای محیطی از یک فایل به سبک dotenv.
-B value: تزریق متغیر RUST_BACKTRACE=<value> به محیط اجرایی.

این گزینه زمانی مفید است که خطاها (panics) مدیریت شده‌اند و شما می‌خواهید ردگیری پشته چاپ شود: در حالت معمول باید RUST_BACKTRACE=1 را خودتان اضافه می‌کردید، اما این گزینه آن را به -B1 کوتاه می‌کند!

-L value: تزریق متغیر RUST_LOG=<value> به محیط اجرایی.
--experimental--env-changes: گزینه ناپایدار و آزمایشی که متغیرهای محیطی WATCHEXEC_* را روی دستور تنظیم می‌کند تا اطلاعات مربوط به تغییرات فایلی که cargo watch مشاهده کرده را جمع‌آوری نماید. به این گزینه اتکا نکنید، ممکن است بدون اطلاع قبلی حذف شده یا تغییر کند.

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

-C, --workdir path: تغییر دایرکتوری کاری به مسیر path مشخص‌شده.

پیش‌فرض، ریشه کریت است، همان‌طور که توسط cargo locate-project پیدا می‌شود.

--postpone: به تعویق انداختن نخستین اجرا تا زمانی که یک فایل تغییر کند.
--poll: اجبار به استفاده از روش سرکشی (polling) برای تشخیص تغییرات فایل.
--no-process-group: به‌طور پیش‌فرض، Cargo Watch از یک گروه فرآیند (process group) برای اجرای دستور(ها) استفاده می‌کند. این گزینه آن رفتار را غیرفعال می‌سازد.
-d, --delay delay: تاخیر حذف نوسان (debounce) به‌روزرسانی فایل‌ها بر حسب ثانیه (پیش‌فرض: 0.5).
--no-restart: دستور را در حالی که هنوز در حال اجراست، مجدداً راه‌اندازی نکن.
--watch-when-idle: نادیده گرفتن رویدادهایی که در حین اجرای دستورات منتشر می‌شوند.
--features features: فهرست قابلیت‌هایی (features) که به فراخوانی‌های cargo ارسال می‌شوند.

این ویژگی‌ها به تمام زیردستورهای پشتیبانی‌شده cargo ارسال خواهند شد. برای نمونه، با این دستور:

$ cargo watch --features foo,bar -x clean -x build -x doc

هر دو دستور build و doc با ویژگی‌های foo و bar اجرا خواهند شد، اما clean این ویژگی‌ها را دریافت نخواهد کرد.

--use-shell use-shell: استفاده از یک پوسته دیگر. به عنوان مثال --use-shell=bash. در ویندوز، --use-shell=powershell را امتحان کنید.

مقدار ویژه none از هیچ پوسته‌ای استفاده نمی‌کند، اما فقط با یک دستور انتهایی کار می‌کند، نه با -x یا -s.

مثال‌ها (EXAMPLES)

اجرای cargo check هنگام ذخیره فایل:

$ cargo watch

فقط اجرای تست‌ها:

$ cargo watch -x test

ابتدا اجرای check و سپس test:

$ cargo watch -x check -x test

اجرای run همراه با آرگومان‌ها:

$ cargo watch -x 'run -- --some-arg'

اجرای یک دستور دلخواه:

$ cargo watch -- echo Hello world

اجرا با ویژگی‌های ارسال‌شده به cargo:

$ cargo watch --features 'foo,bar'

جزئیات (DETAILS)

فایل‌های نادیده‌گیری (Ignore files)

فایل‌های .gitignore به‌طور پیش‌فرض برای نادیده گرفتن مسیرهای تحت نظارت و شروع اجرا استفاده می‌شوند. برای توقف رعایت آن‌ها، گزینه --no-vcs-ignores را ارسال کنید.

فایل‌های .ignore با همان قواعد نحوی نیز به‌طور پیش‌فرض استفاده می‌شوند. این فایل می‌تواند برای مشخص کردن فایل‌هایی استفاده شود که باید توسط cargo watch نادیده گرفته شوند اما در گیت ثبت شوند، بدون اینکه نیاز باشد مدام گزینه‌های --ignore abc را در خط فرمان اضافه کنید. توجه داشته باشید که فایل‌های .ignore ممکن است توسط برنامه‌های دیگر مانند ripgrep(1) نیز استفاده شوند. برای توقف رعایت این فایل‌ها، گزینه --no-dot-ignores را ارسال کنید.

علاوه بر موارد مشخص‌شده در فایل‌ها، Cargo watch دارای یک لیست داخلی از نادیده‌گیری‌های پیش‌فرض است، مانند target/ و .git/ و انواع فایل‌های رایج دیگر (لاگ‌ها، فایل‌های swap ویرایشگر، فایل‌های lock و غیره).

برای نادیده نگرفتن مطلقا هیچ فایلی، از فلگ --ignore-nothing استفاده کنید.

قواعد نحوی نادیده‌گیری (Ignore syntax)

مستندات glob::Pattern در نشانی https://doc.rust-lang.org/glob/glob/struct.Pattern.html را برای مشخصات دقیق‌تر قواعد تطبیق glob مورد استفاده در --ignore مشاهده کنید.

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

اشکالات (BUGS)

لطفاً یک گزارش اشکال در https://github.com/watchexec/cargo-watch/issues باز کنید یا گزارش‌های موجود را بررسی فرمایید.

اگر خروجی با جزئیات بیشتر می‌خواهید، اجرای دستور با فلگ --debug را امتحان کنید. توجه داشته باشید که این کار حالت اشکال‌زدایی را برای watchexec نیز فعال می‌کند. هنگام ثبت گزارش، حتماً گزارشی همراه با --debug فعال ارسال کنید تا مشکلات قابل عیب‌یابی باشند، همچنین --version و سیستم‌عامل خود را ذکر نمایید.

اگر مشکل شما مربوط به watchexec (پروژه بالادستی اصلی ما) است، آن را مستقیماً در https://github.com/watchexec/watchexec/issues مطرح کنید. اگر مطمئن نیستید، می‌توانید آن را در بخش پیگیری اشکالات cargo-watch باز کنید، اما اگر واقعاً مربوط به watchexec باشد، به آنجا منتقل خواهد شد.

اشکالات شناخته‌شده (KNOWN BUGS)

در نسخه 7.8.0، گزینه --workdir دایرکتوری را قبل از پردازش هر گزینه دیگری تغییر می‌دهد، بنابراین مثلاً مسیرهای --watch ممکن است مطابق انتظار عمل نکنند. این مشکل در کتابخانه Watchexec نسخه ۲ بالادست برطرف شده است.

در نسخه 8.x، گزینه‌های -B، -L، -E، --env-var و --env-file متغیرهای محیطی را به فرآیند اصلی cargo-watch تزریق می‌کنند که ممکن است در برخی شرایط نامطمئن باشد و روی خود cargo-watch نیز تأثیر بگذارد. این مورد در کتابخانه Watchexec نسخه ۲ بالادست برطرف شده است.

عیب‌یابی (TROUBLESHOOTING)

همیشه با بررسی نسخه خود با cargo watch --version شروع کنید و در صورت لزوم، با بررسی وب‌سایت پیوند داده‌شده در بالا، به آخرین نسخه ارتقا دهید.

کندی RLS هنگام استفاده از cargo watch یا انتظار طولانی برای قفل پروژه

ساخت‌های Cargo (و دستورات check، clippy و تست‌ها چون تست‌ها نیز باید ساخته شوند) قفلی روی پروژه ایجاد می‌کنند تا دو نمونه cargo به‌طور همزمان اجرا نشوند.

با این حال، Rust Analyzer در این زمینه بسیار بهتر عمل می‌کند، بنابراین به جای RLS از آن استفاده کنید.

اعمال نشدن به‌روزرسانی‌های فایل

برای اجبار به استفاده از روش پشتیبان سرکشی، گزینه --poll را امتحان کنید.

اگر همچنان کار نکرد و از ویرایشگری استفاده می‌کنید که ذخیره امن (safe saving) دارد (مانند IntelliJ / PyCharm)، ممکن است لازم باشد «safe saving» را غیرفعال کنید زیرا ممکن است مانع تولید صحیح اعلان‌های فایل شود.

همچنین می‌توانید از گزینه --why استفاده کنید تا ببینید آیا مسیرهای مورد انتظار شما در حال تغییر هستند یا خیر.

اجرای مکرر بدون تغییر دادن هیچ فایلی

این اتفاق ممکن است زمانی رخ دهد که فایل‌های تحت نظارت توسط همان دستوری که اجرا می‌کنید تغییر داده شوند.

اگر فقط کامپایل‌ها یا بررسی‌ها را اجرا می‌کنید (یعنی هر دستوری که فقط بر پوشه target/ تأثیر می‌گذارد) و از -w استفاده می‌کنید، ممکن است سیستم نادیده‌گیر پوشه target را به اشتباه انداخته باشید. گزینه‌ها و مسیرهای خود را بررسی کنید.

همچنین می‌توانید از فلگ --watch-when-idle برای نادیده گرفتن هر رویدادی که در حین اجرای دستور رخ می‌دهد استفاده کنید. این ویژگی در نسخه 8.0 به حالت پیش‌فرض تبدیل خواهد شد.

اجرای مکرر در حالی که فقط فایل‌های نادیده‌گرفته‌شده دستکاری می‌شوند

مطمئن شوید فایل‌هایی که نادیده گرفته‌اید تنها فایل‌هایی هستند که دستکاری می‌شوند. از گزینه --why استفاده کنید تا دقیقاً ببینید کدام فایل‌ها تغییر کرده و باعث راه‌اندازی مجدد شده‌اند. برخی برنامه‌ها و کتابخانه‌ها فایل‌های موقتی ایجاد می‌کنند که ممکن است با یک الگوی نادیده‌گیری ساده مطابقت نداشته باشند.

همانند بالا، می‌توانید از فلگ --watch-when-idle نیز برای کمک استفاده کنید.

نبود رنگ در خروجی cargo یا آزمون‌های cargo test

این مسئله گاهی در برخی تنظیمات ترمینال یا برای محیط‌های تست رخ می‌دهد. یک راه‌حل سریع (به جای درگیر شدن در رفع اشکال تنظیمات کنسول) ارسال گزینه --color=always به دستور است؛ به عنوان مثال:

$ cargo watch -x 'check --color=always'

برای دستورات test (و bench)، باید این فلگ را به جای cargo به برنامه زیرین ارسال کنید:

$ cargo watch -x 'test -- --color=always'

نویسنده (AUTHOR)

نوشته‌شده و نگهداری‌شده توسط Félix Saparelli.

https://passcod.name

صفحه اصلی پروژه:

https://watchexec.github.io/#cargo-watch

مالکیت عمومی (Public domain).