git-fast-import

Параметры для фронтендов

Расположение файлов меток

Преобразование подмодулей

Настройка производительности и сжатия

Комментарии в потоке

Для упрощения отладки фронтендов fast-import игнорирует любую строку, начинающуюся с # (ASCII-символ решётки), вплоть до конца строки LF включительно. Строка комментария может содержать любую последовательность байтов без LF и поэтому подходит для включения подробной отладочной информации, специфичной для фронтенда и полезной при анализе потока данных fast-import.

Форматы дат

Поддерживаются следующие форматы дат. Фронтенд должен выбрать формат для этого импорта, передав его имя в параметре командной строки --date-format=<fmt>.

Команды

fast-import принимает несколько команд для обновления текущего репозитория и управления текущим процессом импорта. Далее приводится более подробное описание каждой команды с примерами.

commit

Создаёт или обновляет ветку новым коммитом, фиксируя одно логическое изменение проекта.

        'commit' SP <ref> LF
        mark?
        original-oid?
        ('author' (SP <name>)? SP LT <email> GT SP <when> LF)?
        'committer' (SP <name>)? SP LT <email> GT SP <when> LF
        ('gpgsig' SP <algo> SP <format> LF data)?
        ('encoding' SP <encoding> LF)?
        data
        ('from' SP <commit-ish> LF)?
        ('merge' SP <commit-ish> LF)*
        (filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
        LF?

где <ref> — имя ветки, в которую нужно внести коммит. Обычно в Git перед именами веток ставится префикс refs/heads/, поэтому для импорта символа ветки CVS RELENG-1_0 в качестве значения <ref> следует использовать refs/heads/RELENG-1_0. Значение <ref> должно быть допустимым именем ссылки в Git. Поскольку LF недопустимо в имени ссылки Git, синтаксис кавычек или экранирования здесь не поддерживается.

После команды может необязательно указываться команда mark, которая просит fast-import сохранить ссылку на только что созданный коммит для дальнейшего использования фронтендом (формат описан ниже). Фронтенды часто помечают каждый создаваемый ими коммит, что позволяет впоследствии создавать ветки от любого импортированного коммита.

Следующая за committer команда data должна содержать сообщение коммита (синтаксис команды data описан ниже). Чтобы импортировать коммит с пустым сообщением, используйте данные нулевой длины. Сообщения коммитов имеют произвольный формат, и Git их не интерпретирует. В настоящее время они должны быть закодированы в UTF-8, поскольку fast-import не позволяет указывать другие кодировки.

Перед созданием коммита для обновления содержимого ветки можно включить ноль или более команд filemodify, filedelete, filecopy, filerename, filedeleteall и notemodify. Эти команды можно указывать в любом порядке. Однако рекомендуется, чтобы в одном коммите команда filedeleteall предшествовала всем командам filemodify, filecopy, filerename и notemodify, поскольку filedeleteall очищает ветку (см. ниже).

Завершающий команду LF необязателен (раньше он был обязательным). Обратите внимание: для обеспечения обратной совместимости, если коммит заканчивается командой data (то есть в нём нет команд from, merge, filemodify, filedelete, filecopy, filerename, filedeleteall или notemodify), то в конце команды вместо одной могут следовать две команды LF.

        'gpgsig' SP <git-hash-algo> SP <signature-format> LF data

        from refs/heads/branch^0

        'D' SP <path> LF

        'C' SP <path> SP <path> LF

        'R' SP <path> SP <path> LF

        'deleteall' LF

mark

Указывает fast-import сохранить ссылку на текущий объект, чтобы фронтенд мог обратиться к нему в будущем, не зная его SHA-1. Здесь текущим объектом является объект, создаваемый командой, внутри которой находится команда mark. Это может быть commit, tag или blob, но чаще всего используется commit.

        'mark' SP ':' <idnum> LF

где <idnum> — номер метки, назначенный ей фронтендом. Значение <idnum> записывается десятичным целым числом в кодировке ASCII. Значение 0 зарезервировано и не может использоваться как метка. В качестве меток допустимы только значения, большие или равные 1.

Новые метки создаются автоматически. Существующие метки можно переназначить другому объекту, просто повторно использовав то же значение <idnum> в другой команде mark.

original-oid

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

        'original-oid' SP <object-identifier> LF

где <object-identifier> — любая строка, не содержащая LF.

tag

Создаёт аннотированный тег, указывающий на определённый коммит. Чтобы создать облегчённые (без аннотации) теги, см. команду reset ниже.

        'tag' SP <name> LF
        mark?
        'from' SP <commit-ish> LF
        original-oid?
        'tagger' (SP <name>)? SP LT <email> GT SP <when> LF
        data

где <name> — имя создаваемого тега.

При сохранении в Git к именам тегов автоматически добавляется префикс refs/tags/, поэтому для импорта символа ветки CVS RELENG-1_0-FINAL в качестве <name> достаточно указать RELENG-1_0-FINAL, и fast-import запишет соответствующую ссылку как refs/tags/RELENG-1_0-FINAL.

Значение <name> должно быть допустимым именем ссылки в Git и поэтому может содержать косые черты. Поскольку LF недопустим в имени ссылки Git, здесь не поддерживается синтаксис заключения в кавычки или экранирования.

Команда from такая же, как в команде commit; подробности см. выше.

Команда tagger использует тот же формат, что и committer в commit; подробности также см. выше.

Команда data, следующая за tagger, должна предоставлять сообщение аннотированного тега (синтаксис команды data см. ниже). Чтобы импортировать пустое сообщение тега, укажите данные нулевой длины. Сообщения тегов имеют произвольный формат и не интерпретируются Git. В настоящее время они должны быть закодированы в UTF-8, поскольку fast-import не позволяет указывать другие кодировки.

Подписывать аннотированные теги во время импорта из fast-import нельзя. Не рекомендуется пытаться включить собственную подпись PGP/GPG, поскольку интерфейсная программа не имеет (простого) доступа к полному набору байтов, которые обычно входят в такую подпись. Если подпись необходима, создайте с помощью reset облегчённые теги из fast-import, а затем создайте для них аннотированные версии вне программы, используя стандартный процесс git tag.

reset

Создаёт (или пересоздаёт) указанную ветку, при необходимости начиная с определённой ревизии. Команда reset позволяет интерфейсной программе выдать новую команду from для существующей ветки или создать новую ветку на основе существующего коммита, не создавая новый коммит.

        'reset' SP <ref> LF
        ('from' SP <commit-ish> LF)?
        LF?

Подробное описание <ref> и <commit-ish> см. выше в разделах commit и from.

Команда LF после этой команды необязательна (раньше она была обязательной).

Команду reset также можно использовать для создания облегчённых (без аннотации) тегов. Например:

reset refs/tags/938
from :938

создаст облегчённый тег refs/tags/938, указывающий на коммит, на который ссылается метка :938.

blob

Запрашивает запись одной версии файла в pack-файл. Эта версия не связана ни с одним коммитом; связь должна быть установлена последующей командой commit, которая ссылается на blob через назначенную метку.

        'blob' LF
        mark?
        original-oid?
        data

Здесь команда mark необязательна, поскольку некоторые интерфейсные программы генерируют Git SHA-1 для blob самостоятельно и напрямую передают его команде commit. Однако обычно это не стоит затраченных усилий, поскольку хранить метки недорого, а пользоваться ими просто.

data

Передаёт в fast-import необработанные данные (для использования в качестве содержимого blob/файла, сообщений коммитов или сообщений аннотированных тегов). Данные можно передать, указав точное количество байтов или ограничив их завершающей строкой. Интерфейсные программы для преобразований производственного качества всегда должны использовать формат с точным количеством байтов, поскольку он надёжнее и эффективнее. Формат с разделителем предназначен главным образом для тестирования fast-import.

Строки комментариев, встречающиеся в части <raw> команд data, всегда считаются частью тела данных и поэтому никогда не игнорируются fast-import. Это позволяет безопасно импортировать содержимое любых файлов и сообщений, строки которых могут начинаться с #.

alias

Записывает, что метка ссылается на заданный объект, не создавая предварительно нового объекта.

        'alias' LF
        mark
        'to' SP <commit-ish> LF
        LF?

Подробное описание <commit-ish> см. выше в разделе from.

checkpoint

Принудительно закрывает текущий pack-файл, начинает новый и сохраняет все текущие ссылки веток, теги и метки.

        'checkpoint' LF
        LF?

Обратите внимание: fast-import автоматически переключает pack-файлы, когда текущий pack-файл достигает размера --max-pack-size или 4 ГиБ — в зависимости от того, какой предел меньше. При автоматическом переключении pack-файла fast-import не обновляет ссылки веток, теги или метки.

Поскольку выполнение команды checkpoint может потребовать значительного времени процессора и операций ввода-вывода с диском (для вычисления контрольной суммы SHA-1 всего pack-файла, создания соответствующего индексного файла и обновления ссылок), выполнение одной команды checkpoint может легко занять несколько минут.

Интерфейсные программы могут создавать контрольные точки во время очень крупных и длительных импортов или когда необходимо предоставить другому процессу Git доступ к ветке. Однако репозиторий Subversion размером 30 ГиБ можно загрузить в Git с помощью fast-import примерно за 3 часа, поэтому явное создание контрольных точек может быть не нужно.

Символ LF после команды необязателен (раньше он был обязательным).

progress

При обработке команды во входном потоке fast-import выводит всю строку progress без изменений в стандартный канал вывода (дескриптор файла 1). В остальном команда не влияет на текущий импорт или внутреннее состояние fast-import.

        'progress' SP <any> LF
        LF?

Часть команды <any> может содержать любую последовательность байтов, не содержащую LF. Символ LF после команды необязателен. Вывод можно обработать с помощью такого инструмента, как sed, чтобы удалить начальную часть строки. Например:

frontend | git fast-import | sed 's/^progress //'

Команда progress, размещённая сразу после checkpoint, сообщит читателю о завершении checkpoint, после чего можно безопасно обращаться к ссылкам, обновлённым fast-import.

get-mark

Заставляет fast-import вывести SHA-1, соответствующий метке, в stdout или в дескриптор файла, заданный ранее аргументом --cat-blob-fd. В остальном команда не влияет на текущий импорт; она предназначена для получения SHA-1, на которые могут ссылаться более поздние коммиты в своих сообщениях.

        'get-mark' SP ':' <idnum> LF

Подробные сведения о безопасном чтении этого вывода см. ниже в разделе «Ответы на команды».

cat-blob

Заставляет fast-import вывести blob в дескриптор файла, заданный ранее аргументом --cat-blob-fd. В остальном команда не влияет на текущий импорт; её основное назначение — извлекать blob, которые могут находиться в памяти fast-import, но недоступны в целевом репозитории.

        'cat-blob' SP <dataref> LF

<dataref> может быть ссылкой на ранее заданную метку (:<idnum>) или полным 40-байтовым SHA-1 blob Git, уже существующего или готового к записи.

Вывод имеет тот же формат, что и git cat-file --batch:

<sha1> SP 'blob' SP <size> LF
<contents> LF

Эту команду можно использовать там, где может располагаться директива filemodify, в том числе в середине коммита. Для filemodify с директивой inline её также можно разместить непосредственно перед директивой data.

Подробные сведения о безопасном чтении этого вывода см. ниже в разделе «Ответы на команды».

ls

Выводит сведения об объекте по указанному пути в дескриптор файла, заданный ранее аргументом --cat-blob-fd. Это позволяет вывести blob из активного коммита (с помощью cat-blob) или скопировать blob или дерево из предыдущего коммита для использования в текущем (с помощью filemodify).

Команду ls также можно использовать там, где может располагаться директива filemodify, в том числе в середине коммита.

Подробное описание <path> см. выше в разделе filemodify.

Вывод имеет тот же формат, что и git ls-tree <tree> -- <path>:

<mode> SP ('blob' | 'tree' | 'commit') SP <dataref> HT <path> LF

<dataref> представляет объект blob, tree или commit по пути <path> и может использоваться в последующих командах get-mark, cat-blob, filemodify или ls.

Если по этому пути нет файла или поддерева, git fast-import сообщит:

missing SP <path> LF

Подробные сведения о безопасном чтении этого вывода см. ниже в разделе «Ответы на команды».

feature

Требует, чтобы fast-import поддерживал указанную функцию, и прерывает работу, если это не так.

        'feature' SP <feature> ('=' <argument>)? LF

В качестве части <feature> команды можно указать одно из следующих значений:

option

Обрабатывает указанный параметр, чтобы git fast-import работал в соответствии с потребностями интерфейсной программы. Обратите внимание: параметры, указанные интерфейсной программой, переопределяются любыми параметрами, которые пользователь может передать непосредственно git fast-import.

    'option' SP <option> LF

В качестве части команды <option> можно указать любой параметр из раздела ПАРАМЕТРЫ, который не меняет семантику импорта, без ведущего символа --; такой параметр обрабатывается обычным образом.

Команды option должны быть первыми во входном потоке (не считая команд feature); команда option после любой команды, не являющейся option, считается ошибкой.

Следующие параметры командной строки меняют семантику импорта, поэтому их нельзя передавать как option:

done

Если функция done не используется, эта команда обрабатывается так, как если бы был прочитан EOF. Её можно использовать, чтобы указать fast-import завершить работу досрочно.

Если используется параметр командной строки --done или команда feature done, команда done обязательна и обозначает конец потока.

Используйте отдельную метку для каждого коммита

При преобразовании репозитория используйте уникальную метку для каждого коммита (mark :<n>) и укажите параметр --export-marks в командной строке. fast-import создаст файл со списком всех меток и соответствующих им SHA-1 объектов Git. Если интерфейсная программа может связать метки с исходным репозиторием, точность и полноту импорта легко проверить, сравнив каждый коммит Git с соответствующей исходной ревизией.

Если исходная система — например, Perforce или Subversion, это должно быть несложно: метка fast-import может совпадать с номером набора изменений Perforce или номером ревизии Subversion.

Свободно переключайтесь между ветками

Не пытайтесь оптимизировать интерфейсную программу так, чтобы во время импорта она обрабатывала только одну ветку за раз. Хотя это может немного ускорить работу fast-import, сложность кода интерфейсной программы заметно возрастёт.

Встроенный в fast-import механизм LRU для веток работает очень хорошо, а затраты на активацию неактивной ветки настолько малы, что переключение между ветками практически не влияет на производительность импорта.

Обработка переименований

При импорте переименованного файла или каталога просто удалите старые имена и измените новые имена в соответствующем коммите. Git обнаруживает переименования постфактум, а не явно во время создания коммита.

Используйте вспомогательные ветки для исправления тегов

Некоторые другие системы управления версиями позволяют пользователю создать тег для нескольких файлов, которые не относятся к одному коммиту/набору изменений. Или создать тег, включающий только часть файлов репозитория.

Импортировать такие теги в Git как есть невозможно, не создав хотя бы один коммит, который «исправит» файлы в соответствии с содержимым тега. Используйте команду reset fast-import, чтобы сбросить фиктивную ветку за пределами пространства имён обычных веток до базового коммита тега, затем создайте один или несколько коммитов с исправлениями файлов и, наконец, пометьте фиктивную ветку тегом.

Например, поскольку все обычные ветки хранятся под именем refs/heads/, назовите вспомогательную ветку для исправления тегов TAG_FIXUP. Так вспомогательная ветка импортёра не сможет конфликтовать по пространству имён с реальными ветками, импортированными из источника (имя TAG_FIXUP не является refs/heads/TAG_FIXUP).

При создании коммитов с исправлениями рассмотрите возможность использования merge, чтобы связать коммиты, добавляющие версии файлов, со вспомогательной веткой. Это позволит таким инструментам, как git blame, проходить по настоящей истории коммитов и корректно аннотировать исходные файлы.

После завершения fast-import интерфейсной программе нужно выполнить rm .git/TAG_FIXUP, чтобы удалить фиктивную ветку.

Сначала импортируйте, перепакуйте позже

Сразу после завершения fast-import репозиторий Git полностью исправен и готов к использованию. Обычно это занимает совсем немного времени, даже для довольно крупных проектов (более 100 000 коммитов).

Однако для повышения локальности данных и производительности доступа необходимо перепаковать репозиторий. Для очень крупных проектов это также может занять несколько часов (особенно при использовании -f и большого значения параметра --window). Поскольку перепаковку можно безопасно выполнять параллельно с чтением и записью, запустите её в фоновом режиме и дождитесь завершения. Нет причин откладывать знакомство с новым проектом Git!

Если вы решили дождаться завершения перепаковки, не запускайте тесты производительности, пока она не закончится. fast-import создаёт неоптимальные pack-файлы, которые просто не встречаются в реальных сценариях использования.

Перепаковка исторических данных

Если вы перепаковываете очень старые импортированные данные (например, старше года), подумайте о том, чтобы потратить дополнительное время процессора и указать --window=50 (или больше) при запуске git repack. Это займёт больше времени, но позволит создать pack-файл меньшего размера. Потратить усилия нужно только один раз, а меньший размер репозитория будет полезен всем участникам проекта.

Добавляйте сообщения о ходе выполнения

Время от времени интерфейсная программа должна отправлять fast-import сообщение progress. Содержимое таких сообщений может быть произвольным; например, можно выводить текущий месяц и год всякий раз, когда дата текущего коммита переходит на следующий месяц. Пользователям будет спокойнее, если они будут знать, какая часть потока данных уже обработана.

на объект

fast-import хранит в памяти структуру для каждого объекта, записанного в ходе выполнения. В 32-разрядной системе структура занимает 32 байта, в 64-разрядной — 40 байт (из-за большего размера указателей). Объекты в таблице не освобождаются до завершения fast-import. Импорт 2 миллионов объектов в 32-разрядной системе потребует примерно 64 МиБ памяти.

Таблица объектов фактически является хеш-таблицей с ключом в виде имени объекта (уникального SHA-1). Такая конфигурация хранилища позволяет fast-import повторно использовать существующий или уже записанный объект и не записывать дубликаты в выходной пакетный файл. Дубликаты блобов при импорте встречаются на удивление часто, обычно из-за слияния веток в исходном проекте.

на метку

Метки хранятся в разреженном массиве, где на каждую метку приходится 1 указатель (4 или 8 байт в зависимости от размера указателя). Хотя массив разреженный, фронтендам всё же настоятельно рекомендуется использовать метки от 1 до n, где n — общее число меток, необходимых для импорта.

на ветку

Ветки делятся на активные и неактивные. Использование памяти этими двумя категориями существенно различается.

Неактивные ветки хранятся в структуре размером 96 или 120 байт (для 32- или 64-разрядных систем соответственно) плюс длина имени ветки (обычно менее 200 байт) на ветку. fast-import без труда обрабатывает до 10 000 неактивных веток, используя менее 2 МиБ памяти.

Активные ветки имеют такие же накладные расходы, как и неактивные, но также содержат копии всех деревьев, недавно изменённых в этой ветке. Если поддерево include не изменялось с тех пор, как ветка стала активной, его содержимое не будет загружено в память. Но если поддерево src изменялось коммитом после активации ветки, его содержимое будет загружено в память.

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

fast-import автоматически переводит активные ветки в неактивное состояние, используя простой алгоритм вытеснения наименее недавно использовавшихся веток. Цепочка LRU обновляется при выполнении каждой команды commit. Максимальное число активных веток можно увеличить или уменьшить в командной строке с помощью параметра --active-branches=.

на активное дерево

Деревья (то есть каталоги) занимают всего 12 байт памяти сверх памяти, необходимой для их записей (см. ниже раздел «на активную запись файла»). Затраты на дерево практически равны нулю, поскольку его накладные расходы распределяются между отдельными записями файлов.

на активную запись файла

Для файлов (и указателей на поддеревья) в активных деревьях требуется 52 или 64 байта на запись (для 32- и 64-разрядных платформ соответственно). Для экономии места имена файлов и деревьев хранятся в общем пуле строк, поэтому имя файла «Makefile» занимает всего 16 байт (с учётом накладных расходов заголовка строки), независимо от того, сколько раз оно встречается в проекте.

Сочетание LRU для активных веток, пула строк для имён файлов и отложенной загрузки поддеревьев позволяет fast-import эффективно импортировать проекты с более чем 2 000 веток и 45 114 файлами, используя очень мало памяти (менее 2,7 МиБ на активную ветку).