未记录事实核验 · 状态：维护中

记录仅说明核验时间与维护状态，不保证适用于所有环境；使用前请留意正文中的版本、适用条件与风险提示。

warning 适用范围与待维护事项

本文适用于已掌握提交、分支及SSH或HTTPS认证的读者，在有授权的测试仓库练习远程协作；示例地址、表名和性能检查项仅为教学模板，不代表已完成测试。共享分支须遵守团队合并策略，rebase仅用于可安全改写的本地提交。平台规模、访问速度及分支保护界面未在本轮核验，设置路径与选项须以实际账号、权限和部署版本为准。若误推凭据，revert不能清除历史泄露，须立即吊销或轮换并按团队流程处理。

warning 关联材料边界

以下原引用目标缺失或无法唯一确认，已取消跳转并保留提及：数据开发规范。相关素材/延伸说明暂不可用，不能据此声称已经提供配套材料。

远程仓库协作 - Push/Pull 与 Pull Request 工作流

abstract 本章概要

理解本地仓库与远程仓库的关系
掌握 remote/push/pull/fetch 命令
完整的 Pull Request / Merge Request 工作流
代码审查的最佳实践

远程仓库的作用

Git 是分布式的，但团队协作还是需要一个中心点来同步代码。这个中心点就是远程仓库（Remote Repository）。

小李的电脑                   远程仓库                  小张的电脑
  ●──●──●──●  ───push──►   ●──●──●──●  ◄──clone──  ●──●──●──●
              ◄──pull───                ───push──►

远程仓库通常托管在：

GitHub：代码托管平台，可用于开源项目协作
GitLab：代码托管与协作平台，支持私有化部署
Gitee（码云）：国内代码托管平台，实际访问速度取决于网络环境
公司内部 GitLab：组织自行部署的 GitLab 实例

管理远程仓库：git remote

# 查看已配置的远程仓库
git remote
# 输出：origin

# 查看远程仓库详细信息（地址）
git remote -v
# 输出：
# origin  git@github.com:your-org/data-warehouse.git (fetch)
# origin  git@github.com:your-org/data-warehouse.git (push)

# 添加远程仓库
git remote add origin git@github.com:your-org/data-warehouse.git

# 修改远程仓库地址（如从 HTTPS 改为 SSH）
git remote set-url origin git@github.com:your-org/data-warehouse.git

# 删除远程仓库配置
git remote remove upstream

# 添加第二个远程仓库（如 fork 工作流中添加上游）
git remote add upstream git@github.com:original-org/data-warehouse.git

note origin 是什么？

origin 只是一个别名，约定俗成地用来指向"你 clone 的那个远程仓库"。你可以改成任何名字，但 origin 是所有人都懂的默认名称，建议保留。

推送代码：git push

# 推送当前分支到远程（第一次要加 -u 建立追踪关系）
git push -u origin feature/vip-discount

# 之后就可以直接
git push

# 推送到指定远程分支
git push origin local-branch:remote-branch

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

# 推送 tag
git push origin v1.0.0
git push origin --tags    # 推送所有 tag

第一次推送用 -u

-u 是 --set-upstream 的缩写，建立本地分支和远程分支的追踪关系。建立后，以后在这个分支上只需要 git push 就行了，不需要指定远程和分支名。

# 第一次
git push -u origin feature/vip-discount

# 之后
git push   # Git 知道要推到哪里
git pull   # Git 知道要从哪里拉

拉取代码：fetch vs pull

这是很多人混淆的地方，需要说清楚。

git fetch：只下载，不合并

# 按该远程的 fetch 引用配置获取更新（不改本地工作区）
git fetch origin

# 下载某个分支
git fetch origin main

# 之后可以对比看看远程有什么新内容
git log HEAD..origin/main --oneline
git diff HEAD origin/main

fetch 后，origin/main 代表远程 main 的最新状态，你本地的 main 还没变，你可以仔细看看远程的变化再决定要不要合并。

git pull：下载 + 整合（merge 或 rebase）

# 拉取并合并（显式选择 merge；仅允许快进的配置仍可能拒绝分叉历史）
git pull --no-rebase

# 拉取并用 rebase 合并（更干净，推荐）
git pull --rebase

# 从指定远程分支拉取
git pull origin main

tip 推荐用 pull --rebase

