# Git 工作流

> 这个仓库已经 `git init`，首次提交完成。下面是怎么用，以及为什么这么用。

---

## 为什么这个仓库特别适合 git

不是所有项目都值得上 git。这个仓库有三条天然契合：

| 特性 | 带来的好处 |
|---|---|
| **原材料只增不改** | 加文件几乎永远不冲突。这是最关键的——协作时最怕两个人改同一个文件 |
| **全是 Markdown** | diff 读得懂。改了什么、删了什么，一眼看出来，不用看二进制 |
| **索引是派生的** | `_index.md`、`derivations.jsonl` 冲突了直接重生成，不用手工合并 |

还有一条隐藏价值：**知识库的 git 历史 = 课程内容的演进史**。半年后你想知道「客户画像这一页是怎么长成现在这样的」，`git log -p` 能看到它被五份资料逐步充实的过程。这比任何笔记都可靠。

---

## 一次性设置（已配好，换机器要重做）

```bash
git config core.quotepath false     # 中文文件名正常显示，不显示成八进制
git config user.name  "你的名字"
git config user.email "你的邮箱"
```

`core.quotepath false` 这条别漏。不配的话 `git status` 里全是 `\346\212\200\350\203\275` 这种，没法看。

---

## 日常：一次同步，一个提交

```
丢资料 → 说「同步」→ 跑 kb.py check → git add -A → git commit
```

**提交前必须跑一次检查**，别把死链和没出处的数字提交进去：

```bash
python 90-工具/kb.py check
```

### 提交信息规范

统一前缀加一句话，方便日后 `git log --oneline` 扫读：

| 前缀 | 什么时候用 | 例子 |
|---|---|---|
| `sync:` | 增量同步完成 | `sync: 入库 3 份行业报告，派生 9 页` |
| `retract:` | 源删除后的回滚 | `retract: 删除 2024 旧版大纲，归档 4 页` |
| `course:` | 课程产出 | `course: 银行 3 天课大纲初稿` |
| `fix:` | 修复体检问题 | `fix: 清理 12 处死链与 3 个孤儿页` |
| `rule:` | 改契约或技能 | `rule: 新增证据分级 A/B/C/D` |
| `chore:` | 工具改动 | `chore: kb.py 增加 repair 命令` |

不要写 "update"、"修改"、"提交一下"。三个月后自己看不懂。

---

## 多人协作：谁改什么

冲突的根源是两个人改同一个文件。按下面的分工，冲突面能压到接近零。

| 角色 | 主要改 | 基本不碰 |
|---|---|---|
| 资料策展人 | `00-原材料/` 加文件 | 知识库页面 |
| 做课的人 | `20-课程产出/`、`10-知识库/modules/` | 别人的 topic 页 |
| 库维护者 | `10-知识库/topics/`、`entities/`、`_meta/` | 产出目录 |

### 三个冲突高发点

| 文件 | 冲突概率 | 原因 |
|---|---|---|
| `_meta/manifest.json` | **极高** | 单一文件，谁同步都会改 |
| `topics/*.md` | 中 | 两个人可能同时往同一主题页补料 |
| `*/_index.md` | 中 | 每次 `graph` 都重写 |

---

## 冲突怎么解

### 情况一：`manifest.json` 冲突

**不要手动合并 JSON。** 它本质是磁盘状态的缓存，直接从磁盘重建就行：

```bash
git checkout --ours 10-知识库/_meta/manifest.json
python 90-工具/kb.py repair
```

`repair` 会扫磁盘算指纹、扫页面反推派生关系，把 manifest 重新建出来。恢复不了的只有「整理时间」和「已删除源的记录」，不影响使用。

### 情况二：页面冲突

正常解，但注意 **`sources:` 列表要取并集**，不是二选一。少一个源，将来删那个源时这页就回滚不掉。

```yaml
sources:
  - "01-行业资料/报告A.pdf"     # 对方加的
  - "02-客户与需求/访谈.md"      # 你加的
```

### 情况三：`_index.md` 冲突

**别解，直接重生成：**

```bash
git checkout --theirs 10-知识库/topics/_index.md
python 90-工具/kb.py graph
```

它是 `kb.py graph` 的产物，手工合并没有任何意义。

---

## 用 git 做四件具体的事

### 1. 撤销一次糟糕的同步

同步完发现喂了错误的资料，整批派生页都脏了：

```bash
git reset --hard HEAD~1     # 回到上一个提交（会丢未提交的改动，先确认）
```

比手动删页面安全得多。

### 2. 看某一页是怎么长出来的

```bash
git log -p -- 10-知识库/topics/客户画像.md
```

能看到它第一次只是一句话，后来被几份资料逐步补成现在的样子，每次补料是谁、按什么依据。**这是这个仓库最值钱的用法之一。**

### 3. 找回被误删的页

```bash
git log --diff-filter=D --name-only -- 10-知识库/
```

列出所有被删过的文件，配合 `git checkout <commit>^ -- <路径>` 恢复。

### 4. 对比两周前的库

```bash
git diff HEAD~20 --stat
```

一眼看出这两周库长大了多少、哪些方向在长、哪些页一直没动过。

---

## 要不要推到远端

**不要推到公开 GitHub。** 这个库里有客户名称、报价、内部方法论，属于公司资产。

需要多人协作时的选项：

| 方案 | 适合 |
|---|---|
| 公司内网 GitLab / Gitee 私有仓库 | 正式团队协作 |
| 局域网共享盘 + 各自本地仓库 | 三两个人，临时 |
| 一人维护，其他人只读 | 最常见，用 `git pull` 拿最新 |

远端地址配好后：

```bash
git remote add origin <地址>
git push -u origin main
```

---

## 大文件

`00-原材料/` 里如果有超过 50MB 的 PDF 或视频，建议用 git-lfs，否则仓库会很快膨胀到几个 GB：

```bash
git lfs install
git lfs track "00-原材料/**/*.pdf"
git lfs track "00-原材料/**/*.mp4"
git add .gitattributes
```

**已经提交过的大文件不能再靠 lfs 瘦身**，需要用 `git filter-repo` 重写历史。所以最好现在就决定。

---

## 和 kb.py 的分工

别把两件事搞混：

| | 管什么 |
|---|---|
| **git** | 文件的历史版本：谁在什么时候改了什么 |
| **kb.py** | 当前状态的一致性：哪些源整理过、哪些页该删、索引对不对 |

`git` 回答「上周这页写的什么」，`kb.py` 回答「现在库里有没有过期内容」。两个都要，互相替代不了。

---

## 一条最小纪律

> **每次说「同步」结束后，立刻提交一次。**

不要攒着。攒了三天的改动一起提交，出问题时你分不清是哪一批资料搞坏的。