'\" t
.\" Title: git-bundle
.\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot
.\" Date: 2026-06-29
.\" Manual: دستورات عمومی کاربر
.\" Source: Git 2.55.0
.\" Language: Persian
.\"
.TH "GIT\-BUNDLE" "1" "2026\-06\-29" "Git 2\&.55\&.0" "دستورات عمومی کاربر"
.\" -----------------------------------------------------------------
.\" * 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)"
git-bundle \- جابجایی اشیا و ارجاعات از طریق بستهبندی در قالب فایل بایگانی
.SH "خلاصه دستور (SYNOPSIS)"
.sp
.nf
\fIgit bundle\fR create [\-q | \-\-quiet | \-\-progress]
[\-\-version=]
\fIgit bundle\fR verify [\-q | \-\-quiet]
\fIgit bundle\fR list\-heads [\&...]
\fIgit bundle\fR unbundle [\-\-progress] [\&...]
.fi
.sp
.SH "توضیحات (DESCRIPTION)"
.sp
ایجاد، باز کردن و کار با فایلهای «باندل» (bundle)\&. باندلها برای انتقال «آفلاین» اشیای گیت بدون نیاز به وجود یک «سرور» فعال در سمت دیگر ارتباط شبکه استفاده میشوند\&.
.sp
آنها میتوانند هم برای ایجاد پشتیبانهای افزایشی (incremental) و هم پشتیبانهای کامل از یک مخزن (نگاه کنید به مثال «پشتیبان کامل» در بخش «مثالها»)، و هم برای انتقال وضعیت ارجاعات از یک مخزن به مخزنی دیگر استفاده شوند (نگاه کنید به مثال دوم)\&.
.sp
دستورات گیت که از طریق پروتکلهایی مانند \fBssh://\fR و \fBhttps://\fR دادهها را واکشی کرده یا به هر نحو «میخوانند»، میتوانند روی فایلهای باندل نیز عمل کنند\&. میتوان یک مخزن جدید را با \fBgit-clone\fR(1) از یک باندل کلون کرد، از \fBgit-fetch\fR(1) برای واکشی از آن استفاده نمود، و ارجاعات موجود در آن را با \fBgit-ls-remote\fR(1) فهرست کرد\&. با این حال قابلیت متناظری برای «نوشتن» وجود ندارد، یعنی دستور \fIgit push\fR بر روی یک باندل پشتیبانی نمیشود\&.
.SH "قالب بسته (BUNDLE FORMAT)"
.sp
باندلها همان فایلهای \fB\&.pack\fR هستند (نگاه کنید به \fBgit-pack-objects\fR(1)) که دارای یک سرآیند (header) میباشند که نشان میدهد چه ارجاعاتی در درون باندل قرار دارند\&.
.sp
مانند خود قالب بایگانی فشرده (packed archive)، باندلها میتوانند هم خودکفا (self\-contained) باشند و هم با استفاده از استثناها (exclusions) ایجاد شوند\&. بخش «پیشنیازهای اشیا» در ادامه را ببینید\&.
.sp
باندلهایی که با استفاده از استثناهای بازبینی (revision exclusions) ایجاد میشوند، «بستههای نازک» (thin packs) هستند که با استفاده از گزینه \fB\-\-thin\fR در دستور \fBgit-pack-objects\fR(1) ساخته میشوند، و با استفاده از گزینه \fB\-\-fix\-thin\fR در \fBgit-index-pack\fR(1) از حالت بستهبندی خارج (unbundle) میگردند\&.
.sp
هیچ گزینهای برای ایجاد یک «بسته ضخیم» (thick pack) در زمان استفاده از استثناهای بازبینی وجود ندارد، و کاربران نباید نگران تفاوت آنها باشند\&. با استفاده از «بستههای نازک»، باندلهای ایجادشده با استثناها از نظر حجم کوچکتر هستند\&. اینکه آنها در پشت صحنه «نازک» هستند صرفاً به عنوان یک نکته جالب و به عنوان ارجاعی به سایر مستندات در اینجا ذکر شده است\&.
.sp
برای جزئیات بیشتر به \fBgitformat-bundle\fR(5) و برای توضیحات بیشتر درباره «بسته نازک» به \fBgitformat-pack\fR(5) مراجعه کنید\&.
.SH "گزینهها (OPTIONS)"
.PP
create [options]
.RS 4
برای ایجاد یک باندل با نام
\fIfile\fR
استفاده میشود\&. این دستور به آرگومانهای
\fI\fR
برای تعریف محتوای باندل نیاز دارد\&.
\fIoptions\fR
شامل گزینههای خاص زیردستور
\fIgit bundle create\fR
است\&. اگر
\fIfile\fR
برابر با
\fB\-\fR
باشد، باندل در خروجی استاندارد (stdout) نوشته میشود\&.
.RE
.PP
verify
.RS 4
برای بررسی معتبر بودن یک فایل باندل و امکان اعمال تمیز و بدون خطای آن روی مخزن فعلی استفاده میشود\&. این بررسی شامل اعتبارسنجی خود قالب باندل و همچنین اطمینان از وجود داشتن و پیوند کامل داشتن کامیتهای پیشنیاز در مخزن فعلی است\&. سپس،
\fIgit bundle\fR
فهرستی از کامیتهای ناموجود (در صورت وجود) را چاپ میکند\&. در نهایت، اطلاعات مربوط به قابلیتهای اضافی مانند «فیلتر اشیا» (object filter) چاپ میشود\&. برای اطلاعات بیشتر بخش «قابلیتها» در
\fBgitformat-bundle\fR(5)
را ببینید\&. کد خروج در صورت موفقیت صفر است، اما اگر فایل باندل نامعتبر باشد غیرصفر خواهد بود\&. اگر
\fIfile\fR
برابر با
\fB\-\fR
باشد، باندل از ورودی استاندارد (stdin) خوانده میشود\&.
.RE
.PP
list\-heads
.RS 4
ارجاعات تعریفشده در باندل را فهرست میکند\&. در صورت ارائه فهرستی از ارجاعات پس از آن، تنها ارجاعات مطابق با موارد دادهشده چاپ میشوند\&. اگر
\fIfile\fR
برابر با
\fB\-\fR
باشد، باندل از ورودی استاندارد (stdin) خوانده میشود\&.
.RE
.PP
unbundle
.RS 4
اشیای موجود در باندل را به
\fIgit index\-pack\fR
برای ذخیرهسازی در مخزن ارسال میکند، سپس نامهای تمام ارجاعات تعریفشده را چاپ مینماید\&. در صورت ارائه فهرستی از ارجاعات، تنها ارجاعات مطابق با آن فهرست چاپ میشوند\&. این دستور در واقع یک دستور لولهکشی (plumbing) است که تنها با هدف فراخوانی توسط
\fIgit fetch\fR
در نظر گرفته شده است\&. اگر
\fIfile\fR
برابر با
\fB\-\fR
باشد، باندل از ورودی استاندارد (stdin) خوانده میشود\&.
.RE
.PP
.RS 4
فهرستی از آرگومانها، قابل پذیرش توسط
\fIgit rev\-parse\fR
و
\fIgit rev\-list\fR
(و حاوی یک ارجاع نامگذاریشده؛ بخش «مشخص کردن ارجاعات» در ادامه را ببینید)، که اشیا و ارجاعات خاص را برای انتقال تعیین میکند\&. به عنوان مثال،
\fBmaster~10\fR\fB\&.\&.\fR\fBmaster\fR
باعث میشود که ارجاع فعلی master به همراه تمام اشیای اضافه شده از زمان دهمین کامیت نیاکان آن بستهبندی شوند\&. هیچ محدودیت صریحی برای تعداد ارجاعات و اشیایی که میتوانند بستهبندی شوند وجود ندارد\&.
.RE
.PP
[\&...]
.RS 4
فهرستی از ارجاعات که برای محدود کردن ارجاعات گزارششده به عنوان ارجاعات موجود استفاده میشود\&. این مورد عمدتاً برای استفاده
\fIgit fetch\fR
است که انتظار دارد تنها ارجاعات درخواستشده را دریافت کند و نه الزاماً هر آنچه در بسته وجود دارد (در این حالت،
\fIgit bundle\fR
مشابه
\fIgit fetch\-pack\fR
عمل میکند)\&.
.RE
.PP
\-\-progress
.RS 4
وضعیت پیشرفت به طور پیشفرض زمانی که خروجی خطای استاندارد به یک ترمینال متصل باشد روی آن گزارش میشود، مگر اینکه \-q مشخص شده باشد\&. این فلگ نمایش وضعیت پیشرفت را حتی اگر خطای استاندارد به یک ترمینال هدایت نشده باشد اجبار میکند\&.
.RE
.PP
\-\-version=
.RS 4
نسخه باندل را مشخص میکند\&. نسخه 2 قالب قدیمیتر است و تنها برای مخازن SHA\-1 قابل استفاده است؛ نسخه جدیدتر 3 شامل قابلیتهایی است که امکان استفاده از افزونهها را میدهد\&. پیشفرض، قدیمیترین قالب پشتیبانیشده بر اساس الگوریتم هش مورد استفاده است\&.
.RE
.PP
\-q, \-\-quiet
.RS 4
این فلگ باعث میشود دستور وضعیت پیشرفت خود را روی جریان خطای استاندارد گزارش نکند\&.
.RE
.SH "مشخص کردن ارجاعات (SPECIFYING REFERENCES)"
.sp
بازبینیها (revisions) برای بستهبندی در یک باندل باید همراه با نام ارجاع باشند\&. به عنوان روش جایگزین میتوان از \fB\-\-all\fR برای بستهبندی تمام ارجاعات استفاده کرد\&.
.sp
میتوان بیش از یک ارجاع را بستهبندی کرد و بیش از یک مجموعه از اشیای پیشنیاز را مشخص نمود\&. اشیایی که بستهبندی میشوند آنهایی هستند که در اجتماع پیشنیازها قرار ندارند\&.
.sp
دستور \fIgit bundle create\fR نام ارجاعات را با استفاده از همان قوانین \fBgit\fR \fBrev\-parse\fR \fB\-\-abbrev\-ref=loose\fR برای شما حلوفصل میکند\&. هر پیشنیاز میتواند به طور صریح (مانند \fB^master~10\fR) یا ضمنی (مانند \fBmaster~10\fR\fB\&.\&.\fR\fBmaster\fR یا \fB\-\-since=10\&.days\&.ago\fR \fBmaster\fR) مشخص شود\&.
.sp
تمام این موارد ساده مجاز هستند (با فرض اینکه شاخههای "master" و "next" را داریم):
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle create master\&.bundle master
$ echo master | git bundle create master\&.bundle \-\-stdin
$ git bundle create master\-and\-next\&.bundle master next
$ (echo master; echo next) | git bundle create master\-and\-next\&.bundle \-\-stdin
.fi
.if n \{\
.RE
.\}
.sp
.sp
و همچنین موارد زیر (و نمونههای مشابه بدون \fB\-\-stdin\fR):
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle create recent\-master\&.bundle master~10\&.\&.master
$ git bundle create recent\-updates\&.bundle master~10\&.\&.master next~5\&.\&.next
.fi
.if n \{\
.RE
.\}
.sp
.sp
نام یک بازبینی یا بازهای که سمت راست آن نتواند به یک ارجاع حلوفصل شود، پذیرفته نمیشود:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle create HEAD\&.bundle $(git rev\-parse HEAD)
fatal: Refusing to create empty bundle\&.
$ git bundle create master\-yesterday\&.bundle master~10\&.\&.master~5
fatal: Refusing to create empty bundle\&.
.fi
.if n \{\
.RE
.\}
.sp
.SH "پیشنیازهای اشیا (OBJECT PREREQUISITES)"
.sp
هنگام ساخت باندلها، امکان ایجاد یک باندل خودکفا وجود دارد که میتواند در مخزنی بدون هیچ تاریخچه مشترکی باز شود، و همچنین میتوان بازبینیهای منفی ارائه داد تا اشیای مورد نیاز در بخشهای قبلی تاریخچه مستثنی شوند\&.
.sp
دادن یک بازبینی مانند \fBnew\fR به \fBgit\fR \fBbundle\fR \fBcreate\fR فایلی از نوع باندل تولید میکند که حاوی تمام اشیای قابل دسترسی از بازبینی \fBnew\fR است\&. آن باندل میتواند در هر مخزنی باز شود تا تاریخچه کاملی که به بازبینی \fBnew\fR منتهی میشود به دست آید:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle create full\&.bundle new
.fi
.if n \{\
.RE
.\}
.sp
.sp
یک بازه بازبینی مانند \fBold\fR\fB\&.\&.\fR\fBnew\fR فایلی از نوع باندل تولید میکند که برای باز شدن باندل نیازمند وجود بازبینی \fBold\fR (و هر شیء قابل دسترسی از آن) خواهد بود:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle create full\&.bundle old\&.\&.new
.fi
.if n \{\
.RE
.\}
.sp
.sp
یک باندل خودکفا بدون هیچ پیشنیازی را میتوان در هر جایی استخراج کرد، حتی در یک مخزن خالی، یا از آن کلون گرفت (یعنی \fBnew\fR، اما نه \fBold\fR\fB\&.\&.\fR\fBnew\fR)\&.
.sp
احتیاط کردن و گنجاندن اشیایی در فایل باندل که هماکنون در مقصد وجود دارند اشکالی ندارد، زیرا هنگام باز کردن بسته در مقصد نادیده گرفته میشوند\&.
.sp
اگر میخواهید همان مجموعه ارجاعاتی را فراهم کنید که کلون مستقیم از مخزن مبدا دریافت میکند، از \fB\-\-branches\fR \fB\-\-tags\fR برای \fI\fR استفاده کنید\&.
.sp
دستور \fIgit bundle verify\fR میتواند برای بررسی اینکه آیا مخزن گیرنده شما کامیتهای پیشنیاز لازم برای یک باندل را دارد یا خیر، استفاده شود\&.
.SH "مثالها (EXAMPLES)"
.sp
ما دو حالت را بررسی خواهیم کرد:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
تهیه یک پشتیبان کامل از یک مخزن
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
انتقال تاریخچه یک مخزن به ماشینی دیگر هنگامی که دو ماشین ارتباط مستقیم ندارند
.RE
.sp
ابتدا یک پشتیبان کامل از مخزن را در نظر میگیریم\&. دستور زیر یک نسخه پشتیبان کامل از مخزن تهیه میکند به این معنا که تمام ارجاعات در باندل گنجانده میشوند:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle create backup\&.bundle \-\-all
.fi
.if n \{\
.RE
.\}
.sp
.sp
اما مجدداً توجه داشته باشید که این پشتیبان فقط برای ارجاعات است، یعنی شما فقط ارجاعات و کامیتهای قابل دسترسی از آن ارجاعات را شامل خواهید کرد\&. سایر وضعیتهای محلی مانند محتوای ایندکس، درخت کاری (working tree)، استش (stash)، پیکربندیهای خاص هر مخزن، هوکها و غیره را شامل نخواهید کرد\&.
.sp
بعداً میتوانید آن مخزن را برای نمونه با استفاده از \fBgit-clone\fR(1) بازیابی کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git clone backup\&.bundle
.fi
.if n \{\
.RE
.\}
.sp
.sp
برای مثال بعد، فرض کنید میخواهید تاریخچه را از یک مخزن R1 روی ماشین A به مخزن دیگری به نام R2 روی ماشین B منتقل کنید\&. به هر دلیلی، ارتباط مستقیم بین A و B مجاز نیست، اما میتوانیم دادهها را از طریق سازوکاری (سیدی، ایمیل، و غیره) از A به B منتقل کنیم\&. ما میخواهیم R2 را با تغییرات ایجادشده روی شاخه master در R1 بهروز کنیم\&.
.sp
برای راهاندازی اولیه فرآیند، ابتدا میتوانید باندلی ایجاد کنید که هیچ پیشنیازی ندارد\&. میتوانید از یک تگ برای به خاطر سپردن اینکه تا چه کامیتی را قبلاً پردازش کردهاید استفاده کنید، تا بعداً بهروزرسانی مخزن دیگر با یک باندل افزایشی آسانتر شود:
.sp
.if n \{\
.RS 4
.\}
.nf
machineA$ cd R1
machineA$ git bundle create file\&.bundle master
machineA$ git tag \-f lastR2bundle master
.fi
.if n \{\
.RE
.\}
.sp
.sp
سپس فایل file\&.bundle را به ماشین مقصد B منتقل میکنید\&. از آنجا که این باندل برای استخراج نیازی به هیچ شیء موجودی ندارد، میتوانید با کلون کردن از آن یک مخزن جدید در ماشین B ایجاد کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
machineB$ git clone \-b master /home/me/tmp/file\&.bundle R2
.fi
.if n \{\
.RE
.\}
.sp
.sp
این کار یک کنترل از راه دور (remote) به نام "origin" در مخزن حاصل تعریف میکند که به شما امکان میدهد از باندل واکشی (fetch) و دریافت (pull) کنید\&. فایل $GIT_DIR/config در R2 ورودی مشابه این خواهد داشت:
.sp
.if n \{\
.RS 4
.\}
.nf
[remote "origin"]
url = /home/me/tmp/file\&.bundle
fetch = refs/heads/*:refs/remotes/origin/*
.fi
.if n \{\
.RE
.\}
.sp
.sp
برای بهروزرسانی مخزن حاصل، میتوانید پس از جایگزین کردن باندل ذخیرهشده در /home/me/tmp/file\&.bundle با بهروزرسانیهای افزایشی، عملیات fetch یا pull را انجام دهید\&.
.sp
پس از انجام کارهای بیشتر در مخزن اصلی، میتوانید یک باندل افزایشی برای بهروزرسانی مخزن دیگر ایجاد کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
machineA$ cd R1
machineA$ git bundle create file\&.bundle lastR2bundle\&.\&.master
machineA$ git tag \-f lastR2bundle master
.fi
.if n \{\
.RE
.\}
.sp
.sp
سپس باندل را به ماشین دیگر منتقل میکنید تا جایگزین /home/me/tmp/file\&.bundle شود، و از آن pull میکنید\&.
.sp
.if n \{\
.RS 4
.\}
.nf
machineB$ cd R2
machineB$ git pull
.fi
.if n \{\
.RE
.\}
.sp
.sp
اگر بدانید مخزن گیرنده مورد نظر تا چه کامیتی اشیای لازم را در خود دارد، میتوانید از آن آگاهی برای تعیین پیشنیازها استفاده کنید و یک نقطه قطع برای محدود کردن بازبینیها و اشیایی که در باندل حاصل قرار میگیرند تعیین نمایید\&. مثال قبلی از تگ lastR2bundle برای این منظور استفاده کرد، اما شما میتوانید از هر گزینه دیگری که به دستور \fBgit-log\fR(1) میدادید استفاده کنید\&. در اینجا مثالهای بیشتری آمده است:
.sp
میتوانید از تگی استفاده کنید که در هر دو وجود دارد:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle create mybundle v1\&.0\&.0\&.\&.master
.fi
.if n \{\
.RE
.\}
.sp
.sp
میتوانید از پیشنیازی بر اساس زمان استفاده کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle create mybundle \-\-since=10\&.days master
.fi
.if n \{\
.RE
.\}
.sp
.sp
میتوانید از تعداد کامیتها استفاده کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle create mybundle \-10 master
.fi
.if n \{\
.RE
.\}
.sp
.sp
میتوانید دستور \fBgit\-bundle\fR \fBverify\fR را اجرا کنید تا ببینید آیا میتوانید از باندلی که با یک پیشنیاز ایجاد شده است استخراج نمایید یا خیر:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git bundle verify mybundle
.fi
.if n \{\
.RE
.\}
.sp
.sp
این کار کامیتهایی را که برای استخراج از باندل باید داشته باشید فهرست میکند و اگر آنها را نداشته باشید با خطا متوقف میشود\&.
.sp
یک باندل از دیدگاه مخزن گیرنده، دقیقاً مانند یک مخزن معمولی است که از آن واکشی (fetch) یا دریافت (pull) میکند\&. برای نمونه، میتوانید ارجاعات را هنگام واکشی نقشهبرداری کنید:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git fetch mybundle master:localRef
.fi
.if n \{\
.RE
.\}
.sp
.sp
همچنین میتوانید ببینید چه ارجاعاتی ارائه میدهد:
.sp
.if n \{\
.RS 4
.\}
.nf
$ git ls\-remote mybundle
.fi
.if n \{\
.RE
.\}
.sp
.SH "بحث و بررسی (DISCUSSION)"
.sp
یک روش ناشیانه برای تهیه نسخه پشتیبان کامل از یک مخزن، استفاده از دستوری مانند \fBcp\fR \fB\-r\fR \fI\fR \fI\fR است\&. استفاده از این روش توصیه نمیشود، زیرا ممکن است در حین عملیات کپی در مخزن نوشته شود\&. در نتیجه ممکن است برخی از فایلها در \fI\fR دچار خرابی شوند\&.
.sp
به همین دلیل توصیه میشود برای تهیه نسخه پشتیبان از مخزن، از ابزارهای گیت استفاده کنید؛ چه با این دستور یا به عنوان مثال با \fBgit-clone\fR(1)\&. اما در نظر داشته باشید که این ابزارها برای پشتیبانگیری از وضعیتهایی به جز ارجاعات و کامیتها کمکی به شما نخواهند کرد\&. به عبارت دیگر، آنها در تهیه پشتیبان از محتوای ایندکس، درخت کاری، استش، پیکربندی خاص هر مخزن، هوکها و غیره به شما کمکی نمیکنند\&.
.sp
همچنین برای بررسی مشکلات مربوط به همگامسازی فایلها میان سیستمها، به \fBgitfaq\fR(7)، بخش "TRANSFERS" مراجعه کنید\&.
.SH "قالب فایل (FILE FORMAT)"
.sp
به \fBgitformat-bundle\fR(5) مراجعه کنید\&.
.SH "همچنین ببینید (SEE ALSO)"
.sp
\fBgitformat-bundle\fR(5), \fBgit-clone\fR(1), \fBgit-fetch\fR(1), \fBgit-pack-objects\fR(1), \fBgitformat-pack\fR(5)
.SH "گیت (GIT)"
.sp
بخشی از مجموعه \fBgit\fR(1)