# Git 远程仓库操作

> 📚 Git 教程系列 - 第 6 篇  
> 📅 最后更新：2026-03-15  
> 🌐 适合人群：想学习 GitHub/Gitee 协作

---

## 🌍 远程仓库基础

### 什么是远程仓库？

**远程仓库**是托管在服务器上的 Git 仓库，用于团队协作和备份。

**常见平台：**
- **GitHub** - 全球最大代码托管平台
- **Gitee** - 中国本土代码托管平台
- **GitLab** - 可自建的代码托管平台

### 添加远程仓库

```bash
# 查看远程仓库
git remote -v

# 添加远程仓库
git remote add origin git@github.com:Deshill/my-project.git

# 添加多个远程仓库
git remote add gitee git@gitee.com:Deshill/my-project.git

# 重命名远程仓库
git remote rename origin upstream

# 删除远程仓库
git remote remove origin
```

---

## 📤 推送操作

### 基本推送

```bash
# 推送到远程
git push origin main

# 第一次推送（设置上游分支）
git push -u origin main

# 推送所有分支
git push --all origin

# 推送标签
git push --tags
```

### 强制推送（危险！）

```bash
# 强制推送（会覆盖远程历史）
git push -f origin main

# 安全的方式（使用 --force-with-lease）
git push --force-with-lease origin main
```

**⚠️ 警告：** 强制推送会覆盖远程历史，团队协作时慎用！

---

## 📥 拉取操作

### pull vs fetch

```bash
# git pull = git fetch + git merge
git pull origin main

# 只下载不合并
git fetch origin

# 查看远程分支
git branch -r

# 合并远程分支
git merge origin/main
```

### 拉取策略

```bash
# 默认：merge（创建合并提交）
git pull origin main

# 使用 rebase（保持线性历史）
git pull --rebase origin main

# 配置默认使用 rebase
git config --global pull.rebase true
```

---

## 🤝 GitHub 协作流程

### 1. Fork 项目

1. 在 GitHub 上打开项目页面
2. 点击右上角 **Fork** 按钮
3. 会创建你自己的副本

### 2. 克隆 Fork 的项目

```bash
# 克隆你的 Fork
git clone git@github.com:你的用户名/项目名.git
cd 项目名

# 添加原项目为上游
git remote add upstream git@github.com:原作者/项目名.git

# 查看远程仓库
git remote -v
# 输出：
# origin   git@github.com:你的用户名/项目名.git
# upstream git@github.com:原作者/项目名.git
```

### 3. 保持与上游同步

```bash
# 获取上游最新代码
git fetch upstream

# 合并到本地 main 分支
git checkout main
git merge upstream/main

# 推送到你的 Fork
git push origin main
```

### 4. 创建功能分支

```bash
# 创建新分支
git checkout -b feature/new-feature

# 开发和提交
git add .
git commit -m "feat: 添加新功能"

# 推送到你的 Fork
git push -u origin feature/new-feature
```

### 5. 创建 Pull Request

1. 在 GitHub 上打开你的 Fork 页面
2. 点击 **Compare & pull request**
3. 填写 PR 标题和描述
4. 选择合并到原项目的分支
5. 点击 **Create pull request**

### 6. Code Review

- 原作者会 review 你的代码
- 可能需要修改
- 修改后继续推送到同一分支
- PR 会自动更新

---

## 🌟 Gitee 协作流程

### 与 GitHub 类似

```bash
# 克隆 Gitee 仓库
git clone git@gitee.com:你的用户名/项目名.git

# 添加 SSH 密钥到 Gitee
# 访问：https://gitee.com/profile/sshkeys

# 创建 PR（在 Gitee 叫 Pull Request）
# 流程与 GitHub 相同
```

### Gitee 特有功能

```bash
# Gitee 支持私有仓库免费
# 适合国内团队使用

# 企业版支持：
# - 代码审核
# - 项目管理
# - CI/CD
```

---

## 🔧 远程仓库高级操作

### 多远程仓库同步

```bash
# 添加多个远程
git remote add github git@github.com:Deshill/project.git
git remote add gitee git@gitee.com:Deshill/project.git

# 推送到两个远程
git push github main
git push gitee main

# 或创建别名
git remote set-url --add --push origin git@github.com:Deshill/project.git
git remote set-url --add --push origin git@gitee.com:Deshill/project.git

# 一次推送到所有
git push origin main
```

