简体中文 ▾ 主题 ▾ 最新版本 ▾ git-filter-branch 最后更新于 2.44.0

名称

git-filter-branch - 重写分支

概要

git filter-branch [--setup <command>] [--subdirectory-filter <directory>]
	[--env-filter <command>] [--tree-filter <command>]
	[--index-filter <command>] [--parent-filter <command>]
	[--msg-filter <command>] [--commit-filter <command>]
	[--tag-name-filter <command>] [--prune-empty]
	[--original <namespace>] [-d <directory>] [-f | --force]
	[--state-branch <branch>] [--] [<rev-list-options>…​]

警告

git filter-branch 存在大量陷阱，可能导致预期的历史重写结果不明显地遭到破坏（并且由于其糟糕的性能，留给您调查此类问题的时间也很少）。这些安全和性能问题无法向后兼容地修复，因此，不建议使用它。请使用其他历史过滤工具，例如 git filter-repo。如果您仍然需要使用 git filter-branch，请仔细阅读 SAFETY（和 PERFORMANCE），了解 filter-branch 的陷阱，然后尽可能地避免其中列出的危害。

描述

允许您通过重写 <rev-list-options> 中提到的分支来重写 Git 修订历史，对每个修订应用自定义过滤器。这些过滤器可以修改每个树（例如，删除文件或对所有文件运行 perl 重写）或每个提交的信息。否则，所有信息（包括原始提交时间或合并信息）都将保留。

该命令只会重写命令行中提到的正向引用（例如，如果您传递 a..b，则只重写 b）。如果您未指定任何过滤器，提交将不做任何更改地重新提交，这通常不会产生任何效果。尽管如此，这在将来可能有助于弥补一些 Git 错误等，因此允许这种用法。

注意：此命令遵守 .git/info/grafts 文件和 refs/replace/ 命名空间中的引用。如果您定义了任何嫁接或替换引用，运行此命令将使它们永久化。

警告！重写后的历史将为所有对象提供不同的对象名称，并且不会与原始分支收敛。您将无法轻松地在原始分支之上推送和分发重写后的分支。如果您不了解其全部影响，请不要使用此命令，如果一个简单的单次提交足以解决您的问题，请无论如何都避免使用它。（有关重写已发布历史的更多信息，请参阅 git-rebase[1] 中的“从上游 rebase 恢复”部分。）

务必验证重写后的版本是否正确：如果与重写后的引用不同，原始引用将存储在 refs/original/ 命名空间中。

请注意，由于此操作的 I/O 成本很高，因此最好使用 -d 选项将临时目录重定向到磁盘之外，例如在 tmpfs 上。据报道，速度提升非常明显。

过滤器

过滤器按照如下所示的顺序列出。<command> 参数始终在 shell 上下文中通过 eval 命令进行评估（由于技术原因，提交过滤器是唯一的例外）。在此之前，$GIT_COMMIT 环境变量将被设置为包含正在重写的提交 ID。此外，GIT_AUTHOR_NAME、GIT_AUTHOR_EMAIL、GIT_AUTHOR_DATE、GIT_COMMITTER_NAME、GIT_COMMITTER_EMAIL 和 GIT_COMMITTER_DATE 会从当前提交中获取并导出到环境中，以影响过滤器运行后由 git-commit-tree[1] 创建的替换提交的作者和提交者身份。

如果 <command> 的任何评估返回非零退出状态，则整个操作将中止。

提供了一个 map 函数，它接受一个“原始 sha1 ID”参数，如果提交已被重写，则输出一个“重写后的 sha1 ID”，否则输出“原始 sha1 ID”；如果您的提交过滤器发出了多个提交，map 函数可以在单独的行上返回多个 ID。

选项

--setup <command>

这不是针对每个提交执行的实际过滤器，而是在循环之前进行的一次性设置。因此，尚未定义任何提交特定的变量。此处定义的功能或变量可以在后续的过滤器步骤中使用或修改，但提交过滤器除外，这是出于技术原因。

--subdirectory-filter <directory>

仅查看涉及给定子目录的历史。结果将只包含该目录作为其项目根目录。暗示 重映射到祖先。

--env-filter <command>

