GIT-APPLY(1)

Git Manual

GIT-APPLY(1)

نام (NAME)

git-apply - اعمال یک وصله به فایل‌ها و/یا به ایندکس

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

git apply [--stat] [--numstat] [--summary] [--check]
          [--index | --intent-to-add] [--3way] [--ours | --theirs | --union]
          [--apply] [--no-add] [--build-fake-ancestor=<file>] [-R | --reverse]
          [--allow-binary-replacement | --binary] [--reject] [-z]
          [-p<n>] [-C<n>] [--inaccurate-eof] [--recount] [--cached]
          [--ignore-space-change | --ignore-whitespace]
          [--whitespace=(nowarn|warn|fix|error|error-all)]
          [--exclude=<path>] [--include=<path>] [--directory=<root>]
          [--verbose | --quiet] [--unsafe-paths] [--allow-empty] [<patch>...]

توضیحات (DESCRIPTION)

خروجی diff ارائه‌شده (یعنی «یک وصله») را می‌خواند و آن را بر روی فایل‌ها اعمال می‌کند. هنگام اجرا از یک زیردایرکتوری در یک مخزن، مسیرهای وصله‌شده در خارج از دایرکتوری نادیده گرفته می‌شوند. با گزینه --index، وصله به ایندکس نیز اعمال می‌شود، و با گزینه --cached، وصله تنها به ایندکس اعمال می‌گردد. بدون این گزینه‌ها، دستور وصله را فقط روی فایل‌ها اعمال می‌کند و نیازی به قرار داشتن آن‌ها در یک مخزن گیت ندارد.

این دستور وصله را اعمال می‌کند اما کامیت ایجاد نمی‌کند. برای ایجاد کامیت از وصله‌های تولیدشده توسط git-format-patch(1) و/یا دریافت‌شده از طریق ایمیل، از git-am(1) استفاده کنید.

گزینه‌ها (OPTIONS)

<patch>...

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

--stat

به جای اعمال وصله، خروجی diffstat را برای ورودی نمایش می‌دهد. گزینه "apply" را غیرفعال می‌کند.

--numstat

مشابه --stat، اما تعداد خطوط اضافه و حذف‌شده را با نماد ده‌دهی و نام مسیر را بدون اختصار نشان می‌دهد تا برای پردازش ماشینی مناسب‌تر باشد. برای فایل‌های باینری، به جای گفتن 0 0، دو - خروجی می‌دهد. گزینه "apply" را غیرفعال می‌کند.

--summary

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

--check

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

--index

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

--cached

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

-N, --intent-to-add

هنگام اعمال وصله تنها روی درخت کاری، فایل‌های جدید را علامت‌گذاری می‌کند تا بعداً به ایندکس اضافه شوند (گزینه --intent-to-add در git-add(1) را ببینید). در صورت استفاده از --index یا --cached این گزینه نادیده گرفته می‌شود و خارج از یک مخزن گیت هیچ اثری ندارد. توجه داشته باشید که --index می‌تواند به طور ضمنی توسط گزینه‌های دیگر مانند --3way فعال شود.

-3, --3way

اگر وصله هویت blobهایی را که قرار است بر آن‌ها اعمال شود ثبت کرده باشد و ما آن blobها را به صورت محلی در اختیار داشته باشیم، تلاش برای ادغام ۳-طرفه می‌کند و احتمالاً نشانگرهای تعارض را در فایل‌های درخت کاری باقی می‌گذارد تا کاربر آن‌ها را حل کند. این گزینه مستلزم گزینه --index است مگر اینکه از گزینه --cached استفاده شود، و با گزینه --reject ناسازگار است. در صورت استفاده همراه با گزینه --cached، هرگونه تعارض در مراحل بالاتر (higher stages) در کش رها می‌شود.

--ours, --theirs, --union

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

--build-fake-ancestor=<file>

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

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

-R, --reverse

اعمال وصله به صورت معکوس.

--reject

