git-bundle

git-bundle - Перемещение объектов и ссылок через архив

Создание, распаковка и манипулирование файлами «bundle». Бэндлы используются для «оффлайн» передачи Git-объектов без активного «сервера» на другом конце сетевого подключения.

Они могут использоваться для создания как инкрементных, так и полных резервных копий репозитория (см. пример «полной резервной копии» в «ПРИМЕРАХ»), а также для передачи состояния ссылок из одного репозитория в другой (см. второй пример).

Команды Git, которые получают или иным образом «читают» через протоколы, такие как ssh:// и https://, также могут работать с файлами bundle. Возможно git-clone[1] нового репозитория из бэндла, использовать git-fetch[1] для получения данных из него и просмотреть ссылки, содержащиеся в нём, с помощью git-ls-remote[1]. Нет соответствующей поддержки «записи», т.е. git push в бэндл не поддерживается.

Бэндлы являются файлами .pack (см. git-pack-objects[1]) с заголовком, указывающим, какие ссылки содержатся в бэндле.

Как и сам формат упакованного архива, бэндлы могут быть самодостаточными или создаваться с использованием исключений. См. раздел «ПРЕДПОСЫЛКИ ОБЪЕКТОВ» ниже.

Бэндлы, созданные с использованием исключений ревизий, являются «тонкими пакетами», созданными с помощью параметра --thin для git-pack-objects[1], и распаковываются с помощью параметра --fix-thin для git-index-pack[1].

Нет возможности создать «толстый пакет», используя исключения ревизий, и пользователи не должны беспокоиться о различии. Использование «тонких пакетов» приводит к тому, что созданные с исключениями бэндлы занимают меньше места. То, что они являются «тонкими» под капотом, отмечается здесь просто из любопытства и как ссылка на другую документацию.

См. gitformat-bundle[5] для получения более подробной информации и обсуждение «тонких пакетов» в gitformat-pack[5] для получения дополнительных подробностей.

Ревизии должны сопровождаться именами ссылок, чтобы быть упакованными в бэндл. В качестве альтернативы можно использовать --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.

При создании бэндлов можно создать самодостаточный бэндл, который можно распаковать в репозиторий без общей истории, а также указать отрицательные ревизии, чтобы исключить объекты, необходимые в более ранних частях истории.

Передача ревизии, такой как 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 может использоваться для проверки, имеет ли репозиторий получателя необходимые предварительные коммиты для бэндла.

Рассмотрим два случая:

Сначала рассмотрим полное резервное копирование репозитория. Следующая команда выполнит полное резервное копирование репозитория, включив все ссылки (refs):

$ git bundle create backup.bundle --all

Но обратите внимание, что это только для ссылок (refs), т.е. вы включите только ссылки и коммиты, доступные по этим ссылкам. Вы не включите другой локальный статус, например, содержимое индекса, рабочей области, отложенных изменений, конфигурацию репозитория, хуки и т.д.

Позже вы можете восстановить этот репозиторий, например, с помощью git-clone[1]:

$ git clone backup.bundle <new directory>

Для следующего примера предположим, что вы хотите перенести историю репозитория R1 на машине А в другой репозиторий R2 на машине B. По какой-либо причине прямое подключение между А и B недоступно, но мы можем передавать данные с А на B через какой-либо механизм (CD, электронная почта и т.д.). Мы хотим обновить 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

Это определит удалённый ресурс под названием "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, и выполните 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

Это покажет, какие коммиты вам необходимы для извлечения данных из пакета и выдаст ошибку, если их нет.

Пакет с точки зрения репозитория получателя — это просто обычный репозиторий, из которого можно получать или подключать данные. Например, можно сопоставить ссылки при получении данных:

$ git fetch mybundle master:localRef

Также можно посмотреть, какие ссылки он предоставляет:

$ git ls-remote mybundle

Примитивный способ создания полного резервного копирования репозитория — использовать что-то вроде cp -r <repo> <destination>. Это не рекомендуется, так как репозиторий может быть записан во время операции копирования. В результате некоторые файлы в <destination> могут быть повреждены.

Поэтому рекомендуется использовать инструменты Git для создания резервных копий репозиториев, либо с помощью данной команды, либо, например, с помощью git-clone[1]. Но имейте в виду, что эти инструменты не помогут вам создать резервную копию состояния, кроме refs и коммитов. Другими словами, они не помогут вам создать резервную копию содержимого индекса, рабочей области, отложенных изменений, конфигурации репозитория, хуков и т.д.

См. также gitfaq[7], раздел "ПЕРЕДАЧИ", для обсуждения проблем, связанных с синхронизацией файлов между системами.

См. gitformat-bundle[5].