GIT-SHORTLOG(1)

دستورات عمومی کاربر

GIT-SHORTLOG(1)

نام (NAME)

git-shortlog - خلاصه‌سازی خروجی git log

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

git shortlog [<options>] [<revision-range>] [[--] <path>...]
git log --pretty=short | git shortlog [<options>]

توضیحات (DESCRIPTION)

خروجی git log را در قالبی مناسب برای گنجاندن در اطلاعیه‌های انتشار خلاصه‌سازی می‌کند. هر کامیت بر اساس نویسنده و عنوان گروه‌بندی خواهد شد.

علاوه بر این، عبارت «[PATCH]» از توضیحات کامیت حذف خواهد شد.

اگر هیچ بازنگری‌ای در خط فرمان داده نشود و ورودی استاندارد یک ترمینال نباشد یا هیچ شاخه فعلی‌ای وجود نداشته باشد، git shortlog خلاصه‌ای از لاگ خوانده‌شده از ورودی استاندارد را بدون ارجاع به مخزن فعلی در خروجی نمایش می‌دهد.

گزینه‌ها (OPTIONS)

-n, --numbered

خروجی را به‌جای ترتیب الفبایی نویسندگان، بر اساس تعداد کامیت‌های هر نویسنده مرتب می‌کند.

-s, --summary

از توضیحات کامیت صرف‌نظر کرده و تنها خلاصه‌ای از تعداد کامیت‌ها را ارائه می‌دهد.

-e, --email

نشانی ایمیل هر نویسنده را نمایش می‌دهد.

--format[=<format>]

به‌جای موضوع کامیت، از اطلاعات دیگری برای توصیف هر کامیت استفاده می‌کند. <format> می‌تواند هر رشته‌ای باشد که توسط گزینه --format دستور git log پذیرفته می‌شود، مانند * [%h] %s. (بخش PRETTY FORMATS از git-log(1) را ببینید).

هر کامیت با چاپ زیبا (pretty-printed) پیش از نمایش، مجدداً سطرشکنی (rewrap) خواهد شد.

--date=<format>

تاریخ‌ها را با قالب‌بندی متناسب با رشته تاریخ داده‌شده نمایش می‌دهد. (گزینه --date در بخش Commit Formatting از git-log(1) را ببینید). همراه با --group=format:<format> سودمند است.

--group=<type>

کامیت‌ها را بر اساس <type> گروه‌بندی می‌کند. اگر هیچ گزینه --group مشخص نشده باشد، پیش‌فرض author است. <type> یکی از موارد زیر است:

•author, کامیت‌ها بر اساس نویسنده گروه‌بندی می‌شوند

•committer, کامیت‌ها بر اساس ثبت‌کننده گروه‌بندی می‌شوند (مشابه -c)

•trailer:<field>, <field> به‌عنوان یک دنباله (trailer) در پیام کامیت بدون حساسیت به حروف کوچک و بزرگ تفسیر می‌شود (به git-interpret-trailers(1) مراجعه کنید). برای نمونه، اگر پروژه شما از دنباله‌های Reviewed-by استفاده می‌کند، ممکن است بخواهید با دستور زیر ببینید چه کسانی مشغول بازبینی بوده‌اند: git shortlog -ns --group=trailer:reviewed-by.

توجه داشته باشید کامیت‌هایی که شامل این دنباله نباشند شمرده نمی‌شوند. به همین ترتیب، کامیت‌هایی با چند دنباله (برای نمونه چند تاییدیه signoff) ممکن است بیش از یک‌بار شمرده شوند (اما تنها یک‌بار به ازای هر مقدار دنباله یکتا در آن کامیت).

دستور Shortlog تلاش می‌کند هر مقدار دنباله را به‌عنوان یک هویت name <email> تجزیه کند. در صورت موفقیت، mailmap اعمال شده و ایمیل حذف می‌شود مگر اینکه گزینه --email مشخص شده باشد. اگر مقدار نتواند به‌عنوان یک هویت تجزیه شود، به‌صورت تحت‌اللفظی و کامل در نظر گرفته می‌شود.

•format:<format>, هر رشته‌ای که توسط گزینه --format دستور git log پذیرفته می‌شود. (بخش PRETTY FORMATS از git-log(1) را ببینید).

اگر --group چندین بار مشخص شود، کامیت‌ها ذیل هر مقدار شمرده می‌شوند (اما باز هم، تنها یک‌بار به ازای هر مقدار یکتا در آن کامیت). برای نمونه، git shortlog --group=author --group=trailer:co-authored-by هم نویسندگان و هم هم‌نویسندگان (co-authors) را می‌شمارد.

-c, --committer

این یک نام مستعار برای --group=committer است.

-w[<width>[,<indent1>[,<indent2>]]]

خروجی را با شکستن هر خط در width سطرشکنی می‌کند. خط نخست هر مدخل به اندازه indent1 فاصله تورفتگی دارد، و خط دوم و خطوط بعدی به اندازه indent2 فاصله تورفته می‌شوند. مقادیر پیش‌فرض برای width, indent1, و indent2 به‌ترتیب برابر ۷۶، ۶ و ۹ هستند.

اگر عرض برابر 0 (صفر) باشد، خطوط خروجی بدون شکستن آن‌ها تورفته می‌شوند.

<revision-range>

تنها کامیت‌های موجود در محدوده بازنگری مشخص‌شده را نشان می‌دهد. هنگامی که هیچ <revision-range> مشخص نشده باشد، به‌طور پیش‌فرض روی HEAD تنظیم می‌شود (یعنی کل تاریخچه منتهی به کامیت کنونی). origin..HEAD تمام کامیت‌های قابل دسترسی از کامیت فعلی (یعنی HEAD) را که از origin قابل دسترسی نیستند مشخص می‌کند. برای فهرست کامل روش‌های نگارش <revision-range>, به بخش Specifying Ranges از gitrevisions(7) مراجعه کنید.

