GIT-ANNOTATE(1) Git Manual GIT-ANNOTATE(1)

git-annotate - حاشیه‌نویسی خطوط فایل با اطلاعات کامیت

git annotate [<options>] [<rev-opts>] [<rev>] [--] <file>

هر سطر از فایل داده‌شده را با اطلاعات مربوط به کامیتی که آن سطر را ایجاد کرده است، حاشیه‌نویسی می‌کند. همچنین به صورت اختیاری می‌تواند حاشیه‌نویسی را از یک ویرایش (revision) مشخص انجام دهد.

تنها تفاوت میان این دستور و git-blame(1) در این است که آن‌ها از قالب‌های خروجی اندکی متفاوت استفاده می‌کنند؛ و این دستور صرفاً جهت سازگاری با گذشته برای پشتیبانی از اسکریپت‌های موجود، و فراهم کردن نام دستوری آشناتر برای افرادی که از سایر سیستم‌های مدیریت نسخه (SCM) می‌آیند، وجود دارد.

-b

برای کامیت‌های مرزی (boundary commits) یک SHA-1 خالی نشان می‌دهد. این مورد همچنین از طریق گزینه پیکربندی blame.blankBoundary قابل کنترل است.

--root

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

--show-stats

آمار اضافی را در پایان خروجی blame لحاظ می‌کند.

-L <start>,<end>, -L :<funcname>

تنها محدوده خطوط مشخص‌شده توسط <start>,<end>، یا با عبارت باقاعده نام تابع <funcname> را حاشیه‌نویسی می‌کند. می‌تواند چندین بار مشخص شود. محدوده‌های دارای هم‌پوشانی مجاز هستند.

<start> و <end> اختیاری هستند. -L <start> یا -L <start>, از <start> تا انتهای فایل را در بر می‌گیرد. -L ,<end> از ابتدای فایل تا <end> را در بر می‌گیرد.

<start> و <end> می‌توانند یکی از این قالب‌ها را داشته باشند:

•<number>

اگر <start> یا <end> یک عدد باشد، شماره خط مطلق را مشخص می‌کند (شمارش خطوط از ۱ آغاز می‌شود).

•/<regex>/

این قالب از اولین خطی که با <regex> داده‌شده بر اساس POSIX مطابقت داشته باشد استفاده می‌کند. اگر <start> یک عبارت باقاعده باشد، از انتهای محدوده -L قبلی (در صورت وجود)، وگرنه از ابتدای فایل جستجو خواهد کرد. اگر <start> به صورت ^/<regex>/ باشد، از ابتدای فایل جستجو خواهد کرد. اگر <end> یک عبارت باقاعده باشد، جستجو را از خط مشخص‌شده توسط <start> آغاز می‌کند.

•+<offset> یا -<offset>

این حالت فقط برای <end> معتبر است و تعدادی خط قبل یا بعد از خط مشخص‌شده توسط <start> را تعیین می‌کند.

اگر :<funcname> به جای <start> و <end> داده شود، یک عبارت باقاعده است که محدوده را از اولین خط funcname که با <funcname> مطابقت دارد تا خط funcname بعدی نشان می‌دهد. :<funcname> از انتهای محدوده -L قبلی (در صورت وجود)، وگرنه از ابتدای فایل جستجو می‌کند. ^:<funcname> از ابتدای فایل جستجو می‌کند. نام‌های توابع به همان شیوه‌ای تعیین می‌شوند که git diff هدرهای قطعه پچ (patch hunk headers) را محاسبه می‌کند (بخش Defining a custom hunk-header در gitattributes(5) را ببینید).

-l

نمایش ویرایش (rev) طولانی (پیش‌فرض: غیرفعال).

-t

نمایش برچسب زمانی خام (پیش‌فرض: غیرفعال).

-S <revs-file>

استفاده از ویرایش‌های موجود در <revs-file> به جای فراخوانی git-rev-list(1).

--reverse <start>..<end>

پیمایش تاریخچه به سمت جلو به جای عقب. به جای نمایش ویرایشی که یک خط در آن ظاهر شده است، آخرین ویرایشی را که یک خط در آن وجود داشته نمایش می‌دهد. این امر نیازمند محدوده‌ای از ویرایش‌ها مانند <start>..<end> است که در آن مسیر مورد بررسی در <start> وجود داشته باشد. دستور git blame --reverse <start> برای راحتی به صورت git blame --reverse <start>..HEAD در نظر گرفته می‌شود.

--first-parent

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

-p, --porcelain

خروجی را در قالبی طراحی‌شده برای پردازش ماشینی نمایش می‌دهد.

--line-porcelain

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

--incremental

نتیجه را به صورت افزایشی (incremental) در قالبی طراحی‌شده برای پردازش ماشینی نمایش می‌دهد.

--encoding=<encoding>

کدگذاری مورد استفاده برای خروجی نام‌های نویسندگان و خلاصه‌های کامیت را مشخص می‌کند. تنظیم آن روی none باعث می‌شود خروجی blame داده‌های تبدیل‌نشده باشد. برای اطلاعات بیشتر، توضیحات مربوط به کدگذاری را در صفحه راهنمای git-log(1) ببینید.

--contents <file>

