Git 远程协作：抓取、追踪与双远端

" 在分布式版本控制系统中，' 远程 ' 只是另一个人的 ' 本地 '。所谓的同步，本质上是两个数据库之间的对齐。"

1. 建立连接：远程仓库的本质#

远程通常使用没有工作区的裸仓库，也可以指向其他本地或服务端仓库；“remote” 首先是配置的地址与 refspec。在开始同步之前，你需要建立本地与远程的 " 契约 "。

基础连接命令 (通用)

无论你选择哪种协议，以下操作是通用的：

# 1. 关联远程仓库 (通常命名为 origin)
git remote add origin <URL>

# 2. 查看已关联的远程及其 URL
git remote -v

# 3. 首次推送并建立追踪关系 (-u / --set-upstream)
git push -u origin master

# 4. 修改远程仓库地址 (例如从 HTTPS 切换到 SSH)
git remote set-url origin git@example.com:team/project.git

2. GitHub 的三种通行证：配置与平台差异#

A. HTTPS：简单但需凭据管理

地址格式：https://example.com/team/project.git
机制：可用 PAT 或凭据助手管理的 OAuth 等凭据；不要将令牌放进远程 URL 或公开配置。
各平台预配置：
- Windows: 安装 Git for Windows 后自带 Git Credential Manager，会自动处理 OAuth 弹出窗。
- Arch Linux: 使用实际的 Git credential helper 并配置其安全存储后端；git-delta 是差异显示工具，不负责凭据存储。
- NixOS: programs.git.enable = true; 可启用 Git，但不会自动完成 HTTPS 凭据存储；凭据助手需另行配置。

B. SSH：职业开发者的非对称加密 (推荐)

地址格式：git@example.com:team/project.git
机制：用 Ed25519 或 RSA 公私钥认证；可为私钥设置口令并使用 agent，免输账户密码不等于私钥无口令。
各平台预配置与密钥生成：
- 通用生成命令：
  EXCERPT
```
ssh-keygen -t ed25519 -C "user@example.com"
# 生成后将 ~/.ssh/id_ed25519.pub 内容贴到 GitHub Settings -> SSH Keys
```
- Windows: 使用 Git Bash 运行上述命令。密钥存放在 %USERPROFILE%\.ssh\。
- Arch Linux: 安装 openssh。sudo pacman -S openssh
- NixOS: SSH 客户端用于连接 Git 服务器；无需为出站 Git 访问开启 services.openssh.enable，该选项启动本机 SSH 服务端。客户端及 agent 按需要配置。

C. GitHub CLI (gh)：现代化的一键式体验

工具：集成了 Git 操作与 GitHub 管理功能的官方命令行工具。
各平台安装步骤：
- Windows: winget install --id GitHub.cli 或 scoop install gh。
- Arch Linux: sudo pacman -S github-cli。
- NixOS: environment.systemPackages = [ pkgs.github-cli ];。
核心操作：

gh auth login  # 按交互选项授权；Git 凭据配置取决于选择，也可检查 gh auth setup-git
gh repo clone user/repo  # 一键克隆
gh repo set-default user/repo # 关联当前目录到 GitHub
    ```

## 3. 同步三剑客：Fetch, Pull, Push

| 命令 | 行为 | 哲学 |
| :--- | :--- | :--- |
| **`git fetch`** | 下载远程对象和指针 | **只看不拿**：了解进展，不改动本地代码。 |
| **`git pull`** | `fetch` + 按参数/配置合并或变基 | **同步更新**：直接把别人的改动合入当前分支。 |
| **`git push`** | 上传本地 Commit | **发布成果**：将你的快照同步到远程数据库。 |

> 现代推荐写法
> 若只接受快进，使用 `git pull --ff-only`；需要重放未共享的本地提交时，可按团队策略使用 `git pull --rebase`。它会改写本地提交，可能逐次产生冲突，不是所有分支的默认答案。

## 4. 追踪分支与 Upstream

当你看到 "Your branch is ahead of 'origin/master'" 时，Git 正在对比。
- **Upstream (上游)**：本地分支对应的远程 " 锚点 "。
- **手动关联**：`git branch --set-upstream-to=origin/master`。
- **意义**：关联后，只需输入 `git pull`，无需再写长串的远程名。

### 远端默认分支的符号引用

用 `git branch -r` 查看远端跟踪分支时，可能看到 `fork/HEAD -> fork/main`。这里 `fork` 是远端别名，`fork/HEAD` 是指向默认分支的符号引用，不是额外的开发分支，统计分支数时不能把它算进去。可分别检查本地分支的追踪关系和这个符号引用：

```powershell
git branch -vv
git branch -r
git symbolic-ref refs/remotes/fork/HEAD

