'\" t
.\"     Title: git-refs
.\"    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: دستورات عمومی کاربر
.\"    Source: Git 2.55.0
.\"  Language: Persian
.\"
.TH "GIT\-REFS" "1" "2026\-06\-29" "Git 2\&.55\&.0" "دستورات عمومی کاربر"
.\" -----------------------------------------------------------------
.\" * 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-refs \- دسترسی سطح پایین به ارجاع‌ها
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fBgit\fR \fBrefs\fR \fBmigrate\fR \fB\-\-\ref\-format=\fR\fI<format>\fR [\fB\-\-\no\-reflog\fR] [\fB\-\-\dry\-run\fR]
\fBgit\fR \fBrefs\fR \fBverify\fR [\fB\-\-\strict\fR] [\fB\-\-\verbose\fR]
\fBgit\fR \fBrefs\fR \fBlist\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)]
\fBgit\fR \fBrefs\fR \fBexists\fR \fI<ref>\fR
\fBgit\fR \fBrefs\fR \fBoptimize\fR [\fB\-\-\all\fR] [\fB\-\-\no\-prune\fR] [\fB\-\-\auto\fR] [\fB\-\-\include\fR \fI<pattern>\fR] [\fB\-\-\exclude\fR \fI<pattern>\fR]
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
این دستور دسترسی سطح پایین به ارجاع‌ها (refs) را فراهم می‌کند\&.
.SH "دستورات (COMMANDS)"
.PP
\fBmigrate\fR
.RS 4
انتقال مخزن ذخیره‌سازی ارجاع‌ها میان قالب‌های مختلف\&.
.RE
.PP
\fBverify\fR
.RS 4
بررسی و اعتبارسنجی سازگاری پایگاه‌داده ارجاع‌ها\&.
.RE
.PP
list
.RS 4
فهرست کردن ارجاع‌ها در مخزن با پشتیبانی از فیلتر کردن، قالب‌بندی و مرتب‌سازی\&. این زیردستور یک نام مستعار برای
\fBgit-for-each-ref\fR(1)
است و عملکرد یکسانی را ارائه می‌دهد\&.
.RE
.PP
exists
.RS 4
بررسی اینکه آیا ارجاع داده‌شده وجود دارد یا خیر\&. در صورت وجود، کد خروج 0، در صورت ناموجود بودن کد 2، و در صورتی که جستجوی ارجاع با خطایی غیر از مفقود بودن ارجاع با شکست مواجه شود، کد 1 را بازمی‌گرداند\&. این عمل بررسی نمی‌کند که آیا ارجاع به یک شیء واقعی اشاره دارد یا خیر\&.
.RE
.PP
optimize
.RS 4
بهینه‌سازی ارجاع‌ها جهت بهبود عملکرد مخزن و کاهش مصرف فضای دیسک\&. این زیردستور یک نام مستعار برای
\fBgit-pack-refs\fR(1)
است و عملکرد یکسانی را ارائه می‌دهد\&.
.RE
.SH "گزینه‌ها (OPTIONS)"
.sp
گزینه‌های زیر مخصوص \fBgit\fR \fBrefs\fR \fBmigrate\fR هستند:
.PP
\fB\-\-\ref\-format=\fR\fI<format>\fR
.RS 4
قالب ارجاعی که مخزن ارجاع‌ها باید به آن منتقل شود\&. می‌تواند یکی از موارد زیر باشد:
.PP
\fBfiles\fR
.RS 4
برای فایل‌های سست (loose) به همراه packed\-refs\&. این حالت پیش‌فرض است\&.
.RE
.PP
\fBreftable\fR
.RS 4
برای قالب reftable\&.
.RE
.RE
.PP
\fB\-\-\dry\-run\fR
.RS 4
انتقال را انجام می‌دهد، اما مخزن را اصلاح نمی‌کند\&. ارجاع‌های منتقل‌شده در یک پوشه جداگانه نوشته می‌شوند که می‌توان آن را به‌طور مستقل بررسی کرد\&. نام پوشه در stdout گزارش می‌شود\&. این گزینه می‌تواند برای بررسی مجدد و اطمینان از عملکرد صحیح انتقال قبل از انجام انتقال واقعی استفاده شود\&.
.RE
.PP
\fB\-\-\reflog\fR, \fB\-\-\no\-reflog\fR
.RS 4
انتخاب بین انتقال داده‌های لاگ ارجاع (reflog) به بک‌اند جدید، یا نادیده گرفتن آن‌ها\&. حالت پیش‌فرض "\-\-\reflog" برای انتقال داده‌ها است\&.
.RE
.sp
گزینه‌های زیر مخصوص \fBgit\fR \fBrefs\fR \fBverify\fR هستند:
.PP
\fB\-\-\strict\fR
.RS 4
فعال‌سازی بررسی دقیق‌تر خطاها\&. این گزینه باعث می‌شود هشدارها به عنوان خطا گزارش شوند\&. به
\fBgit-fsck\fR(1)
مراجعه کنید\&.
.RE
.PP
\fB\-\-\verbose\fR
.RS 4
هنگام اعتبارسنجی سازگاری پایگاه‌داده ارجاع‌ها، جزئیات بیشتری نمایش داده شود\&.
.RE
.sp
گزینه‌های زیر مخصوص \fIgit refs list\fR هستند:
.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)
می‌شوند، به‌صورت رشته‌های لفظی مناسب برای زبان میزبان مشخص‌شده نقل‌قول می‌شوند\&. هدف این است که یک اسکریپت کوچک تولید شود که بتوان مستقیماً آن را "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
و ارجاع‌های شبه یا pseudorefs) را جدا از ارجاع‌های معمولی فهرست می‌کند\&.
.RE
.PP
\fB\-\-\start\-after=\fR\fI<marker>\fR
.RS 4
امکان صفحه‌بندی خروجی را با پرش از روی ارجاع‌ها تا و شامل نشانگر مشخص‌شده فراهم می‌کند\&. هنگام صفحه‌بندی، باید توجه داشت که ارجاع‌ها ممکن است بین فراخوانی‌ها حذف، ویرایش یا اضافه شوند\&. خروجی فقط ارجاع‌هایی را شامل می‌شود که از نظر الفبایی بعد از نشانگر قرار دارند\&. خروجی از اولین ارجاعی که به ترتیب الفبایی بعد از نشانگر می‌آید آغاز می‌شود\&. این گزینه را نمی‌توان همراه با گزینه‌های
\fB\-\-\sort=\fR\fI<key>\fR
یا
\fB\-\-\stdin\fR
، یا آرگومان(های)
\fI<pattern>\fR
جهت محدود کردن ارجاع‌ها استفاده کرد\&.
.RE
.sp
گزینه‌های زیر مخصوص \fIgit refs optimize\fR هستند:
.PP
\-\-\all
.RS 4
این دستور به‌طور پیش‌فرض تمام برچسب‌ها و ارجاع‌هایی را که از قبل بسته‌بندی شده‌اند بسته‌بندی می‌کند و سایر ارجاع‌ها را به حال خود رها می‌کند\&. علت این است که انتظار می‌رود شاخه‌ها به‌طور فعال توسعه یابند و بسته‌بندی نوک آن‌ها کمکی به عملکرد نمی‌کند\&. این گزینه باعث می‌شود که تمام ارجاع‌ها نیز بسته‌بندی شوند، به استثنای ارجاع‌های پنهان، ارجاع‌های خراب و ارجاع‌های نمادین\&. برای مخزنی با شاخه‌های بسیار از دوره‌های پیشین مفید است\&.
.RE
.PP
\-\-\no\-prune
.RS 4
این دستور معمولاً ارجاع‌های سستِ زیر سلسله‌مراتب
\fB$GIT_DIR/refs\fR
را پس از بسته‌بندی آن‌ها حذف می‌کند\&. این گزینه به آن می‌گوید این کار را انجام ندهد\&.
.RE
.PP
\-\-\auto
.RS 4
ارجاع‌ها را بر اساس وضعیت فعلی پایگاه‌داده ارجاع در صورت نیاز بسته‌بندی می‌کند\&. این رفتار به قالب ارجاع استفاده‌شده توسط مخزن بستگی دارد و ممکن است در آینده تغییر کند\&.
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"files": ارجاع‌های سست بر اساس نسبت ارجاع‌های سست به اندازه فایل
\fBpacked\-refs\fR
در فایل
\fBpacked\-refs\fR
بسته‌بندی می‌شوند\&. هر چه فایل
\fBpacked\-refs\fR
بزرگ‌تر باشد، قبل از اینکه مجدداً بسته‌بندی را انجام دهیم، باید ارجاع‌های سست بیشتری وجود داشته باشد\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
"reftable": جدول‌ها به‌گونه‌ای فشرده می‌شوند که یک دنباله هندسی تشکیل دهند\&. برای دو جدول N و N+1، که در آن N+1 جدیدتر است، این خاصیت حفظ می‌شود که N حداقل دو برابر بزرگ‌تر از N+1 باشد\&. فقط جدول‌هایی فشرده می‌شوند که این خاصیت را نقض کنند\&.
.RE
.RE
.PP
\-\-\include <pattern>
.RS 4
بسته‌بندی ارجاع‌ها بر اساس یک الگوی
\fBglob\fR(\fB7\fR)\&.
تکرار این گزینه الگوهای شمول را انباشته می‌کند\&. اگر یک ارجاع هم در
\fB\-\-\include\fR
و هم در
\fB\-\-\exclude\fR
گنجانده شده باشد،
\fB\-\-\exclude\fR
اولویت دارد\&. استفاده از
\fB\-\-\include\fR
مانع از گنجاندن تمام برچسب‌ها به‌طور پیش‌فرض می‌شود\&. ارجاع‌های نمادین و ارجاع‌های خراب هرگز بسته‌بندی نخواهند شد\&. در صورت استفاده با
\fB\-\-\all\fR
، هیچ اثری نخواهد داشت\&. از
\fB\-\-\no\-include\fR
برای پاک کردن و بازنشانی فهرست الگوها استفاده کنید\&.
.RE
.PP
\-\-\exclude <pattern>
.RS 4
ارجاع‌های منطبق با الگوی
\fBglob\fR(\fB7\fR)
داده‌شده را بسته‌بندی نکنید\&. تکرار این گزینه الگوهای استثنا را انباشته می‌کند\&. از
\fB\-\-\no\-exclude\fR
برای پاک کردن و بازنشانی فهرست الگوها استفاده کنید\&. اگر ارجاعی از قبل بسته‌بندی شده باشد، گنجاندن آن با
\fB\-\-\exclude\fR
باعث باز شدن بسته آن نمی‌شود\&.
.sp
هنگام استفاده با
\fB\-\-\all\fR
، فقط ارجاع‌های سستی را بسته‌بندی کنید که با هیچ‌یک از الگوهای ارائه‌شده
\fB\-\-\exclude\fR
مطابقت نداشته باشند\&.
.sp
هنگام استفاده با
\fB\-\-\include\fR
، ارجاع‌های ارائه‌شده به
\fB\-\-\include\fR
منهای ارجاع‌هایی که به
\fB\-\-\exclude\fR
ارائه شده‌اند بسته‌بندی خواهند شد\&.
.RE
.SH "محدودیت‌های شناخته‌شده (KNOWN LIMITATIONS)"
.sp
مهاجرت قالب ارجاع در شکل فعلی خود دارای چندین محدودیت شناخته‌شده است:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
مهاجرت مخازنی که دارای درخت‌های کاری (worktrees) هستند امکان‌پذیر نیست\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
هیچ راهی برای مسدود کردن نوشتن‌های همزمان در مخزن در طول مهاجرت در حال انجام وجود ندارد\&. عملیات نوشتن همزمان می‌تواند به یک حالت مهاجرت ناسازگار منجر شود\&. از کاربران انتظار می‌رود که نوشتن‌ها را در سطحی بالاتر مسدود کنند\&. اگر مخزن شما برای نگهداری زمان‌بندی‌شده ثبت شده است، توصیه می‌شود ابتدا با git\-maintenance(1) آن را لغو ثبت کنید\&.
.RE
.sp
این محدودیت‌ها ممکن است در آینده برطرف شوند\&.
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)