[--] <path>...

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

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

محدود کردن کامیت‌ها (Commit Limiting)

علاوه بر مشخص کردن محدوده‌ای از کامیت‌ها که باید با استفاده از نمادگذاری‌های ویژه توضیح داده‌شده در بخش توضیحات فهرست شوند، محدودسازی‌های بیشتری نیز روی کامیت‌ها قابل اعمال است.

استفاده از گزینه‌های بیشتر عموماً خروجی را بیشتر محدود می‌کند (برای نمونه --since=<date1> نتایج را به کامیت‌های جدیدتر از <date1> محدود می‌سازد، و استفاده از آن همراه با --grep=<pattern> نتایج را به کامیت‌هایی محدود می‌کند که پیام لاگ آن‌ها شامل خطی منطبق با <pattern> باشد)، مگر اینکه خلاف آن ذکر شده باشد.

توجه داشته باشید که این محدودیت‌ها پیش از گزینه‌های مرتب‌سازی و قالب‌بندی کامیت، مانند --reverse اعمال می‌شوند.

-<number>, -n <number>, --max-count=<number>

خروجی را به نخستین <number> کامیتی که نمایش داده می‌شوند محدود می‌کند.

--max-count-oldest=<number>

خروجی را به آخرین <number> کامیتی که نمایش داده می‌شوند محدود می‌کند.

--skip=<number>

پیش از شروع به نمایش خروجی کامیت‌ها، از <number> کامیت اول صرف‌نظر می‌کند.

--since=<date>, --after=<date>

کامیت‌های جدیدتر از <date> را نمایش می‌دهد. به‌عنوان یک حالت ویژه، today به معنی نیمه‌شب گذشته است.

--since-as-filter=<date>

تمام کامیت‌های جدیدتر از <date> را نمایش می‌دهد. این گزینه به‌جای توقف در نخستین کامیت قدیمی‌تر از <date>, تمام کامیت‌های موجود در محدوده را پیمایش می‌کند.

--until=<date>, --before=<date>

کامیت‌های قدیمی‌تر از <date> را نمایش می‌دهد.

--author=<pattern>, --committer=<pattern>

خروجی کامیت‌ها را به مواردی محدود می‌کند که خطوط هدر نویسنده/ثبت‌کننده آن‌ها با عبارت باقاعده <pattern> مطابقت داشته باشد. با تعیین بیش از یک --author=<pattern>, کامیت‌هایی انتخاب می‌شوند که نویسنده آن‌ها با هر یک از <pattern> ها مطابقت داشته باشد (مشابهاً برای چند مورد --committer=<pattern>).

--grep-reflog=<pattern>

خروجی کامیت‌ها را به مواردی محدود می‌کند که مدخل‌های رِف‌لاگ آن‌ها با عبارت باقاعده <pattern> مطابقت داشته باشد. با تعیین بیش از یک --grep-reflog, کامیت‌هایی انتخاب می‌شوند که پیام رِف‌لاگ آن‌ها با هر یک از الگوهای داده‌شده تطبیق داشته باشد. استفاده از این گزینه بدون به‌کارگیری --walk-reflogs خطا است.

--grep=<pattern>

خروجی کامیت‌ها را به مواردی محدود می‌کند که پیام لاگ آن‌ها با عبارت باقاعده <pattern> مطابقت داشته باشد. با مشخص کردن بیش از یک --grep=<pattern>, کامیت‌هایی انتخاب می‌شوند که پیام آن‌ها با هر یک از <pattern> ها مطابقت کند (اما گزینه --all-match را نیز ببینید).

هنگامی که --notes فعال باشد، پیام موجود در یادداشت‌ها به‌گونه‌ای تطبیق داده می‌شود که گویی بخشی از پیام لاگ است.

--all-match

خروجی کامیت‌ها را به مواردی محدود می‌کند که با تمام الگوهای داده‌شده به --grep مطابقت داشته باشند، به‌جای مواردی که دست‌کم با یکی تطبیق دارند.

--invert-grep

خروجی کامیت‌ها را به مواردی محدود می‌کند که پیام لاگ آن‌ها با <pattern> مشخص‌شده با --grep=<pattern> مطابقت نداشته باشد.

-i, --regexp-ignore-case

الگوهای محدودکننده عبارت باقاعده را بدون حساسیت به حروف کوچک و بزرگ مطابقت می‌دهد.

--basic-regexp

الگوهای محدودکننده را به‌عنوان عبارات باقاعده پایه در نظر می‌گیرد؛ این رفتار پیش‌فرض است.

-E, --extended-regexp

الگوهای محدودکننده را به‌جای عبارات باقاعده پایه پیش‌فرض، به‌عنوان عبارات باقاعده گسترش‌یافته در نظر می‌گیرد.

-F, --fixed-strings

الگوهای محدودکننده را به‌عنوان رشته‌های ثابت در نظر می‌گیرد (الگو را به‌عنوان یک عبارت باقاعده تفسیر نمی‌کند).

-P, --perl-regexp

الگوهای محدودکننده را به‌عنوان عبارات باقاعده سازگار با پرل در نظر می‌گیرد.

پشتیبانی از این نوع عبارات باقاعده یک وابستگی اختیاری در زمان کامپایل است. اگر گیت بدون پشتیبانی از آن‌ها کامپایل شده باشد، ارائه این گزینه باعث خاتمه همراه با خطای برنامه می‌شود.

--remove-empty

هنگامی که یک مسیر داده‌شده از درخت ناپدید شود، متوقف می‌شود.

--merges

تنها کامیت‌های ادغام را چاپ می‌کند. این دقیقاً معادل --min-parents=2 است.

--no-merges

