'\" t
.\"     Title: gitformat-chunk
.\"    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
.\"    Source: Git 2.55.0
.\"  Language: Persian
.\"
.TH "GITFORMAT\-CHUNK" "5" "2026\-06\-29" "Git 2\&.55\&.0" "راهنمای Git"
.\" -----------------------------------------------------------------
.\" * 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)"
gitformat-chunk \- ساختار و قالب‌های فایل مبتنی بر قطعه (chunk) در گیت
.SH "خلاصه دستور (SYNOPSIS)"
.sp
توسط \fBgitformat-commit-graph\fR(5) و قالب «MIDX» استفاده می‌شود (به مستندات قالب pack در \fBgitformat-pack\fR(5) مراجعه کنید)\&.
.SH "توضیحات (DESCRIPTION)"
.sp
برخی از قالب‌های فایل در گیت از مفهوم مشترک «قطعات» (chunks) برای توصیف بخش‌های مختلف فایل استفاده می‌کنند\&. این امر دسترسی ساختاریافته به یک فایل بزرگ را از طریق پیمایش یک «فهرست مطالب» (table of contents) کوچک برای باقی‌مانده داده‌ها فراهم می‌سازد\&. این قالب مشترک توسط فایل‌های \fBcommit\-graph\fR و \fBmulti\-pack\-index\fR استفاده می‌شود\&. برای نحوه استفاده آن‌ها از قطعات برای توصیف داده‌های ساختاریافته، به قالب \fBmulti\-pack\-index\fR در \fBgitformat-pack\fR(5) و قالب \fBcommit\-graph\fR در \fBgitformat-commit-graph\fR(5) مراجعه کنید\&.
.sp
یک قالب فایل مبتنی بر قطعه با اطلاعات سرایند (header) ویژه همان قالب آغاز می‌شود\&. این سرایند باید شامل اطلاعات کافی برای شناسایی نوع فایل، نسخه قالب و تعداد قطعات موجود در فایل باشد\&. از روی این اطلاعات، آن فایل می‌تواند نقطه آغاز ناحیه مبتنی بر قطعه را تعیین کند\&.
.sp
ناحیه مبتنی بر قطعه با یک فهرست مطالب آغاز می‌شود که محل شروع و پایان هر قطعه را توصیف می‌کند\&. این فهرست شامل (C+1) سطر با اندازه ۱۲ بایت به ازای هر سطر است، که در آن C تعداد قطعات می‌باشد\&. جدول زیر را در نظر بگیرید:
.sp
.if n \{\
.RS 4
.\}
.nf
| Chunk ID (4 bytes) | Chunk Offset (8 bytes) |
|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-|
| ID[0]              | OFFSET[0]              |
| \&.\&.\&.                | \&.\&.\&.                    |
| ID[C]              | OFFSET[C]              |
| 0x0000             | OFFSET[C+1]            |
.fi
.if n \{\
.RE
.\}
.sp
هر سطر از یک شناسه قطعه (ID) چهار بایتی و یک آفست (offset) هشت بایتی تشکیل شده است\&. هر عدد صحیح در ترتیب بایت شبکه (network\-byte order) ذخیره می‌شود\&.
.sp
شناسه قطعه \fBID\fR[\fBi\fR] برچسبی برای داده‌های ذخیره‌شده در این فایل از \fBOFFSET\fR[\fBi\fR] (شامل) تا \fBOFFSET\fR[\fBi+1\fR] (غیرشامل) است\&. بنابراین، اندازه قطعه \fBi\fRام برابر با تفاضل بین \fBOFFSET\fR[\fBi+1\fR] و \fBOFFSET\fR[\fBi\fR] است\&. این امر مستلزم آن است که داده‌های قطعات به صورت متوالی و با همان ترتیب فهرست مطالب در فایل ظاهر شوند\&.
.sp
ورودی پایانی در فهرست مطالب باید چهار بایت صفر باشد\&. این موضوع پایان فهرست مطالب را تایید می‌کند و آفست پایان داده‌های مبتنی بر قطعه را ارائه می‌دهد\&.
.sp
نکته: قالب مبتنی بر قطعه انتظار دارد که فایل \fIحداقل\fR شامل یک درهم‌سازی پایانی (trailing hash) پس از \fBOFFSET\fR[\fBC+1\fR] باشد\&.
.sp
توابع کار با قالب‌های فایل مبتنی بر قطعه در \fBchunk\-format\&.h\fR اعلان شده‌اند\&. استفاده از این روش‌ها بررسی‌های مضاعفی را ارائه می‌دهد که به توسعه‌دهندگان در هنگام ایجاد قالب‌های فایل جدید کمک می‌کند\&.
.SH "نوشتن قالب‌های فایل مبتنی بر قطعه (WRITING CHUNK\-BASED FILE FORMATS)"
.sp
برای نوشتن یک قالب فایل مبتنی بر قطعه، با فراخوانی \fBinit_chunkfile\fR() یک \fBstruct\fR \fBchunkfile\fR ایجاد کنید و یک اشاره‌گر به \fBstruct\fR \fBhashfile\fR را ارسال نمایید\&. فراخواننده مسئول باز کردن \fBhashfile\fR و نوشتن اطلاعات سرایند است تا پیش از آغاز قالب مبتنی بر قطعه، نوع فایل قابل شناسایی باشد\&.
.sp
سپس، برای هر قطعه‌ای که قصد نوشتن آن را دارید، تابع \fBadd_chunk\fR() را فراخوانی کنید\&. این کار \fBchunkfile\fR را با اطلاعات مربوط به ترتیب و اندازه هر قطعه برای نوشتن پر می‌کند\&. یک اشاره‌گر تابع \fBchunk_write_fn\fR ارائه دهید تا در صورت درخواست، نوشتن داده‌های قطعه را انجام دهد\&.
.sp
برای نوشتن فهرست مطالب در \fBhashfile\fR و سپس نوشتن هر یک از قطعات، تابع \fBwrite_chunkfile\fR() را فراخوانی کنید\&. این کار بررسی خواهد کرد که هر قطعه به میزان مورد انتظار داده نوشته است تا فهرست مطالب صحیح باشد\&.
.sp
در پایان، \fBfree_chunkfile\fR() را برای پاک‌سازی داده‌های \fBstruct\fR \fBchunkfile\fR فراخوانی کنید\&. فراخواننده مسئول نهایی‌سازی \fBhashfile\fR از طریق نوشتن هش انتهایی و بستن فایل است\&.
.SH "خواندن قالب‌های فایل مبتنی بر قطعه (READING CHUNK\-BASED FILE FORMATS)"
.sp
برای خواندن یک قالب فایل مبتنی بر قطعه، فایل باید به عنوان یک ناحیه نگاشت‌شده در حافظه (memory\-mapped region) باز شود\&. رابط برنامه‌نویسی chunk\-format انتظار دارد که کل فایل به عنوان یک ناحیه پیوسته حافظه نگاشت شود\&.
.sp
یک اشاره‌گر به \fBstruct\fR \fBchunkfile\fR را با \fBinit_chunkfile\fR(\fBNULL\fR) مقداردهی اولیه کنید\&.
.sp
پس از خواندن اطلاعات سرایند از ابتدای فایل، از جمله تعداد قطعات، تابع \fBread_table_of_contents\fR() را فراخوانی کنید تا \fBstruct\fR \fBchunkfile\fR با فهرست قطعات، آفست‌ها و اندازه‌های آن‌ها پر شود\&.
.sp
اطلاعات داده‌ای هر قطعه را با استفاده از \fBpair_chunk\fR() یا \fBread_chunk\fR() استخراج کنید:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
تابع \fBpair_chunk\fR() یک اشاره‌گر معین را به موقعیت درون فایل نگاشت‌شده در حافظه که مربوط به آفست آن قطعه است تخصیص می‌دهد\&. اگر قطعه وجود نداشته باشد، اشاره‌گر تغییر نمی‌کند\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
تابع \fBread_chunk\fR() یک اشاره‌گر تابع
\fBchunk_read_fn\fR
را دریافت می‌کند و آن را با اشاره‌گر اولیه و اطلاعات اندازه مربوطه فراخوانی می‌نماید\&. اگر قطعه وجود نداشته باشد، تابع فراخوانی نمی‌شود\&. اگر نیاز به تجزیه (parsing) فوری دارید یا اگر باید منطقی را بر اساس اندازه قطعه اجرا کنید، از این روش برای خواندن قطعات استفاده کنید\&.
.RE
.sp
پس از فراخوانی این روش‌ها، \fBfree_chunkfile\fR() را فراخوانی کنید تا داده‌های \fBstruct\fR \fBchunkfile\fR پاک‌سازی شوند\&. این کار ناحیه نگاشت‌شده در حافظه را نخواهد بست\&. از فراخواننده‌ها انتظار می‌رود که تا مدت زمانی که به اشاره‌گرهای درون آن ناحیه نیاز است، مالکیت داده‌ها را حفظ کنند\&.
.SH "مثال‌ها (EXAMPLES)"
.sp
این قالب‌های فایل از API فرمت قطعه (chunk\-format) استفاده می‌کنند و می‌توانند به عنوان الگوهایی برای قالب‌های آینده استفاده شوند:
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBcommit\-graph:\fR
توابع
\fBwrite_commit_graph_file\fR()
و
\fBparse_commit_graph\fR()
در
\fBcommit\-graph\&.c\fR
را ببینید تا با نحوه استفاده از API فرمت قطعه برای نوشتن و تجزیه قالب فایل commit\-graph که در
\fBgitformat-commit-graph\fR(5)
مستند شده است آشنا شوید\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
\fBmulti\-pack\-index:\fR
توابع
\fBwrite_midx_internal\fR()
و
\fBload_multi_pack_index\fR()
در
\fBmidx\&.c\fR
را ببینید تا با نحوه استفاده از API فرمت قطعه برای نوشتن و تجزیه قالب فایل multi\-pack\-index که در بخش قالب multi\-pack\-index در
\fBgitformat-pack\fR(5)
مستند شده است آشنا شوید\&.
.RE
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)