نام (NAME)

gitformat-chunk - ساختار و قالب‌های فایل مبتنی بر قطعه (chunk) در گیت

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

توسط gitformat-commit-graph(5) و قالب «MIDX» استفاده می‌شود (به مستندات قالب pack در gitformat-pack(5) مراجعه کنید).

توضیحات (DESCRIPTION)

برخی از قالب‌های فایل در گیت از مفهوم مشترک «قطعات» (chunks) برای توصیف بخش‌های مختلف فایل استفاده می‌کنند. این امر دسترسی ساختاریافته به یک فایل بزرگ را از طریق پیمایش یک «فهرست مطالب» (table of contents) کوچک برای باقی‌مانده داده‌ها فراهم می‌سازد. این قالب مشترک توسط فایل‌های commit-graph و multi-pack-index استفاده می‌شود. برای نحوه استفاده آن‌ها از قطعات برای توصیف داده‌های ساختاریافته، به قالب multi-pack-index در gitformat-pack(5) و قالب commit-graph در gitformat-commit-graph(5) مراجعه کنید.

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

ناحیه مبتنی بر قطعه با یک فهرست مطالب آغاز می‌شود که محل شروع و پایان هر قطعه را توصیف می‌کند. این فهرست شامل (C+1) سطر با اندازه ۱۲ بایت به ازای هر سطر است، که در آن C تعداد قطعات می‌باشد. جدول زیر را در نظر بگیرید:

| Chunk ID (4 bytes) | Chunk Offset (8 bytes) |
|--------------------|------------------------|
| ID[0]              | OFFSET[0]              |
| ...                | ...                    |
| ID[C]              | OFFSET[C]              |
| 0x0000             | OFFSET[C+1]            |

هر سطر از یک شناسه قطعه (ID) چهار بایتی و یک آفست (offset) هشت بایتی تشکیل شده است. هر عدد صحیح در ترتیب بایت شبکه (network-byte order) ذخیره می‌شود.

شناسه قطعه ID[i] برچسبی برای داده‌های ذخیره‌شده در این فایل از OFFSET[i] (شامل) تا OFFSET[i+1] (غیرشامل) است. بنابراین، اندازه قطعه iام برابر با تفاضل بین OFFSET[i+1] و OFFSET[i] است. این امر مستلزم آن است که داده‌های قطعات به صورت متوالی و با همان ترتیب فهرست مطالب در فایل ظاهر شوند.

ورودی پایانی در فهرست مطالب باید چهار بایت صفر باشد. این موضوع پایان فهرست مطالب را تایید می‌کند و آفست پایان داده‌های مبتنی بر قطعه را ارائه می‌دهد.

نکته: قالب مبتنی بر قطعه انتظار دارد که فایل حداقل شامل یک درهم‌سازی پایانی (trailing hash) پس از OFFSET[C+1] باشد.

توابع کار با قالب‌های فایل مبتنی بر قطعه در chunk-format.h اعلان شده‌اند. استفاده از این روش‌ها بررسی‌های مضاعفی را ارائه می‌دهد که به توسعه‌دهندگان در هنگام ایجاد قالب‌های فایل جدید کمک می‌کند.

نوشتن قالب‌های فایل مبتنی بر قطعه (WRITING CHUNK-BASED FILE FORMATS)

برای نوشتن یک قالب فایل مبتنی بر قطعه، با فراخوانی init_chunkfile() یک struct chunkfile ایجاد کنید و یک اشاره‌گر به struct hashfile را ارسال نمایید. فراخواننده مسئول باز کردن hashfile و نوشتن اطلاعات سرایند است تا پیش از آغاز قالب مبتنی بر قطعه، نوع فایل قابل شناسایی باشد.

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

برای نوشتن فهرست مطالب در hashfile و سپس نوشتن هر یک از قطعات، تابع write_chunkfile() را فراخوانی کنید. این کار بررسی خواهد کرد که هر قطعه به میزان مورد انتظار داده نوشته است تا فهرست مطالب صحیح باشد.

در پایان، free_chunkfile() را برای پاک‌سازی داده‌های struct chunkfile فراخوانی کنید. فراخواننده مسئول نهایی‌سازی hashfile از طریق نوشتن هش انتهایی و بستن فایل است.

خواندن قالب‌های فایل مبتنی بر قطعه (READING CHUNK-BASED FILE FORMATS)

برای خواندن یک قالب فایل مبتنی بر قطعه، فایل باید به عنوان یک ناحیه نگاشت‌شده در حافظه (memory-mapped region) باز شود. رابط برنامه‌نویسی chunk-format انتظار دارد که کل فایل به عنوان یک ناحیه پیوسته حافظه نگاشت شود.

یک اشاره‌گر به struct chunkfile را با init_chunkfile(NULL) مقداردهی اولیه کنید.

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

اطلاعات داده‌ای هر قطعه را با استفاده از pair_chunk() یا read_chunk() استخراج کنید:

•تابع pair_chunk() یک اشاره‌گر معین را به موقعیت درون فایل نگاشت‌شده در حافظه که مربوط به آفست آن قطعه است تخصیص می‌دهد. اگر قطعه وجود نداشته باشد، اشاره‌گر تغییر نمی‌کند.

•تابع read_chunk() یک اشاره‌گر تابع chunk_read_fn را دریافت می‌کند و آن را با اشاره‌گر اولیه و اطلاعات اندازه مربوطه فراخوانی می‌نماید. اگر قطعه وجود نداشته باشد، تابع فراخوانی نمی‌شود. اگر نیاز به تجزیه (parsing) فوری دارید یا اگر باید منطقی را بر اساس اندازه قطعه اجرا کنید، از این روش برای خواندن قطعات استفاده کنید.

پس از فراخوانی این روش‌ها، free_chunkfile() را فراخوانی کنید تا داده‌های struct chunkfile پاک‌سازی شوند. این کار ناحیه نگاشت‌شده در حافظه را نخواهد بست. از فراخواننده‌ها انتظار می‌رود که تا مدت زمانی که به اشاره‌گرهای درون آن ناحیه نیاز است، مالکیت داده‌ها را حفظ کنند.

مثال‌ها (EXAMPLES)

این قالب‌های فایل از API فرمت قطعه (chunk-format) استفاده می‌کنند و می‌توانند به عنوان الگوهایی برای قالب‌های آینده استفاده شوند:

•commit-graph: توابع write_commit_graph_file() و parse_commit_graph() در commit-graph.c را ببینید تا با نحوه استفاده از API فرمت قطعه برای نوشتن و تجزیه قالب فایل commit-graph که در gitformat-commit-graph(5) مستند شده است آشنا شوید.

•multi-pack-index: توابع write_midx_internal() و load_multi_pack_index() در midx.c را ببینید تا با نحوه استفاده از API فرمت قطعه برای نوشتن و تجزیه قالب فایل multi-pack-index که در بخش قالب multi-pack-index در gitformat-pack(5) مستند شده است آشنا شوید.

گیت (GIT)

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