українська мова ▾ Topics ▾ Latest version ▾ git-bundle last updated in 2.48.0

НАЗВА

git-bundle - Переміщення об’єктів та посилань за архівом

СИНОПСИС

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>…​]

ОПИС

Створення, розпакування та маніпулювання файлами-"бандрами". Бандри використовуються для "офлайн" передачі об’єктів Git без активного "сервера" на іншому боці мережевого з’єднання.

Їх можна використовувати для створення як інкрементальних, так і повних резервних копій репозиторію (див. приклад «повної резервної копії» в розділі «ПРИКЛАДИ»), а також для передачі стану посилань з одного репозиторію до іншого (див. другий приклад).

Команди Git, які отримують або іншим чином "читають" дані через протоколи, такі як ssh:// та https://, також можуть працювати з файлами пакета. Можна створити новий репозиторій з пакета за допомогою git-clone[1], скористатися git-fetch[1] для отримання даних з нього та переглянути список посилань, що містяться в ньому, за допомогою git-ls-remote[1]. Відповідної підтримки "запису" немає, тобто "внесення змін до пакета" не підтримується.

ФОРМАТ ПАКЕТА

Пакети — це файли .pack (див. git-pack-objects[1]) із заголовком, що вказує на те, які посилання містяться в пакеті.

Як і сам формат упакованого архіву, пакети можуть бути автономними або створюватися за допомогою виключень. Див. розділ «ПЕРЕДУМОВИ ДО ОБ’ЄКТА» нижче.

Пакети, створені за допомогою виключень ревізій, є "тонкими пакетами", створеними за допомогою опції --thin для git-pack-objects[1], та розпакованими за допомогою опції --fix-thin для git-index-pack[1].

Немає опції створення «товстого пакету» під час використання виключень редакцій, і користувачам не варто турбуватися про цю різницю. Завдяки використанню «тонких пакетів» пакети, створені за допомогою виключень, мають менший розмір. Те, що вони «тонкі» під капотом, зазначається тут лише як цікавість та як посилання на іншу документацію.

Див. gitformat-bundle[5] для отримання додаткової інформації та обговорення "тонкого пакету" у gitformat-pack[5] для отримання додаткової інформації.

ОПЦІЇ

створити [опції] <file> <git-rev-list-args>

Використовується для створення пакета з назвою «file». Для цього потрібні аргументи «<git-rev-list-args>» для визначення вмісту пакета. «options» містить опції, специфічні для підкоманди «git bundle create». Якщо «file» має значення -, пакет записується на stdout.

перевірити <file>

Використовується для перевірки валідності файлу пакета та його коректного застосування до поточного репозиторію. Це включає перевірку самого формату пакета, а також перевірку наявності необхідних комітів та їх повного посилання в поточному репозиторії. Потім, git bundle виводить список відсутніх комітів, якщо такі є. Нарешті, виводиться інформація про додаткові можливості, такі як "фільтр об’єктів". Див. "Можливості" в gitformat-bundle[5] для отримання додаткової інформації. Код виходу дорівнює нулю для успішного виконання, але буде відмінним від нуля, якщо файл пакета недійсний. Якщо file має значення -, пакет зчитується зі stdin.

керівники списків <file>

Перелічує посилання, визначені в пакеті. Якщо після нього наведено список посилань, виводяться лише посилання, що відповідають заданим. Якщо file має значення -, пакет зчитується зі stdin.

розпакувати <file>

Передає об’єкти з пакету до git index-pack для зберігання в репозиторії, а потім друкує імена всіх визначених посилань. Якщо задано список посилань, друкуються лише посилання, що відповідають тим, що у списку. Ця команда насправді є ланцюжком посилань, призначена для виклику лише командою git fetch. Якщо file має значення -, пакет зчитується зі stdin.

<git-rev-list-args>

Список аргументів, прийнятних для git rev-parse та git rev-list (і що містять іменований ref, див. ВИЗНАЧЕННЯ ПОСИЛАНЬ нижче), що вказує конкретні об’єкти та посилання для транспортування. Наприклад, master~10..master призводить до того, що поточне master-посилання упаковується разом з усіма об’єктами, доданими з моменту його 10-го коміту-предка. Немає явного обмеження на кількість посилань та об’єктів, які можна упаковати.

[<refname>…​]

Список посилань, що використовується для обмеження посилань, що повідомляються як доступні. Це головним чином корисно для «git fetch», який очікує отримати лише ті посилання, що запитуються, а не обов’язково все з пакета (у цьому випадку «git bundle» діє як «git fetch-pack»).

--progress

Стан виконання за замовчуванням повідомляється у стандартному потоці помилок, коли він підключений до терміналу, якщо не вказано -q. Цей прапорець примусово повідомляє про стан виконання, навіть якщо стандартний потік помилок не спрямований до терміналу.

--version=<version>

Вкажіть версію пакета. Версія 2 — це старіший формат, який можна використовувати лише з репозиторіями SHA-1; новіша версія 3 містить можливості, що дозволяють розширення. За замовчуванням використовується найстаріший підтримуваний формат, що базується на використовуваному алгоритмі хешування.

-q
--quiet