به منظور اتمیک بودن، git apply به طور پیش‌فرض در صورتی که برخی از قطعات (hunks) اعمال نشوند، کل وصله را ناموفق کرده و درخت کاری را دست‌نخورده باقی می‌گذارد. این گزینه بخش‌هایی از وصله را که قابل اعمال هستند اعمال می‌کند و قطعات ردشده را در فایل‌های متناظر *.rej رها می‌سازد.

-z

هنگامی که --numstat مشخص شده باشد، نام مسیرها را تغییر نمی‌دهد، بلکه از یک قالب خوانا برای ماشین که با کاراکتر NUL خاتمه می‌یابد استفاده می‌کند.

بدون این گزینه، نام مسیرهایی با کاراکترهای "غیرعادی" همان‌طور که برای متغیر پیکربندی core.quotePath توضیح داده شده است نقل‌قول می‌شوند (نگاه کنید به git-config(1)).

-p<n>

حذف <n> بخش ابتدایی مسیر (که با اسلش جدا شده‌اند) از مسیرهای سنتی diff. به عنوان مثال با -p2، وصله‌ای که بر روی a/dir/file است مستقیماً بر روی file اعمال خواهد شد. مقدار پیش‌فرض ۱ است.

-C<n>

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

--unidiff-zero

به طور پیش‌فرض، git apply انتظار دارد وصله‌ای که اعمال می‌شود یک diff یکپارچه (unified diff) با حداقل یک خط بافت باشد. این یک اقدام ایمنی مناسب فراهم می‌کند، اما هنگام اعمال یک diff تولیدشده با --unified=0 دچار مشکل می‌شود. برای دور زدن این بررسی‌ها از --unidiff-zero استفاده کنید.

توجه داشته باشید به دلایلی که در بالا ذکر شد، استفاده از وصله‌های بدون بافت توصیه نمی‌شود.

--apply

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

--no-add

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

--allow-binary-replacement, --binary

از لحاظ تاریخی ما اعمال وصله‌های باینری را بدون اجازه صریح از طرف کاربر مجاز نمی‌دانستیم، و این پرچم روشی برای صدور این اجازه بود. در حال حاضر، ما همیشه اعمال وصله‌های باینری را مجاز می‌دانیم، بنابراین این گزینه بی‌اثر (no-op) است.

--exclude=<path-pattern>

تغییرات را روی فایل‌های منطبق با <path-pattern> اعمال نکنید. این گزینه می‌تواند هنگام ایمپورت مجموعه‌های وصله (patchsets) که در آن‌ها می‌خواهید فایل‌ها یا دایرکتوری‌های خاصی را مستثنی کنید مفید باشد.

--include=<path-pattern>

تغییرات را روی فایل‌های منطبق با <path-pattern> اعمال کنید. این گزینه می‌تواند هنگام وارد کردن مجموعه‌های وصله، جایی که می‌خواهید فایل‌ها یا دایرکتوری‌های خاصی را بگنجانید مفید باشد.

هنگامی که الگوهای --exclude و --include استفاده می‌شوند، آن‌ها به ترتیبی که در خط فرمان ظاهر می‌شوند بررسی می‌گردند و اولین تطابق تعیین می‌کند که آیا وصله بر روی هر مسیر اعمال شود یا خیر. وصله برای مسیری که با هیچ الگوی شمول/عدم شمولی مطابقت ندارد، در صورتی که هیچ الگوی شمول (include) در خط فرمان نباشد به طور پیش‌فرض اعمال می‌شود، و اگر الگوی شمول وجود داشته باشد نادیده گرفته خواهد شد.

--ignore-space-change, --ignore-whitespace

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

--whitespace=<action>

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

به طور پیش‌فرض، این دستور پیام‌های هشدار را چاپ می‌کند اما وصله را اعمال می‌نماید. هنگامی که git-apply برای آمارگیری و نه برای اعمال وصله استفاده شود، پیش‌فرض آن nowarn است.

می‌توانید از مقادیر مختلف <action> برای کنترل این رفتار استفاده کنید:

•nowarn هشدار فاصله‌های خالی انتهایی را غیرفعال می‌کند.

•warn برای چند نمونه از این خطاها هشدار چاپ می‌کند، اما وصله را همان‌طور که هست اعمال می‌نماید (پیش‌فرض).

