跨 Gerrit 项目迁移分支并保留完整历史：一份可操作的 Git 指南

1. 背景与痛点

在基于 Gerrit 的代码管理流程中，我们经常会遇到这样的需求：将另一个 Gerrit 工程中的某个分支（如遗留功能分支、公共基础库分支）完整地"复制"到当前工程的仓库中，作为一个新分支，并且要求保留该分支的所有提交历史。

Gerrit 本身提供了分支管理功能，但"跨项目复制分支并保留历史"并不是一个原生操作。如果只是简单地复制代码快照，历史记录的丢失会让代码追溯、责任归属和 git blame 变得毫无意义。更糟糕的是，丢失历史可能会导致未来的合并冲突难以解决。

本文将以一个实战案例，详细介绍如何利用标准 Git 命令，干净、安全地将源 Gerrit 项目的指定分支代码及完整历史导入到目标 Gerrit 项目中，形成一个全新的分支。

2. 核心思路

Git 本身是分布式版本控制系统，每个克隆都包含完整的对象数据库。因此，我们可以：

将源 Gerrit 项目 作为本地仓库的一个远程仓库。
通过 git fetch 拉取源项目的所有分支和提交对象。
基于拉取到的源分支，在本地创建一个新分支（该分支自动继承源分支的完整历史）。
将这个新分支推送到目标 Gerrit 项目的远程仓库。

整个过程中，提交的 SHA-1 哈希值、作者信息、时间戳、提交说明等历史元数据都会被完整保留。

3. 操作步骤（标准流程）

假设：

源 Gerrit 项目地址：ssh://gerrit.example.com:29418/source-project
源分支名称：feature/old-module
目标 Gerrit 项目地址：ssh://gerrit.example.com:29418/target-project
希望在目标项目中创建的新分支名称：imported/legacy-module

3.1 准备本地仓库

首先，将目标项目克隆到本地（如果本地已有该仓库，请确保是最新状态）。

bash 复制代码

git clone ssh://gerrit.example.com:29418/target-project
cd target-project

3.2 添加源项目为远程仓库

在本地仓库中，把源 Gerrit 项目添加为一个额外的远程仓库（例如命名为 source-repo）。

bash 复制代码

git remote add source-repo ssh://gerrit.example.com:29418/source-project

3.3 拉取源项目的所有分支与历史

这一步是保留历史的关键：git fetch 会将源项目的所有引用（分支、标签）和完整的 Git 对象下载到本地，但不会自动合并或修改你当前的工作区。

bash 复制代码

git fetch source-repo

执行后，你可以通过 git branch -r 看到类似 source-repo/feature/old-module 的远程跟踪分支。

3.4 基于源分支创建本地新分支

现在，用源项目的分支来创建一个新的本地分支。这个新分支会完整继承源分支的所有历史。

bash 复制代码

git checkout -b imported/legacy-module source-repo/feature/old-module

说明：git checkout -b <新分支名> <起点> 中的 <起点> 可以是任意 commit 或引用。这里使用了远程跟踪分支 source-repo/feature/old-module，因此新分支会拥有完全相同的 commit 历史。

3.5 推送到目标 Gerrit 项目

将刚刚创建的本地分支推送到目标项目的远程仓库（origin）。

bash 复制代码

git push origin imported/legacy-module

推送成功后，在目标 Gerrit 项目的 Web 界面上就可以看到新分支 imported/legacy-module，其提交历史与源分支完全一致。

4. 高级场景与注意事项

4.1 只导入源仓库的某个子目录，并保留历史

如果需求不是导入整个分支，而是只导入其中的一个子目录（例如 src/common/utils），直接使用 git checkout -b 会带入整个代码树。此时需要用到 git subtree 命令。

基本流程依然是 git remote add + git fetch，但创建分支的步骤改为：

bash 复制代码

# 将源项目的子目录合并到当前分支的一个指定路径下，并保留历史
git subtree add --prefix=my-libs/utils source-repo/feature/old-module --squash