如果您只需要修改执行提交的环境，则可以使用此过滤器。具体来说，您可能希望重写作者/提交者姓名/电子邮件/时间环境变量（有关详细信息，请参阅 git-commit-tree[1]）。

--tree-filter <command>

这是用于重写树及其内容的过滤器。参数在 shell 中评估，工作目录设置为已检出树的根目录。然后新树将按原样使用（新文件自动添加，消失的文件自动删除——.gitignore 文件和任何其他忽略规则都无效！）。

--index-filter <command>

这是用于重写索引的过滤器。它类似于树过滤器，但不会检出树，这使其速度更快。常与 git rm --cached --ignore-unmatch ... 一起使用，详见下面的示例。对于复杂情况，请参阅 git-update-index[1]。

--parent-filter <command>

这是用于重写提交父列表的过滤器。它将从标准输入接收父字符串，并应将新的父字符串输出到标准输出。父字符串的格式在 git-commit-tree[1] 中描述：对于初始提交为空，对于普通提交为 "-p parent"，对于合并提交为 "-p parent1 -p parent2 -p parent3 …​"。

--msg-filter <command>

这是用于重写提交消息的过滤器。参数在 shell 中评估，原始提交消息在标准输入上；其标准输出用作新的提交消息。

--commit-filter <command>

这是执行提交的过滤器。如果指定了此过滤器，它将代替 git commit-tree 命令被调用，参数形式为 "<TREE_ID> [(-p <PARENT_COMMIT_ID>)…​]"，并且日志消息在标准输入上。提交 ID 期望在标准输出上。

作为一项特殊扩展，提交过滤器可以发出多个提交 ID；在这种情况下，原始提交的重写子项将全部将其作为父项。

您可以在此过滤器中使用 map 方便函数，以及其他方便函数。例如，调用 skip_commit "$@" 将跳过当前提交（但不会跳过其更改！如果您想这样做，请改用 git rebase）。

如果您不希望保留只有一个父级且未对树进行任何更改的提交，也可以使用 git_commit_non_empty_tree "$@" 代替 git commit-tree "$@"。

--tag-name-filter <command>

这是用于重写标签名称的过滤器。当传入时，它将对每个指向重写对象（或指向重写对象的标签对象）的标签引用调用。原始标签名称通过标准输入传递，新标签名称期望在标准输出上。

原始标签不会被删除，但可以被覆盖；使用 "--tag-name-filter cat" 只是更新标签。在这种情况下，要非常小心，并确保您已备份旧标签，以防转换出现问题。

支持几乎正确的标签对象重写。如果标签附有消息，将创建一个具有相同消息、作者和时间戳的新标签对象。如果标签附有签名，签名将被剥离。根据定义，无法保留签名。之所以说“几乎”正确，是因为理想情况下，如果标签没有更改（指向同一对象，具有相同名称等），它应该保留任何签名。事实并非如此，签名总是会被删除，买家自负。也不支持更改作者或时间戳（或标签消息）。指向其他标签的标签将被重写以指向底层提交。

--prune-empty

一些过滤器将生成未触及树的空提交。此选项指示 git-filter-branch 删除此类提交，如果它们只有一个或零个未修剪的父级；因此，合并提交将保持不变。此选项不能与 --commit-filter 一起使用，尽管可以使用提交过滤器中提供的 git_commit_non_empty_tree 函数实现相同的效果。

--original <namespace>

使用此选项设置原始提交将存储的命名空间。默认值为 refs/original。

-d <directory>

使用此选项设置用于重写的临时目录的路径。当应用树过滤器时，命令需要将树临时检出到某个目录，这在大型项目中可能会占用大量空间。默认情况下，它在 .git-rewrite/ 目录中执行此操作，但您可以通过此参数覆盖该选择。

-f
--force

除非强制执行，否则 git filter-branch 拒绝在存在临时目录或已有以 refs/original/ 开头的引用时启动。

--state-branch <branch>

此选项将导致旧对象到新对象的映射在启动时从指定分支加载，并在退出时作为新提交保存到该分支，从而实现大型树的增量。如果 <branch> 不存在，它将被创建。

<rev-list options>…​

git rev-list 的参数。这些选项包含的所有正向引用都将被重写。您还可以指定 --all 等选项，但必须使用 -- 将它们与 git filter-branch 选项分开。暗示 重映射到祖先。

