02-Git与GitHub审查

你将完成什么

本页把一次 Git/GitHub 协作拆成可检查的步骤：确认位置，查看状态和差异，建立分支，提交小改动，创建 PR，处理 review 评论，解决冲突，最后按权限和回滚规则交付。读完后，你应该能够：

分清工作区、暂存区和 HEAD 的差异；
使用 status、diff、branch、commit 完成一次任务；
使用 gh 创建、查看、检查和评论 PR；
让每条审查意见都有修改、验证、回复和复查；
处理 merge/rebase 冲突并在必要时中止；
区分 restore、revert 和发布系统回滚；
守住 push、force-push、主干 merge、权限和生产操作红线。

示例使用 macOS、Linux 和 Git Bash。Windows PowerShell 的路径和环境变量写法以本机为准；Git 或 gh 版本有差异时，先运行 git --help、gh --help 和对应子命令帮助。

01 先建立边界

Git 动作的影响范围不同。读状态通常只读，commit 改变本地历史，push 改变远端分支，merge、权限变更和发布会影响团队或用户。

动作	影响	默认策略
`status`、`diff`、`log`	本地只读	可直接执行
`add`、`commit`	本地索引和历史	看完 staged diff 再执行
`fetch`	本地远程跟踪引用	可执行，不改工作文件
`push`	远端分支	核对远端和分支后执行
创建 PR、请求 review	协作记录	核对 base/head 和内容
merge、删除分支	共享历史	有负责人明确放行
`push --force`	改写远端历史	默认禁止
生产、权限、密钥操作	外部系统	使用专门审批和回滚

进入项目先回答：当前目录是否正确？当前分支是否正确？是否有别人的未提交改动？本次命令是否会写远端或影响外部系统？建议在项目 AGENTS.md 或贡献指南中写入测试命令、分支命名、commit 格式、PR 要求和禁止自动 push/merge/force-push 的规则。持久规则写文件，一次性范围写当前任务。

02 `status`：先确认你在哪里

pwd
git rev-parse --show-toplevel
git remote -v
git branch --show-current
git status --short --branch

预期输出：

/work/acme-shop
/work/acme-shop
origin  git@github.com:acme/shop.git (fetch)
origin  git@github.com:acme/shop.git (push)
feat/cart-total
## feat/cart-total...origin/feat/cart-total [ahead 1]
 M src/cart/total.ts
?? tests/cart/total.test.ts

rev-parse 确认仓库根目录；remote -v 确认真实远端；branch --show-current 确认分支；ahead 1 表示本地比远程跟踪分支多一个提交。 status --short 的两个字符分别表示暂存区和工作区：

标记	含义
`M file`	只改了工作区
`M file`	已暂存
`MM file`	暂存后又继续修改
`A file`	新文件已暂存
`?? file`	未跟踪文件
`D file`	文件被删除
`R old -> new`	被识别为重命名

不认识的改动先记录和确认归属。不要为得到“干净状态”直接运行 git restore .、git clean -fd 或覆盖式复制，它们可能删除未提交工作。任务开始时建议记录：

仓库：/work/acme-shop
分支：feat/cart-total
基线：origin/main
允许修改：src/cart、tests/cart
禁止动作：push、merge、删除文件

03 `diff`：看清提交会包含什么

git diff 是工作区相对暂存区，git diff --cached 是暂存区相对 HEAD，git diff HEAD 包含暂存和未暂存改动。

git diff
git diff --cached
git diff HEAD
git diff --stat
git diff --name-only
git diff --check
git diff -- src/cart/total.ts tests/cart/

预期摘要：

 src/cart/total.ts        | 5 ++++-
 tests/cart/total.test.ts | 18 ++++++++++++++++++
 2 files changed, 22 insertions(+), 1 deletion(-)

预期补丁：

-  return items.reduce((sum, item) => sum + item.price, 0);
+  return items.reduce((sum, item) => {
+    if (item.quantity <= 0) return sum;
+    return sum + item.price * item.quantity;
+  }, 0);

