# 协作规范（Collaboration Guide）

本文件是 Marry 项目的 Git 协作守则。**两人协作前请先读完**，遇到问题时对照这里的场景处理。

## 一、首次克隆项目

```bash
git clone https://git.onxiou.cn/ProMax-Marry/Marry.git
cd Marry
git submodule update --init   # 拉取 C++ 绑定库 godot-cpp
```

> 为什么有第三条：godot-cpp 是子模块（仓库里只存指针，不存源码）。
> clone 后必须执行 `git submodule update --init` 才能拿到真正的绑定库，否则 C++ 编译会失败。
> 如果这条偶发报错（网络问题），重跑一遍即可。

## 二、日常开发流程（每天必做）

```
开工前：  git pull                # 拉取对方最新代码
写代码：  修改文件...
提交：    git add .               # 暂存所有改动
          git commit -m "说明"    # 提交到本地
推送：    git push                # 上传到服务器
```

按这个顺序，每次提交前先 `git pull`，可以避免 90% 的冲突。

## 三、推送被拒绝时（最常见场景）

**现象：** `git push` 报错 `non-fast-forward` 或 `fetch first`。

**原因：** 对方先推送了新提交，你的本地历史落后了。

**处理：** 不要慌，按顺序执行：

```bash
git pull --rebase     # 把你的提交"挪"到对方最新提交之上
git push              # 再推送
```

> 为什么用 `--rebase` 而不是直接 `git pull`：
> 普通 pull 会产生一个多余的 "Merge branch" 合并提交，历史变成网状；
> `--rebase` 让历史保持一条直线，清爽且不易混乱。

## 四、关于分叉（diverging branches）

**现象：** `git pull` 提示 `Diverging branches can't be fast-forwarded`。

**原因：** 本地和服务器都有对方没有的提交，两边分开了。

**两种分叉的处理完全不同：**

### 1. 正常协作分叉（会经常遇到，无害）
按第三节处理：`git pull --rebase` → `git push`，完成。

### 2. 历史重写分叉（异常情况，需要统一处理）
当有人改了历史并强制推送（force push）后，其他人的本地历史与服务器对不上。
**处理方式：** 确认自己本地没有未推送的独特提交后：

```bash
git status                        # 先看有没有未提交改动
git fetch origin
git reset --hard origin/main      # 丢弃旧历史，对齐服务器
git submodule update --init       # 重新拉子模块
```

## 五、铁律（违反会坑队友）

1. **永远不要 `git push --force`**
   强制推送会覆盖服务器历史，所有已 clone 的人都会分叉。
   除非要清理误提交（如密码泄露），且**先通知所有人**再操作。

2. **提交推上服务器后，不要 reset / rebase / amend 改它**
   改已推送的历史 = 制造分叉。

3. **两人不要同时改同一个文件**
   分工时尽量各管各的场景/模块。Godot 的 .tscn 场景文件合并很容易冲突。

## 六、哪些文件不该提交（.gitignore 已配置）

- `.godot/` — Godot 编辑器缓存（每次打开都会变，提交了必冲突）
- `bin/`、`build/` — C++ 编译产物
- `*.user`、`.vs/` — IDE 个人配置

> 如果你 `git status` 看到这些文件，说明 .gitignore 没生效或被强制添加了，
> 不要提交它们，告诉我处理。

## 七、环境要求

| 工具 | 版本 | 用途 |
|------|------|------|
| Godot | 4.6（标准版） | 游戏引擎，打开 main/project.godot |
| Visual Studio | 2026+（含 C++ 工具集） | 编写/编译 C++ 扩展 |
| Git | 任意 | 版本控制 |
| Python | 3.12（E:\Python312） | godot-cpp 编译依赖 |

## 八、C++ 扩展编译

```bash
# Windows 命令行
build-marry.bat

# 或 Visual Studio
# 打开 CMakeLists.txt → 生成 → 编译
```

编译产物输出到 `bin/marry.dll`，Godot 通过 `marry.gdextension` 自动加载。

---

遇到文档没覆盖的情况，先 `git pull`，再对照场景处理；拿不准就问对方/管理员，不要乱执行 force 相关命令。