GIT-MERGETOOL(1) راهنمای Git GIT-MERGETOOL(1)

git-mergetool - اجرای ابزارهای حل تعارض برای برطرف کردن تعارضات ادغام

git mergetool [--tool=<tool>] [-y | --[no-]prompt] [<file>...]

از git mergetool برای اجرای یکی از چند ابزار کمکی ادغام جهت حل تعارضات ادغام استفاده کنید. این دستور معمولاً پس از git merge اجرا می‌شود.

اگر یک یا چند پارامتر <file> مشخص شده باشد، برنامه ابزار ادغام برای حل اختلافات در هر فایل اجرا خواهد شد (فایل‌های بدون تعارض نادیده گرفته می‌شوند). مشخص کردن یک دایرکتوری، تمامی فایل‌های حل‌نشده در آن مسیر را در بر خواهد گرفت. اگر هیچ نام <file> مشخص نشده باشد، git mergetool برنامه ابزار ادغام را روی هر فایلی که دارای تعارض ادغام است اجرا می‌کند.

-t <tool>, --tool=<tool>

از برنامه حل ادغام مشخص‌شده توسط <tool> استفاده می‌کند. مقادیر معتبر شامل emerge، gvimdiff، kdiff3، meld، vimdiff و tortoisemerge هستند. دستور git mergetool --tool-help را برای مشاهده فهرست تنظیمات معتبر <tool> اجرا کنید.

اگر برنامه حل ادغام مشخص نشده باشد، git mergetool از متغیر پیکربندی merge.tool استفاده خواهد کرد. اگر متغیر پیکربندی merge.tool تنظیم نشده باشد، git mergetool یک پیش‌فرض مناسب را انتخاب خواهد کرد.

می‌توانید با تنظیم متغیر پیکربندی mergetool.<tool>.path به‌طور صریح مسیر کامل ابزار را مشخص کنید. برای نمونه، می‌توانید مسیر مطلق kdiff3 را با تنظیم mergetool.kdiff3.path پیکربندی کنید. در غیر این صورت، git mergetool فرض می‌کند که ابزار در $PATH در دسترس است.

به جای اجرای یکی از برنامه‌های ابزار ادغام شناخته‌شده، git mergetool می‌تواند با تعیین خط فرمانی که باید فراخوانی شود در متغیر پیکربندی mergetool.<tool>.cmd شخصی‌سازی شود تا یک برنامه جایگزین را اجرا کند.

هنگامی که git mergetool با این ابزار فراخوانی می‌شود (چه از طریق گزینه -t یا --tool و چه از طریق متغیر پیکربندی merge.tool)، خط فرمان پیکربندی‌شده فراخوانی می‌شود در حالی که BASE روی نام یک فایل موقت حاوی پایه مشترک برای ادغام (در صورت وجود) تنظیم شده است؛ LOCAL روی نام یک فایل موقت حاوی محتویات فایل روی شاخه جاری تنظیم شده است؛ REMOTE روی نام یک فایل موقت حاوی محتویات فایلِ در حال ادغام تنظیم شده است، و MERGED روی نام فایلی تنظیم شده است که ابزار ادغام باید نتیجه حل تعارض ادغام را در آن بنویسد.

اگر ابزار ادغام سفارشی با کد خروج خود موفقیت حل ادغام را به درستی نشان دهد، متغیر پیکربندی mergetool.<tool>.trustExitCode می‌تواند روی true تنظیم شود. در غیر این صورت، git mergetool پس از خروج ابزار سفارشی، از کاربر درخواست می‌کند تا موفقیت حل تعارض را مشخص کند.

--tool-help

چاپ فهرستی از ابزارهای ادغام که می‌توان همراه با --tool استفاده کرد.

-y, --no-prompt

پیش از هر بار فراخوانی برنامه حل ادغام، درخواستی برای تأیید نمایش ندهد. اگر برنامه حل ادغام به‌طور صریح با گزینه --tool یا با متغیر پیکربندی merge.tool مشخص شده باشد، این رفتار پیش‌فرض است.

--prompt

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

-g, --gui

هنگامی که git-mergetool با گزینه -g یا --gui فراخوانی می‌شود، ابزار ادغام پیش‌فرض از متغیر پیکربندی‌شده merge.guitool به جای merge.tool خوانده خواهد شد. اگر merge.guitool تنظیم نشده باشد، به ابزار پیکربندی‌شده تحت merge.tool رجوع می‌شود. این مورد ممکن است به‌طور خودکار با استفاده از متغیر پیکربندی mergetool.guiDefault انتخاب شود.

--no-gui