Цей прапорець забороняє команді повідомляти про свій хід виконання у стандартному потоці помилок.

ВКАЗАННЯ ПОСИЛАНЬ

Для упаковки в пакет редакцій необхідно вказати імена посилань. Або ж можна використовувати --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)
фатальний результат: Відмова у створенні порожнього пакета.
$ git bundle create master-yesterday.bundle master~10..master~5
фатальний результат: Відмова у створенні порожнього пакета.

ПЕРЕДУМОВИ ОБ’ЄКТА

Під час створення пакетів можна створити автономний пакет, який можна розпакувати в репозиторії без спільної історії, а також надати негативні ревізії, щоб виключити об’єкти, необхідні в попередніх частинах історії.

Передавання ревізії, такої як new, до git bundle create створить файл пакета, який містить усі об’єкти, доступні з ревізії new. Цей пакет можна розпакувати в будь-якому репозиторії, щоб отримати повну історію, яка веде до ревізії new:

$ git bundle create full.bundle new

Діапазон ревізій, такий як old..new, створить файл пакета, який вимагатиме існування ревізії old (та будь-яких об’єктів, доступних з неї), щоб пакет можна було "розпакувати":

$ git bundle create full.bundle old..new

Автономний пакет без будь-яких передумов можна розпакувати будь-куди, навіть у порожній репозиторій, або клонувати з нього (тобто новий, але не старий..новий).

Це нормально бути обережним, спричиняючи те, що файл пакета містить об’єкти, які вже знаходяться в місці призначення, оскільки вони ігноруються під час розпакування в місці призначення.

Якщо ви хочете надати той самий набір посилань, який отримав би клон безпосередньо з вихідного репозиторію, використовуйте --branches --tags для <git-rev-list-args>.

Команду «git bundle verify» можна використовувати для перевірки того, чи має ваш репозиторій-одержувач необхідні коміти для пакета.

ПРИКЛАДИ

Ми обговоримо два випадки:

  1. Створення повної резервної копії репозиторію

  2. Перенесення історії репозиторію на іншу машину, коли дві машини не мають прямого з’єднання

Спочатку розглянемо повну резервну копію репозиторію. Наступна команда створить повну резервну копію репозиторію, тобто всі посилання будуть включені до пакету:

$ git bundle create backup.bundle --all

Але знову зауважте, що це стосується лише посилань, тобто ви включатимете лише посилання та коміти, доступні з цих посилань. Ви не включатимете інший локальний стан, такий як вміст індексу, робоче дерево, сховище, конфігурацію для кожного репозиторію, перехоплення тощо.

Ви можете пізніше відновити цей репозиторій, використовуючи, наприклад, git-clone[1]:

$ git clone backup.bundle <new directory>

Для наступного прикладу припустимо, що ви хочете перенести історію з репозиторію R1 на машині A до іншого репозиторію R2 на машині B. З якоїсь причини пряме з’єднання між A та B заборонено, але ми можемо перемістити дані з A до B за допомогою певного механізму (компакт-диск, електронна пошта тощо). Ми хочемо оновити R2, враховуючи розробку, виконану на головній гілці в 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

Це визначить віддалений об’єкт під назвою "origin" у результуючому репозиторії, який дозволить вам отримувати дані з пакета. Файл $GIT_DIR/config у R2 матиме запис:

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

Щоб оновити отриманий репозиторій mine.git, ви можете скористатися fetch або pull після заміни пакета, що зберігається в /home/me/tmp/file.bundle, на інкрементальні оновлення.

Після подальшої роботи в оригінальному репозиторії ви можете створити інкрементальний пакет для оновлення іншого репозиторію:

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

Потім ви переносите пакет на іншу машину, щоб замінити /home/me/tmp/file.bundle, та витягуєте з нього дані.

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

Тут буде перераховано, які коміти потрібні для вилучення з пакета, і виникне помилка, якщо їх немає.

З точки зору репозиторію-одержувача, пакет подібний до звичайного репозиторію, з якого він отримує дані. Наприклад, ви можете зіставляти посилання під час отримання:

$ git fetch mybundle master:localRef

Ви також можете побачити, які рекомендації він пропонує:

$ git ls-remote mybundle

ОБГОВОРЕННЯ

Наївний спосіб створити повну резервну копію репозиторію — це використовувати щось на кшталт cp -r <репозиторій> <призначення>. Це не рекомендується, оскільки під час операції копіювання до репозиторію може бути записано дані. У свою чергу, деякі файли в <призначення> можуть бути пошкоджені.

Ось чому рекомендується використовувати інструменти Git для створення резервних копій репозиторіїв, або за допомогою цієї команди, або, наприклад, git-clone[1]. Але майте на увазі, що ці інструменти не допоможуть вам створити резервну копію стану, окрім посилань та комітів. Іншими словами, вони не допоможуть вам створити резервну копію вмісту індексу, робочого дерева, сховища, конфігурації для кожного репозиторію, гачків тощо.

Див. також gitfaq[7], розділ "ПЕРЕДАЧІ" для обговорення проблем, пов’язаних із синхронізацією файлів між системами.

ФОРМАТ ФАЙЛУ

Див. gitformat-bundle[5].

GIT

Частина набору git[1]