Русский ▾ Topics ▾ Latest version ▾ git-fast-import last updated in 2.54.0

НАЗВАНИЕ

git-fast-import - внутренний механизм для быстрых импортёров данных Git

ОБЗОР

интерфейс | git fast-import [<параметры>]

ОПИСАНИЕ

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

fast-import читает смешанный поток команд/данных из стандартного ввода и записывает один или несколько pack-файлов непосредственно в текущий репозиторий. Когда получен EOF в стандартном вводе, fast-import записывает обновлённые ссылки веток и меток, полностью обновляя текущий репозиторий вновь импортированными данными.

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

ПАРАМЕТРЫ

--force

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

--quiet

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

--stats

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

--allow-unsafe-features

Многие параметры командной строки могут быть предоставлены как часть самого потока fast-import с помощью команд feature или option. Однако некоторые из этих параметров небезопасны (например, разрешают fast-import доступ к файловой системе за пределами репозитория). Эти параметры отключены по умолчанию, но их можно разрешить, указав этот параметр в командной строке. В настоящее время это влияет только на команды функций export-marks, import-marks и import-marks-if-exists.

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

--signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort)

Указывает, как обрабатывать подписанные метки. Работает так же, как --signed-commits=<режим> ниже, за исключением того, что режим strip-if-invalid пока не поддерживается. Как и для подписанных коммитов, режим по умолчанию — verbatim.

--signed-commits=<mode>

Указывает, как обрабатывать подписанные коммиты. Поддерживаются следующие <режимы>:

  • verbatim, значение по умолчанию, будет молча импортировать подписи коммитов.

  • warn-verbatim импортирует их, но отобразит предупреждение.

  • abort заставит эту программу завершиться критической ошибкой при обнаружении подписанного коммита.

  • strip сделает коммиты неподписанными молча.

  • warn-strip сделает их неподписанными, но отобразит предупреждение.

  • strip-if-invalid проверит подписи и, если они недействительны, удалит их и отобразит предупреждение. Проверка выполняется так же, как это делает git-verify-commit[1].

  • sign-if-invalid[=<id-ключа>], аналогично strip-if-invalid, проверяет подписи коммитов и заменяет недействительные подписи вновь созданными. Действительные подписи остаются неизменными. Если указан <id-ключа>, этот ключ используется для подписи; в противном случае используется настроенный ключ подписи по умолчанию.

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

--cat-blob-fd=<fd>

Записывает ответы на запросы get-mark, cat-blob и ls в файловый дескриптор <фд> вместо stdout. Позволяет отделить вывод progress, предназначенный для конечного пользователя, от другого вывода.

--date-format=<fmt>

Указывает тип дат, которые интерфейс будет предоставлять fast-import в командах author, committer и tagger. Подробную информацию о том, какие форматы поддерживаются и их синтаксис, см. в разделе “Форматы дат” ниже.

--done

Завершиться с ошибкой, если в конце потока нет команды done. Этот параметр может быть полезен для обнаружения ошибок, которые приводят к завершению интерфейса до того, как он начал запись потока.

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

--export-marks=<file>

Выгружает внутреннюю таблицу меток в <файл> по завершении. Метки записываются по одной на строку как :id-метки SHA-1. Интерфейсы могут использовать этот файл для проверки импорта после его завершения или для сохранения таблицы меток при инкрементальных запусках. Поскольку <файл> открывается и усекается только в контрольной точке (или по завершении), тот же путь также можно безопасно передавать в --import-marks.

--import-marks=<file>

Перед обработкой любых входных данных загрузить метки, указанные в <файле>. Входной файл должен существовать, быть доступным для чтения и использовать тот же формат, который создаётся --export-marks. Может быть указано несколько параметров для импорта более чем одного набора меток. Если метка определена с разными значениями, побеждает последний файл.

--import-marks-if-exists=<file>

Как --import-marks, но вместо завершения ошибкой молча пропускает файл, если он не существует.

--relative-marks
--no-relative-marks

После указания --relative-marks пути, указанные с --import-marks= и --export-marks=, являются относительными относительно внутреннего каталога в текущем репозитории. В git-fast-import это означает, что пути являются относительными относительно каталога .git/info/fast-import. Однако другие импортёры могут использовать другое местоположение.

Относительные и неотносительные метки могут быть объединены путём чередования --(no-)-relative-marks с параметрами --(import|export)-marks=.

Переписывание подмодулей

--rewrite-submodules-from=<имя>:<файл>
--rewrite-submodules-to=<имя>:<файл>

Переписывает идентификаторы объектов для подмодуля, указанного <имя>, из значений, используемых в from <файл>, в значения, используемые в to <файл>. Метки from должны были быть созданы git fast-export, а метки to должны были быть созданы git fast-import при импорте того же самого подмодуля.