读 diff 的顺序是：文件范围、无关格式化、逻辑是否对应需求、异常和边界、权限和数据泄露、测试是否覆盖。git diff --check 无输出通常表示没有空白错误，但它不能证明逻辑正确。发现 trailing whitespace、冲突标记或密钥时先停止。任务范围清楚时按路径暂存：

git add src/cart/total.ts tests/cart/total.test.ts
git status --short
git diff --cached --stat
git diff --cached --check
git diff --cached

混杂文件只暂存部分 hunk：

git add -p src/cart/total.ts

不要把 git add . 当默认提交策略。它可能带入 .env、生成物、调试输出和别的任务。

04 分支：一个任务一条边界

先更新远端引用，再从最新主干创建分支：

git fetch --prune origin
git switch main
git pull --ff-only origin main
git switch -c feat/cart-total

预期：

From github.com:acme/shop
   0b4c2de..7f91a20  main -> origin/main
Switched to a new branch 'feat/cart-total'

也可以直接从远程引用创建：

git fetch origin
git switch -c feat/cart-total origin/main

推荐命名：

feat/SHOP-142-cart-total
fix/API-88-timeout
refactor/auth-token-parser
chore/update-eslint

检查分支：

git branch --show-current
git status --short --branch
git log --oneline --decorate --graph --all -12
git merge-base --is-ancestor origin/main HEAD && echo "based on origin/main"

预期：

feat/cart-total
based on origin/main

不要让两个任务共享一条功能分支。并行开发使用独立 worktree；同一分支同一时间只能在一棵 worktree 中检出。用 git worktree list --porcelain 查看占用关系，不要修改 .git/worktrees 绕过保护。

05 Commit：保存可解释的工作单元

一个 commit 应有单一目的、有限范围、可复现验证和清晰消息。提交前：

git status --short --branch
git diff --cached --stat
git diff --cached --check
git diff --cached --name-only
pnpm test --filter cart
pnpm typecheck

测试命令以项目已有脚本为准，不要猜命令。失败时保留完整输出，先修复再重新查看 diff。提交并检查：

git commit -m "fix: calculate cart total by quantity"
git show --stat --oneline --decorate HEAD
git status --short --branch

预期：

[feat/cart-total 3c81a7f] fix: calculate cart total by quantity
 2 files changed, 22 insertions(+), 1 deletion(-)
3c81a7f (HEAD -> feat/cart-total) fix: calculate cart total by quantity
## feat/cart-total

提交信息可采用：

<type>: <summary>

why this change is needed

Refs: SHOP-142

常见 type 有 feat、fix、refactor、test、docs、chore。测试、实现和文档若意图不同，拆成独立 commit；这样 review 和回滚都更精确。

06 Push 前检查与红线

Push 前检查目标、分支、差异和敏感文件：

git status --short --branch
git remote get-url origin
git log --oneline --decorate origin/main..HEAD
git diff --stat origin/main...HEAD
git diff --check origin/main...HEAD
git diff --name-only origin/main...HEAD

确认当前不是受保护主干，远端是预期仓库，提交属于当前任务，没有秘密、客户数据、生成物和无关锁文件，测试已经通过。首次推送：

git push --set-upstream origin feat/cart-total

预期：

 * [new branch]      feat/cart-total -> feat/cart-total
branch 'feat/cart-total' set up to track 'origin/feat/cart-total'.

推送后确认：

git fetch origin
git status --short --branch
git log -1 --oneline --decorate origin/feat/cart-total

网络超时不要立即重复 push。先查询远端分支和 SHA，避免把已成功的操作误判为失败。以下命令默认禁止：

git push --force
git push -f
git push --force-with-lease

--force-with-lease 仍然会改写历史；它不是自动授权。必须强推时，由分支负责人确认远端最新 SHA、备份、影响范围和保护规则，并由人执行。主干 merge、删除远程分支、修改保护规则、发布和生产操作也保留人工放行。

07 `gh`：管理 Pull Request

