Pro Git 中文版

Appearance

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> 每 <n> 个对象插入 'progress' 语句，由 'git fast-import' 在导入期间显示。

  • --signed-tags=(verbatim|warn-verbatim|warn-strip|strip|abort) 指定如何处理签名标签。由于导出后的任何转换（或导出期间的转换，例如排除修订版本）都可能更改被签名的哈希值，签名可能会变得无效。 当请求 'abort'（默认值）时，此程序在遇到签名标签时将终止。使用 'strip' 时，标签将被静默地去除签名；使用 'warn-strip' 时，标签将被去除签名但会显示警告；使用 'verbatim' 时，标签将被静默导出；使用 'warn-verbatim'（或已弃用的同义词 'warn'）时，标签将被导出但您会看到警告。'verbatim' 和 'warn-verbatim' 仅应在您知道不会对标签或其历史中的任何提交执行转换时使用，或者如果您不关心结果标签具有无效签名。

  • --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"。 例如，SHA-1 提交上的 OpenPGP 签名以 gpgsig sha1 openpgp 开头，而 SHA-256 提交上的 SSH 签名以 gpgsig sha256 ssh 开头。 虽然提交的所有签名都会被导出，但导入器可能只接受其中一部分。例如 git-fast-import(1) 目前每个提交中每个 Git 哈希算法最多存储一个签名。 > 这是高度实验性的，数据流的格式将来可能会在没有兼容性保证的情况下更改。

  • --tag-of-filtered-object=(abort|drop|rewrite) 指定如何处理被标记对象已被过滤掉的标签。由于要导出的修订版本和文件可以按路径限制，标记的对象可能被完全过滤。 当请求 'abort'（默认值）时，此程序在遇到此类标签时将终止。使用 'drop' 时，将从输出中省略此类标签。使用 'rewrite' 时，如果被标记的对象是提交，将重写标签以标记祖先提交（通过父提交重写；参见 git-rev-list(1)）。

  • -M 执行移动和/或复制检测，如 git-diff(1) 手册页中所述，并使用它在输出转储中生成重命名和复制命令。 请注意，此命令的早期版本在您给出这些选项时不会报错并会产生不正确的结果。

  • -C 执行移动和/或复制检测，如 git-diff(1) 手册页中所述，并使用它在输出转储中生成重命名和复制命令。 请注意，此命令的早期版本在您给出这些选项时不会报错并会产生不正确的结果。

  • --export-marks=<file> 完成时将内部标记表转储到 <file>。标记按每行一个的格式写入为 :markid SHA-1。仅转储修订版本的标记；blob 的标记被忽略。后端可使用此文件在导入完成后验证导入，或在增量运行之间保存标记表。由于 <file> 仅在完成时打开和截断，因此相同的路径也可以安全地传递给 --import-marks。如果没有新的对象被标记/导出，该文件将不会被写入。

  • --import-marks=<file> 在处理任何输入之前，加载 <file> 中指定的标记。输入文件必须存在、必须可读，并且必须使用与 --export-marks 产生的相同格式。

  • --mark-tags 除了用标记 ID 标记 blob 和提交外，还标记标签。这与 --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 哈希引用 blob。这在重写目录结构或仓库历史而不触及单个文件内容时很有用。请注意，结果流只能由已包含必要对象的仓库使用。

  • --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~4 不再以 master~5 作为父提交（尽管旧的 master~4 和新的 master~4 将拥有所有相同的文件）。使用 --reference-excluded-parents 可改为让流通过其 sha1sum 引用排除范围内的历史提交。请注意，结果流只能由已包含必要父提交的仓库使用。

  • --show-original-ids 为提交和 blob 向输出添加额外的指令 original-oid <SHA1SUM>。虽然此类指令可能被 git-fast-import 等导入器忽略，但对于中间过滤器可能很有用（例如用于重写引用旧提交的提交消息，或按 ID 剥离 blob）。

  • --reencode=(yes|no|abort) 指定如何处理提交对象中的 encoding 头。当请求 'abort'（默认值）时，此程序在遇到此类提交对象时将终止。使用 'yes' 时，提交消息将被重新编码为 UTF-8。使用 'no' 时，将保留原始编码。

  • --refspec 对导出的每个 ref 应用指定的 refspec。可以指定多个。

  • [<git-rev-list-args>...] 参数列表，可被 'git rev-parse' 和 'git rev-list' 接受，用于指定要导出的特定对象和引用。例如，master~10..master 导出当前 master 引用以及自其第 10 个祖先提交以来添加的所有对象（除非指定了 --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

这将从 'master~5..master'（即如果 'master' 有线性历史，它将取最后 5 个提交）创建一个名为 'other' 的新分支。

请注意，这假设该修订范围引用的任何 blob 和提交消息都不包含字符串 'refs/heads/master'。

匿名化 ​

如果给出 --anonymize 选项，git 将尝试从仓库中删除所有标识信息，同时保留足够的原始树和历史模式以重现某些 bug。目标是在私有仓库上发现的 git bug 将在匿名化仓库中持续存在，后者可以与 git 开发者共享以帮助解决 bug。

使用此选项时，git 将在输出中将所有 refname、路径、blob 内容、提交和标签消息、名称和电子邮件地址替换为匿名化数据。相同字符串的两个实例将被等效替换（例如，两个具有相同作者的提交在输出中将具有相同的匿名化作者，但与原始作者字符串没有相似之处）。提交、分支和标签之间的关系以及提交时间戳将被保留（但提交消息和 refname 与原始内容没有相似之处）。树的相对结构将被保留（例如，如果您有一个包含 10 个文件和 3 个子树的根树，输出也将如此），但它们的名称和文件内容将被替换。

如果您认为发现了 git bug，可以从导出整个仓库的匿名化流开始：

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

然后确认 bug 在从该流创建的仓库中持续存在（许多 bug 不会，因为它们确实依赖于确切的仓库内容）：

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

如果匿名化仓库显示该 bug，那么值得将 anon-stream 与常规 bug 报告一起共享。请注意，匿名化流压缩效果很好，因此建议对其进行 gzip 压缩。如果您想检查流以确保不包含任何私有数据，可以在发送前直接查看。您可能还想尝试：

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

这将显示所有唯一的行（数字转换为 "X"，将 "User 0"、"User 1" 等折叠为 "User X"）。这会产生更小的输出，通常可以快速确认流中没有私有数据。

重现某些 bug 可能需要引用特定的提交或路径，这在 refname 和路径被匿名化后变得具有挑战性。您可以要求将特定标记保留原样或映射到新值。例如，如果您有一个通过 git rev-list sensitive -- secret.c 重现的 bug，可以运行：

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

导入流后，您可以在匿名化仓库中运行 git rev-list foo -- bar.c。

请注意，路径和 refname 在斜杠边界处分割为标记。上面的命令会将 subdir/secret.c 匿名化为类似 path123/bar.c 的内容；然后您可以在匿名化仓库中搜索 bar.c 以确定最终路径名。

为了使引用最终路径名更简单，您可以映射每个路径组件；因此如果您也将 subdir 匿名化为 publicdir，那么最终路径名将是 publicdir/bar.c。

限制 ​

由于 'git fast-import' 无法为树打标签，您将无法完全导出 linux.git 仓库，因为它包含一个引用树而非提交的标签。

另请参阅 ​

git-fast-import(1)

Git ​

git(1) 套件的一部分

基于 CC BY-NC-SA 3.0 许可发布

Pro Git 中文版