3.9 KiB
协作规范（Collaboration Guide）
本文件是 Marry 项目的 Git 协作守则。两人协作前请先读完，遇到问题时对照这里的场景处理。
一、首次克隆项目
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。
原因： 对方先推送了新提交，你的本地历史落后了。
处理： 不要慌，按顺序执行：
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）后，其他人的本地历史与服务器对不上。 处理方式： 确认自己本地没有未推送的独特提交后：
git status # 先看有没有未提交改动
git fetch origin
git reset --hard origin/main # 丢弃旧历史，对齐服务器
git submodule update --init # 重新拉子模块
五、铁律（违反会坑队友）
-
永远不要
git push --force强制推送会覆盖服务器历史，所有已 clone 的人都会分叉。 除非要清理误提交（如密码泄露），且先通知所有人再操作。 -
提交推上服务器后，不要 reset / rebase / amend 改它 改已推送的历史 = 制造分叉。
-
两人不要同时改同一个文件 分工时尽量各管各的场景/模块。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++ 扩展编译
# Windows 命令行
build-marry.bat
# 或 Visual Studio
# 打开 CMakeLists.txt → 生成 → 编译
编译产物输出到 bin/marry.dll，Godot 通过 marry.gdextension 自动加载。
遇到文档没覆盖的情况，先 git pull，再对照场景处理；拿不准就问对方/管理员，不要乱执行 force 相关命令。