CARGO-YANK(1) General Commands Manual CARGO-YANK(1)

cargo-yank - حذف یک کریت ارسال‌شده از نمایه

cargo yank [options] crate@version
cargo yank [options] --version version [crate]

دستور yank نسخهٔ یک کریت که قبلاً منتشر شده است را از نمایهٔ (index) کارساز حذف می‌کند. این دستور هیچ داده‌ای را پاک نمی‌کند و کریت همچنان از طریق پیوند بارگیری مخزن (registry) برای دانلود در دسترس خواهد بود.

ابزار Cargo از نسخهٔ yank‌شده برای هیچ پروژهٔ جدید یا دریافت کدی (checkout) بدون فایل قفل (lockfile) از پیش موجود استفاده نخواهد کرد، و اگر دیگر هیچ نسخهٔ سازگاری برای کریت شما وجود نداشته باشد، یک خطا تولید می‌کند.

این دستور مستلزم آن است که هویت شما با گزینهٔ --token یا با استفاده از cargo-login(1) احراز شده باشد.

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

به عنوان مثال، کریت foo نسخهٔ 1.5.0 را منتشر کرده و کریت دیگری به نام bar وابستگی خود را به نسخهٔ foo = "1.5" اعلام کرده است. اکنون foo نسخهٔ جدید 2.0.0 را که از نظر semver سازگار نیست منتشر می‌کند، و متوجه یک مشکل بحرانی در 1.5.0 می‌شود. اگر 1.5.0 اصطلاحاً yank شود، هیچ پروژهٔ جدید یا checkout بدون lockfile موجود قادر به استفاده از کریت bar نخواهد بود زیرا به 1.5 متکی است.

در این حالت، نگهدارندگان foo باید پیش از yank کردن 1.5.0، ابتدا یک نسخهٔ سازگار با semver مانند 1.5.1 را منتشر کنند تا bar و تمام پروژه‌های وابسته به آن همچنان به کار خود ادامه دهند.

به عنوان مثالی دیگر، کریت bar را با نسخه‌های منتشرشدهٔ 1.5.0، 1.5.1، 1.5.2، 2.0.0 و 3.0.0 در نظر بگیرید. جدول زیر نسخه‌هایی را که cargo می‌تواند در صورت نبود lockfile پس از yank شدن یک نسخهٔ مشخص، برای نیازمندی‌های مختلف SemVer استفاده کند، مشخص می‌کند:

نسخهٔ yank‌شده / نیازمندی SemVer bar = "1.5.0" bar = "=1.5.0" bar = "2.0.0"
1.5.0 استفاده از 1.5.1 یا 1.5.2 بازگرداندن خطا استفاده از 2.0.0
1.5.1 استفاده از 1.5.0 یا 1.5.2 استفاده از 1.5.0 استفاده از 2.0.0
2.0.0 استفاده از 1.5.0، 1.5.1 یا 1.5.2 استفاده از 1.5.0 بازگرداندن خطا

کریت‌ها تنها باید در شرایط استثنایی yank شوند؛ به عنوان مثال، انتشار تصادفی، ناسازگاری ناخواستهٔ SemVer، یا معیوب بودن اساسی و غیرقابل استفاده بودن یک کریت. در صورت وجود آسیب‌پذیری‌های امنیتی، RustSec https://rustsec.org معمولاً سازوکاری با اختلال کمتر برای آگاه‌سازی کاربران و تشویق آن‌ها به ارتقا است، و از احتمال ایجاد اختلال عمده در پروژه‌های پایین‌دستی صرف‌نظر از میزان تأثیرپذیری آن‌ها از آسیب‌پذیری مربوطه جلوگیری می‌کند.

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

هنگام رسیدگی به مسائل مربوط به حق نشر (کپی‌رایت)، مجوزها، یا داده‌های شخصی در یک کریت منتشرشده، صرفاً yank کردن آن ممکن است کافی نباشد. در چنین مواردی، با نگه‌دارندگان مخزنی که استفاده کرده‌اید تماس بگیرید. برای crates.io، به خط‌مشی‌های آن‌ها https://crates.io/policies مراجعه کرده و از طریق <help@crates.io> با آن‌ها ارتباط برقرار کنید.

اگر اطلاعات احراز هویت (credentials) افشا شده باشد، اقدام توصیه‌شده ابطال فوری آن‌ها است. هنگامی که یک کریت منتشر شد، تعیین اینکه آیا اطلاعات احراز هویت افشاشده کپی شده‌اند یا خیر غیرممکن است. عمل yank فقط مانع از آن می‌شود که Cargo به‌طور پیش‌فرض این نسخه را هنگام حل وابستگی‌ها انتخاب کند. فایل‌های lock موجود یا دانلودهای مستقیم تحت تأثیر قرار نمی‌گیرند، بنابراین yank کردن نمی‌تواند جلوی انتشار بیشتر اطلاعات احراز هویت افشاشده را بگیرد.

--vers version, --version version

نسخه‌ای که باید yank شود یا از حالت yank خارج شود (un-yank).