کامیت‌هایی با بیش از یک والد را چاپ نمی‌کند. این دقیقاً معادل --max-parents=1 است.

--min-parents=<number>, --max-parents=<number>, --no-min-parents, --no-max-parents

تنها کامیت‌هایی را نشان می‌دهد که دست‌کم (یا حداکثر) دارای آن تعداد کامیت والد باشند. به‌ویژه، --max-parents=1 مشابه --no-merges, --min-parents=2 مشابه --merges است. --max-parents=0 تمام کامیت‌های ریشه و --min-parents=3 تمام ادغام‌های اختاپوسی را نشان می‌دهد.

گزینه‌های --no-min-parents و --no-max-parents این محدودیت‌ها را دوباره (به حالت بدون محدودیت) بازنشانی می‌کنند. شکل‌های معادل عبارتند از --min-parents=0 (هر کامیتی دارای ۰ یا چند والد است) و --max-parents=-1 (اعداد منفی نشان‌دهنده نبود حد بالاست).

--first-parent

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

--exclude-first-parent-only

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

--maximal-only

کامیت‌های خروجی را به مواردی محدود می‌کند که از هیچ کامیت دیگری در محدوده بازنگری قابل دسترسی نباشند.

--not

معنای پیشوند ^ (یا عدم وجود آن) را برای تمام مشخص‌کننده‌های بازنگری بعدی تا گزینه بعدی --not معکوس می‌کند. هنگامی که در خط فرمان قبل از --stdin استفاده شود، بازنگری‌های دریافت‌شده از stdin تحت تأثیر آن قرار نخواهند گرفت. برعکس، هنگامی که از طریق ورودی استاندارد ارسال شود، بازنگری‌های ارسال‌شده در خط فرمان تحت تأثیر آن قرار نخواهند گرفت.

--all

به‌گونه‌ای عمل می‌کند که گویی تمام ارجاع‌های موجود در refs/, به همراه HEAD, در خط فرمان به‌عنوان <commit> فهرست شده‌اند.

--branches[=<pattern>]

