如何为特定提交生成Git补丁

技术背景

在版本控制中，有时我们需要将某个特定的提交以补丁的形式保存下来，以便在其他分支或者仓库中应用。Git 提供了多种方法来生成和应用补丁，这对于代码的迁移、协作和问题修复都非常有用。

实现步骤

生成单个提交的补丁

若要为最新提交生成补丁，可使用如下命令：

git format-patch -1 HEAD

其中，-1 标志表示包含在补丁中的提交数量，HEAD 指向当前分支的最新提交。

若要为特定的提交生成补丁，将 HEAD 替换为具体的提交哈希值：

git format-patch -1 commit_id

生成多个提交的补丁

生成从特定 SHA - 1 哈希值开始的前 n 个提交的补丁：

git format-patch -<n> <SHA-1> --stdout > <name_of_patch_file>.patch

例如，生成从 HEAD 开始的最后 10 个提交的单个补丁文件：

git format-patch -10 HEAD --stdout > 0001-last-10-commits.patch

基于提交范围生成补丁

git format-patch commit_Id~1..commit_Id

此命令会生成从 commit_Id 的父提交到 commit_Id 本身的补丁。

仅对指定文件生成差异补丁

git diff master 766eceb -- connections/ > 000-mysql-connector.patch

该命令会生成 master 分支与 766eceb 提交之间 connections/ 目录下文件的差异补丁。

核心代码

生成补丁

# 为最新提交生成补丁
git format-patch -1 HEAD

# 为特定提交生成补丁
git format-patch -1 commit_id

# 生成从特定 SHA-1 哈希值开始的前 n 个提交的补丁
git format-patch -<n> <SHA-1> --stdout > <name_of_patch_file>.patch

# 基于提交范围生成补丁
git format-patch commit_Id~1..commit_Id

# 仅对指定文件生成差异补丁
git diff master 766eceb -- connections/ > 000-mysql-connector.patch

应用补丁

# 使用 git am 应用补丁
git am < file.patch

# 使用 git apply 应用补丁
git apply --verbose file.patch

自动应用 Github 提交补丁的 Bash 函数

dapply() {
  if [ -z "$1" ]; then
    echo ".bashrc: dapply: You need to supply a URL to a patch file."
    return 1
  fi

  URL="$1"

  if [[ "${URL}" != *.patch ]]; then
    echo ".bashrc: dapply: Appending .patch to URL=${URL}"
    URL="${URL}.patch"
    echo ".bashrc: dapply: Appended URL=${URL}"
  fi

  curl -L "${URL}" | git apply -v --index
  git commit -m ".bashrc: dapply: Applied ${URL} to current repo $(realpath .)."
}

最佳实践

• 使用 --base 选项：在 Git 2.9 及以上版本中，可使用 --base 选项记录基础树信息，确保补丁在特定提交之上应用。例如：

git format-patch --base=COMMIT_VALUE~ -M -C COMMIT_VALUE~..COMMIT_VALUE

• 配置 format.useAutoBase：在 Git 2.29 及以上版本中，可将 format.useAutoBase 配置为 whenAble，让 format-patch 在能找到有效基础提交时尝试包含它，否则继续格式化补丁而不包含基础提交。

git config format.useAutoBase whenAble

常见问题

git format-patch -o <outdir> 报错

在 Git 2.24 之前，git format-patch -o <outdir> 等价于 mkdir <outdir>，而不是 mkdir -p <outdir>，可能导致目录创建失败。升级到 Git 2.24 及以上版本可解决此问题。

git rebase 与 format.useAutoBase 冲突

在 Git 2.25 之前，当设置 format.useAutoBase 配置变量时，git rebase 可能无法正常工作。升级到 Git 2.25 及以上版本可解决此问题。

git format-patch --output=there 崩溃

在 Git 2.30 之前，git format-patch --output=there 可能会崩溃。升级到 Git 2.30 及以上版本，该选项将得到支持。