git pull --rebase 会在获取远程提交后，将需重放的本地提交接到更新后的上游历史上，并改写这些提交的标识；仅在这些提交尚未共享、且团队允许时使用，遇到冲突需解决后继续，或用 git rebase --abort 中止。 git config --global pull.rebase true 将 rebase 设为全局拉取策略，但仓库级、分支级配置及命令行参数可能覆盖它；设置前确认团队约定。

普通 pull（merge）：
  ●──●──●──●──M  ← M 是 merge commit
         └──●──●

rebase pull：
  ●──●──●──●──●──●  ← 线性历史，干净
  （远程的新提交在前，本地的新提交接在后面）

什么时候用 fetch vs pull

场景                          推荐操作
─────────────────────────────────────────
想看看远程有什么变化再决定    fetch → 对比 → 手动 merge/rebase
同步且本地提交可安全改写     pull --rebase
不确定远程改了什么，谨慎点   fetch → git diff HEAD origin/main

完整的 Pull Request 工作流

Pull Request（GitHub 叫法）或 Merge Request（GitLab 叫法）是现代团队协作的核心流程。它不只是"请求合并代码"，更是代码审查和知识共享的重要环节。

完整流程

1. 从主分支创建功能分支
        ↓
2. 在功能分支上开发
        ↓
3. 推送功能分支到远程
        ↓
4. 在 GitHub/GitLab 创建 PR/MR
        ↓
5. 等待代码审查（Code Review）
        ↓
6. 根据反馈修改代码
        ↓
7. 审查通过，合并到主分支
        ↓
8. 删除功能分支

第一步：创建功能分支

# 确保 main/develop 是最新的
git switch main
git pull origin main

# 创建并切换到新分支
git switch -c feature/add-weekly-gmv-metric

第二步：开发并提交

# 开发过程中频繁提交
git add sql/metrics/gmv_weekly.sql
git commit -m "feat: 新增周GMV指标定义"

git add sql/dws/dws_trade_user_weekly.sql
git commit -m "feat: 新增用户周度交易汇总表"

git add docs/metrics/gmv_weekly.md
git commit -m "docs: 补充周GMV指标文档"

第三步：推送并创建 PR

# 推送功能分支到远程
git push -u origin feature/add-weekly-gmv-metric

然后打开 GitHub，通常会看到一个提示："Recent pushes，Compare & pull request"，点击它创建 PR。

写好 PR 描述（这和写好 commit message 一样重要）：

## 变更内容

新增用户周度 GMV 指标，支持按用户维度、商品类目下钻分析。

## 为什么要做这个变更

业务方需要在周报中展示用户 GMV 趋势，现有日 GMV 需要手动加总，
效率低且容易出错。

## 主要改动

- 新增 `dws_trade_user_weekly` 汇总表（每周 T+1 跑批）
- 新增 `ads_gmv_weekly` 指标表
- 更新数据字典文档

## 测试情况

- [ ] 在测试环境跑通，结果与手动加总日 GMV 吻合
- [ ] 边界值（空用户、0金额）测试通过
- [ ] 性能测试：10亿行数据下执行时间 < 30分钟

## 注意事项

依赖 `dwd_trade_order_detail` 表，需要确认 DWD 层上线后再发版。

第四步：代码审查

审查者（Reviewer）会：

阅读你的代码变更
在具体行上添加评论
提出问题或改进建议
最终 Approve（通过）或 Request Changes（要求修改）

作为被审查者，收到反馈后：

# 在同一个分支上修改并提交
git add sql/metrics/gmv_weekly.sql
git commit -m "fix: 根据 review 意见修复 NULL 值处理"

# 推送更新，PR 会自动更新
git push

作为审查者，代码审查关注点：

逻辑是否正确（最重要）
SQL/代码是否符合团队规范（见数据开发规范（原引用“数据开发规范”未能确定有效目标，暂不可跳转））
是否有明显的性能问题
命名是否清晰
是否有必要的注释

tip 代码审查心态

代码审查不是批评，是协作。作为审查者，提意见时多用"建议"和"问题"而不是"你错了"。作为被审查者，把每次审查都当作学习机会。

好的评论：

"这里的过滤应在聚合前还是聚合后执行？建议先确认 WHERE 与 HAVING 的语义，再结合执行计划和实测评估性能。"
"这个 NULL 处理逻辑，如果用户没有下单记录会怎样？"

不好的评论：

"这段代码写得不对"
"改掉"

第五步：合并 PR

审查通过后，在 GitHub/GitLab 上点击 "Merge Pull Request" 按钮。