به‌گونه‌ای عمل می‌کند که گویی تمام ارجاع‌های موجود در refs/heads در خط فرمان به‌عنوان <commit> فهرست شده‌اند. اگر <pattern> داده شود، شاخه‌ها را به موارد منطبق با الگوی پوسته داده‌شده محدود می‌کند. اگر <pattern> فاقد ?, *, یا [ باشد، وجود /* در انتهای آن به صورت ضمنی فرض می‌شود.

--tags[=<pattern>]

به‌گونه‌ای عمل می‌کند که گویی تمام ارجاع‌های موجود در refs/tags در خط فرمان به‌عنوان <commit> فهرست شده‌اند. اگر <pattern> داده شود، برچسب‌ها را به موارد منطبق با الگوی پوسته داده‌شده محدود می‌کند. اگر الگو فاقد ?, *, یا [ باشد، وجود /* در انتهای آن به صورت ضمنی فرض می‌شود.

--remotes[=<pattern>]

به‌گونه‌ای عمل می‌کند که گویی تمام ارجاع‌های موجود در refs/remotes در خط فرمان به‌عنوان <commit> فهرست شده‌اند. اگر <pattern> داده شود، شاخه‌های ردگیری دوردست را به موارد منطبق با الگوی پوسته داده‌شده محدود می‌کند. اگر الگو فاقد ?, *, یا [ باشد، وجود /* در انتهای آن به صورت ضمنی فرض می‌شود.

--glob=<glob-pattern>

به‌گونه‌ای عمل می‌کند که گویی تمام ارجاع‌های منطبق با الگوی پوسته <glob-pattern> در خط فرمان به‌عنوان <commit> فهرست شده‌اند. پیشوند refs/ در صورت عدم وجود، به‌طور خودکار در ابتدا اضافه می‌شود. اگر الگو فاقد ?, *, یا [ باشد، وجود /* در انتهای آن به صورت ضمنی فرض می‌شود.

--exclude=<glob-pattern>

ارجاع‌های منطبق با <glob-pattern> را که گزینه‌های بعدی --all, --branches, --tags, --remotes, یا --glob در نظر می‌گیرند، شامل نمی‌کند. تکرار این گزینه الگوهای استثنا را تا گزینه بعدی --all, --branches, --tags, --remotes, یا --glob جمع‌آوری می‌کند (سایر گزینه‌ها یا آرگومان‌ها الگوهای جمع‌آوری‌شده را پاک نمی‌کنند).

الگوهای داده‌شده هنگام اعمال روی --branches, --tags, یا --remotes نباید با refs/heads, refs/tags, یا refs/remotes آغاز شوند، و هنگام اعمال روی --glob یا --all باید حتماً با refs/ شروع شوند. اگر یک /* پایانی مد نظر باشد، باید صریحاً قید شود.

--exclude-hidden=(fetch|receive|uploadpack)

ارجاع‌هایی را که توسط git-fetch, git-receive-pack یا git-upload-pack با مراجعه به پیکربندی مناسب fetch.hideRefs, receive.hideRefs یا uploadpack.hideRefs به همراه transfer.hideRefs پنهان می‌شوند، شامل نمی‌کند (به git-config(1) مراجعه کنید). این گزینه بر گزینه شبه‌ارجاع بعدی --all یا --glob تأثیر می‌گذارد و پس از پردازش آن‌ها پاک می‌شود.

--reflog

به‌گونه‌ای عمل می‌کند که گویی تمام اشیای ذکرشده در رِف‌لاگ‌ها در خط فرمان به‌عنوان <commit> فهرست شده‌اند.

--alternate-refs

به‌گونه‌ای عمل می‌کند که گویی تمام اشیای ذکرشده به‌عنوان نوک ارجاع مخازن جایگزین در خط فرمان فهرست شده‌اند. یک مخزن جایگزین هر مخزنی است که پوشه اشیای آن در objects/info/alternates مشخص شده باشد. مجموعه اشیای ارائه‌شده ممکن است توسط core.alternateRefsCommand و غیره اصلاح شود. به git-config(1) مراجعه کنید.

--single-worktree

به‌طور پیش‌فرض، در صورت وجود بیش از یک درخت کاری، تمام درخت‌های کاری توسط گزینه‌های زیر بررسی می‌شوند (به git-worktree(1) مراجعه کنید): --all, --reflog و --indexed-objects. این گزینه آن‌ها را وادار می‌کند تا تنها درخت کاری فعلی را بررسی نمایند.

--ignore-missing

هنگام مشاهده نام شیء نامعتبر در ورودی، به‌گونه‌ای عمل می‌کند که گویی ورودی نامعتبر داده نشده است.

--bisect

به‌گونه‌ای عمل می‌کند که گویی ارجاع تنصیف بد refs/bisect/bad در خط فرمان فهرست شده و پس از آن --not و ارجاع‌های تنصیف خوب refs/bisect/good-* روی خط فرمان آمده است.

--stdin

علاوه بر دریافت آرگومان‌ها از خط فرمان، آن‌ها را از ورودی استاندارد نیز می‌خواند. این گزینه کامیت‌ها و شبه‌گزینه‌هایی مانند --all و --glob= را می‌پذیرد. هنگامی که یک جداکننده -- مشاهده شود، ورودی بعدی به‌عنوان مسیر در نظر گرفته شده و برای محدود کردن نتیجه استفاده می‌شود. گزینه‌هایی مانند --not که از طریق ورودی استاندارد خوانده می‌شوند، تنها برای آرگومان‌هایی که به همان روش ارسال شده‌اند رعایت می‌شوند و بر هیچ‌یک از آرگومان‌های خط فرمان بعدی تأثیر نخواهند گذاشت.

--cherry-mark

مشابه --cherry-pick (در ادامه ببینید) عمل می‌کند اما کامیت‌های معادل را به‌جای حذف کردن، با علامت = و موارد غیرمعادل را با علامت + نشانه‌گذاری می‌نماید.

--cherry-pick

هر کامیتی را که تغییری مشابه کامیت دیگری در «طرف دیگر» ایجاد می‌کند، هنگامی که مجموعه کامیت‌ها با تفاضل متقارن محدود شده باشند، حذف می‌نماید.

برای نمونه، اگر دو شاخه A و B داشته باشید، روش معمول برای فهرست کردن تمام کامیت‌های موجود در یک طرف آن‌ها استفاده از --left-right است (مثال زیر در توضیحات گزینه --left-right را ببینید). با این حال، کامیت‌هایی را که از شاخه دیگر دست‌چین (cherry-pick) شده‌اند نشان می‌دهد (برای مثال «سومین در b» ممکن است از شاخه A دست‌چین شده باشد). با این گزینه، چنین جفت کامیت‌هایی از خروجی مستثنی می‌شوند.

--left-only, --right-only

تنها کامیت‌های سمت مربوطه یک تفاضل متقارن را فهرست می‌کند، یعنی تنها مواردی که با < یا > توسط --left-right علامت‌گذاری می‌شوند.

برای نمونه، --cherry-pick --right-only A...B آن دسته از کامیت‌های موجود در B را که در A هستند یا معادل وصله‌ای با یک کامیت در A می‌باشند حذف می‌کند. به عبارت دیگر، این دستور کامیت‌های + را از git cherry A B فهرست می‌کند. به‌طور دقیق‌تر، --cherry-pick --right-only --no-merges فهرست دقیق را ارائه می‌دهد.

--cherry

مترادفی برای --right-only --cherry-mark --no-merges; سودمند برای محدود کردن خروجی به کامیت‌های سمت خودمان و نشانه‌گذاری مواردی که به سمت دیگر یک تاریخچه شاخه‌بندی‌شده اعمال شده‌اند با دستور git log --cherry upstream...mybranch, مشابه با git cherry upstream mybranch.

-g, --walk-reflogs

به‌جای پیمایش زنجیره نیاکان کامیت، مدخل‌های رِف‌لاگ را از جدیدترین به سمت قدیمی‌ترها پیمایش می‌کند. هنگامی که از این گزینه استفاده می‌شود نمی‌توانید کامیت‌هایی را برای استثنا کردن مشخص کنید (یعنی نمادگذاری‌های ^<commit>, <commit1>..<commit2>, و <commit1>...<commit2> قابل استفاده نیستند).

با قالبی از --pretty به‌جز oneline و reference (به دلایل واضح)، این گزینه باعث می‌شود خروجی دارای دو خط اطلاعات اضافی برگرفته از رِف‌لاگ باشد. نشان‌دهنده رِف‌لاگ در خروجی ممکن است به‌صورت ref@{<Nth>} (که در آن <Nth> اندیس معکوس زمانی در رِف‌لاگ است) یا به‌صورت ref@{<timestamp>} (همراه با <timestamp> آن مدخل) بسته به چند قانون نمایش داده شود:

1.اگر نقطه شروع به‌صورت ref@{<Nth>} مشخص شده باشد، قالب اندیس نمایش داده می‌شود.

2.اگر نقطه شروع به‌صورت ref@{now} مشخص شده باشد، قالب برچسب زمان نمایش داده می‌شود.

3.اگر از هیچ‌کدام استفاده نشده باشد، اما --date در خط فرمان داده شده باشد، برچسب زمان در قالب خواسته‌شده توسط --date نمایش داده می‌شود.

4.در غیر این صورت، قالب اندیس نمایش داده می‌شود.

تحت --pretty=oneline, پیام کامیت با این اطلاعات در همان خط پیشوند می‌گیرد. این گزینه با --reverse قابل ترکیب نیست. همچنین به git-reflog(1) مراجعه کنید.

تحت --pretty=reference, این اطلاعات اصلاً نمایش داده نخواهند شد.

--merge

کامیت‌هایی را که مسیرهای دارای تعارض را در محدوده HEAD...<other> تغییر داده‌اند نمایش می‌دهد، که در آن <other> نخستین شبه‌ارجاع موجود در MERGE_HEAD, CHERRY_PICK_HEAD, REVERT_HEAD یا REBASE_HEAD است. تنها زمانی کار می‌کند که ایندکس دارای مدخل‌های ادغام‌نشده باشد. این گزینه را می‌توان برای نمایش کامیت‌های مرتبط هنگام حل تعارض‌های ناشی از یک ادغام ۳-طرفه استفاده کرد.

--boundary

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

ساده‌سازی تاریخچه (History Simplification)

گاهی اوقات شما تنها به بخش‌هایی از تاریخچه علاقه‌مندید، برای نمونه کامیت‌هایی که یک <path> خاص را تغییر می‌دهند. اما ساده‌سازی تاریخچه دو بخش دارد: یک بخش انتخاب کامیت‌ها است و بخش دیگر چگونگی انجام آن، چرا که راهبردهای گوناگونی برای ساده‌سازی تاریخچه وجود دارد.

گزینه‌های زیر کامیت‌های نمایش‌داده‌شده را انتخاب می‌کنند:

<paths>

کامیت‌هایی که <paths> مشخص‌شده را تغییر می‌دهند انتخاب می‌شوند.

--simplify-by-decoration

کامیت‌هایی که توسط یک شاخه یا برچسب ارجاع داده شده‌اند انتخاب می‌شوند.

توجه داشته باشید که ممکن است کامیت‌های اضافی نیز برای ارائه یک تاریخچه معنادار نمایش داده شوند.

گزینه‌های زیر بر نحوه انجام ساده‌سازی تأثیر می‌گذارند:

حالت پیش‌فرض (Default mode)

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

--show-pulls

تمام کامیت‌های حالت پیش‌فرض را شامل می‌شود، به اضافه هر کامیت ادغامی که نسبت به والد نخست TREESAME نباشد ولی نسبت به والد بعدی TREESAME باشد. این حالت برای نمایش کامیت‌های ادغامی که «نخستین بار تغییری را وارد یک شاخه کردند» سودمند است.

--full-history

مشابه حالت پیش‌فرض است، اما بخشی از تاریخچه را هرس نمی‌کند.

--dense

تنها کامیت‌های انتخاب‌شده به علاوه مواردی برای داشتن تاریخچه معنادار نمایش داده می‌شوند.

--sparse

تمام کامیت‌ها در تاریخچه ساده‌سازی‌شده نمایش داده می‌شوند.

--simplify-merges

گزینه‌ای اضافی برای --full-history جهت حذف برخی از ادغام‌های غیرضروری از تاریخچه حاصل، چرا که هیچ کامیت انتخاب‌شده‌ای در این ادغام نقشی نداشته است.

--ancestry-path[=<commit>]

هنگامی که محدوده‌ای از کامیت‌ها برای نمایش داده می‌شود (مانند <commit1>..<commit2> یا <commit2> ^<commit1>), و یک کامیت <commit> در آن محدوده مشخص گردد، تنها کامیت‌هایی از آن محدوده را نمایش می‌دهد که نیاکان <commit>, نوادگان <commit>, یا خود <commit> باشند. اگر هیچ کامیتی مشخص نشود، از <commit1> (بخش مستثنی‌شده محدوده) به‌عنوان <commit> استفاده می‌کند. می‌توان آن را چندین بار ارسال کرد؛ در این صورت، یک کامیت در صورتی گنجانده می‌شود که هر یک از کامیت‌های ارائه‌شده باشد یا نیا یا نواده یکی از آن‌ها باشد.

توضیحات دقیق‌تر در ادامه می‌آید.

فرض کنید شما foo را به‌عنوان <paths> مشخص کرده‌اید. ما کامیت‌هایی را که foo را تغییر می‌دهند !TREESAME (نایکسان از نظر درخت) و بقیه را TREESAME (یکسان از نظر درخت) می‌نامیم. (در یک diff فیلترشده برای foo، آن‌ها به ترتیب متفاوت و برابر به نظر می‌رسند.)

در ادامه، ما همواره به همین تاریخچه نمونه برای نشان دادن تفاوت‌های بین تنظیمات ساده‌سازی ارجاع خواهیم داد. فرض می‌کنیم شما در حال فیلتر کردن برای فایل foo در این گراف کامیت هستید:

  .-A---M---N---O---P---Q
 /     /   /   /   /   /
I     B   C   D   E   Y
 \   /   /   /   /   /
  `-------------'   X

خط افقی تاریخچه A---Q به‌عنوان والد نخست هر ادغام در نظر گرفته می‌شود. کامیت‌ها عبارتند از:

•I کامیت اولیه است که در آن foo با محتوای asdf و فایلی به نام quux با محتوای quux وجود دارد. کامیت‌های اولیه با یک درخت خالی مقایسه می‌شوند، بنابراین I مقدار !TREESAME دارد.

•در A, فایل foo تنها حاوی foo است.

•B شامل همان تغییر A است. ادغام آن M بدیهی (trivial) است و بنابراین نسبت به تمام والدین TREESAME است.

•C تغییری در foo ایجاد نمی‌کند، اما ادغام آن N آن را به foobar تغییر می‌دهد، بنابراین نسبت به هیچ والدی TREESAME نیست.

•D مقدار foo را روی baz تنظیم می‌کند. ادغام آن O رشته‌های برگرفته از N و D را به foobarbaz ترکیب می‌کند؛ یعنی نسبت به هیچ والدی TREESAME نیست.

•E مقدار quux را به xyzzy تغییر می‌دهد، و ادغام آن P رشته‌ها را به quux xyzzy ترکیب می‌نماید. P نسبت به O دارای وضعیت TREESAME است، اما نسبت به E نیست.

•X یک کامیت ریشه مستقل است که فایل جدید side را اضافه کرده، و Y آن را اصلاح نموده است. Y نسبت به X وضعیت TREESAME دارد. ادغام آن Q فایل side را به P اضافه کرده است، و Q نسبت به P دارای وضعیت TREESAME است، اما نسبت به Y نیست.

دستور rev-list در تاریخچه به سمت عقب پیمایش می‌کند، و بر اساس اینکه آیا --full-history و/یا بازنویسی والدین (از طریق --parents یا --children) استفاده شده باشد، کامیت‌ها را شامل یا مستثنی می‌سازد. تنظیمات زیر در دسترس هستند.

حالت پیش‌فرض (Default mode)

کامیت‌ها در صورتی که نسبت به هیچ والدی TREESAME نباشند گنجانده می‌شوند (اگرچه این قابل تغییر است، --sparse را در ادامه ببینید). اگر کامیت یک ادغام باشد و نسبت به یک والد TREESAME باشد، تنها همان والد را دنبال می‌کند. (حتی اگر چندین والد TREESAME وجود داشته باشد، فقط یکی از آن‌ها دنبال می‌شود.) در غیر این صورت، تمام والدین دنبال می‌شوند.

این منجر به نتیجه زیر می‌شود:

  .-A---N---O
 /     /   /
I---------D

توجه کنید چگونه قاعده دنبال کردن تنها والد TREESAME (در صورت وجود)، B را کاملاً از بررسی حذف کرد. C از طریق N بررسی شد، اما وضعیت TREESAME داشت. کامیت‌های ریشه با یک درخت خالی مقایسه می‌شوند، بنابراین I دارای وضعیت !TREESAME است.

روابط والد/فرزند تنها با --parents قابل مشاهده هستند، اما این موضوع بر کامیت‌های انتخاب‌شده در حالت پیش‌فرض تأثیری ندارد، بنابراین ما خطوط والدین را نمایش داده‌ایم.

--full-history بدون بازنویسی والدین

این حالت با حالت پیش‌فرض در یک نکته تفاوت دارد: همیشه تمام والدین یک ادغام را دنبال می‌کند، حتی اگر نسبت به یکی از آن‌ها TREESAME باشد. حتی اگر بیش از یک سمت ادغام دارای کامیت‌های گنجانده‌شده باشد، این بدان معنا نیست که خود ادغام نیز شامل شده است! در مثال، به این نتیجه می‌رسیم:

I  A  B  N  D  O  P  Q

M حذف شد زیرا نسبت به هر دو والد وضعیت TREESAME داشت. E, C و B همگی پیمایش شدند، اما تنها B دارای وضعیت !TREESAME بود، بنابراین بقیه ظاهر نمی‌شوند.

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

--full-history با بازنویسی والدین

کامیت‌های عادی تنها در صورتی گنجانده می‌شوند که وضعیت !TREESAME داشته باشند (اگرچه این قابل تغییر است، --sparse را در ادامه ببینید).

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

  .-A---M---N---O---P---Q
 /     /   /   /   /
I     B   /   D   /
 \   /   /   /   /
  `-------------'

با --full-history بدون بازنویسی در بالا مقایسه کنید. توجه داشته باشید که E هرس شد زیرا TREESAME بود، اما فهرست والدین P بازنویسی شد تا شامل والد E یعنی I باشد. همین اتفاق برای C و N, و برای X, Y و Q نیز رخ داد.

علاوه بر تنظیمات فوق، می‌توانید تغییر دهید که آیا وضعیت TREESAME بر گنجاندن تأثیر بگذارد یا خیر:

--dense

کامیت‌های پیمایش‌شده در صورتی گنجانده می‌شوند که نسبت به هیچ والدی TREESAME نباشند.

--sparse

تمام کامیت‌هایی که پیمایش می‌شوند گنجانده خواهند شد.

توجه داشته باشید که بدون --full-history, این گزینه همچنان ادغام‌ها را ساده‌سازی می‌کند: اگر یکی از والدین TREESAME باشد، ما تنها همان یکی را دنبال می‌کنیم، بنابراین سمت‌های دیگر ادغام هرگز پیمایش نمی‌شوند.

--simplify-merges

نخست، یک گراف تاریخچه را به همان روشی که --full-history با بازنویسی والدین انجام می‌دهد می‌سازد (بالا را ببینید).

سپس هر کامیت C را به جایگزین آن C' در تاریخچه نهایی بر اساس قوانین زیر ساده می‌کند:

•مقدار C' را روی C تنظیم کنید.

•هر والد P از C' را با نسخه ساده‌شده‌اش P' جایگزین کنید. در این فرایند، والدینی را که نیاکان سایر والدین هستند یا کامیت‌های ریشه‌ای هستند که نسبت به یک درخت خالی وضعیت TREESAME دارند حذف کرده و موارد تکراری را بزدایید، اما دقت کنید که هرگز تمام والدینی را که نسبت به آن‌ها TREESAME هستیم حذف نکنید.

•اگر پس از این بازنویسی والدین، C' یک کامیت ریشه یا ادغام باشد (دارای ۰ یا بیش از ۱ والد باشد)، یک کامیت مرزی باشد، یا !TREESAME باشد، باقی می‌ماند. در غیر این صورت، با تنها والد خود جایگزین می‌شود.

تأثیر این کار به بهترین شکل با مقایسه آن با --full-history همراه با بازنویسی والدین نشان داده می‌شود. مثال به صورت زیر درمی‌آید:

  .-A---M---N---O
 /     /       /
I     B       D
 \   /       /
  `---------'

تفاوت‌های عمده در N, P, و Q را نسبت به --full-history ملاحظه فرمایید:

•از فهرست والدین N's کامیت I حذف شد، زیرا نیاکان والد دیگر یعنی M است. با این وجود، N باقی ماند زیرا وضعیت !TREESAME دارد.

•از فهرست والدین P's نیز مشابهاً I حذف گردید. سپس P به‌طور کامل حذف شد، زیرا یک والد داشت و وضعیت TREESAME داشت.

•فهرست والدین Q's کامیت Y را به X ساده کرد. سپس X حذف شد، چرا که یک ریشه با وضعیت TREESAME بود. Q سپس به‌طور کامل حذف شد، زیرا یک والد داشت و وضعیت TREESAME داشت.

حالت ساده‌سازی دیگری نیز در دسترس است:

--ancestry-path[=<commit>]

کامیت‌های نمایش‌داده‌شده را به مواردی محدود می‌کند که نیاکان <commit>, نوادگان <commit>, یا خود <commit> باشند.

به‌عنوان یک نمونه کاربرد، تاریخچه کامیت زیر را در نظر بگیرید:

    D---E-------F
   /     \       \
  B---C---G---H---I---J
 /                     \
A-------K---------------L--M

یک عبارت معمولی D..M مجموعه کامیت‌هایی را محاسبه می‌کند که نیاکان M هستند، اما مواردی را که نیاکان D می‌باشند مستثنی می‌سازد. این برای مشاهده آنچه برای تاریخچه منتهی به M از زمان D رخ داده مفید است، به این معنی که « M چه چیزی دارد که در D وجود نداشت». نتیجه در این مثال تمام کامیت‌ها خواهد بود، به جز A و B (و البته خود D).

اما هنگامی که بخواهیم بدانیم چه کامیت‌هایی در M به باگ معرفی‌شده توسط D آلوده شده‌اند و نیاز به رفع دارند، ممکن است بخواهیم تنها زیرمجموعه‌ای از D..M را مشاهده کنیم که واقعاً از نوادگان D هستند، یعنی مستثنی کردن C و K. این دقیقاً همان کاری است که گزینه --ancestry-path انجام می‌دهد. اعمال آن روی محدوده D..M به نتیجه زیر می‌انجامد:

E-------F
 \       \
  G---H---I---J
               \
                L--M

ما همچنین می‌توانیم از --ancestry-path=D به‌جای --ancestry-path استفاده کنیم که هنگام اعمال روی محدوده D..M معنای یکسانی دارد اما صریح‌تر است.

اگر در عوض به یک موضوع خاص در این محدوده و تمام کامیت‌های متأثر از آن موضوع علاقه‌مند باشیم، ممکن است تنها بخواهیم زیرمجموعه‌ای از D..M را مشاهده کنیم که آن موضوع را در مسیر نیاکان خود دارند. بنابراین، برای مثال استفاده از --ancestry-path=H D..M به نتیجه زیر می‌انجامد:

  E
   \
C---G---H---I---J
                 \
                  L--M

در حالی که --ancestry-path=K D..M به این نتیجه منجر می‌شود:

K---------------L--M

پیش از بحث درباره گزینه دیگر، یعنی --show-pulls, لازم است یک تاریخچه نمونه جدید بسازیم.

یک مشکل رایج که کاربران هنگام مشاهده تاریخچه ساده‌سازی‌شده با آن مواجه می‌شوند این است که کامیتی که می‌دانند فایلی را تغییر داده است به نوعی در تاریخچه ساده‌شده فایل ظاهر نمی‌شود. بیایید یک مثال جدید را نشان دهیم و بررسی کنیم که گزینه‌هایی مانند --full-history و --simplify-merges در چنین حالتی چگونه کار می‌کنند:

  .-A---M-----C--N---O---P
 /     / \  \  \/   /   /
I     B   \  R-'`-Z'   /
 \   /     \/         /
  \ /      /\        /
   `---X--'  `---Y--'

برای این مثال، فرض کنید I فایل file.txt را ایجاد کرد که توسط A, B, و X به روش‌های متفاوتی اصلاح شد. کامیت‌های تک‌والدی C, Z, و Y تغییری در file.txt ایجاد نمی‌کنند. کامیت ادغام M با حل تعارض ادغام برای گنجاندن هر دو تغییر از A و B ایجاد شد و بنابراین نسبت به هیچ‌کدام TREESAME نیست. اما کامیت ادغام R با نادیده گرفتن محتویات file.txt در M و گرفتن تنها محتویات file.txt در X ایجاد گردید. از این رو، R نسبت به X دارای وضعیت TREESAME است اما نسبت به M نیست. در نهایت، تفکیک طبیعی ادغام برای ایجاد N گرفتن محتویات file.txt در R است، بنابراین N نسبت به R وضعیت TREESAME دارد اما نسبت به C ندارد. کامیت‌های ادغام O و P نسبت به والدین اول خود وضعیت TREESAME دارند، اما به ترتیب نسبت به والدین دوم خود یعنی Z و Y وضعیت TREESAME ندارند.

هنگام استفاده از حالت پیش‌فرض، N و R هر دو دارای یک والد TREESAME هستند، بنابراین آن یال‌ها پیمایش شده و بقیه نادیده گرفته می‌شوند. گراف تاریخچه حاصل به صورت زیر است:

I---X

هنگام استفاده از --full-history, گیت تمام یال‌ها را پیمایش می‌کند. این کار کامیت‌های A و B و ادغام M را آشکار می‌سازد، اما کامیت‌های ادغام O و P را نیز نمایان می‌کند. با بازنویسی والدین، گراف حاصل به شکل زیر خواهد بود:

  .-A---M--------N---O---P
 /     / \  \  \/   /   /
I     B   \  R-'`--'   /
 \   /     \/         /
  \ /      /\        /
   `---X--'  `------'

در اینجا، کامیت‌های ادغام O و P نویز اضافی ایجاد می‌کنند، زیرا در واقع تغییری در file.txt ایجاد نکرده‌اند. آن‌ها تنها موضوعی را ادغام کرده‌اند که بر پایه نسخه قدیمی‌تری از file.txt بنا شده بود. این یک مسئله رایج در مخازنی است که از گردش کاری با مشارکت‌کنندگان موازی زیاد استفاده می‌کنند که شاخه‌های موضوعی خود را در طول یک تنه اصلی ادغام می‌نمایند: ادغام‌های نامرتبط زیادی در نتایج --full-history ظاهر می‌شوند.

هنگام استفاده از گزینه --simplify-merges, کامیت‌های O و P از نتایج ناپدید می‌شوند. دلیل آن این است که والدین دوم بازنویسی‌شده O و P از والدین اول آن‌ها قابل دسترسی هستند. آن یال‌ها حذف می‌شوند و سپس کامیت‌ها مانند کامیت‌های تک‌والدی به نظر می‌رسند که نسبت به والد خود TREESAME هستند. این اتفاق برای کامیت N نیز رخ می‌دهد و نمایی از تاریخچه به صورت زیر ایجاد می‌کند:

  .-A---M--.
 /     /    \
I     B      R
 \   /      /
  \ /      /
   `---X--'

در این نما، ما تمام تغییرات تک‌والدی مهم از A, B, و X را می‌بینیم. همچنین ادغام با دقت حل‌شده M و ادغام نه‌چندان با دقت حل‌شده R را مشاهده می‌کنیم. این معمولاً اطلاعات کافی برای تعیین اینکه چرا کامیت‌های A و B در نمای پیش‌فرض از تاریخچه «ناپدید شدند» را فراهم می‌سازد. با این حال، چند مشکل در این رویکرد وجود دارد.

مشکل نخست کارایی است. برخلاف هر گزینه قبلی، گزینه --simplify-merges مستلزم پیمایش کل تاریخچه کامیت پیش از بازگرداندن حتی یک نتیجه است. این می‌تواند استفاده از این گزینه را برای مخازن بسیار بزرگ دشوار سازد.

مشکل دوم موضوع حسابرسی (auditing) است. هنگامی که مشارکت‌کنندگان زیادی روی یک مخزن کار می‌کنند، مهم است که کدام کامیت‌های ادغام تغییری را وارد یک شاخه مهم کرده‌اند. ادغام مشکل‌ساز R در بالا احتمالاً آن کامیت ادغامی نبوده است که برای ادغام در یک شاخه مهم استفاده شده است. در عوض، ادغام N برای ادغام R و X در شاخه مهم به کار رفته است. این کامیت ممکن است اطلاعاتی درباره اینکه چرا تغییر X جایگزین تغییرات A و B شد در پیام کامیت خود داشته باشد.

--show-pulls

علاوه بر کامیت‌های نمایش‌داده‌شده در تاریخچه پیش‌فرض، هر کامیت ادغامی را که نسبت به والد نخست خود TREESAME نیست اما نسبت به والد بعدی TREESAME است نمایش می‌دهد.

هنگامی که یک کامیت ادغام توسط --show-pulls گنجانده می‌شود، با ادغام به‌گونه‌ای رفتار می‌شود که گویی تغییر را از شاخه دیگری «کشیده» (pull) است. هنگام استفاده از --show-pulls در این مثال (و بدون گزینه‌های دیگر) گراف حاصل عبارت است از:

I---X---R---N

در اینجا، کامیت‌های ادغام R و N گنجانده شده‌اند زیرا آن‌ها به ترتیب کامیت‌های X و R را به شاخه پایه وارد کردند. این ادغام‌ها دلیلی هستند که کامیت‌های A و B در تاریخچه پیش‌فرض ظاهر نمی‌شوند.

هنگامی که --show-pulls همراه با --simplify-merges استفاده شود، گراف شامل تمام اطلاعات لازم خواهد بود:

  .-A---M--.   N
 /     /    \ /
I     B      R
 \   /      /
  \ /      /
   `---X--'

توجه داشته باشید از آنجا که M از R قابل دسترسی است، یال از N به M با ساده‌سازی حذف شد. با این حال، N همچنان به‌عنوان یک کامیت مهم در تاریخچه ظاهر می‌شود زیرا تغییر R را به شاخه اصلی «کشیده» است.

گزینه --simplify-by-decoration به شما امکان می‌دهد تنها نمای کلی از توپولوژی تاریخچه را با حذف کامیت‌هایی که توسط برچسب‌ها ارجاع داده نشده‌اند مشاهده کنید. کامیت‌ها در صورتی به‌عنوان !TREESAME علامت‌گذاری می‌شوند (به عبارت دیگر، پس از قوانین ساده‌سازی تاریخچه توضیح داده‌شده در بالا حفظ می‌شوند) که (۱) توسط برچسب‌ها ارجاع داده شده باشند، یا (۲) محتویات مسیرهای داده‌شده در خط فرمان را تغییر دهند. تمام کامیت‌های دیگر به‌عنوان TREESAME علامت‌گذاری می‌شوند (مشمول حذف از طریق ساده‌سازی).

نگاشت نویسندگان (MAPPING AUTHORS)

gitmailmap(5) را ببینید.

توجه داشته باشید که اگر git shortlog خارج از یک مخزن اجرا شود (برای پردازش محتوای لاگ در ورودی استاندارد)، به دنبال یک فایل .mailmap در دایرکتوری جاری خواهد گشت.

گیت (GIT)

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

2026-06-29

Git 2.55.0