执行filter-branch后如何构建新旧Commit SHA映射以更新引用

搞定这个映射其实不难，Git的filter-branch工具已经悄悄给我们留好了线索，结合GitPython可以轻松实现你的需求。下面分步骤给你讲清楚：

1. 先搞懂filter-branch的备份机制 #

当你运行filter-branch重写提交时，Git会自动把原始的分支引用（比如refs/heads/master）备份到refs/original/目录下。这个备份是我们建立映射的核心依据——原始分支的提交历史和过滤后的新分支历史是一一对应的线性关系。

2. 用GitPython构建映射的两种方法 #

方法一：直接遍历原始分支与新分支的提交 #

这种方法直观可靠，适合大多数线性重写的场景：

from git import Repo

# 初始化仓库对象
repo = Repo("/path/to/your/repository")
target_branch = "master"  # 替换成你实际处理的分支名

# 获取filter-branch备份的原始分支，以及过滤后的新分支
original_ref = repo.refs[f"original/heads/{target_branch}"]
new_ref = repo.refs[target_branch]

# 构建旧SHA到新SHA的映射字典
commit_map = {}
# 同时遍历两个分支的提交（顺序一致，从新到旧一一对应）
for old_commit_entry, new_commit_entry in zip(original_ref.log(), new_ref.log()):
    commit_map[old_commit_entry.newhexsha] = new_commit_entry.newhexsha

# 如果你需要反向映射（新SHA找旧SHA），可以直接反转字典
reverse_commit_map = {v: k for k, v in commit_map.items()}

方法二：解析filter-branch生成的日志文件 #

filter-branch运行时会在.git/refs/original/logs/heads/目录下生成对应分支的日志文件，里面每一行都直接记录了旧提交SHA和对应的新提交SHA，解析这个文件更高效：

import os
from git import Repo

repo = Repo("/path/to/your/repository")
target_branch = "master"
# 拼接日志文件路径
log_file_path = os.path.join(
    repo.git_dir, "refs", "original", "logs", "heads", target_branch
)

commit_map = {}
with open(log_file_path, "r", encoding="utf-8") as log_file:
    for line in log_file:
        # 日志行格式：旧SHA 新SHA 作者信息 时间戳 提交说明
        line_parts = line.strip().split()
        old_sha = line_parts[0]
        new_sha = line_parts[1]
        commit_map[old_sha] = new_sha

3. 优化你的tree-filter命令（小建议） #

顺便提一句，你当前的tree-filter命令用ls | grep可能会遇到目录名含特殊字符（比如空格、括号）的问题，换成find工具更安全：

target_dir = "your-target-dir"  # 替换成你的目标目录名
repo.git.filter_branch(
    '--force',
    '--tree-filter',
    f"""mkdir -p {target_dir} && find . -maxdepth 1 -mindepth 1 ! -name '{target_dir}' -exec mv {{}} {target_dir}/ \\;""",
    '@'
)

用find可以避免特殊字符导致的匹配错误，稳定性更强。

内容的提问来源于stack exchange，提问作者George Mauer