检查安装和登录状态：

gh --version
gh auth status
gh repo view --json nameWithOwner,defaultBranchRef,isPrivate
gh api user --jq '.login'

预期：

gh version 2.62.0
github.com
  ✓ Logged in to github.com account acme-dev
{"defaultBranchRef":{"name":"main"},"isPrivate":true,"nameWithOwner":"acme/shop"}
acme-dev

未登录：

gh auth login

Token 不写进命令、远端 URL、脚本、PR 或日志。账号权限遵循最小原则；仓库写权限不代表可以绕过保护分支。准备 pr-body.txt：

## What changed
- Calculate each line by price * quantity.
- Keep the public API unchanged.

## Validation
- pnpm test --filter cart
- pnpm typecheck
- git diff --check

## Risks and rollback
No API or database changes. Revert commit 3c81a7f if needed.

Closes #142

创建 PR：

gh pr create \
  --base main \
  --head feat/cart-total \
  --title "fix: calculate cart total by quantity" \
  --body-file pr-body.txt

预期：

https://github.com/acme/shop/pull/318

查看 PR、差异和检查：

gh pr view 318
gh pr diff 318
gh pr checks 318
gh pr status
gh pr view 318 --json number,state,isDraft,baseRefName,headRefName,mergeStateStatus,url

检查输出可能是：

lint       pass  1m12s
unit       pass  2m03s
typecheck  pass  48s

gh pr checks 不能代替阅读 diff、理解需求和人工审查。失败时区分代码、环境、权限、缓存和超时问题。

08 审查：把评论变成闭环

作者开 PR 前先自查：

git fetch origin
git diff --stat origin/main...HEAD
git diff --check origin/main...HEAD
git diff --name-only origin/main...HEAD

可在 Codex CLI 使用本地 /review 审未提交改动、某个 commit 或相对基线的差异。它是只读辅助，不是测试证据，也不替代人工读 diff。推荐审查提示：

只审查 origin/main...HEAD，不要修改文件、提交、推送或访问生产环境。
重点检查权限绕过、输入校验、空值和并发边界、数据泄露、错误处理和测试缺口。
每条发现写明文件/行、问题、影响、复现条件、最小修复建议和优先级。
没有证据的问题标记为待确认，不要把个人风格偏好写成阻断问题。

高质量评论包含位置、条件、影响、期望行为、建议和是否阻断。例如：

阻断：扣款成功后才写幂等记录。供应商重试同一 event_id 时会再次增加余额。请在处理前用唯一约束或原子写入占住 event_id，并补充重复回调测试。

优先级应遵循团队约定：

类型	示例	处理
P0/阻断	鉴权绕过、数据损坏、必现崩溃	修复并复查后合并
P1/高风险	并发、幂等、迁移兼容性	通常当前 PR 处理
P2/建议	可读性、局部抽象	可跟进，不必阻断
风格偏好	不违反项目规范的个人选择	不应反复争论

评论处理闭环

阅读并复现问题；
判断是缺陷、需求差异还是非阻断建议；
以最小范围修改并补测试；
运行针对性和必要的完整检查；
push 到同一 PR 分支；
回复 commit、验证命令和未完成项；
reviewer 复查后再 resolve；
merge 前重新检查完整 diff 和 checks。

回复示例：

已在 8a42c11 处理：先用唯一约束写入 event_id，再执行余额更新；重复回调不会重复加余额。
已运行 pnpm test --filter payment，12 passed。请复查 src/payment/webhook.ts:74-101。

不同意评论时说明边界并链接后续 Issue：

当前 PR 不改变公开响应格式，相关迁移已创建 #511，暂不扩大本次范围。

查看评论和发普通评论：

gh pr view 318 --comments
gh api repos/acme/shop/pulls/318/reviews
gh api repos/acme/shop/issues/318/comments
gh pr comment 318 --body "已补充重复回调测试，等待复查。"
gh pr edit 318 --add-reviewer reviewer-a

