Git 与团队协作：一页纸学习计划

• 主题路径：docs/topics/git-and-collaboration/
• 主分类：工程技术
• 辅助分类：项目与职业能力
• 适合对象：会用命令行、但从未做过 PR / Code Review 的开发者；目标是掌握 Git 本地管理 + 一次规范协作全流程
• 建议周期：2～4 周（每周 8～12 小时，含命令演练、阅读、复盘）
• 前置知识：会使用命令行、能装软件、能用文本编辑器写 Markdown / 代码；建议先完成 linux-dev-env（Linux 开发环境基础）
• 最终目标：能独立完成 fork → clone → branch → commit → push → PR → Review → merge 的完整 GitHub 协作闭环；能用 rebase / cherry-pick / reset / revert 改写或修复历史；能为仓库接入 pre-commit 钩子与 GitHub Actions CI；并完成 1 个开源 PR 或模拟协作综合项目

学习路线

本地版本管理（init / add / commit / status / log / diff）
  → 分支管理（branch / checkout / merge / stash）
  → 远程与协作（clone / fetch / pull / push / PR / Review / 冲突解决）
  → 高级改写（rebase / cherry-pick / reset / revert / tag / submodule）
  → 钩子与 CI 集成（pre-commit / husky / lint-staged / GitHub Actions）
  → 综合协作项目（首选：在 GitHub 完成一次开源 PR 流程；备选：模拟 5 人团队开发并合并 3 个 feature 分支）

每一步都是下一步的前置；不要跳级、不要并行学多个阶段。rebase / reset 是高风险操作，必须先在演练仓库里反复试错。

阶段周数分配（2～4 周，量力而行）

2 周方案对应每天满负荷、目标“会做规范 PR 即可”；4 周方案对应每周 6～8 小时、能完整覆盖高级改写与 CI。2 周方案不写阶段 4、5，但综合项目里仍要会用 rebase 维护自己的 PR 分支。

六阶段：核心知识、实践产出、可观察学会标准

第一周（每天 1.5～2 小时）

Day 1 环境约定：本计划统一使用 Git 官方版本（建议 ≥ 2.40）；平台主线为 GitHub（PR / Review / Actions）。配置命令：

git config --global user.name "Your Name"
git config --global user.email "you@example.com"
git config --global init.defaultBranch main
git config --global pull.rebase true   # pull 时默认 rebase，避免多余 merge commit

SSH key 准备：ssh-keygen -t ed25519 -C "you@example.com"，把 ~/.ssh/id_ed25519.pub 添加到 GitHub Settings → SSH and GPG keys。所有源码从 Day 1 起就遵守 Conventional Commits（feat / fix / docs / refactor / chore）；当你已经能稳定写出规范 commit，再引入 husky + commitlint 作为进阶。

Day 7 项目执行次序（避免一次堆叠）

第一周任务量大，按以下次序分两步推进；每一步独立可验证。

步骤 A —— 先打通最小可用版本（预计 60～90 分钟）

1. 在 git-playground 里写一个最小可用的 README.md（项目名、一句话说明、运行步骤）；
2. 用 5 条 commit 完成基础结构：chore: init / docs: add readme / feat: add basic usage / fix: typo / docs: add license；
3. git log --oneline 检查 5 条 commit 都存在；
4. git status 必须 clean；无 git status --ignored 漏网文件。

步骤 B —— 按清单补齐 4 类边界 / 异常用例（预计 30～45 分钟）

在前一步基础上，按下面清单逐步补足 commit，并记录到 notes/week1-day7.md：

进阶检查（非首次门槛）：当步骤 A、B 都稳定通过、且你能解释每个命令含义时，再叠加 husky + commitlint 作为进阶，强制 commit message 必须符合 Conventional Commits。第一周当天不必完成此步。

阶段通用验收（每一阶段都必须通过）

1. 不看 cheatsheet 独立敲出本阶段核心命令；
2. 用自己的话解释该命令“解决什么问题、为什么有效”；
3. 画一张图：分支拓扑 / PR 时间线 / rebase 前后对比；
4. 测试空仓库、单分支、多分支、冲突、远程断开等边界场景；
5. 准备至少 3 组自定义数据 / 仓库并贴出实际输出或日志；
6. 记录每个高风险命令（--force push、reset --hard、rebase on 公共分支）的常见破坏后果；
7. 能修改已有流程（加 hook、修 Action、调整 commit 规范），而不是只能照抄。