--undo

لغو عملیات yank، و بازگرداندن نسخه به نمایه (index).

--token token

توکن API مورد استفاده برای احراز هویت. این گزینه بر توکن ذخیره‌شده در فایل اطلاعات احراز هویت (که توسط cargo-login(1) ایجاد می‌شود) اولویت دارد.

متغیرهای محیطی پیکربندی Cargo https://doc.rust-lang.org/cargo/reference/config.html می‌توانند برای جایگزینی توکن‌های ذخیره‌شده در فایل اعتبارسنجی استفاده شوند. توکن برای crates.io را می‌توان با متغیر محیطی CARGO_REGISTRY_TOKEN تعیین کرد. توکن‌های سایر مخازن را می‌توان با متغیرهای محیطی به قالب CARGO_REGISTRIES_NAME_TOKEN مشخص نمود که در آن NAME نام مخزن با تمام حروف بزرگ است.

--index index

آدرس اینترنتی (URL) نمایهٔ مخزن مورد استفاده.

--registry registry

نام مخزن مورد استفاده. نام‌های مخازن در فایل‌های پیکربندی Cargo https://doc.rust-lang.org/cargo/reference/config.html تعریف می‌شوند. اگر مشخص نشود، مخزن پیش‌فرض استفاده خواهد شد که توسط کلید پیکربندی registry.default تعیین می‌شود و مقدار پیش‌فرض آن crates-io است.

-v, --verbose

استفاده از خروجی پرجزئیات. می‌تواند دو بار برای خروجی “بسیار پرجزئیات” مشخص شود که شامل خروجی‌های اضافی مانند هشدارهای وابستگی و خروجی اسکریپت ساخت است. همچنین می‌تواند با مقدار پیکربندی https://doc.rust-lang.org/cargo/reference/config.html به نام term.verbose تعیین شود.

-q, --quiet

عدم چاپ پیام‌های گزارش cargo. همچنین می‌تواند با مقدار پیکربندی https://doc.rust-lang.org/cargo/reference/config.html به نام term.quiet تعیین شود.

--color when

کنترل زمان استفاده از خروجی رنگی. مقادیر معتبر:
•auto (پیش‌فرض): تشخیص خودکار اینکه آیا پشتیبانی از رنگ در پایانه موجود است یا خیر.
•always: همیشه رنگ‌ها را نمایش بده.
•never: هرگز رنگ‌ها را نمایش نده.

همچنین می‌تواند با مقدار پیکربندی https://doc.rust-lang.org/cargo/reference/config.html به نام term.color تعیین شود.

+toolchain

اگر Cargo با rustup نصب شده باشد و اولین آرگومان cargo با + شروع شود، به عنوان نام زنجیره ابزار (toolchain) در rustup تفسیر می‌شود (مانند +stable یا +nightly). برای اطلاعات بیشتر در مورد نحوهٔ عملکرد بازنویسی‌های زنجیره ابزار، به مستندات rustup https://rust-lang.github.io/rustup/overrides.html مراجعه کنید.

--config KEY=VALUE یا PATH

یک مقدار پیکربندی Cargo را بازنویسی می‌کند. این آرگومان باید در ساختار TOML به صورت KEY=VALUE باشد، یا به عنوان یک مسیر به یک فایل پیکربندی اضافی ارائه شود. این پرچم می‌تواند چندین بار مشخص شود. برای اطلاعات بیشتر به بخش بازنویسی‌های خط فرمان https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides مراجعه کنید.

-C PATH

دایرکتوری کاری فعلی را قبل از اجرای هرگونه عملیات مشخص‌شده تغییر می‌دهد. این امر مواردی از جمله مکانی را که cargo به‌طور پیش‌فرض به دنبال مانیفست پروژه (Cargo.toml) می‌گردد، و همچنین دایرکتوری‌های جستجو شده برای کشف .cargo/config.toml را تحت تأثیر قرار می‌دهد. این گزینه باید قبل از نام دستور بیاید، به عنوان مثال cargo -C path/to/my-project build.

این گزینه فقط در کانال nightly https://doc.rust-lang.org/book/appendix-07-nightly-rust.html در دسترس است و برای فعال‌سازی به پرچم -Z unstable-options نیاز دارد (به #10098 https://github.com/rust-lang/cargo/issues/10098 مراجعه کنید).

-h, --help

اطلاعات راهنما را چاپ می‌کند.

-Z flag

پرچم‌های ناپایدار (فقط nightly) برای Cargo. برای جزئیات، دستور cargo -Z help را اجرا کنید.

برای جزئیات بیشتر دربارهٔ متغیرهای محیطی که Cargo می‌خواند، به مرجع https://doc.rust-lang.org/cargo/reference/environment-variables.html مراجعه کنید.

•0: با موفقیت به پایان رسید.
•101: اجرای Cargo با شکست مواجه شد.

1.حذف یک کریت از نمایه (yank): 
cargo yank foo@1.0.7

cargo(1), cargo-login(1), cargo-publish(1)