Git Fork 工作流：开源贡献者必备的 Git 操作手册

嵌入式开发者过去大多活在 SVN 或者厂商定制 IDE 的世界里，分支操作几乎为零。但如今越来越多的 MCU 工具链（ESP-IDF、Zephyr、Matter SDK）托管在 GitHub 上，参与开源、维护自己的 Fork、向上游提 PR 变成了一项基本功。

本文是一份纯实操手册——不解释 Git 原理，只给经过验证的命令序列。适用于以下场景：

Fork 了一个开源项目，想保持 main 分支干净可同步
需要一个 dev 分支承载自己的改动
不知道 SSH/HTTPS 排障怎么做
想有一套标准化的日常开发流程

一、初始状态

1
2
3

克隆后的默认状态:
  origin → 上游仓库 (如 alibaba/lumenx.git)
  main   → 唯一本地分支

问题：如果直接在 main 上改代码，以后无法干净地同步上游更新（会产生合并冲突和脏提交历史）。

目标架构：

1
2
3

upstream  (alibaba/lumenx)     origin  (jugolink/lumenx)
└── main                       └── main  (镜像 upstream)
                               └── dev   (你的改动)

二、配置 Remote（一次性）

2.1 查看当前 remote

1	git remote -v

典型输出（克隆后）：

1 2	origin https://github.com/alibaba/lumenx.git (fetch) origin https://github.com/alibaba/lumenx.git (push)

2.2 重命名 origin → upstream

1	git remote rename origin upstream

2.3 添加自己的 Fork 作为 origin

# SSH（推荐，需要配置 SSH Key）
git remote add origin git@github.com:你的用户名/仓库名.git

# HTTPS（备选，需要 Personal Access Token）
git remote add origin https://github.com/你的用户名/仓库名.git

2.4 验证

git remote -v

# 期望输出:
# origin    git@github.com:你的用户名/仓库名.git (fetch)
# origin    git@github.com:你的用户名/仓库名.git (push)
# upstream  https://github.com/上游/仓库名.git (fetch)
# upstream  https://github.com/上游/仓库名.git (push)

2.5 验证 Fork 可访问

# SSH
ssh -T git@github.com

# HTTPS（测试只读访问，不涉及认证）
git ls-remote https://github.com/你的用户名/仓库名.git

HTTPS vs SSH 排障：如果 SSH 不通（Connection closed），先用 HTTPS 替代：
1
git remote set-url origin https://github.com/你的用户名/仓库名.git
HTTPS push 时 Git 会弹出认证提示（浏览器 OAuth 或输入 Token）。

三、创建 dev 分支

# 确保在最新 main 上
git checkout main
git fetch upstream
git merge upstream/main

# 创建并切换到 dev 分支
git checkout -b dev

# 确认当前位置
git branch --show-current
# 输出: dev

四、日常开发流程

4.1 在 dev 上开发

# 确认在 dev 分支
git checkout dev

# ... 写代码 ...

# 查看变更
git status
git diff

# 随时同步上游（见第五节）

4.2 分组提交

将逻辑相关的改动分组提交，而不是一个大杂烩：

# 按功能分组 add
git add .env.example .gitignore scripts/
git commit -m "refactor: move API keys to environment variables"

git add frontend/yarn.lock frontend/package-lock.json
git commit -m "chore: replace yarn.lock with npm package-lock"

git add docs/
git commit -m "docs: add deployment troubleshooting guide"

提交信息格式（Conventional Commits）：

1
2
3

<type>: <简短描述>

<详细说明（可选）>

常用 type：feat fix refactor docs chore test perf ci

4.3 推送 dev 到自己的 Fork

# 首次推送（设置 upstream tracking）
git push -u origin dev

# 后续推送
git push origin dev

推送成功后 GitHub 会给出创建 PR 的链接：

1 2	remote: Create a pull request for 'dev' on GitHub by visiting: remote: https://github.com/你的用户名/仓库名/pull/new/dev

五、同步上游更新

5.1 更新 main 分支

git checkout main
git fetch upstream
git merge upstream/main
git push origin main

5.2 将上游更新合并到 dev

git checkout dev
git merge main

# 如果有冲突，解决后：
git add .
git commit -m "merge: sync upstream/main into dev"
git push origin dev

无冲突的理想状态：

1
2
3

upstream/main:  A → B → C → D
                          ↓ merge
dev:            A → B → C → D → X → Y (你的提交)

六、完整操作速查表

# ═══ 一次性配置 ═══

# 1. 设置 remote
git remote rename origin upstream
git remote add origin git@github.com:你的用户名/仓库名.git

# 2. 创建 dev 分支
git checkout -b dev
git push -u origin dev

# ═══ 每次开发 ═══

# 3. 写代码前先同步
git checkout main
git fetch upstream && git merge upstream/main
git push origin main
git checkout dev
git merge main

# 4. 分组提交
git add <相关文件组>
git commit -m "type: description"

# 5. 推送
git push origin dev

# ═══ 定期维护 ═══

# 查看所有分支
git branch -a

# 查看 main vs dev 差异
git diff main..dev --stat

# 查看提交日志
git log --oneline --graph --all -20

七、常见问题

Q: 不小心在 main 上改了代码？

# 先保存改动
git stash

# 切到 dev
git checkout dev

# 把改动弹到 dev
git stash pop

# 正常提交
git add . && git commit -m "..."

Q: Push 时报 “Permission denied”？

# 检查 remote URL 是否正确
git remote -v

# HTTPS → 检查是否配置了 credential helper
git config --global credential.helper

# SSH → 检查 SSH Key 是否添加到 GitHub
ssh -T git@github.com
# 正常输出: Hi <用户名>! You've successfully authenticated...

# 如果 SSH 不通，临时切 HTTPS
git remote set-url origin https://github.com/你的用户名/仓库名.git

Q: 想回到 main 的干净状态？

1 2	git checkout main git reset --hard upstream/main

⚠️ 这会丢弃 main 上的所有本地改动，执行前确认 dev 上已保存。

Q: dev 分支落后 main 太多，Merge 冲突严重？

# 用 rebase 替代 merge（历史更干净，但需谨慎）
git checkout dev
git rebase main

# 如果 rebase 中途出错想放弃
git rebase --abort

# 解决冲突后继续
git add .
git rebase --continue

Q: 如何向开源仓库提 PR？

确保 dev 上的改动已经 push 到你的 Fork
在 GitHub 打开你的 Fork 仓库
点击 “Compare & pull request”
base repository: 上游/仓库名 base: main
head repository: 你的/仓库名 compare: dev
填写 PR 描述，提交

八、推荐配置

设置默认 push 行为

1	git config --global push.default simple

设置 pull 时使用 rebase（避免无意义 merge commit）

1	git config --global pull.rebase true

给常用命令起别名

1
2

git config --global alias.sync-upstream '!git checkout main && git fetch upstream && git merge upstream/main && git push origin main && git checkout -'
git config --global alias.sync-dev '!git merge main'

使用：

1 2	git sync-upstream # 同步上游到 main，然后回到原分支 git checkout dev && git sync-dev # 把 main 合并到 dev

最后更新: 2026-06-12

hello world