'\" t
.\"     Title: git-range-diff
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 2026-06-29
.\"    Manual: Git Manual
.\"    Source: Git 2.55.0
.\"  Language: Persian
.\"
.TH "GIT\-RANGE\-DIFF" "1" "2026\-06\-29" "Git 2\&.55\&.0" "Git Manual"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "نام (NAME)"
git-range-diff \- مقایسه دو بازه کامیت (مثلاً دو نسخه از یک شاخه)
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fBgit\fR \fBrange\-diff\fR [\fB\-\-color=\fR[\fI<when>\fR]] [\fB\-\-no\-color\fR] [\fI<diff\-options>\fR]
        [\fB\-\-no\-dual\-color\fR] [\fB\-\-creation\-factor=\fR\fI<factor>\fR]
        [\fB\-\-left\-only\fR | \fB\-\-right\-only\fR] [\fB\-\-diff\-merges=\fR\fI<format>\fR]
        [\fB\-\-remerge\-diff\fR] [\fB\-\-no\-notes\fR | \fB\-\-notes\fR[\fB=\fR\fI<ref>\fR]]
        ( \fI<range1>\fR \fI<range2>\fR | \fI<rev1>\fR\fB\&...\fR\fI<rev2>\fR | \fI<base>\fR \fI<rev1>\fR \fI<rev2>\fR )
        [[\fB\-\-\fR] \fI<path>\fR\&...]
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
این دستور تفاوت‌های میان دو نسخه از یک مجموعه پچ (patch series)، یا به طور کلی‌تر، دو بازه کامیت را (با نادیده گرفتن کامیت‌های ادغام یا merge) نمایش می‌دهد\&.
.sp
در صورت ارائه آرگومان‌های \fI<path>\fR، این بازه‌های کامیت متناسب با آن‌ها محدود می‌شوند\&.
.sp
برای این منظور، ابتدا جفت کامیت‌هایی را از هر دو بازه کامیت پیدا می‌کند که متناظر با یکدیگرند\&. دو کامیت زمانی متناظر در نظر گرفته می‌شوند که diff میان پچ‌های آن‌ها (یعنی اطلاعات نویسنده، پیام کامیت و diff کامیت) در مقایسه با اندازه پچ‌ها به اندازه کافی کوچک باشد\&. برای جزئیات به بخش \fIالگوریتم (Algorithm)\fR در ادامه مراجعه کنید\&.
.sp
در نهایت، فهرست کامیت‌های منطبق به ترتیب بازه کامیت دوم نشان داده می‌شود، در حالی که کامیت‌های نامنطبق درست پس از نمایش همه نیاکان (ancestors) خود درج می‌گردند\&.
.sp
سه روش برای تعیین بازه‌های کامیت وجود دارد:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI<range1>\fR
\fI<range2>\fR: هر یک از بازه‌های کامیت می‌تواند به شکل
\fI<base>\fR\fB\&.\&.\fR\fI<rev>\fR،
\fI<rev>\fR\fB^\fR! یا
\fI<rev>\fR\fB^\-\fR\fI<n>\fR باشد\&. برای جزئیات بیشتر به بخش
\fISPECIFYING RANGES\fR
در
\fBgitrevisions\fR(7)
مراجعه کنید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI<rev1>\fR\fB\&.\&.\&.\fR\fI<rev2>\fR\&. این معادل است با
\fI<rev2>\fR\fB\&.\&.\fR\fI<rev1>\fR
\fI<rev1>\fR\fB\&.\&.\fR\fI<rev2>\fR\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fI<base>\fR
\fI<rev1>\fR
\fI<rev2>\fR: این معادل است با
\fI<base>\fR\fB\&.\&.\fR\fI<rev1>\fR
\fI<base>\fR\fB\&.\&.\fR\fI<rev2>\fR\&.
.RE
.SH "گزینه‌ها (OPTIONS)"
.PP
\fB\-\-no\-dual\-color\fR
.RS 4
هنگامی که diffهای کامیت متفاوت باشند، دستور \(oqgit range\-diff` رنگ‌بندی diffهای اصلی را بازسازی کرده و نشانگرهای diff بیرونی \-/+ را با
\fBپس‌زمینه (background)\fR
قرمز/سبز اضافه می‌کند تا مثلاً دیدن تغییر دقیق خطوط اضافه‌شده آسان‌تر شود\&.
.sp
علاوه بر این، خطوط diff کامیت که فقط در اولین بازه کامیت وجود دارند به صورت «کم‌رنگ» (dimmed) نشان داده می‌شوند (این رفتار را می‌توان با استفاده از تنظیم پیکربندی
\fBcolor\&.diff\&.\fR\fI<slot>\fR
تغییر داد که در آن
\fI<slot>\fR
یکی از مقادیر
\fBcontextDimmed\fR،
\fBoldDimmed\fR
و
\fBnewDimmed\fR
است)، و خطوط diff کامیت که فقط در بازه کامیت دوم حضور دارند به صورت پررنگ (bold) نمایش می‌یابند (که با تنظیمات پیکربندی
\fBcolor\&.diff\&.\fR\fI<slot>\fR
با
\fI<slot>\fR
برابر با یکی از
\fBcontextBold\fR،
\fBoldBold\fR
یا
\fBnewBold\fR
قابل سفارشی‌سازی است)\&.
.sp
این قابلیت در
\fBrange\-diff\fR
به عنوان «رنگ‌آمیزی دوگانه» (dual coloring) شناخته می‌شود\&. از
\fB\-\-no\-dual\-color\fR
استفاده کنید تا رنگ‌آمیزی تمام خطوط بر اساس نشانگرهای diff بیرونی انجام شود (و diff درونی از نظر رنگ کاملاً نادیده گرفته شود)\&.
.RE
.PP
\fB\-\-creation\-factor=\fR\fI<percent>\fR
.RS 4
ضریب تعدیل (fudge factor) هزینه ایجاد/حذف را روی
\fI<percent>\fR
تنظیم می‌کند\&. مقدار پیش‌فرض ۶۰ است\&. اگر
\fBgit\fR
\fBrange\-diff\fR
به اشتباه یک تغییر بزرگ را بازنویسی کامل تلقی کند (حذف یک کامیت و افزودن کامیتی دیگر)، مقدار بزرگ‌تری را امتحان کنید، و در حالت برعکس مقدار کوچک‌تری را قرار دهید\&. برای توضیح علت نیاز به این ضریب، بخش
\fIالگوریتم (Algorithm)\fR
در ادامه را ببینید\&.
.RE
.PP
\fB\-\-left\-only\fR
.RS 4
کامیت‌هایی را که در اولین بازه مشخص‌شده غایب هستند (یا «بازه چپ» هنگام استفاده از فرم
\fI<rev1>\fR\fB\&.\&.\&.\fR\fI<rev2>\fR)
پنهان می‌کند\&.
.RE
.PP
\fB\-\-right\-only\fR
.RS 4
کامیت‌هایی را که در دومین بازه مشخص‌شده غایب هستند (یا «بازه راست» هنگام استفاده از فرم
\fI<rev1>\fR\fB\&.\&.\&.\fR\fI<rev2>\fR)
پنهان می‌کند\&.
.RE
.PP
\fB\-\-diff\-merges=\fR\fI<format>\fR
.RS 4
به جای نادیده گرفتن کامیت‌های ادغام (merge commits)، با استفاده از گزینه متناظر
\fB\-\-diff\-merges=\fR\fI<format>\fR
در
\fBgit-log\fR(1)
برای آن‌ها diff تولید کرده و آن‌ها را در مقایسه لحاظ می‌کند\&.
.sp
نکته: در حالت معمول، حالت
\fBremerge\fR
طبیعی‌ترین حالت برای استفاده خواهد بود، زیرا فقط diff را روی خروجی حاصل از مکانیزم ادغام گیت نشان می‌دهد\&. به عبارت دیگر، اگر یک کامیت ادغام نتیجه یک
\fBgit\fR
\fBmerge\fR
بدون تداخل باشد، حالت
\fBremerge\fR
آن را با یک diff خالی نمایش خواهد داد\&.
.RE
.PP
\fB\-\-remerge\-diff\fR
.RS 4
گزینه میان‌بر و راحت، معادل
\fB\-\-diff\-merges=remerge\fR\&.
.RE
.PP
\fB\-\-notes\fR[\fB=\fR\fI<ref>\fR], \fB\-\-no\-notes\fR
.RS 4
این فلگ به برنامه
\fBgit\fR
\fBlog\fR
(به
\fBgit-log\fR(1)
مراجعه کنید) که پچ‌ها را تولید می‌کند ارسال می‌شود\&.
.RE
.PP
\fI<range1>\fR \fI<range2>\fR
.RS 4
کامیت‌های مشخص‌شده توسط دو بازه را مقایسه می‌کند، که در آن
\fI<range1>\fR
به عنوان نسخه قدیمی‌ترِ
\fI<range2>\fR
در نظر گرفته می‌شود\&.
.RE
.PP
\fI<rev1>\fR\fB\&.\&.\&.\fR\fI<rev2>\fR
.RS 4
معادل ارسال
\fI<rev2>\fR\fB\&.\&.\fR\fI<rev1>\fR
و
\fI<rev1>\fR\fB\&.\&.\fR\fI<rev2>\fR\&.
.RE
.PP
\fI<base>\fR \fI<rev1>\fR \fI<rev2>\fR
.RS 4
معادل ارسال
\fI<base>\fR\fB\&.\&.\fR\fI<rev1>\fR
و
\fI<base>\fR\fB\&.\&.\fR\fI<rev2>\fR\&. توجه داشته باشید که
\fI<base>\fR
نیازی نیست نقطه انشعاب دقیق شاخه‌ها باشد\&. مثال: پس از ری‌بیس شاخه
\fBmy\-topic\fR،
دستور
\fBgit\fR
\fBrange\-diff\fR
\fBmy\-topic@\fR{u}
\fBmy\-topic@\fR{1}
\fBmy\-topic\fR
تفاوت‌های ایجادشده توسط ری‌بیس را نشان می‌دهد\&.
.RE
.sp
دستور \fBgit\fR \fBrange\-diff\fR همچنین گزینه‌های معمولی diff را می‌پذیرد (به \fBgit-diff\fR(1) مراجعه کنید)، به‌ویژه گزینه‌های \fB\-\-color\fR[\fB=\fR\fI<when>\fR] و \fB\-\-no\-color\fR\&. این گزینه‌ها هنگام تولید «diff میان پچ‌ها» استفاده می‌شوند، یعنی برای مقایسه نویسنده، پیام کامیت و diff کامیت‌های متناظر قدیم/جدید\&. در حال حاضر روشی برای دستکاری بیشتر گزینه‌های diff ارسال‌شده به \fBgit\fR \fBlog\fR هنگام تولید این پچ‌ها وجود ندارد\&.
.SH "پایداری خروجی (OUTPUT STABILITY)"
.sp
خروجی دستور \fBrange\-diff\fR ممکن است تغییر کند\&. این خروجی برای خوانایی توسط انسان طراحی شده است (خروجی پرسلین یا porcelain)، نه چیزی که بتوان در نسخه‌های مختلف گیت برای دستیابی به یک \fBrange\-diff\fR متنی پایدار استفاده کرد (برخلاف گزینه‌ای مانند \fB\-\-stable\fR در \fBgit-patch-id\fR(1))\&. همچنین هیچ معادلی برای \fBgit-apply\fR(1) در \fBrange\-diff\fR وجود ندارد؛ خروجی این دستور برای ماشین‌خوان بودن در نظر گرفته نشده است\&.
.sp
این موضوع به ویژه هنگام ارسال گزینه‌های diff صادق است\&. در حال حاضر برخی گزینه‌ها مانند \fB\-\-stat\fR می‌توانند اثر جانبی داشته باشند و خروجی‌ای تولید کنند که در زمینه \fBrange\-diff\fR کاملاً بی‌فایده است\&. ممکن است نسخه‌های آینده \fBrange\-diff\fR نحوه تفسیر این گزینه‌ها را به روشی ویژه \fBrange\-diff\fR یاد بگیرند (برای مثال برای \fB\-\-stat\fR خروجی خوانا برای انسان تولید کنند که نحوه تغییر diffstat را خلاصه کند)\&.
.SH "پیکربندی (CONFIGURATION)"
.sp
این دستور از تنظیمات \fBdiff\&.color\&.*\fR و \fBpager\&.range\-diff\fR استفاده می‌کند (مورد دوم به طور پیش‌فرض فعال است)\&. به \fBgit-config\fR(1) مراجعه کنید\&.
.SH "مثال‌ها (EXAMPLES)"
.sp
هنگامی که یک ری‌بیس نیازمند حل تداخل‌های ادغام بود، بلافاصله پس از آن تغییرات ایجادشده توسط ری‌بیس را با دستور زیر مقایسه کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git range\-diff @{u} @{1} @
.fi
.if n \{\
.RE
.\}
.sp
.sp
یک خروجی نمونه از \fBgit\fR \fBrange\-diff\fR به این صورت خواهد بود:
.sp
.if n \{\
.RS 4
.\}
.nf
\-:  \-\-\-\-\-\-\- > 1:  0ddba11 Prepare for the inevitable!
1:  c0debee = 2:  cab005e Add a helpful message at the start
2:  f00dbal ! 3:  decafe1 Describe a bug
    @@ \-1,3 +1,3 @@
     Author: A U Thor <author@example\&.com>

    \-TODO: Describe a bug
    +Describe a bug
    @@ \-324,5 +324,6
      This is expected\&.

    \-+What is unexpected is that it will also crash\&.
    ++Unexpectedly, it also crashes\&. This is a bug, and the jury is
    ++still out there how to fix it best\&. See ticket #314 for details\&.

      Contact
3:  bedead < \-:  \-\-\-\-\-\-\- TO\-UNDO
.fi
.if n \{\
.RE
.\}
.sp
.sp
در این مثال، ۳ کامیت قدیمی و ۳ کامیت جدید وجود دارد، که در آن توسعه‌دهنده کامیت سوم را حذف کرده، یک کامیت جدید قبل از دو کامیت اول اضافه کرده، و پیام کامیت دوم و همچنین diff آن را ویرایش کرده است\&.
.sp
هنگامی که خروجی به یک ترمینال ارسال می‌شود، به طور پیش‌فرض رنگ‌بندی می‌شود، درست مانند خروجی معمول \fBgit\fR \fBdiff\fR\&. علاوه بر این، خط اول (افزودن یک کامیت) سبز است، خط آخر (حذف یک کامیت) قرمز است، خط دوم (با تطابق کامل) مانند هدر کامیت در خروجی \fBgit\fR \fBshow\fR زرد است، و خط سوم کامیت قدیمی را قرمز، کامیت جدید را سبز و بقیه را مانند هدر کامیت \fBgit\fR \fBshow\fR رنگ‌آمیزی می‌کند\&.
.sp
با این حال، یک diff ساده از diffها که با رنگ تفکیک شده باشد، خواندنش کمی دشوار است، زیرا کل خطوط را قرمز یا سبز می‌کند\&. به عنوان مثال، خطی که "+What is unexpected" را در کامیت قدیمی اضافه کرده بود کاملاً قرمز است، حتی اگر هدف کامیت قدیمی اضافه کردن چیزی بوده باشد\&.
.sp
برای حل این مشکل، دستور \fBrange\-diff\fR به طور پیش‌فرض از حالت \fB\-\-dual\-color\fR استفاده می‌کند\&. در این حالت، diff از diffها رنگ‌های اصلی diff را حفظ کرده و خطوط را با نشانگرهای \-/+ که دارای \fBپس‌زمینه\fR قرمز یا سبز هستند پیشوندگذاری می‌کند تا واضح‌تر شود که آن‌ها چگونگی تغییر خود diff را توصیف می‌کنند\&.
.SH "الگوریتم (ALGORITHM)"
.sp
ایده کلی به این صورت است: یک ماتریس هزینه بین کامیت‌های هر دو بازه کامیت تولید می‌کنیم، سپس مسئله تخصیص کمترین هزینه (least\-cost assignment) را حل می‌کنیم\&.
.sp
ماتریس هزینه به این شیوه مقداردهی می‌شود: برای هر جفت کامیت، هر دو diff تولید می‌شوند و سپس «diff از diffها» با ۳ خط بافت (context) ایجاد می‌شود، سپس تعداد خطوط موجود در آن diff به عنوان هزینه در نظر گرفته می‌شود\&.
.sp
برای جلوگیری از مثبت‌های کاذب (false positives - مثلاً هنگامی که یک پچ حذف شده و پچ نامرتبط دیگری بین دو تکرار از همان مجموعه پچ اضافه شده است)، ماتریس هزینه با افزودن ورودی‌های دارای هزینه ثابت برای حذف‌ها/افزودن‌های کلی گسترش می‌یابد\&.
.sp
مثال: فرض کنید کامیت‌های \fB1\-\-2\fR اولین تکرار از یک مجموعه پچ و \fBA\-\-C\fR دومین تکرار باشند\&. فرض کنیم \fBA\fR یک cherry\-pick از \fB2\fR باشد، و \fBC\fR یک cherry\-pick از \fB1\fR ولی با تغییری کوچک (مثلاً رفع یک اشتباه تایپی)\&. کامیت‌ها را به صورت یک گراف دوبخشی تجسم کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
    1            A

    2            B

                 C
.fi
.if n \{\
.RE
.\}
.sp
.sp
ما به دنبال «بهترین» توضیح برای مجموعه جدید بر حسب مجموعه قدیمی هستیم\&. می‌توانیم یک «توضیح» را به صورت یک یال در گراف نشان دهیم:
.sp
.if n \{\
.RS 4
.\}
.nf
    1            A
               /
    2 \-\-\-\-\-\-\-\-\*(Aq  B

                 C
.fi
.if n \{\
.RE
.\}
.sp
.sp
این توضیح «رایگان» (بدون هزینه) تمام می‌شود چون هیچ تغییری وجود نداشته است\&. به طور مشابه \fBC\fR می‌تواند با استفاده از \fB1\fR توضیح داده شود، اما این کار به دلیل وجود تغییر با مقداری هزینه c>0 همراه است:
.sp
.if n \{\
.RS 4
.\}
.nf
    1 \-\-\-\-\&.      A
          |    /
    2 \-\-\-\-+\-\-\-\*(Aq  B
          |
          `\-\-\-\-\- C
          c>0
.fi
.if n \{\
.RE
.\}
.sp
.sp
از نظر ریاضی، آنچه به دنبال آن هستیم نوعی تطابق دوبخشی با کمترین هزینه است؛ \(oq1` با مقداری هزینه با \fBC\fR منطبق می‌شود، و الی آخر\&. گراف زیربنایی در واقع یک گراف دوبخشی کامل است؛ هزینه‌ای که به هر یال نسبت می‌دهیم اندازه diff میان پچ‌های دو کامیت است\&. برای توضیح کامیت‌های جدید نیز گره‌های ساختگی (dummy nodes) را در هر دو طرف معرفی می‌کنیم:
.sp
.if n \{\
.RS 4
.\}
.nf
    1 \-\-\-\-\&.      A
          |    /
    2 \-\-\-\-+\-\-\-\*(Aq  B
          |
    o     `\-\-\-\-\- C
          c>0
    o            o

    o            o
.fi
.if n \{\
.RE
.\}
.sp
.sp
هزینه یک یال \fBo\-\-C\fR اندازه diff کامیت \fBC\fR است که با یک ضریب تعدیل (fudge factor) که باید کمتر از ۱۰۰٪ باشد اصلاح می‌شود\&. هزینه یک یال \fBo\-\-o\fR رایگان (صفر) است\&. این ضریب تعدیل ضروری است زیرا حتی اگر \fB1\fR و \fBC\fR هیچ اشتراکی نداشته باشند، ممکن است هنوز چند خط خالی و موارد مشابه را به اشتراک بگذارند، و احتمالاً تخصیص \fB1\-\-C\fR, \fBo\-\-o\fR را کمی ارزان‌تر از \fB1\-\-o\fR, \fBo\-\-C\fR کند، حتی اگر \fB1\fR و \fBC\fR هیچ وجه اشتراکی نداشته باشند\&. با ضریب تعدیل ما بخش مشترک بسیار بزرگ‌تری را برای متناظر دانستن پچ‌ها نیاز داریم\&.
.sp
کل زمان مورد نیاز برای محاسبه این الگوریتم، زمان لازم برای محاسبه n+m دیف کامیت و سپس n*m دیف پچ‌ها است، به علاوه زمان لازم برای محاسبه کم‌هزینه‌ترین تخصیص بین n و m دیف\&. گیت از پیاده‌سازی الگوریتم یانکر-ولگنانت (Jonker\-Volgenant) برای حل مسئله تخصیص استفاده می‌کند که دارای پیچیدگی زمانی مکعبی (cubic) است\&. تطابق یافت‌شده در این حالت به این شکل خواهد بود:
.sp
.if n \{\
.RS 4
.\}
.nf
    1 \-\-\-\-\&.      A
          |    /
    2 \-\-\-\-+\-\-\-\*(Aq  B
       \&.\-\-+\-\-\-\-\-\*(Aq
    o \-\*(Aq  `\-\-\-\-\- C
          c>0
    o \-\-\-\-\-\-\-\-\-\- o

    o \-\-\-\-\-\-\-\-\-\- o
.fi
.if n \{\
.RE
.\}
.sp
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBgit-log\fR(1)
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)