Git cherry-pick 使用教程：只把需要的提交合并到当前分支

前言

使用 Git 开发项目时，经常会遇到这样的情况：某个功能分支还没有开发完成，但其中有一次 Bug 修复需要提前合并到主分支。

如果直接执行 merge，可能把整个功能分支的其他修改也一起合并进来。手动复制代码虽然可以解决问题，但容易遗漏文件，也不方便追踪修改来源。

这时可以使用 Git 自带的 cherry-pick 命令，选择性地把某次提交应用到当前分支。

本文通过几个常见场景，介绍 cherry-pick 的基本使用方法，以及遇到冲突时应该如何处理。

一、cherry-pick 是什么？

cherry-pick 的作用是：将一个已经存在的提交所引入的修改，应用到当前分支，并通常生成一个新的提交。

例如，有两个分支：

main:     A --- B --- C
                 \
feature:          D --- E --- F

假设 E 是一次 Bug 修复，而 D 和 F 都是尚未完成的新功能。

现在希望把 E 中的修复应用到 main，但暂时不合并其他修改。

可以在 main 分支执行：

git cherry-pick E

执行成功后，提交历史可以理解为：

main:     A --- B --- C --- E'
                 \
feature:          D --- E --- F

其中 E’ 是在 main 分支上新创建的提交。

虽然 E 和 E’ 引入的修改可能相同，但它们通常具有不同的提交哈希，因为提交的父节点和历史上下文不同。

这也是 cherry-pick 与普通 merge 的重要区别。

二、先找到需要的提交

假设项目有两个分支：

• main：当前稳定版本。
• feature/login：正在开发的登录功能。

某个修复已经提交到 feature/login，现在需要同步到 main。

首先查看目标分支的提交记录：

git log --oneline feature/login

可能看到类似输出：

a1b2c3d 调整登录页面样式
b2c3d4e 修复登录接口超时问题
c3d4e5f 添加登录状态管理

如果只需要修复登录接口超时的问题，就记下对应的提交哈希：

b2c3d4e

在正式操作前，建议检查当前工作区：

git status

最好确保没有未提交的修改，避免后续 cherry-pick 与现有工作区内容冲突。

三、使用 cherry-pick 复制指定提交

先切换到需要接收修复的分支：

git switch main

然后执行：

git cherry-pick b2c3d4e

如果修改能够正常应用，Git 通常会自动创建一个新提交。

此时可以查看最近的提交：

git log --oneline -3

能够看到新增的修复提交。

这里需要注意两点。

第一，cherry-pick 修改的是当前分支，并不会删除或移动原始分支中的提交。

第二，cherry-pick 不是简单复制整个文件，而是尝试应用指定提交引入的修改。如果两个分支的代码差异较大，仍然可能出现冲突。

四、一次复制多个提交

有时需要同步的不止一次提交，可以在命令中指定多个提交哈希。

例如：

git cherry-pick a1b2c3d b2c3d4e

Git 会按指定的提交顺序依次尝试应用这些修改。

如果需要复制一段连续的提交，也可以使用范围语法。

例如：

git cherry-pick A^..B

这里假设 A 和 B 是实际存在的提交，并且 A 是希望包含的起点，B 是范围终点。

A^..B 会选取从 A 开始到 B 的相关提交，但如果提交历史存在复杂的分叉或合并，实际选取的提交集合可能不只是直观的一条线。

因此，对于历史比较复杂的项目，建议先用 git log 检查范围，再执行 cherry-pick。

五、遇到代码冲突怎么办？

这是 cherry-pick 最常见的问题之一。

假设 feature 分支修改了登录接口，而 main 分支也修改了相同位置。

执行：

git cherry-pick b2c3d4e

可能出现冲突提示。

这时先执行：

git status

查看哪些文件存在冲突。

对于普通文本冲突，Git 可能在文件中加入类似内容：

<<<<<<< HEAD
当前分支的代码
=======
准备应用的提交中的代码
>>>>>>> b2c3d4e

需要手动检查两边的修改，保留正确的最终代码，并删除冲突标记。

处理完成后，将对应文件加入暂存区：

git add path/to/file

然后继续操作：

git cherry-pick --continue