<имя> может быть любой произвольной строкой, не содержащей символа двоеточия, но одно и то же значение должно использоваться с обоими параметрами при указании соответствующих меток. Может быть указано несколько подмодулей с разными значениями для <имя>. Ошибкой является неиспользование этих параметров соответствующими парами.

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

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

--active-branches=<n>

Максимальное количество веток, поддерживаемых активными одновременно. Подробности см. в разделе “Использование памяти” ниже. По умолчанию — 5.

--big-file-threshold=<n>

Максимальный размер blob-объекта, для которого fast-import попытается создать дельту, выраженный в байтах. По умолчанию — 512m (512 МиБ). Некоторые импортёры могут захотеть уменьшить это значение в системах с ограниченной памятью.

--depth=<n>

Максимальная глубина дельты для дельтификации blob-объектов и деревьев. По умолчанию — 50.

--export-pack-edges=<file>

После создания pack-файла выводит строку данных в <файл>, содержащую имя файла pack-файла и последний коммит в каждой ветке, который был записан в этот pack-файл. Эта информация может быть полезна после импорта проектов, общий набор объектов которых превышает ограничение pack-файла в 4 ГиБ, поскольку эти коммиты могут использоваться как граничные точки во время вызовов git pack-objects.

--max-pack-size=<n>

Максимальный размер каждого выходного pack-файла. По умолчанию неограничен.

fastimport.unpackLimit

См. git-config[1]

ПРОИЗВОДИТЕЛЬНОСТЬ

Дизайн fast-import позволяет ему импортировать большие проекты с минимальным использованием памяти и временем обработки. Предполагая, что интерфейс способен успевать за fast-import и передавать ему постоянный поток данных, время импорта для проектов с историей 10+ лет и содержащих 100 000+ отдельных коммитов обычно завершается за 1-2 часа на довольно скромном оборудовании (~$2,000 USD в 2007 году).

Большинство узких мест, по-видимому, находятся в доступе к данным внешнего источника (источник просто не может извлекать редакции достаточно быстро) или в дисковом вводе-выводе (fast-import записывает так быстро, как диск принимает данные). Импорт будет выполняться быстрее, если исходные данные хранятся на другом диске, чем целевой репозиторий Git (из-за меньшей конкуренции за ввод-вывод).

ЗАТРАТЫ НА РАЗРАБОТКУ

Типичный интерфейс для fast-import обычно состоит примерно из 200 строк кода Perl/Python/Ruby. Большинству разработчиков удавалось создать работающие импортёры всего за пару часов, даже если это было их первое знакомство с fast-import, а иногда и с Git. Это идеальная ситуация, учитывая, что большинство инструментов преобразования являются одноразовыми (используются один раз и больше никогда).

ПАРАЛЛЕЛЬНАЯ РАБОТА

Как git push или git fetch, импорт, обрабатываемый fast-import, безопасно запускать параллельно с вызовами git repack -a -d или git gc, или любой другой операцией Git (включая git prune, поскольку fast-import никогда не использует несжатые объекты).

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

Обновления веток могут быть принудительными с помощью --force, но рекомендуется использовать это только в иначе спокойном репозитории. Использование --force не требуется для начального импорта в пустой репозиторий.

ТЕХНИЧЕСКОЕ ОБСУЖДЕНИЕ

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

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

ФОРМАТ ВВОДА

За исключением необработанных данных файлов (которые Git не интерпретирует), формат ввода fast-import основан на тексте (ASCII). Этот текстовый формат упрощает разработку и отладку программ интерфейса, особенно при использовании языка более высокого уровня, такого как Perl, Python или Ruby.

fast-import очень строг к своему вводу. Там, где мы говорим SP ниже, мы имеем в виду ровно один пробел. Аналогично, LF означает один (и только один) перевод строки, а HT — одну (и только одну) горизонтальную табуляцию. Предоставление дополнительных пробельных символов приведёт к неожиданным результатам, таким как имена веток или имена файлов с начальными или конечными пробелами в их именах или преждевременное завершение fast-import при обнаружении неожиданного ввода.

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

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

Форматы дат

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

raw

Это собственный формат Git и имеет вид <время> SP <смещение_utc>. Это также формат fast-import по умолчанию, если --date-format не был указан.

Время события задаётся <время> как количество секунд с начала эпохи UNIX (полночь, 1 января 1970 года, UTC) и записывается как десятичное целое число ASCII.

Местное смещение задаётся <смещение_utc> как положительное или отрицательное смещение от UTC. Например, EST (которое отстаёт от UTC на 5 часов) будет выражено в <tz> как “-0500”, а UTC — как “+0000”. Местное смещение не влияет на <время>; оно используется только как рекомендация, чтобы помочь процедурам форматирования отображать временную метку.