重映射到祖先

通过使用 git-rev-list[1] 参数，例如路径限制器，您可以限制被重写的修订集。但是，命令行上的正向引用是特殊的：我们不允许它们被此类限制器排除。为此，它们会改为指向未被排除的最近祖先。

退出状态

成功时，退出状态为 0。如果过滤器找不到要重写的任何提交，则退出状态为 2。在任何其他错误情况下，退出状态可能为任何其他非零值。

示例

假设您想从所有提交中删除一个文件（包含机密信息或侵犯版权）

git filter-branch --tree-filter 'rm filename' HEAD

但是，如果文件在某些提交的树中不存在，则简单的 rm filename 将对该树和提交失败。因此，您可能希望改用 rm -f filename 作为脚本。

将 --index-filter 与 git rm 结合使用会产生一个显著更快的版本。与使用 rm filename 一样，如果文件在提交的树中不存在，git rm --cached filename 将失败。如果您想“完全忘记”一个文件，它何时进入历史无关紧要，因此我们还添加 --ignore-unmatch

git filter-branch --index-filter 'git rm --cached --ignore-unmatch filename' HEAD

现在，您将获得保存在 HEAD 中的重写历史。

将仓库重写为 foodir/ 作为其项目根目录，并丢弃所有其他历史记录

git filter-branch --subdirectory-filter foodir -- --all

因此，您可以将一个库子目录变成它自己的仓库。注意 -- 将 filter-branch 选项与修订选项分开，以及 --all 以重写所有分支和标签。

将一个提交（通常位于另一个历史的尖端）设置为当前初始提交的父级，以便将另一个历史粘贴到当前历史之后

git filter-branch --parent-filter 'sed "s/^\$/-p <graft-id>/"' HEAD

（如果父字符串为空——这发生在处理初始提交时——则将 graftcommit 添加为父级）。请注意，这假定历史只有一个根（即，没有发生没有共同祖先的合并）。如果不是这种情况，请使用

git filter-branch --parent-filter \
	'test $GIT_COMMIT = <commit-id> && echo "-p <graft-id>" || cat' HEAD

或者更简单地

git replace --graft $commit-id $graft-id
git filter-branch $graft-id..HEAD

从历史中删除“Darl McBribe”所做的提交

git filter-branch --commit-filter '
	if [ "$GIT_AUTHOR_NAME" = "Darl McBribe" ];
	then
		skip_commit "$@";
	else
		git commit-tree "$@";
	fi' HEAD

函数 skip_commit 定义如下

skip_commit()
{
	shift;
	while [ -n "$1" ];
	do
		shift;
		map "$1";
		shift;
	done;
}

这个移位技巧首先丢弃了树 ID，然后是 -p 参数。请注意，这正确地处理了合并！如果 Darl 提交了 P1 和 P2 之间的合并，它将正确传播，并且合并的所有子提交将成为以 P1，P2 为其父级的合并提交，而不是原始合并提交。

注意：由这些提交引入的、且未被后续提交恢复的更改，仍将存在于重写后的分支中。如果您想将更改连同提交一起丢弃，则应使用 git rebase 的交互模式。

您可以使用 --msg-filter 重写提交日志消息。例如，通过 git svn 创建的仓库中的 git svn-id 字符串可以通过这种方式删除

git filter-branch --msg-filter '
	sed -e "/^git-svn-id:/d"
'

如果您需要向例如最后 10 个提交（其中没有一个是合并）添加 Acked-by 行，请使用此命令

git filter-branch --msg-filter '
	cat &&
	echo "Acked-by: Bugs Bunny <bunny@bugzilla.org>"
' HEAD~10..HEAD

--env-filter 选项可用于修改提交者和/或作者身份。例如，如果您发现由于 user.email 配置错误导致您的提交身份错误，则可以在发布项目之前进行更正，如下所示

git filter-branch --env-filter '
	if test "$GIT_AUTHOR_EMAIL" = "root@localhost"
	then
		GIT_AUTHOR_EMAIL=john@example.com
	fi
	if test "$GIT_COMMITTER_EMAIL" = "root@localhost"
	then
		GIT_COMMITTER_EMAIL=john@example.com
	fi
' -- --all