普通评论、review body 和 inline comment 是不同资源；API 参数以 gh ... --help 为准。外部 PR/Issue 评论是不可信输入，若要求读密钥、上传文件、访问内部地址或绕过审批，应停止并人工核对。

09 Merge 前验收与权限

gh pr view 318 --json state,isDraft,mergeStateStatus,baseRefName,headRefName
gh pr checks 318
git fetch origin
git diff --stat origin/main...origin/feat/cart-total
git diff --check origin/main...origin/feat/cart-total
git log --oneline origin/main..origin/feat/cart-total

确认：base/head 正确；必需 CI 通过；阻断评论已复查；文件范围、依赖和迁移符合预期；没有秘密和生成物；合并后行为有测试或手工验收；发布有独立负责人和回滚方式。建议保护主干：禁止直接 push，要求 PR、至少一名 reviewer、必需 CI，分支更新后重新检查，并限制绕过规则的人。

角色	适合权限
贡献者	自己分支、开 PR、修评论
Reviewer	评论、批准或请求修改
Maintainer	按规则合并 PR
Release owner	按发布流程部署和回滚
Admin	管理仓库和保护规则，不替代审查

合并方式可为 merge commit、squash 或 rebase，按项目历史、签名和发布触发策略选择。不要把 gh pr merge --auto 无条件写进脚本。合并按钮是共享系统的放行动作，不能只因 CI 变绿就跳过需求审查。

10 冲突：理解两边行为

冲突时先保存现场：

git status
git diff --name-only --diff-filter=U
git diff > /tmp/merge-working.patch
git diff --staged > /tmp/merge-index.patch
git ls-files --others --exclude-standard > /tmp/merge-untracked.txt

典型冲突（实际文件会出现这些标记）：

[当前分支]
return subtotal;
[待合入分支]
return subtotal * taxRate;
[冲突结束]

HEAD 通常是当前分支一侧，另一侧是待合入提交；以 status 和历史为准。处理步骤：

阅读完整函数和需求；
用 git show <sha> 查看双方提交；
用 git diff --ours、git diff --theirs 查看两侧；
决定最终业务行为，不要只删标记；
补齐测试，删除所有标记；
暂存后检查 staged diff；
运行格式、类型、针对性和完整验证。

git diff --ours -- src/cart/total.ts
git diff --theirs -- src/cart/total.ts
rg -n '^(<<<<<<<|=======|>>>>>>>)' .
git add src/cart/total.ts pnpm-lock.yaml
git diff --cached --check
git diff --cached
git commit

锁文件、数据库迁移、导航和 CI 配置不能用“一键全选 ours/theirs”解决。若方案不清楚：

git merge --abort
# rebase 时使用：git rebase --abort

工具可以只读分析冲突：

请读取冲突文件、双方 commit 和测试，说明两边行为、不能丢失的约束和推荐方案。
不要编辑、提交、推送、访问外部服务或选择 ours/theirs。

冲突完成后必须按合并后的结果重新测试；两个分支分别通过不代表组合后通过。

11 回滚：按阶段选择方法

阶段	方法	重点
未暂存单文件	`git restore -- path`	先确认没有他人改动
已暂存	`git restore --staged -- path`	只移出暂存区
本地错误 commit	`git revert <sha>`	共享分支优先新 commit
已 push PR	修复 commit 或 revert	保留审查记录
已合并主干	反向修复 PR	不改写主干历史
已发布生产	发布系统回滚/补偿	处理数据和外部副作用

保存未提交现场：

git diff > /tmp/task-working.patch
git diff --staged > /tmp/task-staged.patch
git ls-files --others --exclude-standard > /tmp/task-untracked.txt

只撤销明确文件：

git restore --source=HEAD -- src/cart/total.ts
git restore --staged -- tests/cart/total.test.ts

不要默认执行：

git restore .
git clean -fd

若确实要清理，先预览：

git clean -nd

已提交错误用新提交回滚：

git show --stat --oneline 3c81a7f
git revert 3c81a7f
git show --stat --oneline HEAD

