113 行
3.9 KiB
Markdown
113 行
3.9 KiB
Markdown
# 协作规范（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 相关命令。
|