نام (NAME)

git-bundle - جابجایی اشیا و ارجاعات از طریق بسته‌بندی در قالب فایل بایگانی

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

git bundle create [-q | --quiet | --progress]
                    [--version=<version>] <file> <git-rev-list-args>
git bundle verify [-q | --quiet] <file>
git bundle list-heads <file> [<refname>...]
git bundle unbundle [--progress] <file> [<refname>...]

توضیحات (DESCRIPTION)

ایجاد، باز کردن و کار با فایل‌های «باندل» (bundle). باندل‌ها برای انتقال «آفلاین» اشیای گیت بدون نیاز به وجود یک «سرور» فعال در سمت دیگر ارتباط شبکه استفاده می‌شوند.

آن‌ها می‌توانند هم برای ایجاد پشتیبان‌های افزایشی (incremental) و هم پشتیبان‌های کامل از یک مخزن (نگاه کنید به مثال «پشتیبان کامل» در بخش «مثال‌ها»)، و هم برای انتقال وضعیت ارجاعات از یک مخزن به مخزنی دیگر استفاده شوند (نگاه کنید به مثال دوم).

دستورات گیت که از طریق پروتکل‌هایی مانند ssh:// و https:// داده‌ها را واکشی کرده یا به هر نحو «می‌خوانند»، می‌توانند روی فایل‌های باندل نیز عمل کنند. می‌توان یک مخزن جدید را با git-clone(1) از یک باندل کلون کرد، از git-fetch(1) برای واکشی از آن استفاده نمود، و ارجاعات موجود در آن را با git-ls-remote(1) فهرست کرد. با این حال قابلیت متناظری برای «نوشتن» وجود ندارد، یعنی دستور git push بر روی یک باندل پشتیبانی نمی‌شود.

قالب بسته (BUNDLE FORMAT)

باندل‌ها همان فایل‌های .pack هستند (نگاه کنید به git-pack-objects(1)) که دارای یک سرآیند (header) می‌باشند که نشان می‌دهد چه ارجاعاتی در درون باندل قرار دارند.

مانند خود قالب بایگانی فشرده (packed archive)، باندل‌ها می‌توانند هم خودکفا (self-contained) باشند و هم با استفاده از استثناها (exclusions) ایجاد شوند. بخش «پیش‌نیازهای اشیا» در ادامه را ببینید.

باندل‌هایی که با استفاده از استثناهای بازبینی (revision exclusions) ایجاد می‌شوند، «بسته‌های نازک» (thin packs) هستند که با استفاده از گزینه --thin در دستور git-pack-objects(1) ساخته می‌شوند، و با استفاده از گزینه --fix-thin در git-index-pack(1) از حالت بسته‌بندی خارج (unbundle) می‌گردند.

هیچ گزینه‌ای برای ایجاد یک «بسته ضخیم» (thick pack) در زمان استفاده از استثناهای بازبینی وجود ندارد، و کاربران نباید نگران تفاوت آن‌ها باشند. با استفاده از «بسته‌های نازک»، باندل‌های ایجادشده با استثناها از نظر حجم کوچک‌تر هستند. اینکه آن‌ها در پشت صحنه «نازک» هستند صرفاً به عنوان یک نکته جالب و به عنوان ارجاعی به سایر مستندات در اینجا ذکر شده است.

برای جزئیات بیشتر به gitformat-bundle(5) و برای توضیحات بیشتر درباره «بسته نازک» به gitformat-pack(5) مراجعه کنید.

گزینه‌ها (OPTIONS)

create [options] <file> <git-rev-list-args>

verify <file>

list-heads <file>

unbundle <file>

<git-rev-list-args>

[<refname>...]

--progress

--version=<version>

-q, --quiet

مشخص کردن ارجاعات (SPECIFYING REFERENCES)

بازبینی‌ها (revisions) برای بسته‌بندی در یک باندل باید همراه با نام ارجاع باشند. به عنوان روش جایگزین می‌توان از --all برای بسته‌بندی تمام ارجاعات استفاده کرد.

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

دستور git bundle create نام ارجاعات را با استفاده از همان قوانین git rev-parse --abbrev-ref=loose برای شما حل‌وفصل می‌کند. هر پیش‌نیاز می‌تواند به طور صریح (مانند ^master~10) یا ضمنی (مانند master~10..master یا --since=10.days.ago master) مشخص شود.

تمام این موارد ساده مجاز هستند (با فرض اینکه شاخه‌های "master" و "next" را داریم):

$ 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

و همچنین موارد زیر (و نمونه‌های مشابه بدون --stdin):

