'\" t
.\"     Title: git-for-each-ref
.\"    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: English
.\"
.TH "GIT\-FOR\-EACH\-REF" "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-for-each-ref \- چاپ اطلاعات برای هر یک از مراجع
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fBgit\fR \fBfor\-each\-ref\fR [\fB\-\-count=\fR\fI<count>\fR] [\fB\-\-shell\fR|\fB\-\-perl\fR|\fB\-\-python\fR|\fB\-\-tcl\fR]
                   [(\fB\-\-sort=\fR\fI<key>\fR)\&...] [\fB\-\-format=\fR\fI<format>\fR]
                   [\fB\-\-include\-root\-refs\fR] [\fB\-\-points\-at=\fR\fI<object>\fR]
                   [\fB\-\-merged\fR[\fB=\fR\fI<object>\fR]] [\fB\-\-no\-merged\fR[\fB=\fR\fI<object>\fR]]
                   [\fB\-\-contains\fR[\fB=\fR\fI<object>\fR]] [\fB\-\-no\-contains\fR[\fB=\fR\fI<object>\fR]]
                   [(\fB\-\-exclude=\fR\fI<pattern>\fR)\&...] [\fB\-\-start\-after=\fR\fI<marker>\fR]
                   [ \fB\-\-stdin\fR | (\fI<pattern>\fR\fB\&...\fR)]
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
پیمایش روی تمامی مراجعی که با \fI<pattern>\fR مطابقت دارند و نمایش آن‌ها بر اساس \fI<format>\fR داده‌شده، پس از مرتب‌سازی آن‌ها بر اساس مجموعه \fI<key>\fR ارائه‌شده\&. اگر \fI<count>\fR داده شود، پس از نمایش آن تعداد مرجع متوقف می‌شود\&. مقادیر جای‌گذاری‌شده در \fI<format>\fR را می‌توان به‌صورت اختیاری به شکل رشته‌های متنی در زبان میزبان مشخص‌شده نقل‌قول (quote) کرد تا امکان ارزیابی مستقیم آن‌ها در آن زبان فراهم شود\&.
.SH "گزینه‌ها (OPTIONS)"
.PP
\fI<pattern>\fR\&.\&.\&.
.RS 4
اگر یک یا چند پارامتر
\fI<pattern>\fR
داده شود، تنها مراجعی نشان داده می‌شوند که حداقل با یکی از الگوها مطابقت داشته باشند؛ چه با استفاده از
\fBfnmatch\fR(3) یا به‌صورت تحت‌اللفظی، که در حالت دوم تطبیق یا به‌طور کامل یا از ابتدا تا یک علامت اسلش انجام می‌شود\&.
.RE
.PP
\fB\-\-stdin\fR
.RS 4
فهرست الگوها به جای فهرست آرگومان‌ها از ورودی استاندارد خوانده می‌شود\&.
.RE
.PP
\fB\-\-count=\fR\fI<count>\fR
.RS 4
توقف پس از نمایش
\fI<count>\fR
مرجع\&.
.RE
.PP
\fB\-\-sort=\fR\fI<key>\fR
.RS 4
مرتب‌سازی بر اساس نام فیلد
\fI<key>\fR\&.
برای مرتب‌سازی نزولی بر اساس مقدار، پیشوند
\fB\-\fR
را اضافه کنید\&. در صورت عدم تعیین، از
\fBrefname\fR
استفاده می‌شود\&. می‌توانید از گزینه
\fB\-\-sort=\fR\fI<key>\fR
چندین بار استفاده کنید که در این صورت آخرین کلید به عنوان کلید اصلی در نظر گرفته می‌شود\&.
.RE
.PP
\fB\-\-format\fR[\fB=\fR\fI<format>\fR]
.RS 4
رشته‌ای که متغیرهای
\fB%\fR(\fBfieldname\fR) را از مرجع در حال نمایش و شیئی که به آن اشاره می‌کند جای‌گذاری می‌کند\&. علاوه بر این، عبارت متنی
\fB%%\fR
به صورت
\fB%\fR
و
\fB%xx\fR
\- که در آن
\fBxx\fR
ارقام هگزادسیمال هستند \- به صورت نویسه‌ای با کد هگز
\fBxx\fR
رندر می‌شود\&. برای نمونه،
\fB%00\fR
به
\fB\e0\fR
(\fINUL\fR)،
\fB%09\fR
به
\fB\et\fR
(\fITAB\fR)، و
\fB%0a\fR
به
\fB\en\fR
(\fILF\fR)
تبدیل می‌شود\&.
.RE
.sp
در صورت عدم تعیین، \fI<format>\fR به‌طور پیش‌فرض به \fB%\fR(\fBobjectname\fR) \fBSPC\fR \fB%\fR(\fBobjecttype\fR) \fBTAB\fR \fB%\fR(\fBrefname\fR) تنظیم می‌شود\&.
.PP
\fB\-\-color\fR[\fB=\fR\fI<when>\fR]
.RS 4
رعایت رنگ‌های مشخص‌شده در گزینه
\fB\-\-format\fR\&.
فیلد
\fI<when>\fR
باید یکی از مقادیر
\fBalways\fR،
\fBnever\fR، یا
\fBauto\fR
باشد (اگر
\fI<when>\fR
ذکر نشود، مانند این است که
\fBalways\fR
داده شده باشد)\&.
.RE
.PP
\fB\-\-shell\fR, \fB\-\-perl\fR, \fB\-\-python\fR, \fB\-\-tcl\fR
.RS 4
در صورت تعیین، رشته‌هایی که جایگزین متغیرهای نگه‌دارنده
\fB%\fR(\fBfieldname\fR) می‌شوند، به صورت رشته‌های متنی مناسب برای زبان میزبان مشخص‌شده نقل‌قول (quote) می‌شوند\&. هدف از این کار تولید تکه‌کدی است که بتوان آن را مستقیماً با "eval" ارزیابی و اجرا کرد\&.
.RE
.PP
\fB\-\-points\-at=\fR\fI<object>\fR
.RS 4
تنها مراجعی را فهرست می‌کند که به شیء داده‌شده اشاره دارند\&.
.RE
.PP
\fB\-\-merged\fR[\fB=\fR\fI<object>\fR]
.RS 4
تنها مراجعی را فهرست می‌کند که نوک آن‌ها از کامیت مشخص‌شده (در صورت عدم تعیین،
\fBHEAD\fR)
قابل دسترسی است\&.
.RE
.PP
\fB\-\-no\-merged\fR[\fB=\fR\fI<object>\fR]
.RS 4
تنها مراجعی را فهرست می‌کند که نوک آن‌ها از
\fI<object>\fR
(در صورت عدم تعیین،
\fBHEAD\fR)
قابل دسترسی نیست\&.
.RE
.PP
\fB\-\-contains\fR[\fB=\fR\fI<object>\fR]
.RS 4
تنها مراجعی را فهرست می‌کند که حاوی
\fI<object>\fR
(در صورت عدم تعیین،
\fBHEAD\fR)
هستند\&.
.RE
.PP
\fB\-\-no\-contains\fR[\fB=\fR\fI<object>\fR]
.RS 4
تنها مراجعی را فهرست می‌کند که حاوی
\fI<object>\fR
(در صورت عدم تعیین،
\fBHEAD\fR)
نیستند\&.
.RE
.PP
\fB\-\-ignore\-case\fR
.RS 4
مرتب‌سازی و پالایش مراجع بدون در نظر گرفتن بزرگی و کوچکی حروف انجام می‌شود\&.
.RE
.PP
\fB\-\-omit\-empty\fR
.RS 4
پس از مراجع قالب‌بندی‌شده‌ای که فرمت آن‌ها به یک رشته خالی گسترش می‌یابد، خط جدیدی چاپ نکن\&.
.RE
.PP
\fB\-\-exclude=\fR\fI<excluded\-pattern>\fR
.RS 4
اگر یک یا چند گزینه
\fB\-\-exclude\fR
داده شود، تنها مراجعی نمایش داده می‌شوند که با هیچ یک از پارامترهای
\fI<excluded\-pattern>\fR
مطابقت نداشته باشند\&. تطبیق با استفاده از همان قواعد مربوط به
\fI<pattern>\fR
در بالا انجام می‌شود\&.
.RE
.PP
\fB\-\-include\-root\-refs\fR
.RS 4
فهرست کردن مراجع ریشه (
\fBHEAD\fR
و شبه‌مراجع) جدا از مراجع معمولی\&.
.RE
.PP
\fB\-\-start\-after=\fR\fI<marker>\fR
.RS 4
امکان صفحه‌بندی خروجی را با پرش از مراجع تا نشانگر مشخص‌شده (و شامل خود آن) فراهم می‌کند\&. هنگام صفحه‌بندی باید توجه داشت که مراجع ممکن است میان فراخوانی‌ها حذف، تغییر یا اضافه شوند\&. خروجی تنها مراجعی را ارائه می‌دهد که از نظر لغوی پس از نشانگر قرار می‌گیرند\&. خروجی از نخستین مرجعی آغاز می‌شود که از نظر الفبایی پس از نشانگر می‌آید\&. نمی‌توان آن را همراه با گزینه‌های
\fB\-\-sort=\fR\fI<key>\fR
یا
\fB\-\-stdin\fR،
یا آرگومان(های)
\fI<pattern>\fR
برای محدود کردن مراجع استفاده کرد\&.
.RE
.SH "نام‌های فیلد (FIELD NAMES)"
.sp
مقادیر گوناگون برگرفته از فیلدهای ساختاریافته در اشیاء ارجاع‌شده می‌توانند برای جای‌گذاری در خروجی حاصل یا به عنوان کلیدهای مرتب‌سازی استفاده شوند\&.
.sp
برای تمامی اشیاء، نام‌های زیر قابل استفاده هستند:
.PP
\fBrefname\fR
.RS 4
نام مرجع (بخشی که پس از
\fB$GIT_DIR/\fR)\&
می‌آید\&. برای نام کوتاه و بدون ابهام مرجع، پسوند
\fB:short\fR
را اضافه کنید\&. گزینه
\fBcore\&.warnAmbiguousRefs\fR
برای انتخاب حالت اختصار سخت‌گیرانه استفاده می‌شود\&. اگر
\fBlstrip=\fR\fI<n>\fR
(\fBrstrip=\fR\fI<n>\fR)
اضافه شود، تعداد
\fI<n>\fR
مؤلفه مسیر جداشده با اسلش را از ابتدا (انتهای) نام مرجع حذف می‌کند (برای نمونه
\fB%\fR(\fBrefname:lstrip=2\fR)
مقدار
\fBrefs/tags/foo\fR
را به
\fBfoo\fR
و
\fB%\fR(\fBrefname:rstrip=2\fR)
مقدار
\fBrefs/tags/foo\fR
را به
\fBrefs\fR
تبدیل می‌کند)\&. اگر
\fI<n>\fR
یک عدد منفی باشد، به تعداد لازم مؤلفه مسیر از انتهای مشخص‌شده حذف می‌شود تا
\fB\-\fR\fI<n>\fR
مؤلفه مسیر باقی بماند (برای نمونه
\fB%\fR(\fBrefname:lstrip=\-2\fR)
مقدار
\fBrefs/tags/foo\fR
را به
\fBtags/foo\fR
و
\fB%\fR(\fBrefname:rstrip=\-1\fR)
مقدار
\fBrefs/tags/foo\fR
را به
\fBrefs\fR
تبدیل می‌کند)\&. هنگامی که مرجع مؤلفه‌های کافی نداشته باشد، در صورت حذف با
\fI<n>\fR
مثبت نتیجه یک رشته خالی می‌شود، یا اگر با
\fI<N>\fR
منفی حذف شود نام کامل مرجع بازگردانده می‌شود\&. هیچ‌کدام خطا به شمار نمی‌روند\&.
.sp
\fBstrip\fR
می‌تواند به عنوان مترادفی برای
\fBlstrip\fR
استفاده شود\&.
.RE
.PP
\fBobjecttype\fR
.RS 4
نوع شیء (
\fBblob\fR،
\fBtree\fR،
\fBcommit\fR،
\fBtag\fR)\&.
.RE
.PP
\fBobjectsize\fR
.RS 4
اندازه شیء (همان مقداری که
\fIgit cat\-file \-s\fR
گزارش می‌دهد)\&. برای دریافت اندازه اشغال‌شده توسط شیء روی دیسک (به بایت)، پسوند
\fB:disk\fR
را اضافه کنید\&. یادداشت مربوط به اندازه‌ها روی دیسک را در بخش
\fICAVEATS\fR
در زیر ببینید\&.
.RE
.PP
\fBobjectname\fR
.RS 4
نام شیء (معروف به SHA\-1)\&. برای مخفف بدون ابهام نام شیء، پسوند
\fB:short\fR
را اضافه کنید\&. برای اختصار نام شیء با طول دلخواه، پسوند
\fB:short=\fR\fI<length>\fR
را اضافه کنید که حداقل طول آن
\fBMINIMUM_ABBREV\fR
است\&. این طول ممکن است برای اطمینان از یکتا بودن نام شیء افزایش یابد\&.
.RE
.PP
\fBdeltabase\fR
.RS 4
اگر شیء به عنوان دلتا ذخیره شده باشد، این مقدار به نام شیء پایه دلتا (delta base) برای آن شیء گسترش می‌یابد؛ در غیر این صورت به نام شیء پوچ (همه صفرها) تبدیل می‌شود\&.
.RE
.PP
\fBupstream\fR
.RS 4
نام یک مرجع محلی که می‌توان آن را «بالادست» (upstream) مرجع نمایش داده‌شده دانست\&. گزینه‌های
\fB:short\fR،
\fB:lstrip\fR
و
\fB:rstrip\fR
را به همان شیوه
\fBrefname\fR
در بالا پشتیبانی می‌کند\&. علاوه بر این از
\fB:track\fR
برای نمایش "[ahead N, behind M]" و از
\fB:trackshort\fR
برای نمایش نسخه خلاصه: ">" (جلوتر)، "<" (عقب‌تر)، "<>" (هم جلوتر و هم عقب‌تر) یا "=" (همگام) پشتیبانی می‌کند\&. همچنین
\fB:track\fR
هر زمان که با مرجع بالادست نامعلومی روبرو شود عبارت "[gone]" را چاپ می‌کند\&. برای نمایش اطلاعات ردیابی بدون کروشه (یعنی "ahead N, behind M") پسوند
\fB:track\fR,nobracket
را اضافه کنید\&.
.sp
برای هر شاخه ردیابی دوردست
\fB%\fR(\fBupstream\fR)،
عبارات
\fB%\fR(\fBupstream:remotename\fR)
و
\fB%\fR(\fBupstream:remoteref\fR)
به ترتیب به نام مخزن دوردست و نام مرجع دوردست ردیابی‌شده اشاره دارند\&. به عبارت دیگر، شاخه ردیابی دوردست را می‌توان به‌طور صریح و مجزا با استفاده از مشخصه مرجع
\fB%\fR(\fBupstream:remoteref\fR)\fB:%\fR(\fBupstream\fR)
جهت واکشی از
\fB%\fR(\fBupstream:remotename\fR)
به‌روزرسانی کرد\&.
.sp
اگر مرجع فاقد اطلاعات ردیابی مربوطه باشد، هیچ اثری ندارد\&. تمامی گزینه‌ها به جز
\fBnobracket\fR
مانعة‌الجمع هستند، اما اگر با هم استفاده شوند آخرین گزینه انتخاب می‌شود\&.
.RE
.PP
\fBpush\fR
.RS 4
نام یک مرجع محلی که نشان‌دهنده مکان
\fB@\fR{push}
برای مرجع نمایش داده‌شده است\&. همانند
\fBupstream\fR
از گزینه‌های
\fB:short\fR،
\fB:lstrip\fR،
\fB:rstrip\fR،
\fB:track\fR،
\fB:trackshort\fR،
\fB:remotename\fR
و
\fB:remoteref\fR
پشتیبانی می‌کند\&. اگر هیچ مرجع
\fB@\fR{push}
پیکربندی نشده باشد، رشته‌ای خالی تولید می‌کند\&.
.RE
.PP
\fBHEAD\fR
.RS 4
اگر
\fBHEAD\fR
با مرجع جاری (شاخه استخراج‌شده) مطابقت داشته باشد علامت
\fB*\fR،
و در غیر این صورت \*(Aq \*(Aq (یک فاصله)\&.
.RE
.PP
\fBcolor\fR
.RS 4
تغییر رنگ خروجی\&. پس از آن
\fB:\fR\fI<colorname>\fR
می‌آید، که نام‌های رنگ در بخش Values در قسمت "CONFIGURATION FILE" از
\fBgit-config\fR(1)
شرح داده شده‌اند؛ برای نمونه،
\fB%\fR(\fBcolor:bold\fR
\fBred\fR)\&.
.RE
.PP
\fBalign\fR
.RS 4
تراز کردن چپ، وسط یا راست محتوای بین
\fB%\fR(\fBalign:\fR\fB\&.\&.\&.\fR)
و
\fB%\fR(\fBend\fR)\&.
پس از "\fBalign:\fR"، مقادیر
\fBwidth=\fR\fI<width>\fR
و
\fBposition=\fR\fI<position>\fR
به هر ترتیبی و با جداکننده کاما می‌آیند، که در آن
\fI<position>\fR
یکی از مقادیر
\fBleft\fR،
\fBright\fR
یا
\fBmiddle\fR
است (مقدار پیش‌فرض
\fBleft\fR
است) و
\fI<width>\fR
طول کل محتوا با در نظر گرفتن تراز است\&. برای اختصار، پیشوندهای "width=" و/یا "position=" را می‌توان حذف کرد و به جای آن تنها از
\fI<width>\fR
و
\fI<position>\fR
استفاده نمود؛ برای مثال،
\fB%\fR(\fBalign:\fR\fI<width>\fR\fB,\fR\fI<position>\fR)\&.
اگر طول محتوا بیشتر از عرض باشد، هیچ ترازی انجام نمی‌شود\&. در صورت استفاده با
\fB\-\-quote\fR،
تمام موارد میان
\fB%\fR(\fBalign:\fR\fB\&.\&.\&.\fR)
و
\fB%\fR(\fBend\fR)
نقل‌قول می‌شوند، اما در صورت تودرتو بودن، تنها بالاترین سطح نقل‌قول خواهد شد\&.
.RE
.PP
\fBif\fR
.RS 4
به صورت
\fB%\fR(\fBif\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBthen\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBend\fR)
یا
\fB%\fR(\fBif\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBthen\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBelse\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBend\fR)
استفاده می‌شود\&. اگر پس از
\fB%\fR(\fBif\fR)
اتمی دارای مقدار یا یک عبارت رشته‌ای وجود داشته باشد، هر آنچه پس از
\fB%\fR(\fBthen\fR)
باشد چاپ می‌شود؛ در غیر این صورت اگر از اتم
\fB%\fR(\fBelse\fR)
استفاده شده باشد، تمام موارد پس از %(else) چاپ خواهد شد\&. هنگام ارزیابی رشته پیش از
\fB%\fR(\fBthen\fR)،
فاصله‌های خالی نادیده گرفته می‌شوند؛ این امر زمانی مفید است که از اتم
\fB%\fR(\fBHEAD\fR)
استفاده می‌کنیم که یا "\fB*\fR" یا " " را چاپ می‌کند و می‌خواهیم شرط
\fIif\fR
را تنها روی مرجع
\fBHEAD\fR
اعمال کنیم\&. برای مقایسه مقدار میان اتم‌های
\fB%\fR(\fBif:\fR\fB\&.\&.\&.\fR)
و
\fB%\fR(\fBthen\fR)
با رشته داده‌شده، "\fB:equals=\fR\fI<string>\fR" یا "\fB:notequals=\fR\fI<string>\fR" را اضافه کنید\&.
.RE
.PP
\fBsymref\fR
.RS 4
مرجعی که مرجع نمادین مشخص‌شده به آن ارجاع دارد\&. اگر مرجع نمادین نباشد، چیزی چاپ نمی‌شود\&. همانند
\fBrefname\fR
در بالا از گزینه‌های
\fB:short\fR،
\fB:lstrip\fR
و
\fB:rstrip\fR
پشتیبانی می‌کند\&.
.RE
.PP
\fBsignature\fR
.RS 4
امضای GPG یک کامیت\&.
.RE
.PP
\fBsignature:grade\fR
.RS 4
نمایش
.PP
\fBG\fR
.RS 4
برای یک امضای خوب (معتبر)
.RE
.PP
\fBB\fR
.RS 4
برای یک امضای نامعتبر (بد)
.RE
.PP
\fBU\fR
.RS 4
برای یک امضای خوب با اعتبار نامشخص
.RE
.PP
\fBX\fR
.RS 4
برای یک امضای خوب که منقضی شده است
.RE
.PP
\fBY\fR
.RS 4
برای یک امضای خوب ایجادشده با کلیدی که منقضی شده است
.RE
.PP
\fBR\fR
.RS 4
برای یک امضای خوب ایجادشده با کلیدی که لغو (revoked) شده است
.RE
.PP
\fBE\fR
.RS 4
اگر امضا قابل بررسی نباشد (برای نمونه مفقود بودن کلید)
.RE
.PP
\fBN\fR
.RS 4
برای حالت بدون امضا\&.
.RE
.RE
.PP
\fBsignature:signer\fR
.RS 4
امضاکننده امضای GPG یک کامیت\&.
.RE
.PP
\fBsignature:key\fR
.RS 4
کلید امضای GPG یک کامیت\&.
.RE
.PP
\fBsignature:fingerprint\fR
.RS 4
اثر انگشت (fingerprint) امضای GPG یک کامیت\&.
.RE
.PP
\fBsignature:primarykeyfingerprint\fR
.RS 4
اثر انگشت کلید اصلی امضای GPG یک کامیت\&.
.RE
.PP
\fBsignature:trustlevel\fR
.RS 4
سطح اعتماد امضای GPG یک کامیت\&. خروجی‌های ممکن عبارتند از:
\fBultimate\fR،
\fBfully\fR،
\fBmarginal\fR،
\fBnever\fR
و
\fBundefined\fR\&.
.RE
.PP
\fBworktreepath\fR
.RS 4
مسیر مطلق به درخت‌کاری (worktree) که مرجع در آن استخراج شده است، در صورتی که در درختی پیوند‌یافته استخراج شده باشد؛ در غیر این صورت رشته‌ای خالی\&.
.RE
.PP
\fBahead\-behind:\fR\fI<commit\-ish>\fR
.RS 4
دو عدد صحیح جداشده با یک فاصله، که به ترتیب تعداد کامیت‌های جلوتر و عقب‌تر را هنگام مقایسه مرجع خروجی با
\fI<committish>\fR
مشخص‌شده در قالب نشان می‌دهند\&.
.RE
.PP
\fBis\-base:\fR\fI<commit\-ish>\fR
.RS 4
حداکثر در یک ردیف، (\fI<commit\-ish>\fR) ظاهر می‌شود تا مرجعی را نشان دهد که به احتمال زیاد مرجع استفاده‌شده به عنوان نقطه شروع شاخه‌ای است که
\fI<commit\-ish>\fR
را تولید کرده است\&. این انتخاب با استفاده از یک روش ابتکاری (heuristic) انجام می‌شود: انتخاب مرجعی که تعداد کامیت‌ها را در تاریخچه والد اول
\fI<commit\-ish>\fR
و نه در تاریخچه والد اول مرجع، به حداقل می‌رساند\&.
.sp
برای نمونه، نمودار زیر را از تاریخچه‌های والد اول چندین مرجع در نظر بگیرید:
.sp
.if n \{\
.RS 4
.\}
.nf
*\-\-*\-\-*\-\-*\-\-*\-\-* refs/heads/A
\e
 \e
  *\-\-*\-\-*\-\-* refs/heads/B
   \e     \e
    \e     \e
     *     * refs/heads/C
      \e
       \e
        *\-\-* refs/heads/D
.fi
.if n \{\
.RE
.\}
.sp
در اینجا، اگر
\fBA\fR،
\fBB\fR
و
\fBC\fR
مراجع فیلترشده باشند و رشته قالب
\fB%\fR(\fBrefname\fR)\fB:%\fR(\fBis\-base:D\fR)
باشد، خروجی به این صورت خواهد بود:
.sp
.if n \{\
.RS 4
.\}
.nf
refs/heads/A:
refs/heads/B:(D)
refs/heads/C:
.fi
.if n \{\
.RE
.\}
.sp
زیرا تاریخچه والد اول
\fBD\fR
نخستین تقاطع خود را با تاریخچه‌های والد اول مراجع فیلترشده در یک نیای مشترک والد اول از
\fBB\fR
و
\fBC\fR
دارد و در صورت تساوی، نخستین مرجع در ترتیب مرتب‌شده انتخاب می‌شود\&.
.sp
توجه داشته باشید که اگر تاریخچه والد اول
\fI<commit\-ish>\fR
با تاریخچه‌های والد اول مراجع فیلترشده تقاطعی نداشته باشد، این توکن ظاهر نخواهد شد\&.
.RE
.PP
\fBdescribe\fR[\fB:\fR\fI<option>\fR\fB,\fR\&.\&.\&.]
.RS 4
یک نام خوانا برای انسان، مانند
\fBgit-describe\fR(1)؛
رشته‌ای خالی برای کامیت‌های غیرقابل توصیف\&. پس از رشته
\fBdescribe\fR
ممکن است دو نقطه و یک یا چند گزینه جداشده با کاما بیاید\&.
.PP
\fBtags=\fR\fI<bool\-value>\fR
.RS 4
به جای در نظر گرفتن تنها تگ‌های حاشیه‌نویسی‌شده، تگ‌های سبک (lightweight) را نیز لحاظ کن؛ برای جزئیات به گزینه مربوطه در
\fBgit-describe\fR(1)
مراجعه کنید\&.
.RE
.PP
\fBabbrev=\fR\fI<number>\fR
.RS 4
استفاده از حداقل
\fI<number>\fR
رقم هگزادسیمال؛ برای جزئیات به گزینه مربوطه در
\fBgit-describe\fR(1)
مراجعه کنید\&.
.RE
.PP
\fBmatch=\fR\fI<pattern>\fR
.RS 4
تنها تگ‌های منطبق بر الگوی
\fBglob\fR(7)
با نام
\fI<pattern>\fR،
بدون در نظر گرفتن پیشوند
\fBrefs/tags/\fR
را در نظر بگیر؛ برای جزئیات به گزینه مربوطه در
\fBgit-describe\fR(1)
مراجعه کنید\&.
.RE
.PP
\fBexclude=\fR\fI<pattern>\fR
.RS 4
تگ‌های منطبق بر الگوی
\fBglob\fR(7)
با نام
\fI<pattern>\fR،
بدون در نظر گرفتن پیشوند
\fBrefs/tags/\fR
را در نظر نگیر؛ برای جزئیات به گزینه مربوطه در
\fBgit-describe\fR(1)
مراجعه کنید\&.
.RE
.RE
.sp
علاوه بر موارد بالا، برای اشیاء کامیت و تگ، نام فیلدهای سربرگ (\fBtree\fR، \fBparent\fR، \fBobject\fR، \fBtype\fR و \fBtag\fR) را می‌توان برای تعیین مقدار موجود در فیلد سربرگ استفاده کرد\&. فیلدهای \fBtree\fR و \fBparent\fR را نیز می‌توان درست مانند \fBobjectname\fR با اصلاح‌کننده‌های \fB:short\fR و \fB:short=\fR\fI<length>\fR استفاده کرد\&.
.sp
برای اشیاء کامیت و تگ، فیلدهای ویژه \fBcreatordate\fR و \fBcreator\fR بسته به نوع شیء، متناظر با تاریخ مناسب یا چندتایی نام-ایمیل-تاریخ برگرفته از فیلدهای \fBcommitter\fR یا \fBtagger\fR خواهند بود\&. این فیلدها برای کار با ترکیبی از تگ‌های حاشیه‌نویسی‌شده و سبک در نظر گرفته شده‌اند\&.
.sp
برای اشیاء تگ، اگر پیشوند ستاره (\fB*\fR) قبل از \fBfieldname\fR بیاید، به مقدار \fBfieldname\fR شیء پوسته‌گیری‌شده (peeled) گسترش می‌یابد، نه خود شیء تگ\&.
.sp
فیلدهایی که چندتایی نام-ایمیل-تاریخ را به عنوان مقدار خود دارند (\fBauthor\fR، \fBcommitter\fR و \fBtagger\fR) می‌توانند با پسوندهای \fBname\fR، \fBemail\fR و \fBdate\fR همراه شوند تا مؤلفه نام‌برده را استخراج کنند\&. برای فیلدهای ایمیل (\fBauthoremail\fR، \fBcommitteremail\fR و \fBtaggeremail\fR)، می‌توان \fB:trim\fR را اضافه کرد تا ایمیل بدون علامت‌های قلاب‌مانند (<>) به دست آید، و \fB:localpart\fR را برای دریافت بخش پیش از نماد \fB@\fR از ایمیل پیراسته به کار برد\&. علاوه بر این‌ها، گزینه \fB:mailmap\fR و گزینه‌های متناظر \fB:mailmap\fR,trim و \fB:mailmap\fR,localpart را می‌توان (ترتیب اهمیتی ندارد) برای دریافت مقادیر نام و ایمیل مطابق با فایل \&.mailmap یا مطابق با فایل تعیین‌شده در متغیر پیکربندی mailmap\&.file یا mailmap\&.blob استفاده کرد (به \fBgitmailmap\fR(5) مراجعه کنید)\&.
.sp
داده خام در یک شیء، \fBraw\fR است\&.
.PP
\fBraw:size\fR
.RS 4
اندازه داده خام شیء\&.
.RE
.sp
توجه داشته باشید که \fB\-\-format=%\fR(\fBraw\fR) را نمی‌توان همراه با گزینه‌های \fB\-\-python\fR، \fB\-\-shell\fR، \fB\-\-tcl\fR استفاده کرد، زیرا چنین زبان‌هایی ممکن است داده‌های باینری دلخواه را در نوع متغیر رشته‌ای خود پشتیبانی نکنند\&.
.sp
پیام موجود در یک شیء کامیت یا تگ، \fBcontents\fR است که از آن می‌توان \fBcontents:\fR\fI<part>\fR را برای استخراج بخش‌های مختلف به کار برد:
.PP
\fBcontents:size\fR
.RS 4
اندازه پیام کامیت یا تگ به بایت\&.
.RE
.PP
\fBcontents:subject\fR
.RS 4
نخستین پاراگراف پیام، که معمولاً یک خط واحد است، به عنوان «موضوع» (subject) پیام کامیت یا تگ در نظر گرفته می‌شود\&. به جای
\fBcontents:subject\fR،
می‌توان از فیلد
\fBsubject\fR
نیز برای دستیابی به نتایج یکسان استفاده کرد\&. برای به دست آوردن خط موضوع مناسب نام فایل، می‌توان
\fB:sanitize\fR
را به
\fBsubject\fR
الحاق نمود\&.
.RE
.PP
\fBcontents:body\fR
.RS 4
بخش باقی‌مانده از پیام کامیت یا تگ که پس از «موضوع» قرار می‌گیرد\&.
.RE
.PP
\fBcontents:signature\fR
.RS 4
امضای GPG اختیاری تگ\&.
.RE
.PP
\fBcontents:lines=\fR\fI<n>\fR
.RS 4
تعداد
\fI<n>\fR
خط نخست پیام\&.
.RE
.sp
علاوه بر این، تریلرها آن‌گونه که توسط \fBgit-interpret-trailers\fR(1) تفسیر می‌شوند، به صورت \fBtrailers\fR[\fB:\fR\fI<option>\fR\fB,\fR\&.\&.\&.] (یا با استفاده از نام مستعار قدیمی \fBcontents:trailers\fR[\fB:\fR\fI<option>\fR\fB,\fR\&.\&.\&.]) به دست می‌آیند\&. برای مقادیر معتبر \fI<option>\fR، بخش \fBtrailers\fR در \fBgit-log\fR(1) را ببینید\&.
.sp
برای اهداف مرتب‌سازی، فیلدهای دارای مقادیر عددی بر اساس ترتیب عددی مرتب می‌شوند (\fBobjectsize\fR، \fBauthordate\fR، \fBcommitterdate\fR، \fBcreatordate\fR، \fBtaggerdate\fR)\&. تمام فیلدهای دیگر بر اساس ترتیب مقدار بایتی خود مرتب می‌شوند\&.
.sp
همچنین گزینه‌ای برای مرتب‌سازی بر اساس نسخه‌ها وجود دارد که این کار را می‌توان با استفاده از نام فیلد \fBversion:refname\fR یا نام مستعار آن \fBv:refname\fR انجام داد\&.
.sp
در هر صورت، نام فیلدی که به فیلدی غیرقابل اعمال بر شیء ارجاع‌شده توسط مرجع اشاره دارد، باعث بروز خطا نمی‌شود؛ بلکه به جای آن یک رشته خالی برمی‌گرداند\&.
.sp
به عنوان یک حالت خاص برای فیلدهای از نوع تاریخ، می‌توانید با افزودن \fB:\fR و به دنبال آن نام قالب تاریخ، قالبی را برای تاریخ مشخص کنید (مقدارهایی را که گزینه \fB\-\-date\fR در \fBgit-rev-list\fR(1) می‌پذیرد ببینید)\&. اگر این قالب‌بندی در یک کلید \fB\-\-sort\fR ارائه شود، مراجع به جای مقدار عددی برچسب زمانی زیربنایی، بر اساس مقدار بایتی رشته قالب‌بندی‌شده مرتب خواهند شد\&.
.sp
برخی اتم‌ها مانند \fB%\fR(\fBalign\fR) و \fB%\fR(\fBif\fR) همیشه نیازمند یک \fB%\fR(\fBend\fR) منطبق هستند\&. ما به آن‌ها «اتم‌های آغازین» می‌گوییم و گاهی آن‌ها را با \fB%\fR(\fB$open\fR) نشان می‌دهیم\&.
.sp
هنگامی که نقل‌قول ویژه یک زبان اسکریپت‌نویسی فعال است، تمام موارد میان یک اتم آغازین سطح بالا و %(end) منطبق بر آن، بر اساس معناشناسی اتم آغازین ارزیابی می‌شود و تنها نتیجه نهایی آن در سطح بالا نقل‌قول خواهد شد\&.
.SH "مثال‌ها (EXAMPLES)"
.sp
نمونه‌ای که مستقیماً متنی قالب‌بندی‌شده تولید می‌کند\&. نمایش ۳ کامیت تگ‌شده اخیر:
.sp
.if n \{\
.RS 4
.\}
.nf
#!/bin/sh

git for\-each\-ref \-\-count=3 \-\-sort=\*(Aq\-*authordate\*(Aq \e
`\-\-format=\*(AqFrom: %(*authorname) %(*authoremail)
Subject: %(*subject)
Date: %(*authordate)
Ref: %(*refname)

%(*body)
\*(Aq \*(Aqrefs/tags\*(Aq
.fi
.if n \{\
.RE
.\}
.sp
.sp
یک مثال ساده که استفاده از eval در پوسته را روی خروجی نشان می‌دهد و کاربرد \fB\-\-shell\fR را به نمایش می‌گذارد\&. فهرست کردن پیشوندهای تمامی headها:
.sp
.if n \{\
.RS 4
.\}
.nf
#!/bin/sh

git for\-each\-ref \-\-shell \-\-format="ref=%(refname)" refs/heads | \e
while read entry
do
        eval "$entry"
        echo `dirname $ref`
done
.fi
.if n \{\
.RE
.\}
.sp
.sp
گزارشی جامع‌تر درباره تگ‌ها، که نشان می‌دهد قالب می‌تواند یک اسکریپت کامل باشد:
.sp
.if n \{\
.RS 4
.\}
.nf
#!/bin/sh

fmt=\*(Aq
        r=%(refname)
        t=%(*objecttype)
        T=${r#refs/tags/}

        o=%(*objectname)
        n=%(*authorname)
        e=%(*authoremail)
        s=%(*subject)
        d=%(*authordate)
        b=%(*body)

        kind=Tag
        if test "z$t" = z
        then
                # could be a lightweight tag
                t=%(objecttype)
                kind="Lightweight tag"
                o=%(objectname)
                n=%(authorname)
                e=%(authoremail)
                s=%(subject)
                d=%(authordate)
                b=%(body)
        fi
        echo "$kind $T points at a $t object $o"
        if test "z$t" = zcommit
        then
                echo "The commit was authored by $n $e
at $d, and titled

    $s

Its message reads as:
"
                echo "$b" | sed \-e "s/^/    /"
                echo
        fi
\*(Aq

eval=`git for\-each\-ref \-\-shell \-\-format="$fmt" \e
        \-\-sort=\*(Aq*objecttype\*(Aq \e
        \-\-sort=\-taggerdate \e
        refs/tags`
eval "$eval"
.fi
.if n \{\
.RE
.\}
.sp
.sp
نمونه‌ای برای نمایش کاربرد \fB%\fR(\fBif\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBthen\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBelse\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBend\fR)\&. این الگو پیش از نام شاخه جاری یک ستاره قرار می‌دهد\&.
.sp
.if n \{\
.RS 4
.\}
.nf
git for\-each\-ref \-\-format="%(if)%(HEAD)%(then)* %(else)  %(end)%(refname:short)" refs/heads/
.fi
.if n \{\
.RE
.\}
.sp
.sp
نمونه‌ای برای نمایش کاربرد \fB%\fR(\fBif\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBthen\fR)\fB\&.\&.\&.\fR\fB%\fR(\fBend\fR)\&. در صورت وجود، نام نویسنده را چاپ می‌کند\&.
.sp
.if n \{\
.RS 4
.\}
.nf
git for\-each\-ref \-\-format="%(refname)%(if)%(authorname)%(then) Authored by: %(authorname)%(end)"
.fi
.if n \{\
.RE
.\}
.sp
.SH "هشدارها (CAVEATS)"
.sp
توجه داشته باشید که اندازه‌های اشیاء روی دیسک به طور دقیق گزارش می‌شوند، اما باید در نتیجه‌گیری درباره اینکه کدام مراجع یا اشیاء مسئول مصرف فضای دیسک هستند احتیاط کرد\&. اندازه یک شیء بسته‌بندی‌شده غیردلتا ممکن است بسیار بزرگتر از اندازه اشیایی باشد که با آن تفاضل دلتا دارند، اما اینکه کدام شیء به عنوان پایه و کدام یک به عنوان دلتا تعیین شود اختیاری بوده و در طول یک repack دستخوش تغییر می‌شود\&.
.sp
همچنین توجه داشته باشید که ممکن است چندین نسخه از یک شیء در پایگاه داده اشیاء وجود داشته باشد؛ در این حالت، مشخص نیست که اندازه یا پایه دلتای کدام نسخه گزارش خواهد شد\&.
.SH "نکات (NOTES)"
.sp
هنگام ترکیب چندین فیلتر \fB\-\-contains\fR و \fB\-\-no\-contains\fR، تنها مراجعی نمایش داده می‌شوند که حداقل شامل یکی از کامیت‌های \fB\-\-contains\fR بوده و هیچ‌یک از کامیت‌های \fB\-\-no\-contains\fR را در بر نداشته باشند\&.
.sp
هنگام ترکیب چندین فیلتر \fB\-\-merged\fR و \fB\-\-no\-merged\fR، تنها مراجعی نمایش داده می‌شوند که حداقل از یکی از کامیت‌های \fB\-\-merged\fR قابل دسترسی بوده و از هیچ‌یک از کامیت‌های \fB\-\-no\-merged\fR قابل دسترسی نباشند\&.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBgit-show-ref\fR(1)
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)