要将重写限制为历史的某个部分，除了新的分支名称之外，还要指定一个修订范围。新的分支名称将指向 git rev-list 打印的此范围的最高修订。

考虑这段历史

     D--E--F--G--H
    /     /
A--B-----C

要仅重写提交 D、E、F、G、H，而保留 A、B 和 C 不变，请使用

git filter-branch ... C..H

要重写提交 E、F、G、H，请使用以下之一

git filter-branch ... C..H --not D
git filter-branch ... D..H --not C

将整个树移动到子目录中，或从其中删除

git filter-branch --index-filter \
	'git ls-files -s | sed "s-\t\"*-&newsubdir/-" |
		GIT_INDEX_FILE=$GIT_INDEX_FILE.new \
			git update-index --index-info &&
	 mv "$GIT_INDEX_FILE.new" "$GIT_INDEX_FILE"' HEAD

缩减仓库的清单

git-filter-branch 可以用于去除文件的子集，通常结合使用 --index-filter 和 --subdirectory-filter。人们期望最终的仓库会比原始仓库小，但您需要多做几步才能真正使其变小，因为 Git 会努力不丢失您的对象，直到您告诉它这样做。首先确保：

  • 如果一个 blob 在其生命周期中被移动过，您确实删除了所有文件名变体。git log --name-only --follow --all -- filename 可以帮助您找到重命名。

  • 您确实过滤了所有引用：调用 git-filter-branch 时使用 --tag-name-filter cat -- --all。

然后有两种方法可以获得更小的仓库。一种更安全的方法是克隆，这会使您的原始仓库保持完整。

  • 使用 git clone file:///path/to/repo 克隆它。克隆将不包含已删除的对象。请参阅 git-clone[1]。（请注意，使用纯路径克隆只会硬链接所有内容！）

如果您出于任何原因真的不想克隆它，请检查以下几点（按此顺序）。这是一种非常具有破坏性的方法，所以请务必备份或回到克隆方式。您已收到警告。

  • 删除 git-filter-branch 备份的原始引用：执行 git for-each-ref --format="%(refname)" refs/original/ | xargs -n 1 git update-ref -d。

  • 使用 git reflog expire --expire=now --all 使所有引用日志过期。

  • 使用 git gc --prune=now 垃圾回收所有未引用的对象（如果您的 git-gc 不够新，不支持 --prune 的参数，请改用 git repack -ad; git prune）。

性能

git-filter-branch 的性能缓慢得像冰川；它的设计使得向后兼容的实现不可能快速

  • 在编辑文件时，git-filter-branch 的设计是检出原始仓库中存在的每一个提交。如果您的仓库有 10^5 个文件和 10^5 个提交，但每个提交只修改五个文件，那么 git-filter-branch 将强制您执行 10^10 次修改，尽管最多只有 5*10^5 个唯一 blob。

  • 如果您试图作弊，并让 git-filter-branch 只处理提交中修改的文件，那么会发生两件事

    • 当用户只是尝试重命名文件时，您会遇到删除问题（因为尝试删除不存在的文件看起来是空操作；需要一些诡计才能在文件重命名通过任意用户提供的 shell 发生时重新映射删除）

    • 即使您成功地进行了重命名删除的诡计，您仍然在技术上违反了向后兼容性，因为用户被允许以依赖提交拓扑而不是仅仅基于文件内容或名称的方式过滤文件（尽管这在实践中尚未观察到）。

  • 即使您不需要编辑文件，而只是想重命名或删除一些文件，从而可以避免检出每个文件（即，您可以使用 --index-filter），您仍然在为您的过滤器传递 shell 片段。这意味着对于每个提交，您都必须有一个准备好的 git 仓库，以便可以在其中运行这些过滤器。这是一个重要的设置。

  • 此外，git-filter-branch 会为每个提交创建或更新几个额外的文件。其中一些是为了支持 git-filter-branch 提供的便捷函数（如 map()），而另一些则是为了跟踪内部状态（但也可能被用户过滤器访问；git-filter-branch 的一个回归测试就是这样做的）。这实质上相当于使用文件系统作为 git-filter-branch 和用户提供的过滤器之间的 IPC 机制。磁盘通常是一种缓慢的 IPC 机制，并且写入这些文件实际上也代表了我们每次提交时都会遇到的独立进程之间的强制同步点。

  • 用户提供的 shell 命令可能涉及命令管道，导致每个提交创建许多进程。创建和运行另一个进程在不同操作系统之间需要不同量的时间，但在任何平台上，相对于调用函数来说，这都非常慢。

  • git-filter-branch 本身是用 shell 编写的，这有点慢。这是唯一一个可以向后兼容修复的性能问题，但与 git-filter-branch 设计固有的上述问题相比，工具本身的语言是一个相对次要的问题。

    • 旁注：不幸的是，人们倾向于专注于“用 shell 编写”这一方面，并定期询问 git-filter-branch 是否可以用其他语言重写以解决性能问题。这不仅忽略了设计中固有的更大问题，而且帮助也比您预期的要少：如果 git-filter-branch 本身不是 shell，那么便捷函数（map()，skip_commit() 等）和 --setup 参数将无法在程序开始时只执行一次，而是需要添加到每个用户过滤器前面（因此在每次提交时重新执行）。

