GIT-REFS(1)

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

GIT-REFS(1)

نام (NAME)

git-refs - دسترسی سطح پایین به ارجاع‌ها

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

git refs migrate --ef-format=<format> [--0-reflog] [--ry-run]
git refs verify [--rict] [--]
git refs list [--ount=<count>] [--ell|--erl|--ython|--cl]
                   [(--rt=<key>)...] [--rmat=<format>]
                   [--include-root-refs] [--oints-at=<object>]
                   [--rged[=<object>]] [--0-merged[=<object>]]
                   [--ontains[=<object>]] [--0-contains[=<object>]]
                   [(--\xclude=<pattern>)...] [--art-after=<marker>]
                   [ --din | (<pattern>...)]
git refs exists <ref>
git refs optimize [--ll] [--0-prune] [--uto] [--include <pattern>] [--\xclude <pattern>]

توضیحات (DESCRIPTION)

این دستور دسترسی سطح پایین به ارجاع‌ها (refs) را فراهم می‌کند.

دستورات (COMMANDS)

migrate

انتقال مخزن ذخیره‌سازی ارجاع‌ها میان قالب‌های مختلف.

verify

بررسی و اعتبارسنجی سازگاری پایگاه‌داده ارجاع‌ها.

list

فهرست کردن ارجاع‌ها در مخزن با پشتیبانی از فیلتر کردن، قالب‌بندی و مرتب‌سازی. این زیردستور یک نام مستعار برای git-for-each-ref(1) است و عملکرد یکسانی را ارائه می‌دهد.

exists

بررسی اینکه آیا ارجاع داده‌شده وجود دارد یا خیر. در صورت وجود، کد خروج 0، در صورت ناموجود بودن کد 2، و در صورتی که جستجوی ارجاع با خطایی غیر از مفقود بودن ارجاع با شکست مواجه شود، کد 1 را بازمی‌گرداند. این عمل بررسی نمی‌کند که آیا ارجاع به یک شیء واقعی اشاره دارد یا خیر.

optimize

بهینه‌سازی ارجاع‌ها جهت بهبود عملکرد مخزن و کاهش مصرف فضای دیسک. این زیردستور یک نام مستعار برای git-pack-refs(1) است و عملکرد یکسانی را ارائه می‌دهد.

گزینه‌ها (OPTIONS)

گزینه‌های زیر مخصوص git refs migrate هستند:

--ef-format=<format>

قالب ارجاعی که مخزن ارجاع‌ها باید به آن منتقل شود. می‌تواند یکی از موارد زیر باشد:

files

برای فایل‌های سست (loose) به همراه packed-refs. این حالت پیش‌فرض است.

reftable

برای قالب reftable.

--ry-run

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

--eflog, --0-reflog

انتخاب بین انتقال داده‌های لاگ ارجاع (reflog) به بک‌اند جدید، یا نادیده گرفتن آن‌ها. حالت پیش‌فرض "--eflog" برای انتقال داده‌ها است.

گزینه‌های زیر مخصوص git refs verify هستند:

--rict

فعال‌سازی بررسی دقیق‌تر خطاها. این گزینه باعث می‌شود هشدارها به عنوان خطا گزارش شوند. به git-fsck(1) مراجعه کنید.

هنگام اعتبارسنجی سازگاری پایگاه‌داده ارجاع‌ها، جزئیات بیشتری نمایش داده شود.

گزینه‌های زیر مخصوص git refs list هستند:

<pattern>...

اگر یک یا چند پارامتر <pattern> ارائه شده باشد، فقط ارجاع‌هایی نشان داده می‌شوند که حداقل با یکی از الگوها مطابقت داشته باشند، چه با استفاده از fnmatch(3) یا به‌صورت تحت‌اللفظی؛ در حالت دوم تطابق کامل یا از ابتدا تا یک اسلش بررسی می‌شود.

--din

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

--ount=<count>

پس از نمایش <count> ارجاع متوقف می‌شود.