این گزینه تنظیمات قبلی -g یا --gui یا پیکربندی mergetool.guiDefault را نادیده گرفته و ابزار ادغام پیش‌فرض را از متغیر پیکربندی‌شده merge.tool می‌خواند.

-O<orderfile>

پردازش فایل‌ها به ترتیبی که در <orderfile> مشخص شده است، که در هر خط آن یک الگوی تطابق شل (glob) قرار دارد. این گزینه متغیر پیکربندی diff.orderFile را بازنویسی می‌کند (به git-config(1) مراجعه کنید). برای لغو diff.orderFile، از -O/dev/null استفاده کنید.

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

mergetool.<tool>.path

مسیر ابزار داده‌شده را بازنویسی می‌کند. این مورد در صورتی که ابزار شما در $PATH قرار ندارد مفید است.

mergetool.<tool>.cmd

دستور فراخوانی ابزار ادغام مشخص‌شده را تعیین می‌کند. دستور مشخص‌شده در شل با متغیرهای زیر که در دسترس هستند ارزیابی می‌شود: BASE نام یک فایل موقت حاوی پایه مشترک فایل‌های در حال ادغام (در صورت وجود) است؛ LOCAL نام یک فایل موقت حاوی محتویات فایل روی شاخه جاری است؛ REMOTE نام یک فایل موقت حاوی محتویات فایل از شاخه در حال ادغام است؛ MERGED شامل نام فایلی است که ابزار ادغام باید نتایج یک ادغام موفق را در آن بنویسد.

mergetool.<tool>.hideResolved

به کاربر امکان می‌دهد مقدار سراسری mergetool.hideResolved را برای یک ابزار خاص بازنویسی کند. برای توضیحات کامل به mergetool.hideResolved مراجعه کنید.

mergetool.<tool>.trustExitCode

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

mergetool.meld.hasOutput

نسخه‌های قدیمی‌تر meld از گزینه --output پشتیبانی نمی‌کنند. گیت با بررسی خروجی meld --help تلاش می‌کند تشخیص دهد که آیا meld از --output پشتیبانی می‌کند یا خیر. پیکربندی mergetool.meld.hasOutput باعث می‌شود گیت این بررسی‌ها را نادیده بگیرد و به جای آن از مقدار پیکربندی‌شده استفاده کند. تنظیم mergetool.meld.hasOutput روی true به گیت می‌گوید که بدون قید و شرط از گزینه --output استفاده کند، و مقدار false از استفاده از --output خودداری می‌کند.

mergetool.meld.useAutoMerge

هنگامی که گزینه --auto-merge داده شود، meld تمام بخش‌های بدون تعارض را به‌طور خودکار ادغام می‌کند، بخش‌های دارای تعارض را برجسته می‌سازد و منتظر تصمیم کاربر می‌ماند. تنظیم mergetool.meld.useAutoMerge روی true به گیت می‌گوید که بدون قید و شرط از گزینه --auto-merge همراه با meld استفاده کند. تنظیم این مقدار روی auto باعث می‌شود گیت بررسی کند که آیا --auto-merge پشتیبانی می‌شود یا خیر و تنها در صورت در دسترس بودن از --auto-merge استفاده کند. مقدار false به‌طور کلی از استفاده از --auto-merge خودداری می‌کند و مقدار پیش‌فرض است.

mergetool.<variant>.layout

چیدمان پنجره‌های تقسیم‌شده را برای <variant> ابزار vimdiff پیکربندی می‌کند، که می‌تواند هر یک از vimdiff، nvimdiff یا gvimdiff باشد. هنگام اجرای git mergetool با --tool=<variant> (یا بدون --tool اگر merge.tool به عنوان <variant> پیکربندی شده باشد)، گیت به mergetool.<variant>.layout مراجعه می‌کند تا چیدمان ابزار را تعیین کند. اگر پیکربندی ویژه نسخه در دسترس نباشد، تنظیمات vimdiff به عنوان جایگزین استفاده می‌شود. اگر آن هم در دسترس نباشد، یک چیدمان پیش‌فرض با ۴ پنجره استفاده خواهد شد. برای پیکربندی چیدمان، به بخش BACKEND SPECIFIC HINTS مراجعه کنید.

mergetool.hideResolved

در طول ادغام، گیت به‌طور خودکار تا حد امکان تعارضات را حل کرده و فایل $MERGED را شامل نشانگرهای تعارض در اطراف هر تعارضی که نتوانسته حل کند می‌نویسد؛ $LOCAL و $REMOTE به‌طور معمول نسخه‌های فایل از قبل از حل تعارض گیت هستند. این پرچم باعث می‌شود $LOCAL و $REMOTE بازنویسی شوند به‌گونه‌ای که فقط تعارضات حل‌نشده به ابزار ادغام ارائه گردند. می‌تواند برای هر ابزار از طریق متغیر پیکربندی mergetool.<tool>.hideResolved پیکربندی شود. مقدار پیش‌فرض false است.

