git fetch upstream 是同步前提，只安全下载元数据；直接 git pull upstream main 易失败，因本地未跟踪 upstream 分支，须先 fetch 再 merge 或 rebase。
git fetch upstream 是同步的前提，不是 git pull
直接 git pull upstream main 很容易失败，因为本地默认不跟踪 upstream 的分支。必须先用 git fetch upstream 把主仓库所有分支的最新提交、新分支、删除记录都拉到本地缓存 —— 这步不改你任何文件，纯下载元数据，安全。
常见错误现象：fatal: 'upstream' does not appear to be a git repository，说明没添加上游；fatal: couldn't find remote ref main，说明主仓库默认分支名是 master 或 develop，得查清楚再操作。
- 添加上游（仅首次需要）：
git remote add upstream https://github.com/owner/repo.git - 验证是否成功：
git remote -v应同时显示origin（你的 fork）和upstream（主仓库） - 定期执行：
git fetch upstream，推荐加--prune自动清理已删除的远程分支：git fetch upstream --prune
同步本地 main 分支时，merge 和 rebase 选哪个
如果你只是想让本地 main 跟上主仓库进度，且本地没有未推送的提交，git merge upstream/main 最直白；但如果你本地有自己提交过、又不想污染主仓库历史，git rebase upstream/main 更干净 —— 它会把你的提交“重放”在主仓库最新提交之后，线性清晰。
性能与风险：rebase 会改写本地提交 SHA，如果已推送到 origin，后续 git push 必须加 --force-with-lease，否则被拒绝；merge 则无此顾虑，但会多一个合并提交。
- 安全合并（推荐新手）：
git checkout main && git merge upstream/main - 线性历史（适合维护者）：
git checkout main && git rebase upstream/main - 避免覆盖本地修改：
git stash再操作，完事git stash pop
怎么把主仓库的新分支同步到本地并开始工作
主仓库新增了 feature/auth，你在本地 git branch -r 能看到 upstream/feature/auth，但 git branch 查不到它 —— 因为这只是远程引用，还没落地为本地分支。
不能直接 git checkout feature/auth，Git 会报错 “pathspec 'feature/auth' did not match any file(s)”。必须显式创建并关联：
- 一步到位：
git checkout -b feature/auth upstream/feature/auth - 或分两步：
git checkout --track upstream/feature/auth（自动命名本地分支同名） - 验证追踪关系：
git branch -vv应显示该分支指向upstream/feature/auth
注意：如果主仓库分支名含特殊字符（如 /），Windows 文件系统可能对本地分支名有限制，建议用短横线替代，例如 git checkout -b feature-auth upstream/feature/auth。
同步后 push 到自己的 fork，为什么有时被拒绝
最常见原因是：你本地 main 已通过 merge 或 rebase 改变了提交历史，而 origin/main 还停留在旧位置。此时 git push origin main 会被拒绝，提示 “non-fast-forward update”。
这不是错误，是 Git 在保护你 —— 强制推送前必须确认：这些变更确实是你主动重写的，且没有别人基于旧 main 开发。
- 若确定无协作影响：
git push --force-with-lease origin main（比--force更安全） - 若只是同步主仓库、无本地提交，用
git reset --hard upstream/main && git push --force-with-lease origin main - 别忽略
--force-with-lease：它会检查远程分支是否被他人更新，防止误覆盖
真正容易被忽略的是：同步不是单向“抄作业”，而是持续维护两个远程源（origin 和 upstream）之间的映射关系。一旦疏于 fetch upstream，后续所有基于它的操作都会滞后甚至失效。