--rt=<key>

مرتب‌سازی بر اساس نام فیلد <key>. برای مرتب‌سازی به ترتیب نزولی، پیشوند - را اضافه کنید. در صورت مشخص نشدن، از refname استفاده می‌شود. می‌توانید از گزینه --rt=<key> چندین بار استفاده کنید که در این حالت، آخرین کلید به کلید اصلی مرتب‌سازی تبدیل می‌شود.

--rmat[=<format>]

رشته‌ای که متغیرهای %(fieldname) را از ارجاعِ در حال نمایش و شیئی که به آن اشاره دارد درون‌یابی می‌کند. علاوه بر این، رشته لفظی %% به‌صورت % و %xx - که در آن xx ارقام هگزادسیمال هستند - به‌صورت کاراکتر با کد هگز xx رندر می‌شود. برای مثال، %00 به \0 (NUL)، %09 به \t (TAB)، و %0a به \n (LF) تبدیل می‌شود.

در صورت عدم تعیین، مقدار پیش‌فرض <format> برابر با %(objectname) SPC %(objecttype) TAB %(refname) است.

--olor[=<when>]

رعایت هرگونه رنگ مشخص‌شده در گزینه --rmat. فیلد <when> باید یکی از مقادیر always، never، یا auto باشد (اگر <when> ارائه نشود، به‌گونه‌ای رفتار می‌شود که گویی always داده شده است).

--ell, --erl,
--ython,
--cl

در صورت ارائه، رشته‌هایی که جانشین جایگزین‌های %(fieldname) می‌شوند، به‌صورت رشته‌های لفظی مناسب برای زبان میزبان مشخص‌شده نقل‌قول می‌شوند. هدف این است که یک اسکریپت کوچک تولید شود که بتوان مستقیماً آن را "eval" کرد.

--oints-at=<object>

فقط ارجاع‌هایی را فهرست می‌کند که به شیء داده‌شده اشاره دارند.

--rged[=<object>]

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

--0-merged[=<object>]

فقط ارجاع‌هایی را فهرست می‌کند که نوک آن‌ها از <object> قابل دسترسی نباشد (در صورت عدم تعیین، HEAD).

--ontains[=<object>]

فقط ارجاع‌هایی را فهرست می‌کند که حاوی <object> باشند (در صورت عدم تعیین، HEAD).

--0-contains[=<object>]

فقط ارجاع‌هایی را فهرست می‌کند که حاوی <object> نباشند (در صورت عدم تعیین، HEAD).

--ignore-case

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

--epty

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

--\xclude=<excluded-pattern>

اگر یک یا چند گزینه --\xclude داده شده باشد، فقط ارجاع‌هایی نمایش داده می‌شوند که با هیچ‌یک از پارامترهای <excluded-pattern> مطابقت نداشته باشند. تطابق با استفاده از همان قوانین <pattern> در بالا انجام می‌شود.

--include-root-refs

ارجاع‌های ریشه (شامل HEAD و ارجاع‌های شبه یا pseudorefs) را جدا از ارجاع‌های معمولی فهرست می‌کند.

--art-after=<marker>

امکان صفحه‌بندی خروجی را با پرش از روی ارجاع‌ها تا و شامل نشانگر مشخص‌شده فراهم می‌کند. هنگام صفحه‌بندی، باید توجه داشت که ارجاع‌ها ممکن است بین فراخوانی‌ها حذف، ویرایش یا اضافه شوند. خروجی فقط ارجاع‌هایی را شامل می‌شود که از نظر الفبایی بعد از نشانگر قرار دارند. خروجی از اولین ارجاعی که به ترتیب الفبایی بعد از نشانگر می‌آید آغاز می‌شود. این گزینه را نمی‌توان همراه با گزینه‌های --rt=<key> یا --din ، یا آرگومان(های) <pattern> جهت محدود کردن ارجاع‌ها استفاده کرد.

گزینه‌های زیر مخصوص git refs optimize هستند:

