基于三方开源项目二次开发的版本管理最佳实践

我这里分两个思路开始一个新项目

一、 先从克隆本地gitlab仓库开始，再添加三方仓库

二、 先从克隆三方仓库开始，再添加本地gitlab仓库

一、先从克隆本地gitlab仓库开始，再添加三方仓库

最佳实践概述

1. 保持上游仓库为远程仓库
2. 在本地维护两个长期分支：一个跟踪上游更新，一个用于你的二次开发
3. 定期将上游变更合并到你的开发分支

具体操作步骤

1. 初始设置

# 克隆你的内网仓库（假设已经存在）
git clone git@your-gitlab.com:your-team/your-project.git
cd your-project

# 添加上游仓库作为远程仓库
git remote add upstream https://github.com/original/repo.git

# 获取上游所有分支和标签
git fetch upstream

2. 基于特定版本创建二次开发分支

# 假设上游的v1.2.0是你基于开发的版本
git checkout -b custom-dev upstream/v1.2.0

# 进行你的二次开发并提交
# ... 修改代码 ...
git add .
git commit -m "Initial custom development"

# 推送到你的内网仓库
git push origin custom-dev

3. 创建跟踪上游更新的分支

# 创建一个专门跟踪上游更新的分支
git checkout -b upstream-track upstream/master

4. 定期合并上游更新

当上游有新功能发布时：

# 1. 更新上游跟踪分支
git checkout upstream-track
git pull upstream master

# 2. 切换到你的开发分支
git checkout custom-dev

# 3. 合并上游更新（推荐使用rebase或merge）
# 方法一：使用merge（保留完整历史）
git merge upstream-track

# 方法二：使用rebase（线性历史，更整洁）
git rebase upstream-track

# 如果有冲突，解决冲突后继续
# git add <冲突文件>
# git rebase --continue

# 4. 推送到你的内网仓库
git push origin custom-dev

5. 处理冲突的最佳实践

当合并/变基时遇到冲突：

1. 优先保留上游的变更（除非你的修改有特殊原因）
2. 使用git mergetool或手动解决冲突
3. 测试确保合并后的代码正常工作

高级技巧

使用git rerere记住冲突解决方案

# 启用rerere功能
git config --global rerere.enabled true

创建合并请求前的检查

# 在合并前检查差异
git diff upstream-track..custom-dev

# 或者使用图形化工具
gitk upstream-track..custom-dev

使用子模块（适用于大型项目）

如果项目结构允许，可以考虑将上游代码作为子模块：

git submodule add https://github.com/original/repo.git upstream-code
cd upstream-code
git checkout v1.2.0
cd ..

自动化脚本示例

你可以创建一个脚本update-from-upstream.sh来自动化这个过程：

#!/bin/bash

set -e

# 切换到上游跟踪分支
git checkout upstream-track

# 获取最新上游代码
git pull upstream master

# 切换回开发分支
git checkout custom-dev

# 合并上游更新
git merge upstream-track

# 如果有冲突，停止并提示用户
if [ $? -ne 0 ]; then
    echo "合并冲突，请手动解决冲突后继续"
    exit 1
fi

# 运行测试（如果有）
# ./run-tests.sh

# 推送更新
git push origin custom-dev

echo "上游更新已成功合并到custom-dev分支"

二、先从克隆三方仓库开始，再添加本地gitlab仓库

操作步骤：将三方代码设为 upstream，并添加 origin 指向本地 GitLab

你的需求是：

1. 保留三方代码作为 upstream（用于后续同步官方更新）。
2. 添加一个新的 origin，指向你的本地 GitLab（用于推送你的修改）。

---

具体操作流程

1. 克隆三方代码（如果尚未克隆）

git clone <三方代码仓库地址>
cd <项目目录>

此时默认的远程仓库是 origin（指向三方代码）。

2. 重命名 origin 为 upstream

git remote rename origin upstream

• 现在 upstream 指向三方代码仓库（官方源）。

• 检查远程仓库：

  git remote -v

  输出示例：

  upstream  git@github.com:official/repo.git (fetch)
  upstream  git@github.com:official/repo.git (push)

3. 添加新的 origin，指向你的本地 GitLab

git remote add origin <你的本地GitLab仓库地址>

• 例如：

  git remote add origin ssh://git@10.60.5.32:222/your-team/your-repo.git

• 再次检查远程仓库：

  git remote -v

  输出示例：

  origin    ssh://git@10.60.5.32:222/your-team/your-repo.git (fetch)
  origin    ssh://git@10.60.5.32:222/your-team/your-repo.git (push)
  upstream  git@github.com:official/repo.git (fetch)
  upstream  git@github.com:official/repo.git (push)

4. 推送代码到你的 origin（本地 GitLab）

git push -u origin --all   # 推送所有分支
git push -u origin --tags  # 推送所有标签

• -u（--set-upstream）会建立本地分支与远程分支的关联，以后可以直接用 git push 而不用指定远程分支。

---

后续工作流程

1. 从 upstream 同步官方更新

git fetch upstream          # 获取三方代码的最新提交
git merge upstream/main    # 合并到你的当前分支（或使用 `git rebase`）

2. 推送你的修改到 origin（你的 GitLab）

git push origin main       # 推送到你的仓库

---

关键点总结

操作	命令	作用
重命名 origin 为 upstream	git remote rename origin upstream	将三方代码设为上游
添加新的 origin	git remote add origin <GitLab地址>	设置你的 GitLab 仓库
推送代码到 origin	git push -u origin --all --tags	初始化推送所有分支和标签
从 upstream 同步更新	git fetch upstream + git merge upstream/main	获取官方最新代码

---

注意事项

1. 权限问题
   • 确保你有权限推送到本地 GitLab 仓库（SSH 密钥或账号配置正确）。
2. 冲突处理
   • 如果三方代码和你的修改有冲突，需要手动解决后再推送。
3. 长期维护
   • 定期从 upstream 拉取更新，避免代码脱节。

---

完整示例

# 1. 克隆三方代码
git clone git@github.com:official/repo.git
cd repo

# 2. 重命名 origin 为 upstream
git remote rename origin upstream

# 3. 添加新的 origin（指向你的 GitLab）
git remote add origin ssh://git@10.60.5.32:222/your-team/your-repo.git

# 4. 推送所有代码到你的仓库
git push -u origin --all
git push -u origin --tags

# 后续同步官方更新
git fetch upstream
git merge upstream/main

这样你就建立了一个既能同步官方更新，又能独立维护自己代码的工作流！ 🚀