mergetool.keepBackup

پس از انجام یک ادغام، فایل اصلی دارای نشانگرهای تعارض را می‌توان با پسوند .orig ذخیره کرد. اگر این متغیر روی false تنظیم شود، این فایل نگهداری نمی‌شود. مقدار پیش‌فرض true است (یعنی فایل‌های پشتیبان نگه‌داشته می‌شوند).

mergetool.keepTemporaries

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

mergetool.writeToTemp

گیت به‌طور پیش‌فرض نسخه‌های موقت BASE، LOCAL و REMOTE فایل‌های دارای تعارض را در درخت کاری می‌نویسد. هنگامی که این متغیر روی true تنظیم شود، گیت تلاش خواهد کرد تا از یک دایرکتوری موقت برای این فایل‌ها استفاده کند. مقدار پیش‌فرض false است.

mergetool.prompt

پیش از هر بار فراخوانی برنامه حل ادغام درخواست تأیید نمایش دهد.

mergetool.guiDefault

مقدار true را تنظیم کنید تا به‌طور پیش‌فرض از merge.guitool استفاده شود (معادل مشخص کردن آرگومان --gui)، یا auto را برای انتخاب merge.guitool یا merge.tool بسته به وجود مقدار در متغیر محیطی DISPLAY تنظیم کنید. مقدار پیش‌فرض false است، که در آن آرگومان --gui باید به‌طور صریح ارائه شود تا merge.guitool مورد استفاده قرار گیرد.

دستور git mergetool هنگام حل تعارض‌های ادغام، فایل‌های پشتیبان *.orig ایجاد می‌کند. پس از ادغام موفق یک فایل و پایان یافتن نشست git mergetool آن، حذف این فایل‌ها بی‌خطر است.

تنظیم متغیر پیکربندی mergetool.keepBackup روی false باعث می‌شود git mergetool هم‌زمان با ادغام موفق فایل‌ها، فایل‌های پشتیبان را به‌طور خودکار حذف کند.

توضیحات

هنگام مشخص کردن --tool=vimdiff در git mergetool، گیت ابزار Vim را با چیدمان ۴ پنجره که به روش زیر توزیع شده است باز می‌کند:

---------------------------------------------
|             |           |              |
|   LOCAL     |   BASE    |   REMOTE     |
|             |           |              |
---------------------------------------------
|                                        |
|                MERGED                  |
|                                        |
---------------------------------------------

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

MERGED یک بافر قابل‌نوشتن است که در آن باید تعارضات را برطرف کنید (با استفاده از سایر بافرهای فقط‌خواندنی به عنوان مرجع). پس از پایان کار، مانند معمول ذخیره کرده و از Vim خارج شوید (:wq) یا اگر می‌خواهید عملیات را لغو کنید، با استفاده از :cq خارج شوید.

پیکربندی چیدمان

می‌توانید چیدمان پنجره‌های مورد استفاده توسط Vim را با تنظیم متغیر پیکربندی mergetool.vimdiff.layout تغییر دهید که رشته‌ای را می‌پذیرد که در آن جداکننده‌های زیر دارای معنای ویژه‌ای هستند:

•+ برای «باز کردن یک برگه جدید» استفاده می‌شود
•, برای «ایجاد یک تقسیم عمودی جدید» استفاده می‌شود
•/ برای «ایجاد یک تقسیم افقی جدید» استفاده می‌شود
•@ برای مشخص کردن فایلی که حاوی نسخه نهایی پس از حل تعارضات است استفاده می‌شود. اگر وجود نداشته باشد، به‌طور پیش‌فرض از MERGED استفاده خواهد شد.

اولویت عملگرها به صورت زیر است (می‌توانید از پرانتز برای تغییر آن استفاده کنید):

`@` > `+` > `/` > `,`

اجازه دهید برای درک نحوه عملکرد، چند مثال را بررسی کنیم:

•layout = "(LOCAL,BASE,REMOTE)/MERGED"

این دقیقاً همان چیدمان پیش‌فرضی است که قبلاً دیده‌ایم.

توجه داشته باشید که / بر , تقدم دارد و بنابراین در این مورد پرانتزها لازم نیستند. تعریف چیدمان بعدی معادل است:

layout = "LOCAL,BASE,REMOTE / MERGED"
•layout = "LOCAL,MERGED,REMOTE"

اگر بنا به دلایلی علاقه‌ای به بافر BASE نداشته باشیم.

---------------------------------------------
|             |           |              |
|             |           |              |
|   LOCAL     |   MERGED  |   REMOTE     |
|             |           |              |
|             |           |              |
---------------------------------------------
•layout = "MERGED"