$ git bundle create recent-master.bundle master~10..master
$ git bundle create recent-updates.bundle master~10..master next~5..next

نام یک بازبینی یا بازه‌ای که سمت راست آن نتواند به یک ارجاع حل‌وفصل شود، پذیرفته نمی‌شود:

$ 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.

پیش‌نیازهای اشیا (OBJECT PREREQUISITES)

هنگام ساخت باندل‌ها، امکان ایجاد یک باندل خودکفا وجود دارد که می‌تواند در مخزنی بدون هیچ تاریخچه مشترکی باز شود، و همچنین می‌توان بازبینی‌های منفی ارائه داد تا اشیای مورد نیاز در بخش‌های قبلی تاریخچه مستثنی شوند.

دادن یک بازبینی مانند new به git bundle create فایلی از نوع باندل تولید می‌کند که حاوی تمام اشیای قابل دسترسی از بازبینی new است. آن باندل می‌تواند در هر مخزنی باز شود تا تاریخچه کاملی که به بازبینی new منتهی می‌شود به دست آید:

$ git bundle create full.bundle new

یک بازه بازبینی مانند old..new فایلی از نوع باندل تولید می‌کند که برای باز شدن باندل نیازمند وجود بازبینی old (و هر شیء قابل دسترسی از آن) خواهد بود:

$ git bundle create full.bundle old..new

یک باندل خودکفا بدون هیچ پیش‌نیازی را می‌توان در هر جایی استخراج کرد، حتی در یک مخزن خالی، یا از آن کلون گرفت (یعنی new، اما نه old..new).

احتیاط کردن و گنجاندن اشیایی در فایل باندل که هم‌اکنون در مقصد وجود دارند اشکالی ندارد، زیرا هنگام باز کردن بسته در مقصد نادیده گرفته می‌شوند.

اگر می‌خواهید همان مجموعه ارجاعاتی را فراهم کنید که کلون مستقیم از مخزن مبدا دریافت می‌کند، از --branches --tags برای <git-rev-list-args> استفاده کنید.

دستور git bundle verify می‌تواند برای بررسی اینکه آیا مخزن گیرنده شما کامیت‌های پیش‌نیاز لازم برای یک باندل را دارد یا خیر، استفاده شود.

مثال‌ها (EXAMPLES)

ما دو حالت را بررسی خواهیم کرد:

ابتدا یک پشتیبان کامل از مخزن را در نظر می‌گیریم. دستور زیر یک نسخه پشتیبان کامل از مخزن تهیه می‌کند به این معنا که تمام ارجاعات در باندل گنجانده می‌شوند:

$ git bundle create backup.bundle --all

اما مجدداً توجه داشته باشید که این پشتیبان فقط برای ارجاعات است، یعنی شما فقط ارجاعات و کامیت‌های قابل دسترسی از آن ارجاعات را شامل خواهید کرد. سایر وضعیت‌های محلی مانند محتوای ایندکس، درخت کاری (working tree)، استش (stash)، پیکربندی‌های خاص هر مخزن، هوک‌ها و غیره را شامل نخواهید کرد.

بعداً می‌توانید آن مخزن را برای نمونه با استفاده از git-clone(1) بازیابی کنید:

$ git clone backup.bundle <new directory>

برای مثال بعد، فرض کنید می‌خواهید تاریخچه را از یک مخزن R1 روی ماشین A به مخزن دیگری به نام R2 روی ماشین B منتقل کنید. به هر دلیلی، ارتباط مستقیم بین A و B مجاز نیست، اما می‌توانیم داده‌ها را از طریق سازوکاری (سی‌دی، ایمیل، و غیره) از A به B منتقل کنیم. ما می‌خواهیم R2 را با تغییرات ایجادشده روی شاخه master در R1 به‌روز کنیم.

برای راه‌اندازی اولیه فرآیند، ابتدا می‌توانید باندلی ایجاد کنید که هیچ پیش‌نیازی ندارد. می‌توانید از یک تگ برای به خاطر سپردن اینکه تا چه کامیتی را قبلاً پردازش کرده‌اید استفاده کنید، تا بعداً به‌روزرسانی مخزن دیگر با یک باندل افزایشی آسان‌تر شود:

machineA$ cd R1
machineA$ git bundle create file.bundle master
machineA$ git tag -f lastR2bundle master

سپس فایل file.bundle را به ماشین مقصد B منتقل می‌کنید. از آنجا که این باندل برای استخراج نیازی به هیچ شیء موجودی ندارد، می‌توانید با کلون کردن از آن یک مخزن جدید در ماشین B ایجاد کنید:

