git-fast-import
快速 Git 数据导入器的后端
概要
frontend | 'git fast-import' [<options>]描述
此程序通常不是最终用户想要直接运行的。大多数最终用户希望使用现有的前端程序之一，该程序解析特定类型的外部源并将存储在那里的内容馈送到 'git fast-import'。
fast-import 从标准输入读取混合的命令/数据流，并将一个或多个包文件直接写入当前仓库。当在标准输入上收到 EOF 时，fast-import 写出更新的分支和标签引用，用新导入的数据完全更新当前仓库。
fast-import 后端本身可以导入到空仓库（已通过 'git init' 初始化的仓库）或增量更新现有的已填充仓库。是否支持从特定外部源进行增量导入取决于所使用的前端程序。
选项
--force强制更新已修改的现有分支，即使这样做会导致提交丢失（因为新提交不包含旧提交）。--quiet禁用 --stats 显示的输出，使 fast-import 在成功时通常保持静默。但是，如果导入流具有旨在显示用户输出的指令（例如progress指令），相应的消息仍将被显示。--stats显示有关 fast-import 创建的对象、存储它们的包文件以及 fast-import 在此运行期间使用的内存的基本统计信息。显示此输出目前是默认行为，但可以通过 --quiet 禁用。--allow-unsafe-features许多命令行选项可以通过使用feature或option命令作为 fast-import 流本身的一部分提供。但是，其中一些选项是不安全的（例如，允许 fast-import 访问仓库外部的文件系统）。这些选项默认被禁用，但可以通过在命令行上提供此选项来允许。目前这只影响export-marks、import-marks和import-marks-if-exists功能命令。 仅在您信任生成 fast-import 流的程序时才启用此选项！对于使用import能力的远程助手，此选项会自动启用，因为它们已经被信任运行自己的代码。--signed-tags=<mode>指定如何处理签名标签。行为与下面的--signed-commits=<mode>相同。与签名提交一样，默认模式为verbatim。--signed-commits=<mode>指定如何处理签名提交。支持以下 <mode>：verbatim（默认）将静默导入提交签名。warn-verbatim将导入它们，但会显示警告。abort将使此程序在遇到签名提交时终止。strip将静默地使提交变为未签名。warn-strip将使它们变为未签名，但会显示警告。strip-if-invalid将检查签名，如果无效，将剥离它们并显示警告。验证方式与 git-verify-commit(1) 相同。sign-if-invalid[=<keyid>]，类似于strip-if-invalid，验证提交签名并用新创建的签名替换无效签名。有效签名保持不变。如果提供了<keyid>，则使用该密钥进行签名；否则使用配置的默认签名密钥。abort-if-invalid将使此程序在遇到无法验证的签名提交时终止。
前端选项
--cat-blob-fd=<fd>将对get-mark、cat-blob和ls查询的响应写入文件描述符 <fd> 而不是stdout。允许将面向最终用户的progress输出与其他输出分离。--date-format=<fmt>指定前端将在author、committer和tagger命令中提供给 fast-import 的日期类型。有关支持的格式及其语法的详细信息，请参阅下面的"日期格式"。--done如果流末尾没有done命令，则以错误终止。此选项对于检测导致前端在开始写入流之前终止的错误可能很有用。
标记文件位置
--export-marks=<file>完成时将内部标记表转储到 <file>。标记按每行一个的格式写入为:markid SHA-1。前端可使用此文件在导入完成后验证导入，或在增量运行之间保存标记表。由于 <file> 仅在检查点（或完成时）打开和截断，因此相同的路径也可以安全地传递给 --import-marks。--import-marks=<file>在处理任何输入之前，加载 <file> 中指定的标记。输入文件必须存在、必须可读，并且必须使用与 --export-marks 产生的相同格式。可以提供多个选项以导入多组标记。如果一个标记被定义为不同的值，最后一个文件获胜。--import-marks-if-exists=<file>类似于 --import-marks，但如果文件不存在则静默跳过而不是报错。--relative-marks指定 --relative-marks 后，--import-marks= 和 --export-marks= 指定的路径相对于当前仓库中的内部目录。在 git-fast-import 中，这意味着路径相对于 .git/info/fast-import 目录。但是，其他导入器可能使用不同的位置。 相对和非相对标记可以通过将 --(no-)-relative-marks 与 --(import|export)-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=<name>:<file>将由 <name> 指定的子模块的对象 ID 从 <file> 中使用的值重写为 to <file> 中使用的值。from 标记应由git fast-export创建，to 标记应在导入同一子模块时由git fast-import创建。 <name> 可以是不包含冒号字符的任意字符串，但在指定相应标记时必须对两个选项使用相同的值。可以使用不同的 <name> 值指定多个子模块。不对应对使用这些选项是错误的。 这些选项在将仓库从一种哈希算法转换为另一种哈希算法时特别有用；如果没有它们，fast-import 在遇到子模块时会失败，因为它无法将对象 ID 写入新的哈希算法。--rewrite-submodules-to=<name>:<file>将由 <name> 指定的子模块的对象 ID 从 <file> 中使用的值重写为 to <file> 中使用的值。from 标记应由git fast-export创建，to 标记应在导入同一子模块时由git fast-import创建。 <name> 可以是不包含冒号字符的任意字符串，但在指定相应标记时必须对两个选项使用相同的值。可以使用不同的 <name> 值指定多个子模块。不对应对使用这些选项是错误的。 这些选项在将仓库从一种哈希算法转换为另一种哈希算法时特别有用；如果没有它们，fast-import 在遇到子模块时会失败，因为它无法将对象 ID 写入新的哈希算法。
性能和压缩调优
--active-branches=<n>一次保持活动状态的最大分支数。有关详细信息，请参阅下面的"内存利用"。默认值为 5。--big-file-threshold=<n>fast-import 将尝试为其创建增量的最大 blob 大小，以字节表示。默认值为 512m（512 MiB）。一些导入器可能希望在内存受限的系统上降低此值。--depth=<n>blob 和树增量的最大增量深度。默认值为 50。--export-pack-edges=<file>创建包文件后，向 <file> 打印一行数据，列出包文件的文件名以及写入该包文件的每个分支上的最后一个提交。当导入的对象集超过 4 GiB 包文件限制时，此信息可能很有用，因为这些提交可用作调用 'git pack-objects' 时的边缘点。--max-pack-size=<n>每个输出包文件的最大大小。默认值为无限制。fastimport.unpackLimit参见 git-config(1)
性能
fast-import 的设计允许它以最少的内存使用和处理时间导入大型项目。假设前端能够跟上 fast-import 的速度并为其提供持续的数据流，在相当普通的硬件（2007 年约 2,000 美元）上，包含 10 年以上历史和 100,000 个以上单独提交的项目通常只需 1-2 小时即可完成导入。
大多数瓶颈似乎在于外部源数据访问（源无法足够快地提取修订版本）或磁盘 IO（fast-import 以磁盘接受数据的速度写入）。如果源数据存储在与目标 Git 仓库不同的驱动器上，导入将运行得更快（由于更少的 IO 争用）。
开发成本
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_DIR 引用的当前 Git 仓库。）因此，导入前端可以将工作目录用于自己的目的，例如从外部源提取文件修订版本。对工作目录的忽略也允许 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=<fmt> 命令行选项中传递格式名称来选择用于此次导入的格式。
raw这是 Git 原生格式，为<time> SP <offutc>。如果未指定 --date-format，它也是 fast-import 的默认格式。 事件的时间由<time>指定，为自 UNIX 纪元（1970 年 1 月 1 日午夜，UTC）以来的秒数，写为 ASCII 十进制整数。 本地偏移由<offutc>指定，为 UTC 的正或负偏移。例如 EST（比 UTC 晚 5 小时）在<tz>中表示为 "-0500"，而 UTC 为 "+0000"。本地偏移不影响<time>；它仅用作帮助格式化例程显示时间戳的建议。 如果源材料中没有本地偏移，请使用 "+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格式不同，RFC 2822 日期字符串中包含的时区/UTC 偏移信息用于在存储之前将日期值调整为 UTC。因此，此信息尽可能准确非常重要。 如果源材料使用 RFC 2822 风格的日期，前端应让 fast-import 处理解析和转换（而不是尝试自己执行），因为 Git 解析器在实际使用中经过了充分测试。 如果源材料已经使用 UNIX 纪元格式、可以被引导以该格式给出日期或其格式易于转换为该格式，前端应首选raw格式，因为解析没有歧义。now始终使用当前时间和时区。必须始终为<when>提供字面量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 关闭当前包文件，生成其唯一的 SHA-1 校验和和索引，并启动新的包文件。此命令是可选的，执行导入不需要它。progress使 fast-import 将整行回显到自己的标准输出。此命令是可选的，执行导入不需要它。done标记流的结束。除非使用--done命令行选项或feature done命令请求了done功能，否则此命令是可选的。get-mark使 fast-import 将与标记对应的 SHA-1 打印到用--cat-blob-fd设置的文件描述符，如果未指定则打印到stdout。cat-blob使 fast-import 以 'cat-file --batch' 格式将 blob 打印到用--cat-blob-fd设置的文件描述符，如果未指定则打印到stdout。ls使 fast-import 以 'ls-tree' 格式打印描述目录项的行到用--cat-blob-fd设置的文件描述符，如果未指定则打印到stdout。feature启用指定的功能。这要求 fast-import 支持指定的功能，如果不支持则中止。option指定 OPTIONS 下列出的不改变流语义的任何选项以适应前端的需求。此命令是可选的，执行导入不需要它。
命令响应
fast-import 写入的新对象不会立即可用。大多数 fast-import 命令在下一个检查点（或完成）之前没有可见效果。前端可以发送命令来填充 fast-import 的输入管道，而无需担心它们生效的速度，这通过简化调度提高了性能。
但是，对于某些前端，能够在更新时从当前仓库读回数据很有用（例如，当源材料描述要应用于先前导入的对象的补丁时的对象）。这可以通过双向管道连接前端和 fast-import 来实现：
mkfifo fast-import-output
frontend <fast-import-output |
git fast-import >fast-import-output以此方式设置的前端可以使用 progress、get-mark、ls 和 cat-blob 命令从正在进行的导入中读取信息。
为避免死锁，此类前端必须在执行可能阻塞的 fast-import 写入之前完全消耗 progress、ls、get-mark 和 cat-blob 的所有待处理输出。
崩溃报告
如果 fast-import 收到无效输入，它将以非零退出状态终止并在正在导入到的 Git 仓库的顶层创建崩溃报告。崩溃报告包含内部 fast-import 状态的快照以及导致崩溃的最新命令。
所有最近的命令（包括流注释、文件更改和进度命令）都在崩溃报告中的命令历史中显示，但原始文件数据和提交消息被排除在崩溃报告之外。此排除节省了报告文件中的空间，并减少了 fast-import 在执行期间必须执行的缓冲量。
写入崩溃报告后，fast-import 将关闭当前包文件并导出标记表。这允许前端开发者检查仓库状态并从崩溃点恢复导入。修改的分支和标签在崩溃期间不会更新，因为导入未成功完成。分支和标签信息可以在崩溃报告中找到，如果需要更新则必须手动应用。
提示和技巧
以下提示和技巧收集自 fast-import 的各种用户，在此作为建议提供。
每个提交使用一个标记
进行仓库转换时，每个提交使用唯一的标记（mark :<n>）并在命令行上提供 --export-marks 选项。fast-import 将转储一个文件，列出每个标记及其对应的 Git 对象 SHA-1。如果前端可以将标记关联回源仓库，则通过比较每个 Git 提交与相应的源修订版本可以轻松验证导入的准确性和完整性。
来自 Perforce 或 Subversion 等系统，这应该相当简单，因为 fast-import 标记也可以是 Perforce 变更集编号或 Subversion 修订版本号。
自由跳转分支
不要费心尝试优化前端在导入期间一次只处理一个分支。虽然这样做对 fast-import 可能会稍微快一些，但它往往会大大增加前端代码的复杂性。
fast-import 内置的分支 LRU 表现非常好，激活非活动分支的成本非常低，因此在分支之间跳转对导入性能几乎没有影响。
处理重命名
导入重命名的文件或目录时，只需在相应提交期间删除旧名称并修改新名称。Git 在事后执行重命名检测，而不是在提交期间显式执行。
使用标签修正分支
一些其他 SCM 系统允许用户从不是来自同一提交/变更集的多个文件创建标签。或者创建仓库中可用文件子集的标签。
在 Git 中按原样导入这些标签是不可能的，除非至少创建一个"修正"文件以匹配标签内容的提交。使用 fast-import 的 reset 命令将正常分支空间之外的虚拟分支重置为标签的基础提交，然后提交一个或多个文件修正提交，最后为虚拟分支打标签。
例如，由于所有正常分支都存储在 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 输出的包文件不是最优的，在实际使用中根本不会出现。
重新打包历史数据
如果您要重新打包非常旧的导入数据（例如超过一年），考虑在运行 'git repack' 时花费一些额外的 CPU 时间并提供 --window=50（或更高）。这将花费更长时间，但也会产生更小的包文件。您只需付出一次努力，使用您项目的每个人都将从更小的仓库中受益。
包含一些进度消息
偶尔让您的前端向 fast-import 发出 progress 消息。消息的内容完全是自由格式的，因此一个建议是在当前提交日期进入下一个月时输出当前月份和年份。您的用户会感觉更好，知道已处理了多少数据流。
包文件优化
打包 blob 时，fast-import 始终尝试针对最后写入的 blob 进行增量。除非前端特别安排，否则这可能不是同一文件的先前版本，因此生成的增量将不是最小的。结果包文件将被压缩，但不是最优的。
能够高效访问单个文件所有修订版本（例如读取 RCS/CVS ,v 文件）的前端可以选择将该文件的所有修订版本作为一系列连续的 blob 命令提供。这允许 fast-import 对不同的文件修订版本相互进行增量，从而节省最终包文件中的空间。标记可用于在一系列 commit 命令期间稍后识别单个文件修订版本。
fast-import 创建的包文件不鼓励良好的磁盘访问模式。这是因为 fast-import 按照在标准输入上接收的顺序写入数据，而 Git 通常在包文件内组织数据以使最新（当前提示）数据出现在历史数据之前。Git 还将提交聚集在一起，通过更好的缓存局部性加速修订遍历。
因此，强烈建议用户在 fast-import 完成后使用 git repack -a -d 重新打包仓库，允许 Git 重新组织包文件以加快数据访问。如果 blob 增量不是最优的（见上文），那么添加 -f 选项以强制重新计算所有增量可以显著减小最终包文件大小（小 30-50% 是很典型的）。
除了运行 git repack 之外，您还可以运行 git gc --aggressive，它也会在导入后优化其他内容（例如打包松散引用）。如 git-gc(1) 中"激进"部分所述，--aggressive 选项将使用 -f 选项查找新增量。基于上述原因，在 fast-import 之后使用 --aggressive 是已知值得这样做的少数情况之一。
内存利用
有许多因素影响 fast-import 执行导入所需的内存量。像核心 Git 的关键部分一样，fast-import 使用自己的内存分配器来摊销与 malloc 相关的任何开销。在实践中，fast-import 由于使用大块分配，倾向于将任何 malloc 开销摊销为 0。
每个对象
fast-import 为此执行中写入的每个对象维护一个内存中结构。在 32 位系统上，该结构为 32 字节；在 64 位系统上，该结构为 40 字节（由于更大的指针大小）。表中的对象在 fast-import 终止之前不会被释放。在 32 位系统上导入 200 万个对象将需要大约 64 MiB 的内存。
对象表实际上是一个以对象名称（唯一的 SHA-1）为键的哈希表。这种存储配置允许 fast-import 重用现有或已写入的对象，并避免向输出包文件写入重复项。在导入中重复 blob 出奇地常见，通常是由于源中的分支合并。
每个标记
标记存储在稀疏数组中，每个标记使用 1 个指针（4 字节或 8 字节，取决于指针大小）。虽然数组是稀疏的，但仍强烈鼓励前端使用 1 到 n 之间的标记，其中 n 是此导入所需的标记总数。
每个分支
分支被分类为活动和非活动。两类的内存使用显著不同。
非活动分支存储在一个结构中，每个分支使用 96 或 120 字节（32 位或 64 位系统），加上分支名称的长度（通常不超过 200 字节）。fast-import 可以轻松处理多达 10,000 个非活动分支，使用不到 2 MiB 的内存。
活动分支与非活动分支具有相同的开销，但还包含该分支上最近修改的每个树的副本。如果子树 include 自分支变为活动以来未被修改，其内容将不会被加载到内存中，但如果子树 src 自分支变为活动以来已被提交修改，则其内容将被加载到内存中。
由于活动分支存储有关该分支上包含的文件的元数据，其内存中存储大小可能增长到相当大的大小（见下文）。
fast-import 基于简单的最近最少使用算法自动将活动分支移至非活动状态。LRU 链在每个 commit 命令时更新。可以通过命令行上的 --active-branches= 增加或减少活动分支的最大数量。
每个活动树
树（即目录）在其条目所需的内存之上仅使用 12 字节的内存（见下面的"每个活动文件条目"）。树的成本实际上为 0，因为其开销在单个文件条目上摊销。
每个活动文件条目
活动树中的文件（和指向子树的指针）每个条目需要 52 或 64 字节（32/64 位平台）。为了节省空间，文件和树名称在公共字符串表中共享，允许文件名 "Makefile" 无论在项目中出现多少次都只使用 16 字节（包括字符串头开销后）。
活动分支 LRU 与文件名字符串池和子树的延迟加载相结合，允许 fast-import 在非常有限的内存占用（每个活动分支少于 2.7 MiB）中高效导入具有 2,000+ 分支和 45,114+ 文件的项目。
信号
向 'git fast-import' 进程发送 SIGUSR1 将提前结束当前包文件，模拟 checkpoint 命令。没有耐心的操作员可以使用此功能查看正在进行的导入中的对象和引用，代价是一些额外的运行时间和更差的压缩。
配置
本节中此行以下的内容是从 git-config(1) 文档中选择性包含的。内容与其中的相同：
fastimport.unpackLimit如果 git-fast-import(1) 导入的对象数量低于此限制，则对象将被解包为松散对象文件。但是，如果导入的对象数量等于或超过此限制，则包将作为包存储。存储来自 fast-import 的包可以使导入操作完成得更快，特别是在慢速文件系统上。如果未设置，则使用transfer.unpackLimit的值。
另请参阅
Git
git(1) 套件的一部分