نام (NAME)

gitformat-bundle - ساختار و قالب فایل‌های بسته آرشیو (bundle) در گیت

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

*.bundle
*.bdl

توضیحات (DESCRIPTION)

قالب باندل گیت (Git bundle format) ساختاری است که هم ارجاع‌ها (refs) و هم اشیاء گیت را بازنمایی و ذخیره می‌کند. یک باندل شامل یک سرایند (header) با قالبی مشابه git-show-ref(1) است که به دنبال آن یک بسته با قالب *.pack قرار می‌گیرد.

این قالب توسط دستور git-bundle(1) ایجاد و خوانده می‌شود و برای نمونه توسط دستورات git-fetch(1) و git-clone(1) نیز پشتیبانی می‌گردد.

قالب (FORMAT)

ما از نشانه‌گذاری ABNF برای تعریف قالب باندل گیت استفاده می‌کنیم. برای جزئیات به gitprotocol-common(5) مراجعه کنید.

یک باندل نسخه ۲ (v2) به شکل زیر است:

bundle    = signature *prerequisite *reference LF pack
signature = "# v2 git bundle" LF
prerequisite = "-" obj-id SP comment LF
comment      = *CHAR
reference    = obj-id SP refname LF
pack         = ... ; packfile

یک باندل نسخه ۳ (v3) به این صورت است:

bundle    = signature *capability *prerequisite *reference LF pack
signature = "# v3 git bundle" LF
capability   = "@" key ["=" value] LF
prerequisite = "-" obj-id SP comment LF
comment      = *CHAR
reference    = obj-id SP refname LF
key          = 1*(ALPHA / DIGIT / "-")
value        = *(%01-09 / %0b-FF)
pack         = ... ; packfile

معناشناسی (SEMANTICS)

یک باندل گیت از چندین بخش تشکیل شده است.

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

•«پیش‌نیازها» (Prerequisites) اشیائی را فهرست می‌کنند که در باندل گنجانده نشده‌اند و خواننده باندل برای استفاده از داده‌های داخل باندل، الزاماً باید از قبل آن‌ها را داشته باشد. اشیاء ذخیره‌شده در باندل ممکن است به اشیاء پیش‌نیاز و هر آنچه از طریق آن‌ها در دسترس است ارجاع دهند (برای نمونه یک شیء درخت در باندل می‌تواند به یک blob ارجاع دهد که از طریق یک پیش‌نیاز در دسترس است) یا به صورت دلتا بر مبنای اشیاء پیش‌نیاز بیان شوند.

•«ارجاع‌ها» (References) رأس‌های گراف تاریخچه را ثبت می‌کنند؛ یعنی آنچه خواننده باندل می‌تواند از طریق «git fetch» از آن دریافت کند.

•«بسته» (Pack) همان جریان داده‌های بسته‌ای است که دستور «git fetch» ارسال می‌کرد، اگر از مخزنی با ارجاع‌های ثبت‌شده در بخش «ارجاع‌ها» به مخزنی با ارجاع‌هایی به اشیاء فهرست‌شده در بخش «پیش‌نیازها» دریافت (fetch) انجام می‌دادید.

در قالب باندل، ممکن است یک توضیح (comment) به دنبال شناسه شیء (obj-id) پیش‌نیاز بیاید. این تنها یک توضیح است و معنای خاصی ندارد. نویسنده باندل می‌تواند هر رشته‌ای را در اینجا قرار دهد. خواننده باندل باید این توضیح را نادیده بگیرد.

نکته‌ای درباره کلون‌های کم‌عمق و باندل‌های گیت

توجه داشته باشید که پیش‌نیازها نمایانگر مرز کلون کم‌عمق (shallow clone) نیستند. معناشناسی پیش‌نیازها و مرزهای کلون کم‌عمق متفاوت است و قالب نسخه ۲ باندل گیت نمی‌تواند یک مخزن کلون کم‌عمق را بازنمایی کند.

قابلیت‌ها (CAPABILITIES)

از آنجا که فرصتی برای مذاکره (negotiation) وجود ندارد، قابلیت‌های ناشناخته باعث لغو و توقف اجرای git bundle می‌شوند.

•object-format الگوریتم درهم‌سازی (هش) مورد استفاده را مشخص می‌کند و می‌تواند مقادیری مشابه با مقدار پیکربندی extensions.objectFormat بپذیرد.

•filter یک فیلتر شیء را همانند گزینه --filter در دستور git-rev-list(1) مشخص می‌کند. فایل بسته حاصل پس از استخراج از باندل باید به عنوان یک فایل بسته .promisor نشانه‌گذاری شود.

گیت (GIT)

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