提交与历史

每一次 commit 都是项目时间线上的检查点。GitHub 把本地历史可视化：Commits 列表、单行对比、blame、关联 PR。本课对应 git-github 路线图 的 committing-changes、viewing-commit-history、commit-messages。

git add / git commit 在 git-essentials 已练；这里强化 message 规范 与 在 GitHub 读历史。

学习目标

• 写清晰、可检索的 commit message（Conventional Commits 入门）
• 用 git log 与 GitHub Commits 页读历史、看 diff
• 理解 amend、revert 在协作中的注意事项

工作区 → 暂存 → 提交

git status
git add src/utils.ts README.md
git commit -m "feat(utils): 添加日期格式化 helper"
git push origin main

小步提交： 一个 commit 只做一件事，便于 review 和 git bisect 排错。

Commit message 规范

推荐 Conventional Commits 简化版：

<type>(<scope>): <subject>

<body 可选>

<footer 可选，如 Closes #123>

常见 type：

type	含义
feat	新功能
fix	修复 bug
docs	文档
chore	构建、依赖、杂项
refactor	重构（不改行为）

示例：

git commit -m "fix(api): 修复分页参数 off-by-one

Closes #42"

避免：update、fix bug、改了一下——Review 与 git log --grep 都无法检索。

查看历史

本地：

git log --oneline --graph -15
git log --follow -- path/to/file.ts
git show abc1234

GitHub 仓库页 Commits → 点 SHA → 看 Browse files 与该 commit 的 diff。PR 合并后也会留下 merge commit 或 squash 后的单 commit。

amend 与 revert（协作注意）

# 仅改最后一次 commit（未 push 或 force push 前安全）
git commit --amend -m "docs: 修正 typo"

# 撤销某次提交（生成新 commit，安全）
git revert abc1234

已 push 到共享分支的 commit 不要 amend + force push，除非团队明确允许。公开历史以 revert 或新 fix commit 为准。

关联 Issue

在 message 或 PR 描述写 Closes #123、Fixes #456，合并后 GitHub 自动关闭 Issue（见 ghg-issues）。

练习

• 对练习仓做 3 次 commit，分别用 feat / docs / fix type
• git log --oneline --graph 与 GitHub Commits 页对照
• 找一条含 Co-authored-by 或 issue 引用的开源 commit 阅读

小结

好历史 = 小步提交 + 可读 message + 平台可视化。 下一课分支进阶：rebase、squash、cherry-pick 与 detached HEAD。