--squash 会压缩历史（不推荐保留完整历史时使用）。若要完整保留子目录的历史，可以使用 git subtree add --prefix=my-libs/utils source-repo/feature/old-module（不加 squash），但这样会把源分支的整个历史 引入，而不仅仅是子目录相关的提交。对于精确的子目录历史迁移，更复杂的方法可借助 git filter-branch 或 git filter-repo，但不在本文展开。

4.2 关于 Gerrit Change-Id

Gerrit 通常要求在提交信息中包含 Change-Id（形如 Change-Id: Ixxxx...）。迁移过来的旧提交中如果原本就有 Change-Id，这些行会作为提交信息的一部分被保留。但请注意：这些 Change-Id 在新项目中是无效的，因为 Gerrit 的变更（Change）与项目、分支强绑定。这不会影响代码本身，只是你无法通过原来的 Change-Id 在新项目中跳转。

如果你希望新分支上的所有提交都符合新项目的提交规范（例如重新生成 Change-Id），可能需要使用 git filter-branch 或 git rebase 修改提交信息，但这会改变提交的 SHA-1，相当于重写历史，操作需极度谨慎。

4.3 推送失败：分支权限与保护

如果在执行 git push origin <new-branch> 时被拒绝，通常是以下原因：

Gerrit 权限不足 ：你的账号在目标项目中没有 Create Reference 或直接 Push 的权限。请联系项目管理员添加。
分支命名限制 ：Gerrit 可能配置了 refs/for/* 的推送规则。创建分支应直接推送到 refs/heads/*，而 Gerrit 的默认权限允许项目所有者直接推送分支。如果被拒绝，可以尝试使用 Gerrit 的 Web 界面手动创建分支（从任意已有分支或 commit 创建），但那样不会保留源项目的完整历史------Web 界面只能基于当前仓库的已有对象创建分支。

因此，使用上述 Git 命令方式是最可靠的。若权限不足，可请管理员临时开放 Push 权限，或使用 Gerrit 的 REST API 创建分支（仍然需要基础权限）。

4.4 避免污染当前工作区

整个操作过程中，git fetch 不会修改你当前所在分支（比如 main）的文件。git checkout -b 会切换到新分支，工作区会变成源分支的内容。如果你不希望改变工作区，也可以使用 git branch <新分支名> source-repo/<源分支名> 来仅创建分支而不切换。

5. 完整示例脚本

为了方便自动化，可以将以下脚本保存为 import-branch.sh：

bash 复制代码

#!/bin/bash
# 用法: ./import-branch.sh <目标项目本地路径> <源项目URL> <源分支名> <新分支名>

set -e

TARGET_REPO_PATH=$1
SOURCE_REPO_URL=$2
SOURCE_BRANCH=$3
NEW_BRANCH=$4

cd "$TARGET_REPO_PATH"
git remote add source-temp "$SOURCE_REPO_URL"
git fetch source-temp
git checkout -b "$NEW_BRANCH" "source-temp/$SOURCE_BRANCH"
git push origin "$NEW_BRANCH"
git remote remove source-temp

echo "分支 $NEW_BRANCH 已成功导入并推送，历史完整保留。"

6. 总结

通过 git remote add + git fetch + git checkout -b 这个经典的组合，我们可以在几分钟内完成跨 Gerrit 项目的分支迁移，且完整保留每一次提交的历史记录。这个方法不需要任何 Gerrit 插件或管理员后台操作，只需要你在本地有对源项目的读取权限和对目标项目的推送权限。

核心步骤回顾：

git clone 目标项目
git remote add 源项目
git fetch 源项目
git checkout -b 基于源分支创建新分支
git push 推送到目标项目

适用场景：

将公共库的某个历史分支合并到业务项目中
合并两个独立演进的 Gerrit 项目
将旧项目的遗留分支"迁移"到新的项目仓库中

这种方法充分利用了 Git 分布式特性的优势，干净、安全、可审计。希望这篇文章能帮助你在 Gerrit 工作流中更灵活地管理跨项目代码与历史。