若本地尚未建立 fork/HEAD，最后一个命令会报错；这不代表 fork/main 不存在。远端默认分支变化后，可用 git remote set-head fork -a 查询远端并更新本地默认分支引用。详见 git remote 官方文档。

5. 协同工作流：PR / MR 模式#

Fork：在网页端克隆别人仓库到自己账号。
Clone：git clone 到本地。
Develop：新建分支开发。
Push：推送到自己的远程。
Pull Request (PR)：在网页端请求原作者合并你的改动。

5.1 双远端实例：origin 指原仓库，fork 指个人仓库

origin、fork、upstream 都只是本地别名，没有 Git 层面的特殊权限；实际读取和推送的仓库由 URL 决定，权限由服务器控制。GitHub 贡献工作流采用 upstream 指原仓库、origin 指个人 fork 的命名；下面展示另一种同样有效的配置，执行命令前应先确认自己使用哪一种。

以虚构的 project 为例；以下 example.com 地址不能直接连接真实仓库，目标配置为：

origin  https://example.com/upstream/project.git
fork    https://example.com/contributor/project.git

先查看现状；只在对应名称尚不存在时添加远端：

git remote -v
git remote add origin https://example.com/upstream/project.git
git remote add fork https://example.com/contributor/project.git

如果克隆后 origin 已指向个人 fork，且尚无名为 fork 的远端，则改用以下配置步骤：

git remote rename origin fork
git remote add origin https://example.com/upstream/project.git
git remote -v

开发分支推送到个人 fork，并建立追踪关系：

# 将占位符替换为实际分支名
git push -u fork <branch>
git branch -vv

5.2 分清三种同步：引用、本地 main 与 fork main

刷新所有远端的跟踪引用：

git fetch --all --prune