حاشیه‌نویسی را با استفاده از محتوای <file> انجام می‌دهد، که در صورت تعیین <rev> از آن ویرایش آغاز می‌شود، و در غیر این صورت از HEAD شروع خواهد شد. می‌توانید - را تعیین کنید تا دستور، محتویات فایل را از ورودی استاندارد بخواند.

--date <format>

قالب مورد استفاده برای خروجی تاریخ‌ها را مشخص می‌کند. اگر --date ارائه نشود، از مقدار متغیر پیکربندی blame.date استفاده می‌شود. اگر متغیر پیکربندی blame.date نیز تنظیم نشده باشد، از قالب iso استفاده خواهد شد. برای مقادیر پشتیبانی‌شده، توضیحات مربوط به گزینه --date را در git-log(1) ببینید.

--progress, --no-progress

گزارش پیشرفت را در جریان خطای استاندارد فعال می‌کند، حتی اگر به یک ترمینال متصل نباشد. به صورت پیش‌فرض، وضعیت پیشرفت تنها زمانی گزارش می‌شود که به ترمینال متصل باشد. شما نمی‌توانید از --progress همراه با --porcelain یا --incremental استفاده کنید.

-M[<num>]

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

<num> اختیاری است، اما حد پایینی بر تعداد کاراکترهای حرفی‌عددی است که گیت باید به عنوان جابجایی/کپی درون یک فایل تشخیص دهد تا آن خطوط را به کامیت والد مرتبط سازد. مقدار پیش‌فرض ۲۰ است.

-C[<num>]

علاوه بر -M، خطوط جابجا شده یا کپی شده از سایر فایل‌هایی را که در همان کامیت تغییر یافته‌اند تشخیص می‌دهد. این ویژگی زمانی مفید است که برنامه خود را بازسازماندهی کرده و کدها را بین فایل‌های مختلف جابجا می‌کنید. هنگامی که این گزینه دو بار داده شود، دستور همچنین به دنبال کپی‌ها از سایر فایل‌ها در کامیتی می‌گردد که فایل را ایجاد کرده است. هنگامی که این گزینه سه بار داده شود، دستور علاوه بر آن به دنبال کپی‌ها از سایر فایل‌ها در هر کامیتی می‌گردد.

<num> اختیاری است، اما حد پایینی برای تعداد کاراکترهای حرفی‌عددی است که گیت باید به عنوان جابجایی/کپی بین فایل‌ها تشخیص دهد تا بتواند آن خطوط را به کامیت والد نسبت دهد. مقدار پیش‌فرض ۴۰ است. اگر بیش از یک گزینه -C داده شود، آرگومان <num> آخرین گزینه -C اعمال خواهد شد.

--ignore-rev <rev>

تغییرات ایجادشده توسط آن ویرایش را هنگام انتساب منشا خطوط نادیده می‌گیرد، به گونه‌ای که گویی این تغییر هرگز رخ نداده است. خطوطی که توسط یک کامیت نادیده‌گرفته‌شده تغییر یافته یا اضافه شده‌اند، به کامیت قبلی که آن خط یا خطوط مجاور را تغییر داده است منتسب می‌شوند. این گزینه ممکن است چندین بار برای نادیده گرفتن بیش از یک ویرایش مشخص شود. اگر گزینه پیکربندی blame.markIgnoredLines تنظیم شده باشد، خطوطی که توسط یک کامیت نادیده‌گرفته‌شده تغییر یافته و به کامیت دیگری منتسب شده‌اند، با یک علامت ? در خروجی blame مشخص می‌شوند. اگر گزینه پیکربندی blame.markUnblamableLines تنظیم شده باشد، آن خطوطی که توسط یک کامیت نادیده‌گرفته‌شده دستکاری شده‌اند و نتوانسته‌ایم آن‌ها را به ویرایش دیگری منتسب کنیم، با یک علامت * مشخص می‌شوند. در حالت‌های porcelain، به ترتیب عبارات ignored و unblamable در یک خط جدید چاپ می‌شوند.

--ignore-revs-file <file>

ویرایش‌های فهرست‌شده در <file> را که باید در همان قالب fsck.skipList باشد، نادیده می‌گیرد. این گزینه می‌تواند تکرار شود، و این فایل‌ها پس از هر فایلی که با گزینه پیکربندی blame.ignoreRevsFile تعیین شده باشد، پردازش خواهند شد. یک نام فایل خالی، ""، فهرست ویرایش‌های به‌دست‌آمده از فایل‌های پردازش‌شده قبلی را پاک خواهد کرد.

--color-lines

حاشیه‌نویسی‌های خطوط را در قالب پیش‌فرض به رنگ‌های متفاوتی درمی‌آورد اگر از همان کامیت خط قبلی آمده باشند. این کار تشخیص بلوک‌های کد اضافه‌شده توسط کامیت‌های مختلف را آسان‌تر می‌کند. رنگ پیش‌فرض فیروزه‌ای (cyan) است و می‌تواند با استفاده از گزینه پیکربندی color.blame.repeatedLines تنظیم شود.

--color-by-age

حاشیه‌نویسی‌های خطوط را در قالب پیش‌فرض بسته به قدمت خط رنگ‌آمیزی می‌کند. گزینه پیکربندی color.blame.highlightRecent کنترل می‌کند که برای هر بازه قدمت از چه رنگی استفاده شود.

-h

نمایش پیام راهنما.

git-blame(1)

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

2026-06-29 Git 2.55.0