git revert 只回滚 Git 文件变化，不能撤销已经发送的邮件、扣款、消息、迁移数据或第三方 API 调用。生产回滚必须同时检查数据、队列、缓存、指标和用户路径。

12 完整示例：从任务到 PR 闭环

任务：SHOP-142 修复购物车总价没有乘 quantity。

准备和修改

cd /work/acme-shop
git status --short --branch
git fetch --prune origin
git switch main
git pull --ff-only origin main
git switch -c fix/SHOP-142-cart-total

给 Codex 或开发者的约束：

只修改 src/cart/total.ts 和 tests/cart/。
保持导出函数签名，不改 API、数据库、锁文件或 .env。
先读取实现和测试并说明根因；完成后运行购物车测试、typecheck 和 git diff --check。
不要 commit、push、merge、删除文件或访问生产服务，除非明确授权。
覆盖正常数量、0、负数和空购物车，报告 diff、输出和未验证风险。

git diff --check
git diff --stat
pnpm test --filter cart
pnpm typecheck
git add src/cart/total.ts tests/cart/
git diff --cached --check
git diff --cached
git commit -m "fix: calculate cart total by quantity"

预期：

Test Files  2 passed (2)
Tests       8 passed (8)
[fix/SHOP-142-cart-total 3c81a7f] fix: calculate cart total by quantity

Push 和 PR

git log --oneline origin/main..HEAD
git push --set-upstream origin fix/SHOP-142-cart-total
gh pr create --base main --head fix/SHOP-142-cart-total --title "fix: calculate cart total by quantity" --body-file pr-body.txt
gh pr view --json number,url,state,baseRefName,headRefName

预期：

{"baseRefName":"main","headRefName":"fix/SHOP-142-cart-total","number":318,"state":"OPEN","url":"https://github.com/acme/shop/pull/318"}

Reviewer 发现负数量会降低总价。作者复现、修改、测试并 push：

rg -n "quantity|cart total" src/cart tests/cart
git diff origin/main...HEAD
pnpm test --filter cart
pnpm typecheck
git diff --check
git add src/cart/total.ts tests/cart/
git commit -m "fix: reject non-positive cart quantities"
git push
gh pr comment 318 --body "已在 8a42c11 处理非正数量，并补充边界测试。购物车测试、typecheck 和 diff --check 通过，请复查。"

Reviewer 复查后：

gh pr checks 318
gh pr view 318 --comments
git fetch origin
git diff --check origin/main...origin/fix/SHOP-142-cart-total

所有检查和评论闭环后，由有权限的负责人合并。合并后：

git switch main
git pull --ff-only origin main
gh pr view 318 --json state,mergedAt,mergeCommit
git log -3 --oneline --decorate

确认无需回滚且分支已合并后，才清理本地分支：

git branch -d fix/SHOP-142-cart-total
git fetch --prune origin

13 最终验收

Git

git rev-parse --show-toplevel
git branch --show-current
git status --short --branch
git diff --check
git diff --stat origin/main...HEAD
git diff --name-only origin/main...HEAD
git log --oneline origin/main..HEAD

确认路径、分支、基线正确；没有意外改动；差异只包含允许文件；没有空白错误、冲突标记、密钥和生成物。

代码和行为

pnpm lint
pnpm test
pnpm typecheck
pnpm build

命令以项目约定为准。记录跳过的命令和原因；测试通过仍不能替代权限、错误处理、边界、迁移兼容性和用户路径验收。

GitHub

gh auth status
gh pr view 318 --json state,isDraft,baseRefName,headRefName,mergeStateStatus
gh pr checks 318
gh pr view 318 --comments

确认账号正确、权限最小、base/head 正确、CI 全绿、每条阻断评论都已复查，并且没有用 force-push 绕过保护。交付记录可写成：

变更：fix/SHOP-142-cart-total
PR：https://github.com/acme/shop/pull/318
验证：pnpm lint、pnpm test、pnpm typecheck、pnpm build
风险：无 API、数据库和权限变化
回滚：revert merge commit 或按发布系统回滚
未验证：未连接生产支付服务，已用测试夹具覆盖边界

