Git for FDE（FDE 的版本管理）

知识库位置：FDE Knowledge Base/03 Engineering/Software Engineering/Git/Git-for-FDE.md 术语不确定时，请查阅 Glossary（中英文术语表）。

1. Why Git Matters（为什么 Git 重要）

Git（版本管理工具）不只是：

保存代码的工具。

对于 FDE，Git 是：

Change History（变更历史）
+
Collaboration（协作）
+
Review（评审）
+
Rollback（回滚）
+
Reproducibility（可复现性）

的基础。

真实客户项目经常变化很快。

如果没有可靠版本控制，很容易出现：

Production code only exists on laptop（生产代码只存在于一台笔记本上）

或：

Nobody knows which config was deployed（没人知道部署的是哪份配置）

2. Core Mental Model（核心心智模型）

Working Directory（工作目录）
↓
Stage（暂存区）
↓
Commit（提交）
↓
Branch（分支）
↓
Remote Repository（远程仓库）

3. Minimum Commands / Concepts（最低命令/概念集）

FDE 至少熟悉：

clone（克隆）
status（查看状态）
add（暂存）
commit（提交）
push（推送）
pull（拉取）
branch（分支）
checkout / switch（切换分支）
merge（合并）
rebase basics（变基基础）
log（提交日志）
diff（差异比较）
revert（回退提交）
tag（标签）

4. Commit（提交）

Commit 应代表一个有意义的 Change（变更）。

不推荐：

fix
fix2
final
final2

更好：

Add permission filter before RAG retrieval（在 RAG 检索前增加权限过滤器）

5. Branch（分支）

Branch 允许不同工作并行。

典型：

main（主分支）
feature/*（功能分支）
fix/*（修复分支）

团队具体策略可能不同。

FDE 应遵循客户或组织已有规则。

6. Pull Request（拉取请求）

PR（Pull Request，拉取请求）的价值：

review（评审）
discussion（讨论）
audit（审计）
CI validation（持续集成校验）

高风险修改不应该：

直接 Push（推送）到 main（主分支）。

7. Merge vs Rebase（合并 vs 变基）

FDE 不需要陷入宗教战争。

需要理解：

Merge（合并）

保留分支合并历史。

Rebase（变基）

重写本地提交基线，使历史更线性。

重要原则：

不要随意重写别人已经依赖的共享历史。

8. Conflict Resolution（冲突解决）

发生冲突时：

Understand both changes（理解双方变更）
↓
Choose intended final state（选择期望的最终状态）
↓
Test（测试）
↓
Commit（提交）

不要只机械点：

Accept ours / theirs（采用我方/对方版本）。

9. Revert vs Reset（回退 vs 重置）

生产代码出问题时，通常更安全的是：

Revert commit（回退提交）

因为它创建新的历史记录。

reset（重置）可能改写历史，使用要谨慎。

10. Tags（标签）

Tags 常用于：

v1.0.0
release-2026-10-31（发布标识）

帮助明确：

哪个代码版本进入 Production（生产）。

11. Git and Deployment Traceability（Git 与部署可追溯性）

理想链路：

Commit（提交）
↓
Build（构建）
↓
Artifact（构建物）
↓
Deployment（部署）
↓
Production Version（生产版本）

发生 Incident（事故）时可以回答：

Production 当前跑的是哪个 Commit？

12. Configuration（配置安全）

不要把：

API key（API 密钥）
production password（生产密码）
client secret（客户端密钥）

提交到 Git。

即使之后删除：

Secret 可能仍然存在 Git History（Git 历史）。

泄漏后应该：

Rotate Secret（轮换密钥）

而不是只删除 Commit。

13. Customer-specific Code（客户特定代码）

FDE 很容易出现：

Customer A custom code（客户 A 定制代码）
Customer B custom code（客户 B 定制代码）
Customer C custom code（客户 C 定制代码）

如果没有策略，会产生严重分叉。

优先考虑：

Configuration（配置）
Adapters（适配器）
Feature Flags（功能开关）

而不是为每个客户复制整个 Codebase（代码库）。

14. Git and Fast Prototyping（Git 与快速原型）

Prototype（原型）可以快。

但不意味着：

不使用版本控制。

即使只做两天 POC（Proof of Concept，概念验证），也应该有：

Repository（仓库）
README（自述文件）
Dependencies（依赖清单）
Config example（配置示例）
Commit history（提交历史）

15. README Minimum（README 最低要求）

每个项目至少说明：

What is this?（这是什么？）

How to run?（如何运行？）

Required dependencies?（需要什么依赖？）

Configuration?（如何配置？）

Environment variables?（有哪些环境变量？）

How to test?（如何测试？）

How to deploy?（如何部署？）

16. Common Failure Modes（常见失败模式）

Failure 1 — Direct Production Changes（直接修改生产）

SSH 到机器直接改代码。

之后 Repository（仓库）不知道发生了什么。

Failure 2 — Secret Committed（密钥入库）

必须立即 Rotate（轮换）。

Failure 3 — Giant Commit（巨型提交）

一万行变化无法 Review（评审）。

Failure 4 — Long-lived Customer Branch（长期客户分支）

最终无法合并。

Failure 5 — No Tag / Release Mapping（无标签/发布映射）

事故发生时不知道生产版本。

17. Suggested FDE Workflow（建议的 FDE 工作流）

Create branch（创建分支）
↓
Implement（实现）
↓
Test（测试）
↓
Commit（提交）
↓
Push（推送）
↓
PR（拉取请求）
↓
Review / CI（评审/持续集成）
↓
Merge（合并）
↓
Deploy（部署）
↓
Tag / Track Release（打标签/追踪发布）

18. FDE Safety Rule（FDE 安全规则）

在客户 Repository（仓库）操作前确认：

Which repo?（哪个仓库？）

Which branch?（哪个分支？）

Which environment?（哪个环境？）

What review process?（什么评审流程？）

Can I force push?（可以强制推送吗？）

Who owns release?（谁负责发布？）

不要假设自己熟悉的 Git Workflow（Git 工作流）就是客户的 Workflow。

19. FDE Depth（FDE 深度要求）

目标：

Level B — Operate（B 级：操作）

FDE 必须能够：

独立使用 Git
处理冲突
Review PR（评审拉取请求）
回滚 Change（变更）
追踪 Production Version（生产版本）
避免 Secret（密钥）泄漏

Senior FDE（高级 FDE）还应能设计合理 Repository / branching / release（仓库/分支/发布）实践。