•fix برای چند نمونه از این خطاها هشدار چاپ می‌کند و وصله را پس از اصلاح آن‌ها اعمال می‌نماید (strip یک نام مترادف است — در گذشته این ابزار فقط کاراکترهای فاصله سفید انتهایی را به عنوان خطا در نظر می‌گرفت و اصلاح شامل حذف آن‌ها بود، اما گیت امروزی کارهای بیشتری انجام می‌دهد).

•error برای چند نمونه از این خطاها هشدار چاپ می‌کند و از اعمال وصله خودداری می‌ورزد.

•error-all مشابه error است اما تمامی خطاها را نمایش می‌دهد.

--inaccurate-eof

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

-v, --verbose

گزارش روند پیشرفت به stderr. به طور پیش‌فرض، فقط پیامی درباره وصله فعلی در حال اعمال چاپ می‌شود. این گزینه باعث گزارش اطلاعات اضافی خواهد شد.

-q, --quiet

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

--recount

به شمارش خطوط در سرآیندهای قطعات (hunk headers) اعتماد نکنید، بلکه آن‌ها را با بازرسی وصله استنباط کنید (مثلاً پس از ویرایش وصله بدون تنظیم مناسب سرآیندهای قطعات).

--directory=<root>

پیشوند دادن <root> به تمام نام‌های فایل. اگر آرگومان -p نیز ارسال شده باشد، قبل از پیشوند کردن ریشه جدید اعمال می‌شود.

به عنوان مثال، وصله‌ای که درباره به‌روزرسانی a/git-gui.sh به b/git-gui.sh صحبت می‌کند، می‌تواند با اجرای git apply --directory=modules/git-gui بر روی فایل موجود در درخت کاری modules/git-gui/git-gui.sh اعمال شود.

--unsafe-paths

به طور پیش‌فرض، وصله‌ای که خارج از محدوده کاری را تحت تأثیر قرار دهد (چه یک درخت کاری تحت کنترل گیت، یا دایرکتوری کاری فعلی هنگامی که git apply به عنوان جایگزینی برای GNU patch استفاده می‌شود) به عنوان یک اشتباه (یا اقدام مخرب) رد می‌شود.

هنگامی که git apply به عنوان یک "GNU patch بهتر" استفاده می‌شود، کاربر می‌تواند گزینه --unsafe-paths را برای لغو این بررسی ایمنی ارسال کند. این گزینه هنگامی که --index یا --cached در حال استفاده باشد هیچ اثری ندارد.

--allow-empty

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

پیکربندی (CONFIGURATION)

تمام موارد زیر این خط در این بخش به طور گزینشی از مستندات git-config(1) گنجانده شده است. محتوا همان چیزی است که در آنجا یافت می‌شود:

apply.ignoreWhitespace

هنگامی که روی change تنظیم شود، به git apply می‌گوید که تغییرات در فاصله‌های خالی را نادیده بگیرد، همانند گزینه --ignore-space-change. هنگامی که روی یکی از مقادیر: no، none، never، false تنظیم شود، به git apply می‌گوید که به تمامی تفاوت‌های فاصله خالی احترام بگذارد.

apply.whitespace

به git apply می‌گوید چگونه با فاصله‌های خالی رفتار کند، همانند گزینه --whitespace.

زیرماژول‌ها (SUBMODULES)

اگر وصله شامل هرگونه تغییری در زیرماژول‌ها باشد، آن‌گاه git apply با این تغییرات به شرح زیر رفتار می‌کند.

اگر --index مشخص شده باشد (به صورت صریح یا ضمنی)، کامیت‌های زیرماژول باید دقیقاً با ایندکس مطابقت داشته باشند تا وصله اعمال شود. اگر هر یک از زیرماژول‌ها چک‌اوت (checked-out) شده باشند، این چک‌اوت‌ها کاملاً نادیده گرفته می‌شوند، یعنی نیازی نیست که آن‌ها به‌روز یا تمیز باشند و به‌روزرسانی نیز نمی‌شوند.

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

همچنین ببینید (SEE ALSO)

git-am(1).

گیت (GIT)

بخشی از مجموعه git(1)

2026-06-29

Git 2.55.0