交付存放：第 3 项的图、第 5 项的输出截图 / 文本、第 6 项的风险日志，统一存到当前阶段对应项目目录的 notes/ 或 README 章节，例如阶段 3 远程协作的 PR 截图写在 stage3-remote-collab/notes/pr-screenshots/。不要散落在聊天记录或临时文件里，便于后续复盘与综合项目引用。

最终验收（学完全部六阶段后）

• 独立命令能力：本地新建分支并完成 PR merge；用 git reflog 找回误删分支；解释 fast-forward 与 no-ff 的差异；解释 reset 与 revert 的差异；写一份 pre-commit 配置或 husky + lint-staged 配置；写一份最小 GitHub Actions workflow（install → lint → test）；
• 协作闭环：完成至少 1 次完整的 fork → PR → Review → merge 流程（首选：向真实开源仓库发 PR；备选：5 人模拟项目里至少 3 个 feature 分支合并）；
• 风险意识：能列出 5 条 Git 高风险命令清单（push --force、reset --hard、在公共分支 rebase、误删 .git/、泄露 SSH key）并说明每条的补救手段；
• 综合项目：完成 1 个综合协作项目（见下文），自带 README，能被他人按文档复现；
• 讲解能力：能用 15 分钟讲清楚整个学习路线和每个阶段的协作纪律。

综合项目

首选：开源仓库 PR 实战（必做：向一个真实开源仓库提交 PR 并被合并）。
备选：5 人模拟协作（必做：邀请 4 位同伴，分配 3 个 feature 分支，通过 PR 合入 main）。

首选项目要求

• 选仓库：在 GitHub 上找一个 good first issue 标签的开源仓库（推荐：自己熟悉的语言生态；示例：first-contributions 演练仓、cli/cli 等）；
• 流程：fork → clone → 新建 feat/<short-desc> 分支 → 多次语义化 commit → push → 在 GitHub 上发起 PR（带模板：动机 / 改动 / 截图 / 测试）→ 回应 Review → 修改 → 被 maintainer merge；
• 产出：notes/pr-link.md 写 PR 链接、Review 评论截图、最终 merge commit SHA；
• 必做验证：PR 页面截图、CI 跑通截图、合并后 commit 历史截图；
• 可选扩展：在 PR 中给 review 留至少 1 条建设性 comment（不是 “LGTM”，而是“建议把 X 抽成函数”）。

备选项目要求

• 团队规模：5 人（1 个 maintainer + 4 个 contributor），每人负责 1 个 feature；
• 分支策略：main（受保护）/ dev（集成分支）/ feature/<name>（每人 1 条）；
• 冲突场景：至少 2 个 feature 修改同一文件，强制走一次手动冲突解决；
• CI：每个 PR 触发 GitHub Actions 跑 lint + test；
• 产出：完整 PR 列表（含链接）、冲突解决日志、CI 截图、复盘。

notes/ 与 README 存放规范

所有“分支拓扑图”、“PR 时间线截图”、“CI 跑通截图”、“冲突解决日志”类交付物统一存放在项目根目录的 notes/ 子目录或 README 的对应章节；提交时一并带上，避免散落在聊天或临时文件里。综合项目的 notes/ 至少包含：

• notes/design.md：分支策略、PR 模板、CI 设计；
• notes/pr-log.md：每个 PR 的链接、Review 评论、merge 状态；
• notes/conflict-log.md：至少 1 次冲突解决的完整过程（冲突文件、git status、git add、git rebase --continue）；
• notes/ci-screenshots/：CI 跑通截图（首次绿、再现绿）；
• notes/retrospective.md：复盘（用时、难点、收获、下一步）。

任何综合项目都必须包含：

1. 需求说明：要解决的真实问题 / 团队规模 / 角色分工；
2. 分支策略说明：为什么这样切分支（main / dev / feature 的来源）；
3. PR 模板与 Review 记录：每个 PR 的描述、review 反馈、修改 commit；
4. 冲突解决日志：至少 1 次手动解决冲突的完整步骤；
5. CI 集成证据：GitHub Actions 跑通的截图或链接；
6. README：项目介绍、运行步骤、目录结构、复盘（踩过的坑、可改进点）；
7. 复盘记录：用时、难点、收获、下一步。

推荐开源资料（按角色分工，避免堆链接）

许可证提示：从 pre-commit、husky、lint-staged 等开源仓库复制或参考配置前，必须先打开其 LICENSE 文件确认许可证类型（MIT / Apache-2.0 / GPL 等）。GPL 类代码用于商业 / 闭源项目前请逐条阅读；MIT/Apache 在保留版权声明的前提下通常可直接使用。默认做法是读思路后自己重写配置，而不是复制粘贴 workflow。