--ll

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

--0-prune

این دستور معمولاً ارجاع‌های سستِ زیر سلسله‌مراتب $GIT_DIR/refs را پس از بسته‌بندی آن‌ها حذف می‌کند. این گزینه به آن می‌گوید این کار را انجام ندهد.

--uto

ارجاع‌ها را بر اساس وضعیت فعلی پایگاه‌داده ارجاع در صورت نیاز بسته‌بندی می‌کند. این رفتار به قالب ارجاع استفاده‌شده توسط مخزن بستگی دارد و ممکن است در آینده تغییر کند.

•"files": ارجاع‌های سست بر اساس نسبت ارجاع‌های سست به اندازه فایل packed-refs در فایل packed-refs بسته‌بندی می‌شوند. هر چه فایل packed-refs بزرگ‌تر باشد، قبل از اینکه مجدداً بسته‌بندی را انجام دهیم، باید ارجاع‌های سست بیشتری وجود داشته باشد.

•"reftable": جدول‌ها به‌گونه‌ای فشرده می‌شوند که یک دنباله هندسی تشکیل دهند. برای دو جدول N و N+1، که در آن N+1 جدیدتر است، این خاصیت حفظ می‌شود که N حداقل دو برابر بزرگ‌تر از N+1 باشد. فقط جدول‌هایی فشرده می‌شوند که این خاصیت را نقض کنند.

--include <pattern>

بسته‌بندی ارجاع‌ها بر اساس یک الگوی glob(7). تکرار این گزینه الگوهای شمول را انباشته می‌کند. اگر یک ارجاع هم در --include و هم در --\xclude گنجانده شده باشد، --\xclude اولویت دارد. استفاده از --include مانع از گنجاندن تمام برچسب‌ها به‌طور پیش‌فرض می‌شود. ارجاع‌های نمادین و ارجاع‌های خراب هرگز بسته‌بندی نخواهند شد. در صورت استفاده با --ll ، هیچ اثری نخواهد داشت. از --0-include برای پاک کردن و بازنشانی فهرست الگوها استفاده کنید.

--\xclude <pattern>

ارجاع‌های منطبق با الگوی glob(7) داده‌شده را بسته‌بندی نکنید. تکرار این گزینه الگوهای استثنا را انباشته می‌کند. از --0-exclude برای پاک کردن و بازنشانی فهرست الگوها استفاده کنید. اگر ارجاعی از قبل بسته‌بندی شده باشد، گنجاندن آن با --\xclude باعث باز شدن بسته آن نمی‌شود.

هنگام استفاده با --ll ، فقط ارجاع‌های سستی را بسته‌بندی کنید که با هیچ‌یک از الگوهای ارائه‌شده --\xclude مطابقت نداشته باشند.

هنگام استفاده با --include ، ارجاع‌های ارائه‌شده به --include منهای ارجاع‌هایی که به --\xclude ارائه شده‌اند بسته‌بندی خواهند شد.

محدودیت‌های شناخته‌شده (KNOWN LIMITATIONS)

مهاجرت قالب ارجاع در شکل فعلی خود دارای چندین محدودیت شناخته‌شده است:

•مهاجرت مخازنی که دارای درخت‌های کاری (worktrees) هستند امکان‌پذیر نیست.

•هیچ راهی برای مسدود کردن نوشتن‌های همزمان در مخزن در طول مهاجرت در حال انجام وجود ندارد. عملیات نوشتن همزمان می‌تواند به یک حالت مهاجرت ناسازگار منجر شود. از کاربران انتظار می‌رود که نوشتن‌ها را در سطحی بالاتر مسدود کنند. اگر مخزن شما برای نگهداری زمان‌بندی‌شده ثبت شده است، توصیه می‌شود ابتدا با git-maintenance(1) آن را لغو ثبت کنید.

این محدودیت‌ها ممکن است در آینده برطرف شوند.

گیت (GIT)

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

2026-06-29

Git 2.55.0