فقط بافر MERGED نمایش داده خواهد شد. با این حال توجه داشته باشید که تمام بافرهای دیگر همچنان در vim بارگذاری شده‌اند و می‌توانید با دستور «buffers» به آن‌ها دسترسی داشته باشید.

---------------------------------------------
|                                        |
|                                        |
|                 MERGED                 |
|                                        |
|                                        |
---------------------------------------------
•layout = "@LOCAL,REMOTE"

هنگامی که MERGED در چیدمان وجود ندارد، باید یکی از بافرها را با علامت ات‌ساین (@) «نشانه‌گذاری» کنید. آن بافر به بافری تبدیل می‌شود که باید پس از حل تعارضات آن را ویرایش کرده و ذخیره نمایید.

---------------------------------------------
|                   |                    |
|                   |                    |
|                   |                    |
|     LOCAL         |    REMOTE          |
|                   |                    |
|                   |                    |
|                   |                    |
---------------------------------------------
•layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE"

سه برگه باز خواهد شد: اولین برگه یک نسخه از چیدمان پیش‌فرض است، در حالی که دو برگه دیگر به‌ترتیب فقط تفاوت‌های میان (BASE و LOCAL) و (BASE و REMOTE) را نشان می‌دهند.

---------------------------------------------
| <TAB #1> |  TAB #2  |  TAB #3  |       |
---------------------------------------------
|             |           |              |
|   LOCAL     |   BASE    |   REMOTE     |
|             |           |              |
---------------------------------------------
|                                        |
|                MERGED                  |
|                                        |
---------------------------------------------
---------------------------------------------
|  TAB #1  | <TAB #2> |  TAB #3  |       |
---------------------------------------------
|                   |                    |
|                   |                    |
|                   |                    |
|     BASE          |    LOCAL           |
|                   |                    |
|                   |                    |
|                   |                    |
---------------------------------------------
---------------------------------------------
|  TAB #1  |  TAB #2  | <TAB #3> |       |
---------------------------------------------
|                   |                    |
|                   |                    |
|                   |                    |
|     BASE          |    REMOTE          |
|                   |                    |
|                   |                    |
|                   |                    |
---------------------------------------------
•layout = "LOCAL,BASE,REMOTE / MERGED + BASE,LOCAL + BASE,REMOTE + (LOCAL/BASE/REMOTE),MERGED"

مشابه مثال قبل، اما یک برگه چهارم با همان اطلاعات برگه اول و با چیدمانی متفاوت اضافه می‌کند.

-------------------------------------------------
|  TAB #1  |  TAB #2  |  TAB #3  | <TAB #4> |
-------------------------------------------------
|       LOCAL         |                     |
|---------------------|                     |
|       BASE          |        MERGED       |
|---------------------|                     |
|       REMOTE        |                     |
-------------------------------------------------

توجه داشته باشید که در تعریف برگه نهایی چگونه باید از پرانتز استفاده کنیم تا , بر / تقدم پیدا کند.

گونه‌ها (Variants)

به جای --tool=vimdiff، می‌توانید از یکی از این گونه‌های دیگر نیز استفاده کنید:

•--tool=gvimdiff، برای باز کردن gVim به جای Vim.
•--tool=nvimdiff، برای باز کردن Neovim به جای Vim.

هنگام استفاده از این گونه‌ها، برای تعیین یک چیدمان سفارشی باید متغیرهای پیکربندی mergetool.gvimdiff.layout و mergetool.nvimdiff.layout را به جای mergetool.vimdiff.layout تنظیم کنید (اگرچه در صورت تنظیم نشدن متغیر ویژه آن گونه، متغیر دوم به عنوان جایگزین استفاده خواهد شد).

علاوه بر این، برای سازگاری با نسخه‌های قبلی گیت، می‌توانید 1، 2 یا 3 را به vimdiff یا هر یک از گونه‌ها اضافه کنید (مثلاً: vimdiff3، nvimdiff1 و غیره) تا از یک چیدمان از پیش تعریف‌شده استفاده نمایید. به عبارت دیگر، استفاده از --tool=[g|n]vimdiff<x> معادل است با استفاده از --tool=[g|n]vimdiff و تنظیم متغیر پیکربندی mergetool.[g|n]vimdiff.layout روی...

•<x>=1: "@LOCAL, REMOTE"
•<x>=2: "LOCAL, MERGED, REMOTE"
•<x>=3: "MERGED"

مثال: استفاده از --tool=gvimdiff2 برنامه gvim را با سه ستون (LOCAL، MERGED و REMOTE) باز می‌کند.

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

2026-06-29 Git 2.55.0