源码阅读时机：Pro Git 第 7～10 章放到“阶段 3 远程协作完成之后”再深入读。原因是：前 3 阶段目标是建立“从 commit 到 PR”的独立操作能力；过早读历史改写章节会变成“会用 rebase —force”而非“理解协作纪律”。阶段 4 之后你已经能完成 PR，此时读改写章节才有意义。

默认使用顺序：先用 Learn Git Branching 建立分支直觉 → 用 Pro Git 中文版查概念 → 在本地真实仓库敲命令 → 在 first-contributions 完成首次 PR → 接 husky + GitHub Actions → 阶段 4 之后读 Pro Git 第 7 章 → 综合项目。

常见误区

• 把“看过 Pro Git”当成会 Git；不敲命令、不做 PR，就以为自己懂了；
• 跳过阶段 1 直接学 rebase，结果在公共分支 rebase 把同事的 commit 改没了；
• 滥用 git push --force / git reset --hard，丢代码后才发现 git reflog 也救不回来（被 git gc 回收）；
• commit message 写“update”“fix bug”，半年后 git blame 完全看不懂当年改了什么；
• 只在 master / main 上提交，不开分支，多人协作时直接互相覆盖；
• git pull 不指定策略，默认产生多余 merge commit，污染历史；
• 在 PR 中写“LGTM”但不给出实质反馈，让作者不知道哪里要改；
• 跳过冲突解决，第一次 merge conflict 就放弃 PR；
• 不写 .gitignore，把 node_modules / .DS_Store / 编译产物全部提交，仓库膨胀；
• SSH key 配置错误，导致每次 push 都要输密码，最后把密码 hardcode 到 HTTPS URL；
• 不接 CI / hook，main 分支里出现 print("debug") / TODO 注释；
• 误以为 git revert 会删除 commit，结果发现它只是新增一条反向提交。

所有知识点分类（统一规则）

后续新增主题时按此归类，再套用一页纸模板；一个主题可有一个主分类和一个辅助分类。本计划归属见最末行。

1. 编程语言：C、Java、Python、JavaScript 等
2. 数据结构与算法：排序、查找、图、DP 等
3. 计算机基础：OS、网络、数据库、组成原理等
4. 工程技术：Git、Linux、Docker、测试、CI/CD 等
5. Web 与后端：HTTP、REST、Spring Boot、数据库开发等
6. 前端与客户端：HTML/CSS、JavaScript、React、移动开发等
7. 数据与人工智能：SQL、机器学习、深度学习、数据分析等
8. 项目与职业能力：软件设计、调试、代码规范、技术写作等

本计划：工程技术 主 + 项目与职业能力 辅。

学习资料汇聚（v0.3）

本节是主题文件自包含的最后一节；不再依赖 notes/ 子目录。补足内容直接写在本节内，缺失处标 “由本计划生成”。外部图片或大型标准文档以链接 / 附件形式挂在本节。

由本计划生成 / Generated by this plan（本节内容基于公开资料的整理与示范；非第三方讲解的复制）。

9.1 背景与动机

• Git 由 Linus Torvalds 于 2005 年为管理 Linux 内核开发而创建；最初用 C 写成，目标是“速度极快、完全分布式、适合大型项目”。
• 关键事件：BitKeeper 许可证变更 → Linus 用 10 天写出 Git 首个版本 → Junio Hamano 接手至今是维护者。
• 行业位置：今天几乎所有软件项目的版本控制事实标准；GitHub、GitLab、Bitbucket、Codeberg、Gitee 等平台都以 Git 为协议底座；开源贡献、CI/CD、代码评审全部建立在 Git 工作流上。
• 一句话总结：Git 是“让分布式协作从 push/pull 升级为可审计的工程协议”的工具；不会 Git 等于不会团队协作。

9.2 概念地图

核心概念（≥5）：

flowchart LR
    工作区((工作区))
    暂存区[(暂存区 / Index)]
    本地仓库[(本地仓库 .git)]
    远程仓库[(远程仓库 origin)]
    Commit[Commit 对象]
    Branch[Branch 引用]
    Tag[Tag 引用]
    Merge[Merge]
    Rebase[Rebase]
    CherryPick[Cherry-pick]
    Revert[Revert]
    Reset[Reset]
    Stash[Stash]
    Submodule[Submodule]
    Hook[Hook]
    Action[GitHub Actions]
    工作区 -->|git add| 暂存区
    暂存区 -->|git commit| 本地仓库
    本地仓库 -->|git push| 远程仓库
    远程仓库 -->|git pull / fetch| 本地仓库
    本地仓库 --> Commit
    Commit --> Branch
    Commit --> Tag
    Branch --> Merge
    Branch --> Rebase
    Commit --> CherryPick
    Commit --> Revert
    本地仓库 --> Reset
    工作区 --> Stash
    本地仓库 --> Submodule
    本地仓库 --> Hook
    远程仓库 --> Action