### 跟踪远程分支

```bash
# 创建跟踪远程分支的本地分支
git checkout -b feature origin/feature

# 设置上游分支
git branch --set-upstream-to=origin/main main

# 简写
git branch -u origin/main main

# 查看上游分支
git branch -vv
```

### 清理远程分支

```bash
# 查看远程已删除的分支
git fetch -p

# 清理本地已合并的分支
git branch --merged main | grep -v "main" | xargs git branch -d

# 删除远程已合并的分支（谨慎！）
git branch -r --merged main | grep -v "main" | xargs -n 1 git push --delete origin
```

---

## 📊 查看远程信息

### 远程仓库详情

```bash
# 查看远程仓库信息
git remote show origin

# 输出示例：
# * remote origin
#   Fetch URL: git@github.com:Deshill/project.git
#   Push  URL: git@github.com:Deshill/project.git
#   HEAD branch: main
#   Remote branches:
#     main    tracked
#     develop tracked
#   Local branch configured for 'git pull':
#     main merges with remote main
```

### 分支对比

```bash
# 查看本地与远程的差异
git log main..origin/main

# 查看远程有但本地没有的提交
git log origin/main..main

# 查看哪些分支落后于远程
git branch -vv
```

---

## 🛠️ 常见问题解决

### 问题 1：推送被拒绝

```bash
# 原因：远程有本地没有的提交
# 解决：先拉取再推送

git pull --rebase origin main
git push origin main

# 或强制推送（危险！）
git push -f origin main
```

### 问题 2：权限错误

```bash
# GitHub
# 错误：Permission denied (publickey)
# 解决：重新配置 SSH 密钥

ssh-keygen -t ed25519 -C "your-email@example.com"
cat ~/.ssh/id_ed25519.pub
# 添加到 GitHub: Settings → SSH and GPG keys

# 测试连接
ssh -T git@github.com
```

### 问题 3：SSL 证书验证失败

```bash
# GitHub
# 错误：SSL certificate problem
# 解决：更新 CA 证书

git config --global http.sslVerify true
git config --global http.sslCAInfo "C:/Program Files/Git/mingw64/ssl/certs/ca-bundle.crt"

# 或禁用 SSL 验证（不推荐）
git config --global http.sslVerify false
```

### 问题 4：大文件推送失败

```bash
# 错误：File is too big
# 解决：使用 Git LFS

# 安装 Git LFS
git lfs install

# 跟踪大文件
git lfs track "*.psd"
git lfs track "*.zip"

# 提交 .gitattributes
git add .gitattributes
git commit -m "Configure Git LFS"

# 正常提交大文件
git add large-file.psd
git commit -m "Add large file"
git push origin main
```

---

## 🎯 最佳实践

### 提交前检查清单

- [ ] 代码已通过本地测试
- [ ] 提交信息清晰明确
- [ ] 没有敏感信息（密码、密钥）
- [ ] 没有大文件（使用 LFS）
- [ ] 已拉取最新代码（避免冲突）

### PR/MR 规范

**标题：**
```
feat: 添加用户登录功能
fix: 修复登录接口 500 错误
```

**描述：**
```markdown
## 变更说明
- 添加用户登录接口
- 添加 JWT 认证

## 测试
- [ ] 单元测试通过
- [ ] 手动测试通过

## 截图
（如果有 UI 变更）
```

### 分支保护

**在 GitHub/Gitee 设置：**
1. Settings → Branches
2. Add branch protection rule
3. 分支模式：`main`
4. 选项：
   - Require pull request reviews
   - Require status checks to pass
   - Require branches to be up to date

---

## 📚 扩展阅读

- [GitHub 文档](https://docs.github.com/zh)
- [Gitee 文档](https://gitee.com/help)
- [Git LFS](https://git-lfs.github.com/)

---

## 🎯 小结

| 操作 | 命令 |
|------|------|
| 添加远程 | `git remote add origin url` |
| 查看远程 | `git remote -v` |
| 推送 | `git push origin main` |
| 拉取 | `git pull origin main` |
| 获取 | `git fetch origin` |
| 跟踪分支 | `git branch -u origin/main` |
| Fork 流程 | Clone → Add upstream → Fetch → Merge |
| PR 流程 | Branch → Commit → Push → Create PR |

---

> 💡 **下一步**：继续学习 [07-版本回退与恢复](./07-版本回退与恢复.md)