Git 会尝试完成当前提交，并继续处理剩余的提交。

如果冲突无法合理解决，或者发现选错了提交，可以执行：

git cherry-pick --abort

该命令会取消当前 cherry-pick 操作，并尝试恢复到操作开始前的状态。

因此，遇到冲突时不需要急着 reset，也不要直接删除仓库重新拉取。

六、暂时不自动创建提交

默认情况下，cherry-pick 成功后会自动创建提交。

如果希望先检查修改内容，再决定如何提交，可以使用：

git cherry-pick --no-commit b2c3d4e

也可以简写成：

git cherry-pick -n b2c3d4e

这会尝试把指定提交的修改应用到工作区和暂存区，但不自动生成新的提交。

然后可以检查：

git status
git diff --cached

确认修改符合预期后，再手动提交：

git commit -m "修复登录接口超时问题"

这种方式适合需要调整提交内容，或者希望将多个小提交中的修改整合成一次提交的场景。

需要注意，使用 --no-commit 时更应该提前检查工作区和暂存区，因为该参数允许在暂存区已有修改的情况下操作，后续提交可能包含原先暂存的内容。

七、如何保留原始提交信息？

有时需要把新版本中的修复同步回旧版本维护分支。

例如，main 分支已经修复了一个 Bug，而 release 分支仍然需要相同的修复。

可以使用：

git cherry-pick -x b2c3d4e

其中 -x 会在符合条件的成功 cherry-pick 提交说明中附加原始提交的哈希信息。

这样后续查看 release 分支历史时，就能知道这次修复来源于哪个提交。

对于公开维护的多个版本分支，这种方式比较实用。

不过它不会自动建立两个提交之间的同步关系。如果原始提交后续被修改或撤销，其他分支中的对应提交不会跟着自动变化。

八、cherry-pick 与 merge、rebase 的区别

这三个命令都与分支修改有关，但使用目的不同。

如果一个功能分支已经完成开发，准备整体合并到主分支，通常使用 merge 或根据团队规范使用 rebase 更合适。

如果只需要从另一个分支挑选一个独立修复，cherry-pick 会比较方便。

不过不建议长期依赖 cherry-pick 在多个分支之间反复同步相同修改，否则容易产生重复提交，也会增加后续维护和合并的复杂度。

九、几个容易忽略的问题

1. cherry-pick 不会自动包含依赖提交

假设 E 提交中的代码依赖 D 提交新增的函数。

即使只 cherry-pick E 成功，也可能因为缺少 D 中的函数而导致项目无法运行。

因此，应用提交之前，应检查它是否依赖其他修改。

2. 已经应用过的修改可能无法再次应用

如果当前分支已经包含了相同的修改，cherry-pick 可能产生空提交并暂停，要求决定如何处理。

这时应该检查当前分支的实际内容，而不是为了执行成功就强行创建重复提交。

3. 不要直接处理不熟悉的合并提交

普通 cherry-pick 主要针对常规提交。

如果指定的是一个包含多个父提交的 merge commit，Git 通常无法直接判断应该相对于哪个父提交应用修改，需要使用 -m 指定主线。

对于不熟悉提交拓扑的情况，建议先检查合并提交内容，不要随意指定主线编号。

4. 操作完成后检查和测试

即使 cherry-pick 没有出现冲突，也不代表代码一定能够正常工作。

特别是跨版本同步修复时，两个分支可能使用不同的接口、依赖或配置。

建议在提交完成后运行必要的测试，确认修复真正适用于目标分支。

十、总结

Git cherry-pick 适合只需要从其他分支拿出部分提交，而不希望合并整个分支的情况。

最常用的命令包括：

# 应用指定提交
git cherry-pick <commit>

# 遇到冲突后继续
git cherry-pick --continue

# 取消当前操作
git cherry-pick --abort

# 应用修改但不自动提交
git cherry-pick -n <commit>

# 附加原始提交来源
git cherry-pick -x <commit>

日常开发中，建议先确认目标提交的作用和依赖关系，再决定是否使用 cherry-pick。

对于独立的 Bug 修复和版本回补，它通常比手动复制代码方便；但对于完整功能分支的合并，仍然应该优先考虑正常的分支合并流程。