Git 操作手册
Git Fork项目同步与维护手册
一、仓库角色理解
假设：
上游仓库：
HKUDS/nanobot
你的 Fork：
leeyorke/nanobot
本地仓库：
~/workspace/nanobot
对应关系：
upstream
↓
HKUDS/nanobot
origin
↓
leeyorke/nanobot
local
↓
本地工作目录
查看远程：
git remote -v
理想结果：
origin git@github.com:leeyorke/nanobot.git
upstream git@github.com:HKUDS/nanobot.git
如果缺少 upstream：
git remote add upstream git@github.com:HKUDS/nanobot.git
二、日常检查命令
查看当前状态：
git status
查看分支：
git branch -vv
查看最近提交：
git log --oneline --decorate -10
查看远程：
git remote -v
三、同步 Upstream 最新代码
获取最新数据：
git fetch upstream
查看 Upstream 默认分支：
git remote show upstream
通常：
HEAD branch: main
四、推荐同步方式：Rebase
执行：
git rebase upstream/main
效果：
同步前：
A---B---C upstream
\
D---E local
同步后：
A---B---C---D'---E'
优点：
- 历史干净
- 没有多余 Merge Commit
- 便于后续 PR
五、发生冲突怎么办
例如：
git rebase upstream/main
出现：
CONFLICT (content)
查看状态：
git status
编辑冲突文件：
<<<<<<< HEAD
upstream内容
=======
我的内容
>>>>>>> commit
手动修改为最终版本。
添加到暂存区：
git add 文件名
继续：
git rebase --continue
重复直到完成。
六、放弃 Rebase
完全撤销：
git rebase --abort
恢复到 Rebase 之前。
七、查看与 Upstream 的差异
查看本地独有提交：
git log upstream/main..HEAD --oneline
查看 Upstream 独有提交：
git log HEAD..upstream/main --oneline
查看双方差异：
git log --left-right --graph --oneline HEAD...upstream/main
符号说明：
< 本地独有
> upstream独有
八、查看代码差异
查看所有变更：
git diff upstream/main..HEAD
仅查看文件：
git diff --name-status upstream/main..HEAD
输出：
M 修改
A 新增
D 删除
九、为什么 Rebase 后 Push 失败
错误：
non-fast-forward
原因：
Rebase 会重写 Commit Hash。
原来：
A---B---C
Rebase后：
A---X---Y---C'
虽然内容一样：
C ≠ C'
Hash已经改变。
Git认为历史不连续。
所以普通 Push 会失败：
git push origin main
报：
non-fast-forward
十、Force Push
普通 Push：
git push origin main
要求：
远程历史必须包含于本地历史
否则拒绝。
十一、Force Push 与 Force-With-Lease
危险方式：
git push --force origin main
作用：
无条件覆盖远程历史
风险：
可能删除别人提交。
推荐方式：
git push --force-with-lease origin main
作用：
覆盖远程历史
但先检查：
远程是否被别人改过
如果别人提交了新代码：
push被拒绝
更安全。
十二、Fork项目标准同步流程
每次同步上游：
git fetch upstream
git rebase upstream/main
git push --force-with-lease origin main
这是 Fork 项目最常见流程。
十三、查看 Fork 与 Upstream 差异
查看 Fork 落后多少：
git fetch origin
git fetch upstream
git log --left-right --graph --oneline origin/main...upstream/main
查看领先落后数量：
git rev-list --left-right --count origin/main...upstream/main
结果：
3 10
表示：
Fork领先3个commit
Fork落后10个commit
十四、SSH Push 失败排查
测试认证：
ssh -T git@github.com
成功：
Hi <username>!
You've successfully authenticated
测试端口：
nc -vz github.com 22
成功：
Connection succeeded
查看详细日志：
ssh -vT git@github.com
十五、重要原则
原则1： 不要在 Rebase 后执行 git pull，尤其出现 non-fast-forward 时，因为可能产生额外 Merge Commit。
原则2： 同步 Upstream 推荐 rebase，而非 merge。
原则3： 个人 Fork 仓库中 git push --force-with-lease 是正常操作。
原则4： 任何危险操作前先看 git status、git log --oneline --decorate -10、git branch -vv，先确认当前状态。