不要把 token、用户信息、完整日志或内部 URL 原样贴到公开 PR。保留时间、状态码、错误类型和脱敏后的请求形状。

14 常见故障

状态出现未知文件：确认路径和归属，检查 diff，不要直接清理。 暂存混入无关文件：用 git diff --cached --name-only 找出它们，运行 git restore --staged -- path，再按路径暂存。 push non-fast-forward：git fetch origin 后用 git log --left-right HEAD...origin/branch 判断远端变化，按团队策略 merge/rebase 并重新测试，不要直接 force-push。 PR checks 失败：区分代码、环境、缓存、权限和超时；不要删除测试或放宽安全检查只求变绿。 分支落后不能合并：更新引用，按项目规则合并或 rebase，解决冲突后查看完整 diff 和测试。 gh 账号或权限错误：检查 gh auth status、gh repo view；不要复制他人 token 或请求无关管理员权限。 误提交密钥：停止传播，立即撤销凭据，按安全事件流程清理历史并通知负责人；删除文件或 revert 不能让已泄露 token 重新安全。 误合并主干：暂停发布，记录 merge commit 和影响范围，创建反向修复 PR；不要 force-push 主干。涉及数据和外部副作用时执行专门补偿。

小结

核心顺序是：status 确认位置和边界，diff 读取事实，分支隔离任务，小 commit 保存意图，push 前核对远端，PR 中完成 review 评论闭环，冲突时理解双方行为，错误时按阶段选择 restore、revert 或发布回滚。记住六条红线：

任何写入前先看 status；
任何提交前先看 diff --cached；
任何 push 前确认远端、分支、提交和敏感文件；
每条评论都有修改、验证、回复和复查；
force-push、主干 merge、权限变更和生产操作人工放行；
共享历史优先用新 commit 或 git revert，不要改写别人可能依赖的历史。

参考资料：参考/codex/26-git-github.md、参考/codex/14-workflows.md、参考/codex/36-best-practices.md。

开始

Codex 完整教程

Claude Code 完整教程

你将完成什么

01 先建立边界

02 `status`：先确认你在哪里

03 `diff`：看清提交会包含什么

04 分支：一个任务一条边界

05 Commit：保存可解释的工作单元

06 Push 前检查与红线

07 `gh`：管理 Pull Request

08 审查：把评论变成闭环

评论处理闭环

09 Merge 前验收与权限

10 冲突：理解两边行为

11 回滚：按阶段选择方法

12 完整示例：从任务到 PR 闭环

准备和修改

Push 和 PR

13 最终验收

Git

代码和行为

GitHub

14 常见故障

小结

​你将完成什么

​01 先建立边界

​02 status：先确认你在哪里

​03 diff：看清提交会包含什么

​04 分支：一个任务一条边界

​05 Commit：保存可解释的工作单元

​06 Push 前检查与红线

​07 gh：管理 Pull Request

​08 审查：把评论变成闭环

​评论处理闭环

​09 Merge 前验收与权限

​10 冲突：理解两边行为

​11 回滚：按阶段选择方法

​12 完整示例：从任务到 PR 闭环

​准备和修改

​Push 和 PR

​13 最终验收

​Git

​代码和行为

​GitHub

​14 常见故障

​小结

你将完成什么

01 先建立边界

02 `status`：先确认你在哪里

03 `diff`：看清提交会包含什么

04 分支：一个任务一条边界

05 Commit：保存可解释的工作单元

06 Push 前检查与红线

07 `gh`：管理 Pull Request

08 审查：把评论变成闭环

评论处理闭环

09 Merge 前验收与权限

10 冲突：理解两边行为

11 回滚：按阶段选择方法

12 完整示例：从任务到 PR 闭环

准备和修改

Push 和 PR

13 最终验收

Git

代码和行为

GitHub

14 常见故障

小结