git filter-repo 工具是 git-filter-branch 的替代品，它没有这些性能问题或安全问题（下文提及）。对于那些现有工具依赖于 git-filter-branch 的用户，git filter-repo 也提供了 filter-lamely，一个即插即用的 git-filter-branch 替代品（有一些注意事项）。尽管 filter-lamely 具有与 git-filter-branch 相同的所有安全问题，但它至少在一定程度上缓解了性能问题。

安全

git-filter-branch 充满了陷阱，很容易导致仓库损坏或结果比开始时更糟糕

  • 某人可能有一套“工作且经过测试的过滤器”，他们将其记录或提供给同事，然后同事在不同的操作系统上运行它们，而相同的命令在那里未工作/未测试（git-filter-branch 手册页中的一些示例也受此影响）。BSD 与 GNU 用户空间差异确实会造成麻烦。如果幸运，会喷出错误消息。但同样有可能的是，命令要么没有执行请求的过滤，要么通过进行一些不需要的更改而悄悄地损坏。不需要的更改可能只影响少数提交，因此也不一定明显。（问题不一定明显的事实意味着它们很可能在重写后的历史被使用了相当长一段时间后才被注意到，此时很难再为另一次重写辩解了。）

  • 带有空格的文件名常常被 shell 片段错误处理，因为它们会给 shell 管道带来问题。不是每个人都熟悉 find -print0, xargs -0, git-ls-files -z 等。即使熟悉这些的人也可能认为这些标志不相关，因为在做过滤的人加入项目之前，其他人已经在他们的仓库中重命名了任何此类文件。而且通常，即使那些熟悉处理带空格参数的人也不会这样做，只是因为他们没有考虑所有可能出错的事情的心态。

  • 非 ASCII 文件名可能会在不知不觉中被删除，尽管它们位于所需的目录中。保留所需的路径通常使用管道来完成，例如 git ls-files | grep -v ^WANTED_DIR/ | xargs git rm。ls-files 只会在需要时引用文件名，所以人们可能不会注意到其中一个文件与正则表达式不匹配（至少直到太晚）。是的，了解 core.quotePath 的人可以避免这种情况（除非他们有其他特殊字符，如 \t、\n 或 "），以及使用 ls-files -z 和 grep 以外的东西的人可以避免这种情况，但这并不意味着他们会。

  • 同样，在移动文件时，可能会发现带有非 ASCII 或特殊字符的文件名最终出现在不同的目录中，其中包含一个双引号字符。（这在技术上与上述引用问题相同，但也许是一种有趣的、不同的方式，它已经并确实表现为一个问题。）

  • 意外地混淆新旧历史太容易了。使用任何工具仍然可能发生，但 git-filter-branch 几乎是在鼓励这样做。如果幸运，唯一的缺点是用户感到沮丧，因为他们不知道如何缩小仓库并删除旧内容。如果不走运，他们将旧历史与新历史合并，最终得到每个提交的多个“副本”，其中一些包含不需要或敏感的文件，而另一些则没有。这以多种不同的方式发生

    • 默认只进行部分历史重写（--all 不是默认选项，很少有示例显示它）

    • 没有自动的运行后清理功能

    • --tag-name-filter（用于重命名标签时）不会删除旧标签，而只是添加带有新名称的新标签

    • 没有提供足够的教育信息来告知用户重写的后果以及如何避免混淆新旧历史。例如，本手册页讨论了用户需要理解他们需要将所有分支的更改 rebase 到新历史之上（或删除并重新克隆），但这只是需要考虑的多个问题之一。有关更多详细信息，请参阅 git filter-repo 手册页的“DISCUSSION”部分。

  • 由于以下两个问题之一，带注释的标签可能会意外地转换为轻量级标签

    • 有人可能进行了历史重写，意识到搞砸了，从 refs/original/ 中的备份恢复，然后重新执行他们的 git-filter-branch 命令。（refs/original/ 中的备份不是真正的备份；它首先解引用标签。）

    • 在您的 <rev-list-options> 中使用 --tags 或 --all 运行 git-filter-branch。为了将带注释的标签保留为带注释的，您必须使用 --tag-name-filter（并且不得在先前搞砸的重写中从 refs/original/ 恢复）。

  • 任何指定了编码的提交消息在重写后都会损坏；git-filter-branch 会忽略编码，获取原始字节，然后将其提供给 commit-tree，而不告知其正确的编码。（无论是否使用 --msg-filter，都会发生这种情况。）

  • 提交消息（即使都是 UTF-8）默认情况下也会因未更新而损坏——提交消息中对其他提交哈希的任何引用现在都将指向不再存在的提交。

  • 没有为帮助用户找到他们应该删除的不需要的垃圾提供设施，这意味着他们更有可能进行不完整或部分清理，这有时会导致混乱和人们浪费时间试图理解。（例如，人们倾向于只寻找大文件删除，而不是大目录或扩展名，一旦他们这样做，那么过了一段时间，使用新仓库并回顾历史的人会注意到一个构建产物目录，其中有一些文件但不是全部，或者一个依赖缓存（node_modules 或类似），它永远无法正常工作，因为它缺少一些文件。）

  • 如果未指定 --prune-empty，则过滤过程可能会创建大量令人困惑的空提交

  • 如果指定了 --prune-empty，那么在过滤操作之前有意放置的空提交也会被修剪，而不仅仅是修剪因过滤规则而变空的提交。

  • 如果指定了 --prune-empty，有时空提交会被遗漏并仍然存在（一个相对罕见的 bug，但它确实发生…​）

  • 一个小问题是，用户如果目标是更新仓库中的所有姓名和电子邮件，可能会被引向 --env-filter，这只会更新作者和提交者，而忽略标签创建者。

  • 如果用户提供的 --tag-name-filter 将多个标签映射到同一名称，则不会提供警告或错误；git-filter-branch 只会以某种未记录的预定义顺序覆盖每个标签，导致最终只剩下一个标签。（git-filter-branch 的一个回归测试要求这种令人惊讶的行为。）