Если местное смещение недоступно в исходном материале, используйте “+0000” или наиболее распространённое местное смещение. Например, у многих организаций есть репозиторий CVS, к которому когда-либо обращались только пользователи, находящиеся в одном и том же месте и часовом поясе. В этом случае можно предположить разумное смещение от UTC.

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

raw-permissive

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

rfc2822

Это стандартный формат даты, описанный в RFC 2822.

Пример значения: “Tue Feb 6 11:22:18 2007 -0500”. Анализатор Git точен, но немного снисходителен. Это тот же анализатор, который используется git am при применении патчей, полученных по электронной почте.

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

В отличие от формата raw выше, информация о часовом поясе/смещении UTC, содержащаяся в строке даты RFC 2822, используется для корректировки значения даты до UTC перед сохранением. Поэтому важно, чтобы эта информация была максимально точной.

Если исходный материал использует даты в стиле RFC 2822, интерфейс должен позволить fast-import обрабатывать анализ и преобразование (а не пытаться сделать это самостоятельно), поскольку анализатор Git хорошо проверен в реальных условиях.

Интерфейсы должны предпочитать формат raw, если исходный материал уже использует формат эпохи UNIX, может быть преобразован для выдачи дат в этом формате или его формат легко преобразуется в него, поскольку при анализе нет неоднозначности.

now

Всегда использует текущее время и часовой пояс. Для <когда> всегда должен указываться литерал now.

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

Этот конкретный формат предоставлен, поскольку его легко реализовать, и он может быть полезен процессу, который хочет создать новый коммит прямо сейчас, без необходимости использовать рабочий каталог или git update-index.

Если в commit используются отдельные команды author и committer, временные метки могут не совпадать, поскольку системные часы будут опрошены дважды (один раз для каждой команды). Единственный способ гарантировать, что информация об идентификаторе автора и коммиттера имеет одинаковую временную метку, — это опустить author (таким образом, копируя из committer) или использовать формат даты, отличный от now.

Команды

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

commit

Создаёт новую ветку или обновляет существующую, создавая новый коммит и обновляя ветку так, чтобы она указывала на вновь созданный коммит.

tag

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

reset

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

blob

Преобразует необработанные данные файла в blob-объект для последующего использования в команде commit. Эта команда необязательна и не требуется для выполнения импорта.

alias

Записывает, что метка ссылается на данный объект без предварительного создания какого-либо нового объекта. Использование --import-marks и ссылка на отсутствующие метки приведут к сбою fast-import, поэтому псевдонимы могут предоставить способ установить для иначе обрезанных коммитов допустимое значение (например, ближайшего необрезанного предка).

checkpoint

Заставляет fast-import закрыть текущий pack-файл, сгенерировать его уникальную контрольную сумму SHA-1 и индекс и начать новый pack-файл. Эта команда необязательна и не требуется для выполнения импорта.

progress

Заставляет fast-import выводить всю строку в свой собственный стандартный вывод. Эта команда необязательна и не требуется для выполнения импорта.

done

Отмечает конец потока. Эта команда необязательна, если только функция done не была запрошена с помощью параметра командной строки --done или команды feature done.

get-mark

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

cat-blob

Заставляет fast-import выводить blob-объект в формате cat-file --batch в файловый дескриптор, установленный с помощью --cat-blob-fd, или в stdout, если не указано.

ls

Заставляет fast-import выводить строку, описывающую запись каталога в формате ls-tree, в файловый дескриптор, установленный с помощью --cat-blob-fd, или в stdout, если не указано.

feature

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

option

Указывает любой из параметров, перечисленных в разделе ПАРАМЕТРЫ, которые не изменяют семантику потока, в соответствии с потребностями интерфейса. Эта команда необязательна и не требуется для выполнения импорта.

commit

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

	'commit' SP <ссылка> LF
	mark?
	original-oid?
	('author' (SP <имя>)? SP LT <адрес-электронной-почты> GT SP <когда> LF)?
	'committer' (SP <имя>)? SP LT <адрес-электронной-почты> GT SP <когда> LF
	('gpgsig' SP <алгоритм> SP <формат> LF data)?
	('encoding' SP <кодировка> LF)?
	data
	('from' SP <указатель-коммита> LF)?
	('merge' SP <указатель-коммита> LF)*
	(filemodify | filedelete | filecopy | filerename | filedeleteall | notemodify)*
	LF?

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

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

