git-fast-export

Название

git-fast-export — средство экспорта данных Git

Краткое описание

git fast-export [<options>] | git fast-import

Описание

Эта программа выгружает указанные ревизии в формате, который можно передать через конвейер в git fast-import.

Её можно использовать вместо удобного для чтения человеком bundle-файла (см. git-bundle[1]) или в качестве формата, который можно отредактировать перед передачей в git fast-import для переписывания истории (эту возможность используют такие инструменты, как git filter-repo).

Параметры

--progress=<n>

Вставлять инструкции progress через каждые <n> объектов, чтобы git fast-import выводил их во время импорта.

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

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

При выборе abort (значение по умолчанию) программа завершит работу при обнаружении подписанного тега. При выборе strip подписи тегов будут удалены без предупреждения; при выборе warn-strip подписи будут удалены с выводом предупреждения; при выборе verbatim теги будут экспортированы без предупреждения; при выборе warn-verbatim (или warn — устаревшего синонима) теги будут экспортированы с выводом предупреждения. verbatim и warn-verbatim следует использовать, только если вы уверены, что ни вы, ни fast-export, ни fast-import не будете выполнять преобразования, затрагивающие теги или коммиты в их истории, либо если вас не беспокоит, что итоговый тег будет иметь недействительную подпись.

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

Указывает, как обрабатывать подписанные коммиты. Работает точно так же, как --signed-tags, но для коммитов. Значение по умолчанию — strip; так же вели себя предыдущие версии этой команды, в которых этого параметра не было.

При экспорте подпись начинается с:

gpgsig <git-hash-algo> <signature-format>

где <git-hash-algo> — алгоритм хеширования объектов Git, то есть «sha1» или «sha256», а <signature-format> — тип подписи: «openpgp», «x509», «ssh» или «unknown».

Например, подпись OpenPGP коммита SHA-1 начинается с gpgsig sha1 openpgp, а подпись SSH коммита SHA-256 — с gpgsig sha256 ssh.

Хотя экспортируются все подписи коммита, импортирующая программа может принять только некоторые из них. Например, git-fast-import[1] в настоящее время сохраняет не более одной подписи для каждого алгоритма хеширования Git в каждом коммите.

Примечание

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

--tag-of-filtered-object=(abort|drop|rewrite)

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

При выборе abort (значение по умолчанию) программа завершит работу при обнаружении такого тега. При выборе drop такие теги не попадут в выходные данные. При выборе rewrite, если помеченный объект является коммитом, тег будет изменён так, чтобы указывать на коммит-предок (посредством переписывания родителей; см. git-rev-list[1]).

-M

-C

Выполняет обнаружение перемещений и/или копирований, как описано в руководстве git-diff[1], и использует его для формирования команд переименования и копирования в выгрузке.

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

--export-marks=<file>

По завершении сохраняет внутреннюю таблицу меток в <file>. Метки записываются по одной в строке в формате :markid SHA-1. Сохраняются только метки ревизий; метки blobs игнорируются. Серверные программы могут использовать этот файл для проверки импорта после его завершения или для сохранения таблицы меток между инкрементальными запусками. Поскольку <file> открывается и усекается только по завершении работы, тот же путь можно безопасно указать и для --import-marks. Файл не будет записан, если ни одному новому объекту не была назначена метка и он не был экспортирован.

--import-marks=<file>

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

--mark-tags

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

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

--fake-missing-tagger

В некоторых старых репозиториях есть теги без указания создателя. Протокол fast-import довольно строг в этом отношении и не допускает такие теги. Поэтому для возможности импорта вывода fast-import подставляется фиктивный создатель тега.

--use-done-feature

Начинает поток с директивы feature done и завершает его командой done.

--no-data

Пропускает вывод объектов blob и вместо этого ссылается на них по исходному хешу SHA-1. Это полезно, когда нужно изменить структуру каталогов или историю репозитория, не затрагивая содержимое отдельных файлов. Обратите внимание: полученный поток можно использовать только в репозитории, который уже содержит необходимые объекты.

--full-tree

Этот параметр заставляет fast-export выдавать директиву «deleteall» для каждого коммита, за которой следует полный список всех файлов в коммите (вместо списка только тех файлов, которые отличаются от файлов в первом родительском коммите).

--anonymize

Анонимизирует содержимое репозитория, сохраняя при этом структуру истории и сохранённого дерева. См. раздел ANONYMIZING ниже.

--anonymize-map=<from>[:<to>]

Заменяет токен <from> на <to> в анонимизированных выходных данных. Если <to> не указан, токен <from> сопоставляется сам с собой (то есть не анонимизируется). См. раздел ANONYMIZING ниже.

--reference-excluded-parents

По умолчанию команда вроде git fast-export master~5..master не включает коммит master~5 и удаляет master~5 из списка родителей master~4 (хотя старый и новый коммиты master~4 будут содержать одни и те же файлы). Используйте --reference-excluded-parents, чтобы поток ссылался на коммиты из исключённого диапазона истории по их sha1sum. Обратите внимание: полученный поток можно использовать только в репозитории, который уже содержит необходимые родительские коммиты.

--show-original-ids

