如何解决git filter-repo --path-rename的“File renaming caused colliding pathnames!”错误？

错误含义："colliding pathnames"到底是什么？ #

你执行--path-rename做路径重命名时，在提交d8ab28d76da9371bf1db0dac8870122e57dc6713里，重命名后的<new-path>已经存在了。说白了就是：你想把旧路径改成新路径，但这个新路径在当前处理的提交里已经有对应的文件或目录，两者撞车了。

Git filter-repo在处理重命名时，会逐个检查每个提交的文件结构，确保重命名后的路径不会和提交里已有的路径重复，一旦发现重复就会抛出这个冲突错误。

解决方法 #

1. 先搞清楚冲突提交里的内容 #

先查看冲突提交的文件列表，确认<new-path>是不是真的存在：

git show d8ab28d76da9371bf1db0dac8870122e57dc6713 --name-only

如果能看到<new-path>，就说明这个提交里确实同时有你要重命名的旧路径和新路径的内容，重命名后必然重复。

2. 单独修改冲突提交 #

如果只是个别提交出问题，可以先修改这个提交，再重新执行filter-repo：

• 用交互式rebase定位到冲突提交的前一个版本：

  git rebase -i d8ab28d76da9371bf1db0dac8870122e57dc6713~1
  

• 在弹出的编辑器里，把该提交对应的命令改成edit，保存退出。
• 此时仓库会停在这个冲突提交，删除或移走提交里的<new-path>内容：

  # 如果是文件就直接删，目录加-r
  git rm -r <new-path>
  # 提交修改
  git commit --amend
  # 继续完成rebase
  git rebase --continue
  

• 等rebase完成后，再重新运行你的filter-repo命令。

3. 调整重命名规则 #

如果冲突是因为路径层级的问题（比如旧路径是a/b，新路径是a，但提交里已经有a目录），可以把重命名规则改得更具体，确保新路径不会和现有路径重叠。

4. 用--partial参数强制继续（谨慎用） #

如果确定冲突提交可以后续手动修复，或者不需要保留，可以尝试加--partial参数让filter-repo继续执行，不过这个操作会让处理不完整，之后需要手动清理冲突：

git filter-repo --replace-refs delete-no-add --path-rename <old-path>:<new-path> --force --partial

执行完后检查仓库状态，手动处理残留的冲突路径。

内容的提问来源于stack exchange，提问作者Geoff Alexander