关系说明：

• 三态流：工作区 → 暂存区 → 本地仓库 → 远程仓库；每一步都可被 restore / reset 撤回。
• 历史改写：merge（保留分支拓扑）/ rebase（线性化历史）/ cherry-pick（挑选 commit）/ revert（新增反向提交）——四者语义不同。
• 协作扩展：submodule（嵌套仓库）/ hook（本地触发）/ Action（远程触发）——三者覆盖不同自动化场景。

9.3 基础知识讲解

主推（评分 ≥4，命令行友好）：

备查（评分 3）：

缺失部分：本计划不重写第三方资料；如读者在“高级改写”阶段仍卡住，请按 §9.4 中的高风险命令清单逐条演练。

9.4 经典问题与经典案例

9.5 学习难点

概念难点

思维难点

工程难点

9.6 技术标准与接口

9.6.1 Entity

9.6.2 Scope

• Git 协议：定义 commit / tree / blob / tag 对象，定义 pack / loose 存储，定义 push / fetch / clone 协议；不规定 UI、不规定平台。
• GitHub / GitLab 平台：在 Git 之上提供 PR / Review / Issue / Actions / Pages 等服务；不同平台流程略有差异。
• Conventional Commits：定义 commit message 语义；与 Git 协议正交，可独立使用。
• pre-commit / husky：定义 hook 配置格式；husky 依赖 Node 生态，pre-commit 依赖 Python。
• GitHub Actions：定义 workflow YAML schema；与其他 CI（GitLab CI / Jenkins）概念相通但语法不同。

9.6.3 Structure

• Git 命令族：
  • 本地：init / add / commit / status / log / diff / restore / rm
  • 分支：branch / switch / checkout / merge / stash / tag
  • 远程：remote / fetch / pull / push / clone
  • 改写：rebase / cherry-pick / reset / revert / reflog
  • 嵌套：submodule / subtree（subtree 仅作概念提及）
• GitHub PR 元数据：title / body / reviewers / labels / milestone / draft；CI checks；merge button（merge / squash / rebase）。
• Conventional Commits 结构：<type>(<scope>)?: <description>，type ∈ {feat, fix, docs, style, refactor, perf, test, chore, build, ci}；可加 ! 标记 BREAKING CHANGE。
• GitHub Actions workflow：.github/workflows/*.yml，包含 name / on / jobs.<job_id>.runs-on / steps，常用 action：actions/checkout@v4、actions/setup-node@v4、actions/setup-python@v5。

9.6.4 Ecosystem

• Git 实现：官方 C 实现（git/git）、JGit（Java）、libgit2（C 库）、Dulwich（Python）；编辑器插件几乎都基于这几种。
• 平台实现：GitHub、GitLab、Bitbucket、Codeberg、Gitee、SourceHut；协议层互通，平台层各异。
• commit 规范生态：Conventional Commits + commitlint + husky + lint-staged；Angular 团队的规范是事实源头。
• CI 生态：GitHub Actions（GitHub 原生）/ GitLab CI（GitLab 原生）/ CircleCI / Jenkins / Buildkite；本计划只覆盖 GitHub Actions。
• 事实标准 vs 标准本身：Conventional Commits 是事实标准而非 ISO；git-flow 是一种分支策略事实标准，GitHub Flow 是另一种；本计划不强制任一，读者根据团队选。

9.6.5 Depth Tiers

本计划目标：阶段 6 综合项目时达到 L3；能在真实开源仓库发 PR 时尝试 L4。

9.6.6 Source

• git-scm.com：Pro Git（CC BY-NC-SA 3.0）+ Git 命令文档。
• docs.github.com：PR / Review / Actions 官方文档。
• conventionalcommits.org：Conventional Commits 1.0.0 规范。
• pre-commit.com / github.com/typicode/husky / github.com/lint-staged/lint-staged：钩子与 lint-staged 配置文档。
• 引用的版本快照日期：2026-07-28。

引用

• 模板： ../../template/_TEMPLATE.md