Добавляет в выходные данные дополнительную директиву для коммитов и blobs: original-oid <SHA1SUM>. Импортирующие программы, такие как git-fast-import, скорее всего, будут игнорировать эти директивы, однако они могут быть полезны для промежуточных фильтров (например, для переписывания сообщений коммитов, ссылающихся на более ранние коммиты, или для удаления blobs по идентификатору).

--reencode=(yes|no|abort)

Указывает, как обрабатывать заголовок encoding в объектах-коммитах. При выборе abort (значение по умолчанию) программа завершит работу при обнаружении такого объекта-коммита. При выборе yes сообщение коммита будет перекодировано в UTF-8. При выборе no исходная кодировка будет сохранена.

--refspec

Применяет указанную refspec к каждой экспортируемой ссылке. Можно указать несколько refspec.

[<git-rev-list-args>…]

Список аргументов, допустимых для git rev-parse и git rev-list, задающих объекты и ссылки для экспорта. Например, master~10..master приводит к экспорту текущей ссылки master вместе со всеми объектами, добавленными после её десятого коммита-предка, а также (если не указан параметр --reference-excluded-parents) всеми файлами, общими для master~9 и master~10.

Примеры

$ git fast-export --all | (cd /empty/repository && git fast-import)

Эта команда экспортирует весь репозиторий и импортирует его в существующий пустой репозиторий. За исключением перекодирования коммитов, не использующих UTF-8, результат будет точной копией.

$ git fast-export master~5..master |
        sed "s|refs/heads/master|refs/heads/other|" |
        git fast-import

Создаёт новую ветку с именем other из master~5..master (то есть, если у master линейная история, в неё попадут последние 5 коммитов).

Обратите внимание: предполагается, что ни один из blobs и ни одно сообщение коммита, на которые ссылается этот диапазон ревизий, не содержат строку refs/heads/master.

Анонимизация

Если указан параметр --anonymize, Git попытается удалить из репозитория всю идентифицирующую информацию, сохранив при этом достаточно исходной структуры дерева и истории, чтобы можно было воспроизвести некоторые ошибки. Цель состоит в том, чтобы ошибка Git, обнаруженная в закрытом репозитории, сохранялась и в анонимизированном репозитории, который затем можно передать разработчикам Git для помощи в устранении ошибки.

При использовании этого параметра Git заменит в выходных данных все имена ссылок, пути, содержимое blobs, сообщения коммитов и тегов, имена и адреса электронной почты анонимизированными данными. Одинаковые строки будут заменены одинаково (например, два коммита одного автора будут иметь в выходных данных одного и того же анонимизированного автора, но не будут похожи на исходную строку автора). Связи между коммитами, ветками и тегами, а также временные метки коммитов сохраняются (однако сообщения коммитов и имена ссылок не будут похожи на исходные). Относительная структура дерева сохраняется (например, если корневое дерево содержит 10 файлов и 3 дерева, в выходных данных будет так же), но имена и содержимое файлов будут заменены.

Если вы считаете, что обнаружили ошибку Git, можно начать с экспорта анонимизированного потока всего репозитория:

$ git fast-export --anonymize --all >anon-stream

Затем убедитесь, что ошибка сохраняется в репозитории, созданном из этого потока (многие ошибки не сохраняются, поскольку действительно зависят от точного содержимого репозитория):

$ git init anon-repo
$ cd anon-repo
$ git fast-import <../anon-stream
$ ... test your bug ...

Если ошибка воспроизводится в анонимизированном репозитории, возможно, стоит приложить anon-stream к обычному сообщению об ошибке. Обратите внимание: анонимизированный поток очень хорошо сжимается, поэтому рекомендуется сжать его с помощью gzip. Если вы хотите убедиться, что поток не содержит личных данных, его можно просмотреть перед отправкой. Также можно попробовать:

$ perl -pe 's/\d+/X/g' <anon-stream | sort -u | less

Эта команда показывает все уникальные строки (заменяя числа на «X», чтобы объединить «User 0», «User 1» и т. д. в «User X»). Это значительно сокращает вывод и обычно позволяет быстро убедиться, что поток не содержит личных данных.

Для воспроизведения некоторых ошибок может потребоваться указать конкретные коммиты или пути, что становится сложнее после анонимизации имён ссылок и путей. Можно указать, что определённый токен следует оставить без изменений или заменить новым значением. Например, если ошибка воспроизводится с помощью git rev-list sensitive -- secret.c, можно выполнить:

$ git fast-export --anonymize --all \
      --anonymize-map=sensitive:foo \
      --anonymize-map=secret.c:bar.c \
      >stream

После импорта потока можно выполнить git rev-list foo -- bar.c в анонимизированном репозитории.

Обратите внимание: пути и имена ссылок разбиваются на токены по косым чертам. Приведённая выше команда анонимизирует subdir/secret.c примерно как path123/bar.c; затем можно выполнить поиск bar.c в анонимизированном репозитории, чтобы определить итоговый путь.

Чтобы упростить указание итогового пути, можно сопоставить каждый компонент пути; например, если также анонимизировать subdir как publicdir, итоговый путь будет publicdir/bar.c.

Ограничения

Поскольку git fast-import не может помечать деревья, полностью экспортировать репозиторий linux.git не удастся: в нём есть тег, указывающий на дерево, а не на коммит.

См. также

git-fast-import[1]

© 2005–2026 Linus Torvalds and others
Licensed under the GNU General Public License version 2.
https://git-scm.com/docs/git-fast-export