在通常的 fetch 配置下，这会更新 origin/*、fork/*，并清理远端已删除分支的陈旧跟踪引用，不会把本地开发分支覆盖为远端内容。抓取范围仍受各远端 refspec 和跳过配置影响；窄范围克隆并不会自动变成全分支抓取。git fetch 官方文档说明了 --all、--prune 与 refspec 的作用。

同步本地 main 到原仓库，先检查工作区，再仅允许快进更新：

git status --short
git switch main
git pull --ff-only origin main

若有未提交改动，先保存并妥善处理后再切换；若双方已经分叉，--ff-only 会拒绝更新，应检查独有提交后决定如何保留。

同步个人 fork 的 main，可以直接把刚抓取的 origin/main 推到远端 main：

git fetch origin --prune
git push fork origin/main:main

origin/main:main 表示 " 以本地的原仓库跟踪引用为来源，更新 fork 的 main"。这一步不要求本地 main 已同步，也不会更新 fork 的其他开发分支。fork 的 main 存在分叉或分支保护限制时，普通推送会拒绝；不要改用强推来掩盖分叉。

因此，日常同时更新引用、本地 main 和 fork main 的完整顺序是：

git status --short
git fetch --all --prune
git switch main
git pull --ff-only origin main
git push fork origin/main:main

逐条检查结果，前一步失败时先处理原因。这里的 " 全量同步 " 不意味着把所有开发分支强行改成原仓库 main；尚未合并的投稿提交应保留。

5.3 同步与比较单个 fork 分支

已有本地分支时，从 fork 快进更新：

git switch fix/review-feedback
git pull --ff-only fork fix/review-feedback

本地还没有该分支时，先抓取，再创建同名追踪分支：

git fetch fork
git switch --track -c fix/review-feedback fork/fix/review-feedback

比较 fork 分支与原仓库 main 前，明确抓取两个远端：

git fetch --multiple --prune origin fork
git rev-list --left-right --count origin/main...fork/fix/review-feedback
git log --left-right --cherry-pick --oneline origin/main...fork/fix/review-feedback

不能写成 git fetch origin fork --prune：单远端语法会将 fork 解释为从 origin 抓取的 refspec，而不是第二个远端；多个远端需使用 --multiple，也可分别执行两次 fetch。

rev-list 输出左侧数字为仅 origin/main 拥有的提交数，右侧为仅 fork 分支拥有的提交数。log 用 <、> 区分两侧提交，并通过 --cherry-pick 排除双方补丁等价的提交，因此其行数不一定与前面的计数相同。

5.4 开发分支数不等于待合并 PR 数

示例分支	示例状态
`fix/bug-a`	有一条开放 PR
`fix/review-feedback`	有另一条开放 PR
`feature/previous-contribution`	PR 已合并，但分支仍保留

这三个开发分支只对应两条开放 PR；已合并分支仍可能留在 fork，fork/HEAD 不应计为第四个开发分支。清理前应核对当前 PR 状态、合并方式及是否保留独有提交，不能只按分支数量删除。

6. 常见痛点与最佳实践：优雅地解决冲突#

场景：多人修改了同一远程分支导致 Push 失败

以下适合尚未共享的本地提交；已共享历史按团队策略使用 merge 或其他协调方式：

git commit (保存本地改动)。
git fetch origin (获取远程最新快照)。
git rebase origin/master (在远程基础上重排本地提交)。
检查变基结果与测试，再 git push；远端继续更新或保护规则仍可能拒绝。

深度解析：为什么 git push -f 会导致灾难？

当你执行 git push -f 时，你实际上是在告诉服务器："别管别人提交了什么，直接把远程分支强行覆盖成我现在的状态。"

场景模拟：

共同起点：你和同事 A 都有 Commit 1 -> Commit 2。
同事 A 提交：他开发了功能并 Push，远程现在是 1 -> 2 -> 3。
你重写历史：你在本地觉得 Commit 2 写得不好，用了 rebase 或 amend 修改了它，本地变成了 1 -> 2'(新哈希)。
你执行 Push -f：服务器被你强行改成了 1 -> 2'。同事 A 的 Commit 3 在远程消失了！
灾难发生：当同事 A 再次同步时，本地与远端历史可能分叉，需要按改写后的历史重新协调。因为它发现：
- 本地的 Commit 3 是基于旧的 Commit 2 的。
- 但远程已经变成了 2'。
- 这会导致极其复杂的冲突，如果他处理不当（比如直接合并），就会把已经被你删掉的旧代码又带回来，甚至导致整个项目的历史拓扑变成一团乱麻。

公共分支的历史改写必须事先协调，并检查服务器保护规则；普通同步失败不能用强推掩盖。

安全方案：--force-with-lease

如果你非要强制推送（比如在自己的独立 feature 分支上），请使用： git push --force-with-lease 机制：它要求远端引用匹配预期值。无显式期望值时通常依赖本地远端跟踪引用；后台 fetch 可能刷新该引用，削弱保护。需要严格限定时，先记录并核对允许替换的 tip，再显式指定远端分支与期望提交：

# 仅在已协调历史改写且确认目标分支允许时；两个占位符需实际核对
git push --force-with-lease=refs/heads/feature/example:<expected-tip> origin HEAD:refs/heads/feature/example

lease 不能判断被覆盖的提交是否有价值，也不能自动恢复误删数据。

7. 权限管理：谁能推送代码？#

分布式历史本身不赋予远端写权限。服务器可通过 SSH/HTTP 认证、文件系统权限、接收钩子及托管平台规则控制读取与推送；不是只有托管平台才有权限控制。

A. 仓库访问级别 (以 GitHub 为例)

Public (公开)：任何人都能读（Clone/Fetch），但只有 " 协作者 " 能写（Push）。
Private (私有)：可由个人、组织团队、应用或部署凭据等授予访问，读与写权限分别控制。
协作角色：
- Read (只读)：可读取并参与相应讨论，通常不能推送代码。
- Write (写权限)：可以直接 Push 代码到非保护分支。
- Maintain/Admin：维护与管理员权限不同；删除仓库等敏感设置通常受管理员权限控制，按平台角色核实。

B. 分支保护规则 (Protected Branches)

在专业团队中，即便你有 " 写权限 "，也不代表你可以乱来。

限制直接推送：通常会锁定 main 或 master 分支，禁止任何人直接 push。
强制 Pull Request：所有代码必须通过分支开发 -> 提起 PR -> 按规则要求的 Review 与自动化检查通过后，由有相应合并权限的人合并。
限制强制推送：默认禁止在保护分支上使用 push -f。

哲学思考权限管理的最高境界不是 " 防小人 "，而是 " 防误操作 "。好的规则能让团队成员在不破坏主干代码的前提下，自由地在功能分支上进行实验。

参考与延伸

根据技术笔记重新整理，示例使用通用名称。