GITFORMAT-COMMIT-GRAPH(5)

راهنمای Git

GITFORMAT-COMMIT-GRAPH(5)

نام (NAME)

gitformat-commit-graph - ساختار و قالب فایل گراف کامیت (commit-graph) در گیت

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

$GIT_DIR/objects/info/commit-graph
$GIT_DIR/objects/info/commit-graphs/*

توضیحات (DESCRIPTION)

فایل گراف کامیت گیت (commit-graph) فهرستی از شناسه‌های اشیاء کامیت (OID) و برخی فراداده‌های مرتبط را ذخیره می‌کند، از جمله:

•شماره نسل (generation number) کامیت.

•شناسه شیء درخت ریشه (root tree OID).

•تاریخ ثبت کامیت.

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

•فیلتر بلوم (Bloom filter) کامیت حامل مسیرهایی که بین کامیت و والد اول آن تغییر یافته‌اند (در صورت درخواست).

این ارجاع‌های موقعیتی به صورت اعداد صحیح ۳۲ بیتی بدون علامت متناظر با موقعیت آرایه در فهرست OIDهای کامیت ذخیره می‌شوند. به دلیل استفاده از برخی ثابت‌های ویژه برای ردیابی والدین، ما می‌توانیم حداکثر (1 << 30) + (1 << 29) + (1 << 28) - 1 (حدود ۱.۸ میلیارد) کامیت را ذخیره کنیم.

فایل‌های گراف کامیت ساختار زیر را دارند (COMMIT-GRAPH FILES HAVE THE FOLLOWING FORMAT)

به منظور امکان افزودن افزونه‌هایی که داده‌های اضافی به گراف اضافه می‌کنند، ما بدنه را به «قطعات» (chunks) سازمان‌دهی می‌کنیم و یک جدول جستجوی دودویی در ابتدای بدنه ارائه می‌دهیم. سرایند شامل مقادیر خاصی مانند تعداد قطعات و نوع الگوریتم هش است.

تمام اعداد چندبایتی در ترتیب بایت شبکه (network byte order) هستند.

امضای ۴ بایتی:
    امضا عبارت است از: {'C', 'G', 'P', 'H'}

شماره نسخه ۱ بایتی:
    در حال حاضر تنها نسخه معتبر، نسخه ۱ است.

نسخه درهم‌سازی ۱ بایتی (Hash Version):
    طول هش (H) از روی این مقدار استنتاج می‌شود:
      1 => SHA-1
      2 => SHA-256
    اگر نوع هش با الگوریتم هش مخزن مطابقت نداشته باشد، فایل commit-graph
    باید نادیده گرفته شده و یک هشدار به کاربر نمایش داده شود.

تعداد قطعات ۱ بایتی (C)

تعداد گراف‌های پایه ۱ بایتی (B):
    طول قطعه گراف‌های پایه (H*B) از روی این مقدار استنتاج می‌شود.

جستجوی قطعه (CHUNK LOOKUP):

(C + 1) * 12 بایت که فهرست مطالب قطعات را فهرست می‌کند:
    ۴ بایت نخست شناسه قطعه (chunk id) را توصیف می‌کند. مقدار 0 یک برچسب پایان‌دهنده است.
    ۸ بایت دیگر، آفست بایتی در فایل جاری را برای شروع قطعه ارائه می‌دهد.
    (قطعات به طور پیوسته در فایل مرتب شده‌اند، بنابراین در صورت نیاز می‌توانید
    طول را با استفاده از موقعیت قطعه بعدی استنتاج کنید.)
    هر شناسه قطعه حداکثر یک بار ظاهر می‌شود.

بخش CHUNK LOOKUP با فهرست مطالب قالب فایل مبتنی بر قطعه مطابقت دارد؛
به linkgit:gitformat-chunk[5] مراجعه کنید.

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

داده‌های قطعه (CHUNK DATA):

OID Fanout (ID: {O, I, D, F}) (256 * 4 bytes)

ورودی iام، یعنی F[i]، تعداد OIDهایی را که بایت اول آن‌ها حداکثر برابر با
i است ذخیره می‌کند. بنابراین F[255] تعداد کل کامیت‌ها (N) را ذخیره می‌کند.

OID Lookup (ID: {O, I, D, L}) (N * H bytes)

شناسه‌های OID تمام کامیت‌های موجود در گراف، مرتب‌شده به صورت صعودی.

Commit Data (ID: {C, D, A, T }) (N * (H + 16) bytes)

•نخستین H بایت برای OID درخت ریشه است.

•۸ بایت بعدی برای موقعیت‌های دو والد نخستِ کامیت iام است. اگر در آن موقعیت والدی وجود نداشته باشد، مقدار 0x70000000 را ذخیره می‌کند. اگر بیش از دو والد وجود داشته باشد، با ارزش‌ترین بیت مقدار دوم ۱ است و سایر بیت‌ها موقعیت آرایه‌ای را در قطعه Extra Edge List ذخیره می‌کنند.

•۸ بایت بعدی سطح توپولوژیکی (شماره نسل نسخه ۱) کامیت و زمان ثبت کامیت به ثانیه از مبدا زمان (EPOCH) را ذخیره می‌کند. شماره نسل از ۳۰ بیت بالایی ۴ بایت اول استفاده می‌کند، در حالی که زمان ثبت کامیت از ۳۲ بیت ۴ بایت دوم همراه با ۲ بیت کم‌ارزش پایین‌ترین بایت استفاده می‌کند که بیت‌های ۳۳ و ۳۴ زمان ثبت کامیت را ذخیره می‌نمایند.

Generation Data (ID: {G, D, A, 2 }) (N * 4 bytes) [Optional]

•این فهرست از مقادیر ۴ بایتی، آفست‌های اصلاح‌شده تاریخ کامیت را برای کامیت‌ها ذخیره می‌کند که با همان ترتیب قطعه داده‌های کامیت مرتب شده‌اند.

•اگر آفست اصلاح‌شده تاریخ کامیت نتواند در ۳۱ بیت ذخیره شود، پرارزش‌ترین بیت مقدار روشن (۱) خواهد بود و بیت‌های دیگر موقعیت تاریخ کامیت اصلاح‌شده را در قطعه سرریز داده‌های نسل (Generation Data Overflow) ذخیره می‌کنند.

•قطعه داده‌های نسل تنها زمانی وجود دارد که فایل commit-graph توسط نسخه‌های سازگار گیت نوشته شده باشد و در صورت وجود زنجیره‌های گراف کامیت تفکیک‌شده (split commit-graph chains)، بالاترین لایه نیز حاوی قطعه داده‌های نسل خواهد بود.

Generation Data Overflow (ID: {G, D, O, 2 }) [Optional]

•این فهرست از مقادیر ۸ بایتی آفست‌های اصلاح‌شده تاریخ کامیت را برای کامیت‌هایی که آفست آن‌ها در ۳۱ بیت جا نمی‌شود ذخیره می‌کند.

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

Extra Edge List (ID: {E, D, G, E}) [Optional]

این فهرست از مقادیر ۴ بایتی والدین دوم تا nام را برای تمام ادغام‌های اختاپوسی
(octopus merges) ذخیره می‌کند. مقدار والد دوم در داده‌های کامیت، یک موقعیت
آرایه‌ای درون این فهرست را به همراه فعال بودن پرارزش‌ترین بیت ذخیره می‌نماید.
با شروع از آن موقعیت آرایه، این فهرست از موقعیت‌های کامیت برای والدین را پیمایش کنید
تا زمانی که به مقداری برسید که پرارزش‌ترین بیت آن ۱ باشد. بیت‌های دیگر متناظر
با موقعیت والد پایانی هستند.

Bloom Filter Index (ID: {B, I, D, X}) (N * 4 bytes) [Optional]

•ورودی iام، یعنی BIDX[i]، تعداد بایت‌ها در تمام فیلترهای بلوم از کامیت ۰ تا کامیت i (شامل) را به ترتیب واژه‌نگاشتی (lexicographic) ذخیره می‌کند. فیلتر بلوم برای کامیت iام از BIDX[i-1] تا BIDX[i] (به اضافه طول سرایند) امتداد دارد، که در آن BIDX[-1] برابر با ۰ است.

•اگر قطعه BDAT وجود نداشته باشد، قطعه BIDX نادیده گرفته می‌شود.

Bloom Filter Data (ID: {B, D, A, T}) [Optional]

•با یک سرایند متشکل از سه عدد صحیح ۳۲ بیتی بدون علامت شروع می‌شود:

•نسخه الگوریتم هش مورد استفاده. در حال حاضر ما از مقدار ۲ پشتیبانی می‌کنیم که متناظر با نسخه ۳۲ بیتی هش murmur3 است که دقیقاً همان‌طور که در https://en.wikipedia.org/wiki/MurmurHash#Algorithm توصیف شده پیاده‌سازی گشته، و تکنیک درهم‌سازی دوگانه با استفاده از مقادیر seed برابر با 0x293ae76f و 0x7e646e2 که در https://doi.org/10.1007/978-3-540-30494-4_26 تحت عنوان «Bloom Filters in Probabilistic Verification» شرح داده شده است. فیلترهای بلوم نسخه ۱ دارای باگی هستند که وقتی char علامت‌دار است و مخزن نام‌های مسیری دارد که کاراکترهای >= 0x80 دارند ظاهر می‌شود؛ گیت خواندن و نوشتن آن‌ها را پشتیبانی می‌کند، اما این قابلیت در نسخه‌های آینده گیت حذف خواهد شد.

•تعداد دفعاتی که یک مسیر هش می‌شود و در نتیجه تعداد موقعیت‌های بیتی که به صورت تجمعی تعیین می‌کنند آیا فایلی در کامیت وجود دارد یا خیر.

•حداقل تعداد بیت‌های b به ازای هر ورودی در فیلتر بلوم. اگر فیلتر شامل n ورودی باشد، اندازه فیلتر حداقل تعداد کلمات ۶۴ بیتی خواهد بود که شامل n*b بیت باشند.

•باقی‌مانده قطعه، الحاق تمام فیلترهای بلوم محاسبه‌شده برای کامیت‌ها به ترتیب واژه‌نگاشتی است.

•نکته: کامیت‌های بدون تغییر یا با بیش از ۵۱۲ تغییر دارای فیلترهای بلوم با طول یک هستند، که به ترتیب تمام بیت‌های آن‌ها روی صفر یا یک تنظیم شده‌اند.

•قطعه BDAT اگر و تنها اگر BIDX موجود باشد، وجود دارد.

Base Graphs List (ID: {B, A, S, E}) [Optional]

این فهرست از هش‌های H بایتی، مجموعه‌ای از B فایل commit-graph را توصیف می‌کند که
یک زنجیره گراف کامیت را تشکیل می‌دهند. موقعیت گراف برای کامیت iام در قطعه
OID Lookup این فایل، برابر است با i به اضافه تعداد کامیت‌ها در تمام گراف‌های پایه.
اگر B غیرصفر باشد، این قطعه الزامی است.

بخش انتهایی (TRAILER):

چکسام HASH با طول H بایت از تمام موارد فوق.

نکات تاریخی (HISTORICAL NOTES)

قطعات داده‌های نسل (GDA2) و سرریز داده‌های نسل (GDO2) عدد 2 را در شناسه قطعه خود دارند زیرا نسخه قبلی گیت داده‌های احتمالاً نادرستی را در این قطعات با شناسه‌های «GDAT» و «GDOV» می‌نوشت. با تغییر شناسه‌ها، نسخه‌های جدیدتر گیت این قطعات قدیمی‌تر را بی‌صدا نادیده می‌گیرند و اطلاعات جدید را بدون اعتماد به داده‌های نادرست می‌نویسند.

گیت (GIT)

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

2026-06-29

Git 2.55.0