如何为git filter-repo --path-rename操作添加更名说明提交？

核心问题说明 #

git filter-repo --path-rename会重写整个仓库历史，将旧路径映射为新路径，但它不会自动生成专门记录更名操作的提交。直接执行重命名后尝试git commit会失败，因为工作区没有实际变更。以下是两种可行的解决办法：

方案1：重写历史后添加空提交记录更名 #

1. 先用git filter-repo重写所有历史中的路径：

   git filter-repo --path-rename old/path:new/path
   

   这一步会让所有历史提交都使用新的文件/文件夹名称，完整保留历史关联。
2. 由于重写后工作区文件已是新名称，无实际变更，需创建空提交记录更名：

   git commit --allow-empty -m "Rename old/path to new/path (historical paths rewritten via git filter-repo)"
   

   这个空提交会作为明确的变更节点，方便后续追溯更名操作。

方案2：先创建正常更名提交，再重写历史（避免空提交） #

如果希望更名提交包含实际的文件变更记录，可以按以下步骤操作：

1. 先在当前分支执行常规重命名并提交：

   git mv old/path new/path
   git commit -m "Rename old/path to new/path"
   

2. 使用git filter-repo的提交回调，重写历史中所有旧路径为新路径，但保留刚才创建的更名提交：

   git filter-repo --commit-callback '
   # 跳过专门的更名提交，不修改其内容
   if commit.message.startswith(b"Rename old/path to new/path"):
       return
   # 替换其他所有提交中的旧路径
   for change in commit.file_changes:
       if change.old_path and change.old_path.startswith(b"old/path"):
           change.old_path = change.old_path.replace(b"old/path", b"new/path", 1)
       if change.new_path and change.new_path.startswith(b"old/path"):
           change.new_path = change.new_path.replace(b"old/path", b"new/path", 1)
   '
   

   处理完成后，所有历史提交的文件路径都会更新为新名称，同时保留那个包含实际变更的更名提交。

关于git filter-repo --path-rename自动添加提交的问题 #

git filter-repo --path-rename的设计目标是重写现有历史，而非生成新提交，因此没有内置的自动添加更名提交的功能。必须通过上述额外步骤，手动添加专门的更名记录。

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