按团队策略选择 Squash and merge、Rebase and merge 或普通 Merge：前两者便于形成线性历史，普通 Merge 可保留分支合并关系；可选方式取决于平台及仓库配置。

合并后：

# 本地切回 main，拉取最新代码
git switch main
git pull origin main

# 删除已合并的本地分支；Squash/Rebase 合并后，-d 可能无法识别其已合并
git branch -d feature/add-weekly-gmv-metric
# 若被拒绝，先核对 PR 已合并、改动已保留且没有未保留的本地提交，再决定是否用 -D 删除

上游同步（Fork 工作流）

如果你 fork 了别人的仓库，需要定期同步上游的变更：

# 添加上游仓库
git remote add upstream git@github.com:original/data-warehouse.git

# 拉取上游变更
git fetch upstream

# 把上游 main 的内容合并到你的 main
git switch main
git merge upstream/main

# 推送到你的 fork
git push origin main

常见场景处理

场景：push 被拒绝

$ git push
# 报错：! [rejected] main -> main (non-fast-forward)
# hint: Updates were rejected because the remote contains work that you do
# hint: not have locally.

原因：远程有你本地没有的提交（别人 push 了）。

解决：

# 方式一：rebase 方式（推荐，历史更干净）
git pull --rebase
git push

# 方式二：显式选择 merge；若配置仅允许快进且历史已分叉，需按团队策略处理
git pull --no-rebase
git push

场景：误 push 了不该 push 的东西

# 仅当误推内容位于最新的普通提交时，创建撤销提交（不删除历史）
git revert HEAD
git push
# 若涉及密码、令牌等敏感信息，立即吊销或轮换，并按团队流程清理历史；revert 不能消除泄露

warning 不要用 `git push --force` 到共享分支

push --force 会覆盖远程历史，让其他人的本地仓库和远程产生冲突。只有在明确知道后果且团队知晓的情况下才能用。个人分支上用 --force-with-lease（更安全的版本）可以接受，main/develop 等共享分支绝对不允许。

场景：需要查看某个远程分支的代码

# 创建并切换到远程分支的本地追踪分支
git checkout -b feature/colleague-branch origin/feature/colleague-branch
# 或
git switch --track origin/feature/colleague-branch

保护分支配置（GitHub/GitLab）

在 GitHub/GitLab 上为 main 分支配置保护规则，防止直接 push：

GitHub 设置路径：Settings → Branches → Add branch protection rule

推荐设置：

Require pull request reviews before merging（合并前需要审查）
Require status checks to pass before merging（需要 CI 通过）
Do not allow bypassing the above settings（管理员也不能绕过）

小结

操作	命令
查看远程仓库	`git remote -v`
添加远程仓库	`git remote add origin <url>`
推送（首次）	`git push -u origin <branch>`
推送（后续）	`git push`
拉取（rebase）	`git pull --rebase`
只下载不合并	`git fetch origin`
查看远程分支	`git branch -r`

info 前置知识

分支管理 - 远程协作的核心就是分支推送和 PR，需要先理解分支的概念
Git安装与配置 - SSH 密钥配置好，才能无密码 push 到远程

掌握检查

[ ] 能说出 fetch 和 pull 的区别：fetch 获取远程更新但不整合到当前分支，pull 获取后按参数和配置执行 merge 或 rebase；仅允许快进时，历史分叉会导致操作拒绝
[ ] 知道 git push -u origin feature/xxx 中 -u 的含义：建立本地分支和远程分支的追踪关系
[ ] 遇到 push rejected (non-fast-forward) 报错时，知道先检查远程差异，再按团队策略用 merge 或对未共享的本地提交执行 rebase，解决冲突后 push，而不是直接强推
[ ] 理解 Pull Request 的工作流：本地分支 → push → 创建 PR → Review → 合并到 main
[ ] 知道为什么 git push --force 到共享分支是危险操作，以及 --force-with-lease 是更安全的替代

实践练习

基础题：在 GitHub 上创建一个新仓库，把本地已有的项目目录推送上去（git remote add origin + git push -u origin main），验证在 GitHub 页面能看到你的提交历史。

进阶题：Fork 一个 GitHub 上的开源仓库，创建一个本地特性分支，做一个小改动并提交，push 到你的 fork，然后在 GitHub 上向原仓库创建 Pull Request（PR 描述清楚改动原因）。

下一步：冲突解决 - 学习如何处理合并冲突，这是多人协作中不可避免的技能。

上一步：分支管理 | 返回：Git学习路线图