Команда data, следующая за committer, должна предоставлять сообщение коммита (синтаксис команды 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.

author

Может опционально присутствовать команда author, если информация об авторе может отличаться от информации о коммиттере. Если author опущена, fast-import автоматически использует информацию коммиттера для части автора коммита. Описание полей в author см. ниже, поскольку они идентичны committer.

committer

Команда committer указывает, кто сделал этот коммит и когда.

Здесь <имя> — это отображаемое имя человека (например, “Com M Itter”), а <адрес-электронной-почты> — это адрес электронной почты человека (“cm@example.com”). LT и GT — это буквальные символы "меньше" (\x3c) и "больше" (\x3e). Они необходимы для отделения адреса электронной почты от других полей в строке. Обратите внимание, что <имя> и <адрес-электронной-почты> имеют свободную форму и могут содержать любую последовательность байтов, кроме LT, GT и LF. <имя> обычно закодировано в UTF-8.

Время изменения задаётся <когда> с использованием формата даты, выбранного параметром командной строки --date-format=<формат>. Набор поддерживаемых форматов и их синтаксис см. в разделе “Форматы дат” выше.

gpgsig

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

	'gpgsig' SP <алгоритм-хеша-git> SP <формат-подписи> LF data

Команда gpgsig принимает два аргумента:

  • <алгоритм-хеша-git> указывает, к какому формату объектов Git применяется эта подпись: sha1 или sha256. Это позволяет узнать, какое представление коммита было подписано (версия SHA-1 или SHA-256), что помогает как при проверке подписи, так и при взаимодействии между репозиториями с разными хеш-функциями.

  • <формат-подписи> указывает тип подписи, например openpgp, x509, ssh или unknown. Это удобно для инструментов, обрабатывающих поток, чтобы им не приходилось анализировать ASCII-броню для определения типа подписи.

Коммит может иметь не более одной подписи для формата объектов SHA-1 (хранящейся в заголовке "gpgsig") и одной для формата объектов SHA-256 (хранящейся в заголовке "gpgsig-sha256").

Подробное описание команды data, содержащей необработанные данные подписи, см. ниже.

Однако в текущей реализации подписи ещё не проверяются. (Установка параметра конфигурации extensions.compatObjectFormat уже сейчас может помочь с проверкой подписей как в формате объектов SHA-1, так и SHA-256, когда это будет реализовано.)

Note
 Это очень экспериментально, и формат команды gpgsig может измениться в будущем без гарантий совместимости.

encoding

Необязательная команда encoding указывает кодировку сообщения коммита. Большинство коммитов используют UTF-8, и кодировка опускается, но это позволяет импортировать сообщения коммитов в git без их предварительного перекодирования.

from

Команда from используется для указания коммита, от которого инициализируется эта ветка. Эта редакция будет первым предком нового коммита. Состояние дерева, созданного в этом коммите, будет начинаться с состояния в коммите from и будет изменено модификациями содержимого в этом коммите.

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

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

Здесь <указатель-коммита> может быть любым из следующих:

  • Имя существующей ветки, уже находящейся во внутренней таблице веток fast-import. Если fast-import не знает это имя, оно обрабатывается как выражение SHA-1.

  • Ссылка на метку, :<id-номера>, где <id-номера> — это номер метки.

    Причина, по которой fast-import использует : для обозначения ссылки на метку, заключается в том, что этот символ недопустим в имени ветки Git. Ведущий : позволяет легко различать метку 42 (:42) и ветку 42 (42 или refs/heads/42) или сокращённый SHA-1, который случайно состоит только из десятичных цифр.

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

  • Полный 40-байтовый или сокращённый SHA-1 коммита в шестнадцатеричном виде.

  • Любое допустимое выражение SHA-1 Git, которое преобразуется в коммит. Подробности см. в разделе “ЗАДАНИЕ РЕВИЗИЙ” в gitrevisions[7].

  • Специальный нулевой SHA-1 (40 нулей) указывает, что ветка должна быть удалена.

Особый случай перезапуска инкрементального импорта из текущего значения ветки должен быть записан как:

	from refs/heads/ветка^0

Суффикс ^0 необходим, поскольку fast-import не позволяет ветке начинаться с самой себя, а ветка создаётся в памяти ещё до того, как команда from будет прочитана из ввода. Добавление ^0 заставит fast-import разрешить коммит через библиотеку анализа редакций Git, а не через свою внутреннюю таблицу веток, тем самым загружая существующее значение ветки.

merge

Включает один дополнительный родительский коммит. Дополнительная связь с предком не изменяет способ построения состояния дерева в этом коммите. Если команда from опущена при создании новой ветки, первый коммит merge будет первым предком текущего коммита, и ветка начнётся без файлов. fast-import разрешает неограниченное количество команд merge на коммит, устанавливая тем самым n-стороннее слияние.

Здесь <указатель-коммита> может быть любым из выражений спецификации коммита, также принимаемых from (см. выше).

filemodify

Включается в команду commit для добавления нового файла или изменения содержимого существующего файла. Эта команда имеет два различных способа указания содержимого файла.

Формат внешних данных

Содержимое данных для файла уже было предоставлено предыдущей командой blob. Интерфейсу нужно только связать их.

	'M' SP <режим> SP <ссылка-на-данные> SP <путь> LF

Здесь обычно <ссылка-на-данные> должна быть либо ссылкой на метку (:<id-номера>), установленной предыдущей командой blob, либо полным 40-байтовым SHA-1 существующего blob-объекта Git. Если <режим> равен 040000, то <ссылка-на-данные> должна быть полным 40-байтовым SHA-1 существующего объекта дерева Git или ссылкой на метку, установленной с помощью --import-marks.

Встроенный формат данных

Содержимое данных для файла ещё не было предоставлено. Интерфейс хочет предоставить его как часть этой команды изменения.

	'M' SP <режим> SP 'inline' SP <путь> LF
	data

Подробное описание команды data см. ниже.

В обоих форматах <режим> — это тип записи файла, указанный в восьмеричном виде. Git поддерживает только следующие режимы:

  • 100644 или 644: Обычный (не исполняемый) файл. Большинство файлов в большинстве проектов используют этот режим. Если сомневаетесь, это то, что вам нужно.

  • 100755 или 755: Обычный, но исполняемый файл.

  • 120000: Символьная ссылка, содержимым файла будет цель ссылки.

  • 160000: Ссылка на git, SHA-1 объекта ссылается на коммит в другом репозитории. Ссылки на git могут быть указаны только через SHA или через метку коммита. Они используются для реализации подмодулей.

  • 040000: Подкаталог. Подкаталоги могут быть указаны только через SHA или через метку дерева, установленную с помощью --import-marks.

В обоих форматах <путь> — это полный путь к файлу, который будет добавлен (если ещё не существует) или изменён (если уже существует).

<путь> может быть записан как байты без кавычек или как строка в кавычках в стиле C.

Если <путь> не начинается с двойной кавычки ("), то это строка без кавычек, которая разбирается как литеральные байты без каких-либо escape-последовательностей. Однако если имя файла содержит LF или начинается с двойной кавычки, оно не может быть представлено как строка без кавычек и должно быть заключено в кавычки. Кроме того, исходный <путь> в filecopy или filerename должен быть заключён в кавычки, если он содержит SP.

Если <путь> начинается с двойной кавычки ("), то это строка в стиле C, заключённая в кавычки, где полное имя файла заключено в пару двойных кавычек и используются escape-последовательности. Определённые символы должны быть экранированы обратным слешем: LF записывается как \n, обратный слеш как \\, а двойная кавычка как \". Некоторые символы могут быть опционально записаны с escape-последовательностями: \a для звонка, \b для возврата на шаг, \f для подачи страницы, \n для перевода строки, \r для возврата каретки, \t для горизонтальной табуляции и \v для вертикальной табуляции. Любой байт может быть записан с помощью 3-значных восьмеричных кодов (например, \033). Все имена файлов могут быть представлены как строки в кавычках.

<Путь> должен использовать разделители каталогов в стиле UNIX (прямой слэш /), и его значение должно быть в канонической форме. То есть он не должен:

  • содержать пустой компонент каталога (например, foo//bar недопустим),

  • заканчиваться разделителем каталогов (например, foo/ недопустим),

  • начинаться с разделителя каталогов (например, /foo недопустим),

  • содержать специальный компонент . или .. (например, foo/./bar и foo/../bar недопустимы).

Корень дерева может быть представлен пустой строкой в качестве <путь>.

<Путь> не может содержать NUL ни буквально, ни экранированным как \000. Рекомендуется, чтобы <путь> всегда был закодирован в UTF-8.

filedelete

Включается в команду commit для удаления файла или рекурсивного удаления целого каталога из ветки. Если удаление файла или каталога делает его родительский каталог пустым, родительский каталог также будет автоматически удалён. Это каскадно поднимается по дереву, пока не будет достигнут первый непустой каталог или корень.

	'D' SP <путь> LF

здесь <путь> — это полный путь к файлу или подкаталогу, который нужно удалить из ветки. Смотрите filemodify выше для подробного описания <путь>.

filecopy

Рекурсивно копирует существующий файл или подкаталог в другое место внутри ветки. Существующий файл или каталог должен существовать. Если целевой объект существует, он будет полностью заменён содержимым, скопированным из источника.

	'C' SP <путь> SP <путь> LF

здесь первый <путь> — это исходное расположение, а второй <путь> — это целевое расположение. Смотрите filemodify выше для подробного описания того, как может выглядеть <путь>. Чтобы использовать исходный путь, содержащий SP, путь должен быть заключён в кавычки.

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

filerename

Переименовывает существующий файл или подкаталог в другое место внутри ветки. Существующий файл или каталог должен существовать. Если целевой объект существует, он будет заменён исходным каталогом.

	'R' SP <путь> SP <путь> LF

здесь первый <путь> — это исходное расположение, а второй <путь> — это целевое расположение. Смотрите filemodify выше для подробного описания того, как может выглядеть <путь>. Чтобы использовать исходный путь, содержащий SP, путь должен быть заключён в кавычки.

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

Обратите внимание, что filerename — это то же самое, что filecopy с последующим filedelete исходного расположения. Использование filerename даёт небольшое преимущество в производительности, но оно настолько мало, что никогда не стоит пытаться преобразовывать пару удаление/добавление в исходном материале в переименование для fast-import. Эта команда filerename предоставлена только для упрощения интерфейсных программ, которые уже имеют информацию о переименованиях и не хотят возиться с разложением её на filecopy с последующим filedelete.

filedeleteall

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

	'deleteall' LF

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

Выполнение filedeleteall с последующими необходимыми командами filemodify для установки правильного содержимого даст те же результаты, что и отправка только необходимых команд filemodify и filedelete. Однако подход filedeleteall может потребовать от fast-import немного больше памяти на активную ветку (менее 1 МиБ даже для большинства крупных проектов); поэтому интерфейсным программам, которые могут легко получить только затронутые пути для коммита, рекомендуется так и делать.

notemodify

Включается в команду commit <ссылка-на-заметки> для добавления новой заметки, аннотирующей <указатель-на-коммит>, или изменения содержимого этой аннотации. Внутри это похоже на filemodify 100644 по пути <указатель-на-коммит> (возможно, разбитому на подкаталоги). Не рекомендуется использовать какие-либо другие команды для записи в дерево <ссылка-на-заметки>, кроме filedeleteall для удаления всех существующих заметок в этом дереве. Эта команда имеет два различных способа указания содержимого заметки.

Формат внешних данных

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

	'N' SP <ссылка-на-данные> SP <указатель-на-коммит> LF

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

Встроенный формат данных

Содержимое данных для заметки ещё не было предоставлено. Интерфейсная программа хочет предоставить его как часть этой команды изменения.

	'N' SP 'inline' SP <указатель-на-коммит> LF
	data

Подробное описание команды data см. ниже.

В обоих форматах <указатель-на-коммит> — это любое из выражений спецификации коммита, которые также принимаются from (см. выше).

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 <идентификатор-объекта> LF

где <идентификатор-объекта> — это любая строка, не содержащая LF.

tag

Создаёт аннотированную метку, ссылающуюся на определённый коммит. Для создания легковесных (неаннотированных) меток смотрите команду reset ниже.

	'tag' SP <имя> LF
	mark?
	'from' SP <указатель-на-коммит> LF
	original-oid?
	'tagger' (SP <имя>)? SP LT <эл.почта> GT SP <когда> LF
	data

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

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

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

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

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

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

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

reset

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

	'reset' SP <ссылка> LF
	('from' SP <указатель-на-коммит> LF)?
	LF?

Подробное описание <ссылка> и <указатель-на-коммит> смотрите выше в разделах 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 здесь необязательна, так как некоторые интерфейсные программы предпочитают генерировать SHA-1 Git для blob-объекта самостоятельно и передавать его непосредственно в commit. Однако это обычно больше работы, чем она стоит, поскольку метки недороги в хранении и просты в использовании.

data

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

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

Формат с точным количеством байтов

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

	'data' SP <количество> LF
	<raw> LF?

где <количество> — это точное количество байтов, содержащихся в <raw>. Значение <количество> выражается как десятичное целое число ASCII. LF по обе стороны от <raw> не включается в <количество> и не будет включён в импортируемые данные.

LF после <raw> является необязательным (раньше был обязательным), но рекомендуется. Всегда включая его, отладка потока fast-import упрощается, так как следующая команда всегда начинается в столбце 0 следующей строки, даже если <raw> не заканчивался на LF.

Формат с разделителем

Строка-разделитель используется для обозначения конца данных. fast-import вычислит длину, выполняя поиск разделителя. Этот формат полезен в первую очередь для тестирования и не рекомендуется для реальных данных.

	'data' SP '<<' <разделитель> LF
	<raw> LF
	<разделитель> LF
	LF?

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

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

alias

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

	'alias' LF
	mark
	'to' SP <указатель-на-коммит> LF
	LF?

Подробное описание <указатель-на-коммит> смотрите выше в разделе from.

checkpoint

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

	'checkpoint' LF
	LF?

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

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

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

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

progress

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

	'progress' SP <любое> LF
	LF?

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

интерфейсная_программа | 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 <ссылка-на-данные> LF

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

Вывод использует тот же формат, что и git cat-file --batch:

<sha1> SP 'blob' SP <размер> LF
<содержимое> LF

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

Смотрите раздел “Ответы на команды” ниже для получения подробностей о том, как безопасно читать этот вывод.

ls

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

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

Чтение из активного коммита

Эта форма может использоваться только в середине commit. Путь указывает на запись каталога в активном коммите fast-import. В этом случае путь должен быть заключён в кавычки.

	'ls' SP <путь> LF
Чтение из именованного дерева

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

	'ls' SP <ссылка-на-данные> SP <путь> LF

Смотрите filemodify выше для подробного описания <путь>.

Вывод использует тот же формат, что и git ls-tree <дерево> -- <путь>:

<режим> SP ('blob' | 'tree' | 'commit') SP <ссылка-на-данные> HT <путь> LF

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

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

missing SP <путь> LF

Смотрите раздел “Ответы на команды” ниже для получения подробностей о том, как безопасно читать этот вывод.

feature

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

	'feature' SP <функциональность> ('=' <аргумент>)? LF

Часть команды <функциональность> может быть любой из следующих:

date-format
export-marks
relative-marks
no-relative-marks
принудительно

Действует так, как если бы соответствующий параметр командной строки с ведущим -- был передан в командной строке (см. ПАРАМЕТРЫ выше).

import-marks
import-marks-if-exists

Как --import-marks, за исключением двух аспектов: во-первых, допускается только одна команда "feature import-marks" или "feature import-marks-if-exists" на поток; во-вторых, параметр командной строки --import-marks= или --import-marks-if-exists переопределяет любые из этих команд "feature" в потоке; в-третьих, "feature import-marks-if-exists", как и соответствующий параметр командной строки, молча пропускает несуществующий файл.

get-mark
cat-blob
ls

Требует, чтобы внутренняя часть поддерживала команды get-mark, cat-blob или ls соответственно. Версии fast-import, не поддерживающие указанную команду, завершат работу с соответствующим сообщением. Это позволяет импорту завершиться с ошибкой на раннем этапе с понятным сообщением, вместо того чтобы тратить время на начальную часть импорта до обнаружения неподдерживаемой команды.

заметки

Требует, чтобы внутренняя часть поддерживала подкоманду notemodify (N) для команды commit. Версии fast-import, не поддерживающие заметки, завершат работу с соответствующим сообщением.

готово

Завершается с ошибкой, если поток заканчивается без команды done. Без этой функциональности ошибки, приводящие к внезапному завершению интерфейсной программы в удобной точке потока, могут остаться незамеченными. Это может произойти, например, если интерфейсная программа импорта умирает в середине операции без отправки SIGTERM или SIGKILL своему подчинённому экземпляру git fast-import.

option

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

    'option' SP <параметр> LF

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

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

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

  • date-format

  • import-marks

  • export-marks

  • cat-blob-fd

  • принудительно

done

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

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

ОТВЕТЫ НА КОМАНДЫ

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

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

mkfifo fast-import-output
интерфейсная_программа <fast-import-output |
git fast-import >fast-import-output

Интерфейсная программа, настроенная таким образом, может использовать команды progress, get-mark, ls и cat-blob для чтения информации из импорта в процессе выполнения.

Чтобы избежать взаимоблокировки, такие интерфейсные программы должны полностью потребить любой ожидающий вывод от progress, ls, get-mark и cat-blob перед выполнением записей в fast-import, которые могут заблокироваться.

ОТЧЁТЫ О СБОЯХ

Если fast-import передаются недопустимые входные данные, он завершится с ненулевым кодом выхода и создаст отчёт о сбое в верхнем уровне репозитория Git, в который он выполнял импорт. Отчёты о сбоях содержат снимок внутреннего состояния fast-import, а также самые последние команды, которые привели к сбою.

Все недавние команды (включая комментарии потока, изменения файлов и команды progress) показаны в истории команд внутри отчёта о сбое, но необработанные данные файлов и сообщения коммитов исключены из отчёта о сбое. Это исключение экономит место в файле отчёта и уменьшает объём буферизации, которую fast-import должен выполнять во время выполнения.

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

Пример сбоя:

$ cat >in <<END_OF_INPUT
# мой самый первый тестовый коммит
commit refs/heads/master
committer Shawn O. Pearce <spearce> 19283 -0400
# кто этот парень в любом случае?
data <<EOF
это мой коммит
EOF
M 644 inline .gitignore
data <<EOF
.gitignore
EOF
M 777 inline bob
END_OF_INPUT
$ git fast-import <in
fatal: Corrupt mode: M 777 inline bob
fast-import: dumping crash report to .git/fast_import_crash_8434
$ cat .git/fast_import_crash_8434
fast-import crash report:
    fast-import process: 8434
    parent process     : 1391
    at Sat Sep 1 00:58:12 2007
fatal: Corrupt mode: M 777 inline bob
Most Recent Commands Before Crash
---------------------------------
  # мой самый первый тестовый коммит
  commit refs/heads/master
  committer Shawn O. Pearce <spearce> 19283 -0400
  # кто этот парень в любом случае?
  data <<EOF
  M 644 inline .gitignore
  data <<EOF
* M 777 inline bob

Active Branch LRU

active_branches = 1 cur, 5 max

	  pos clock name ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	   1)      0 refs/heads/master

Inactive Branches

refs/heads/master: status : active loaded dirty tip commit : 0000000000000000000000000000000000000000 old tree : 0000000000000000000000000000000000000000 cur tree : 0000000000000000000000000000000000000000 commit clock: 0 last pack :

------------------- END OF CRASH REPORT

СОВЕТЫ И ХИТРОСТИ

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

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

При выполнении преобразования репозитория используйте уникальную метку для каждого коммита (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-файл. Вам нужно приложить усилия только один раз, и все, кто использует ваш проект, выиграют от меньшего репозитория.

Включайте некоторые сообщения о ходе выполнения

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

ОПТИМИЗАЦИЯ PACK-ФАЙЛА

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

Интерфейсные программы, которые имеют эффективный доступ ко всем редакциям одного файла (например, чтение файла RCS/CVS ,v), могут предоставить все редакции этого файла в виде последовательных команд blob. Это позволяет fast-import выполнять дельта-сжатие различных редакций файла друг относительно друга, экономя место в итоговом pack-файле. Метки могут использоваться для последующей идентификации отдельных редакций файла во время последовательности команд commit.

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

По этой причине настоятельно рекомендуется, чтобы пользователи перепаковывали репозиторий с помощью git repack -a -d после завершения fast-import, позволяя Git реорганизовать pack-файлы для более быстрого доступа к данным. Если дельты blob-объектов неоптимальны (см. выше), то добавление параметра -f для принудительного перевычисления всех дельт может значительно уменьшить итоговый размер pack-файла (типично уменьшение на 30-50%).

Вместо запуска git repack вы также можете запустить git gc --aggressive, что также оптимизирует другие вещи после импорта (например, упакует неупакованные ссылки). Как отмечено в разделе "AGGRESSIVE" в git-gc[1], параметр --aggressive найдет новые дельты с помощью параметра -f к git-repack[1]. По причинам, подробно описанным выше, использование --aggressive после fast-import — один из немногих случаев, когда это, как известно, стоит делать.

ИСПОЛЬЗОВАНИЕ ПАМЯТИ

Существует ряд факторов, которые влияют на то, сколько памяти требуется fast-import для выполнения импорта. Как и критические секции ядра Git, fast-import использует собственные распределители памяти, чтобы амортизировать любые накладные расходы, связанные с malloc. На практике fast-import, как правило, амортизирует любые накладные расходы malloc до 0 благодаря использованию выделения больших блоков.

на объект

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

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

на метку

Метки хранятся в разрежённом массиве, используя 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 байт памяти сверх памяти, требуемой для их записей (см. “на активный файл” ниже). Стоимость дерева практически равна 0, поскольку его накладные расходы амортизируются по отдельным записям файлов.

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

Файлы (и указатели на поддеревья) в активных деревьях требуют 52 или 64 байта (32/64-битные платформы) на запись. Для экономии пространства имена файлов и деревьев объединяются в общую таблицу строк, что позволяет имени файла “Makefile” использовать всего 16 байт (после включения накладных расходов на заголовок строки), независимо от того, сколько раз оно встречается в проекте.

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

СИГНАЛЫ

Отправка SIGUSR1 процессу git fast-import досрочно завершает текущий pack-файл, имитируя команду checkpoint. Нетерпеливый оператор может использовать эту возможность, чтобы заглянуть в объекты и ссылки из импорта в процессе выполнения, ценой некоторого дополнительного времени работы и худшего сжатия.

КОНФИГУРАЦИЯ

Дальнейшее содержание этого раздела, повторяет то, что может быть найдено в git-config[1]:

Warning

Missing ru/config/fastimport.adoc

See original version for this content.

СМ. ТАКЖЕ

git-fast-export[1]

GIT

Является частью пакета git[1]