此外，git-filter-branch 的糟糕性能常常导致安全问题

  • 想出正确的 shell 片段来执行您想要的过滤有时很困难，除非您只是进行微不足道的修改，例如删除几个文件。不幸的是，人们通常通过尝试来判断片段是否正确，但正确与否可能因特殊情况而异（文件名中的空格、非 ASCII 文件名、有趣的作者姓名或电子邮件、无效时区、存在嫁接或替换对象等），这意味着他们可能需要等待很长时间，遇到错误，然后重新开始。git-filter-branch 的性能如此糟糕，使得这个循环非常痛苦，减少了仔细重新检查的可用时间（更不用说它对执行重写的人的耐心造成了什么影响，即使他们确实在技术上拥有更多时间）。这个问题更加复杂，因为损坏的过滤器导致的错误可能长时间不显示和/或在大量输出中丢失。更糟糕的是，损坏的过滤器通常只会导致静默的错误重写。

  • 最重要的是，即使用户最终找到了可用的命令，他们也自然希望分享它们。但他们可能不知道自己的仓库没有一些别人仓库才有的特殊情况。因此，当其他人使用不同的仓库运行相同的命令时，他们就会遇到上述问题。或者，用户只是运行了确实经过特殊情况验证的命令，但他们将其运行在不同的操作系统上，在那里它不起作用，如上所述。

GIT

Git[1] 套件的一部分

scroll-to-top