machineB$ git clone -b master /home/me/tmp/file.bundle R2

این کار یک کنترل از راه دور (remote) به نام "origin" در مخزن حاصل تعریف می‌کند که به شما امکان می‌دهد از باندل واکشی (fetch) و دریافت (pull) کنید. فایل $GIT_DIR/config در R2 ورودی مشابه این خواهد داشت:

[remote "origin"]
    url = /home/me/tmp/file.bundle
    fetch = refs/heads/*:refs/remotes/origin/*

برای به‌روزرسانی مخزن حاصل، می‌توانید پس از جایگزین کردن باندل ذخیره‌شده در /home/me/tmp/file.bundle با به‌روزرسانی‌های افزایشی، عملیات fetch یا pull را انجام دهید.

پس از انجام کارهای بیشتر در مخزن اصلی، می‌توانید یک باندل افزایشی برای به‌روزرسانی مخزن دیگر ایجاد کنید:

machineA$ cd R1
machineA$ git bundle create file.bundle lastR2bundle..master
machineA$ git tag -f lastR2bundle master

سپس باندل را به ماشین دیگر منتقل می‌کنید تا جایگزین /home/me/tmp/file.bundle شود، و از آن pull می‌کنید.

machineB$ cd R2
machineB$ git pull

اگر بدانید مخزن گیرنده مورد نظر تا چه کامیتی اشیای لازم را در خود دارد، می‌توانید از آن آگاهی برای تعیین پیش‌نیازها استفاده کنید و یک نقطه قطع برای محدود کردن بازبینی‌ها و اشیایی که در باندل حاصل قرار می‌گیرند تعیین نمایید. مثال قبلی از تگ lastR2bundle برای این منظور استفاده کرد، اما شما می‌توانید از هر گزینه دیگری که به دستور git-log(1) می‌دادید استفاده کنید. در اینجا مثال‌های بیشتری آمده است:

می‌توانید از تگی استفاده کنید که در هر دو وجود دارد:

$ git bundle create mybundle v1.0.0..master

می‌توانید از پیش‌نیازی بر اساس زمان استفاده کنید:

$ git bundle create mybundle --since=10.days master

می‌توانید از تعداد کامیت‌ها استفاده کنید:

$ git bundle create mybundle -10 master

می‌توانید دستور git-bundle verify را اجرا کنید تا ببینید آیا می‌توانید از باندلی که با یک پیش‌نیاز ایجاد شده است استخراج نمایید یا خیر:

$ git bundle verify mybundle

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

یک باندل از دیدگاه مخزن گیرنده، دقیقاً مانند یک مخزن معمولی است که از آن واکشی (fetch) یا دریافت (pull) می‌کند. برای نمونه، می‌توانید ارجاعات را هنگام واکشی نقشه‌برداری کنید:

$ git fetch mybundle master:localRef

همچنین می‌توانید ببینید چه ارجاعاتی ارائه می‌دهد:

$ git ls-remote mybundle

بحث و بررسی (DISCUSSION)

یک روش ناشیانه برای تهیه نسخه پشتیبان کامل از یک مخزن، استفاده از دستوری مانند cp -r <repo> <destination> است. استفاده از این روش توصیه نمی‌شود، زیرا ممکن است در حین عملیات کپی در مخزن نوشته شود. در نتیجه ممکن است برخی از فایل‌ها در <destination> دچار خرابی شوند.

به همین دلیل توصیه می‌شود برای تهیه نسخه پشتیبان از مخزن، از ابزارهای گیت استفاده کنید؛ چه با این دستور یا به عنوان مثال با git-clone(1). اما در نظر داشته باشید که این ابزارها برای پشتیبان‌گیری از وضعیت‌هایی به جز ارجاعات و کامیت‌ها کمکی به شما نخواهند کرد. به عبارت دیگر، آن‌ها در تهیه پشتیبان از محتوای ایندکس، درخت کاری، استش، پیکربندی خاص هر مخزن، هوک‌ها و غیره به شما کمکی نمی‌کنند.

همچنین برای بررسی مشکلات مربوط به همگام‌سازی فایل‌ها میان سیستم‌ها، به gitfaq(7)، بخش "TRANSFERS" مراجعه کنید.

قالب فایل (FILE FORMAT)

به gitformat-bundle(5) مراجعه کنید.

همچنین ببینید (SEE ALSO)

gitformat-bundle(5), git-clone(1), git-fetch(1), git-pack-objects(1), gitformat-pack(5)

گیت (GIT)

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