# Git 协作规范 v1.0

## 1. 目标与适用范围

本规范用于降低 `git pull` 后冲突率，避免本地改动被覆盖，统一 TTMusic 项目的团队协作流程。

适用范围：所有参与本仓库开发与评审的成员。

## 2. 分支模型与集成规则

- 主干分支（`main`/`master`）仅用于集成，禁止直接提交。
- 功能开发使用 `feature/*` 分支。
- 缺陷修复使用 `fix/*` 分支。
- 主干合入必须通过 PR，并完成代码评审后合入。

分支命名示例：
- `feature/webdav-upload-refactor`
- `fix/local-music-crash-on-resume`

## 3. 日常同步 SOP

### 3.1 拉取前强制检查

每次 `pull` / `rebase` / 切分支前，必须执行：

```bash
git status
```

判定规则：
- 工作区干净：可继续同步。
- 存在未提交改动：必须先 `commit` 或 `stash`，禁止直接同步。

### 3.2 标准同步流程

```bash
git status
git fetch origin
git rebase origin/<base-branch>
```

适用边界：
- 个人分支优先使用 rebase 保持线性历史。
- 对共享分支或已公开历史，若不适合 rebase，可使用 merge，但需在 PR 说明中注明。

### 3.3 推送与集成检查

推送前检查：
- 提交是否按语义组织，避免把无关改动混到同一 commit。
- 是否已完成基础构建/自测。
- PR 描述是否包含：改动范围、风险点、验证结果。

## 4. 冲突处理 SOP

### 4.1 冲突定位

```bash
git status
```

定位含冲突文件后，逐个处理冲突标记（`<<<<<<<`、`=======`、`>>>>>>>`）。

### 4.2 手工解决与验证

- 按业务语义合并，不做机械保留。
- 解决后执行：

```bash
git add <file>
git rebase --continue   # 或 git commit（merge 场景）
```

- 完成后至少执行一次关键路径验证（构建/核心流程冒烟）。

### 4.3 提交与记录

冲突解决提交信息建议包含 `conflict-resolve` 关键字，并在 PR 说明中记录冲突来源与处理原则。

## 5. 本地改动保护与恢复 SOP

### 5.1 命名 stash 规范

```bash
git stash push -m "<date>-<branch>-<purpose>"
```

示例：`2026-02-06-feature-webdav-sync-before-rebase`

### 5.2 临时备份分支规范

```bash
git switch -c backup/<date>-<topic>
```

用于保护未完成改动，避免误操作覆盖。

### 5.3 恢复流程

```bash
git stash list
git stash apply stash@{n}
```

若冲突，回到“冲突处理 SOP”处理。

## 6. 高风险命令红线

以下命令属于高风险操作，默认禁止直接执行：
- `git reset --hard`
- `git checkout -- <path>`（覆盖工作区）
- `git clean -fd`

允许前置条件：
- 已创建可恢复点（commit / stash / backup 分支）。
- 明确知晓影响范围并经过二次确认。

## 7. 仓库基线策略

### 7.1 文本归一化

- 统一通过 `.gitattributes` 管理行尾与文本识别，避免跨平台伪冲突。

### 7.2 二进制与不可安全文本合并文件

- 二进制文件标记为 `-text`，禁止按文本方式合并。
- 对锁文件、HAR 等生成/归档文件，根据版本管理策略决定是否纳入版本库。

## 8. 已知限制与后续优化

已知限制：
- 团队尚未建立自动化冲突预警机制，流程依赖人工执行。
- 某些跨团队紧急变更可能临时偏离标准流程。

后续优化：
- 结合 PR 模板与 CI 检查增强流程约束。
- 统计冲突热点文件并优化模块边界。