# Git 工作流与远程托管

> 本仓库**已初始化**：分支 `main`，首次提交 `5319589`（76 文件），工作区干净。
> 尚未配置远程，之后托管到你自己的 Gitea。

---

## 一、仓库约定

### 行尾

由 `.gitattributes` 强制：**仓库内一律 LF**，checkout 时不做自动转换。

原因：AGENTS.md 要求 shell 脚本 UTF-8 无 BOM + LF；而这个仓库会被队友在
Windows / WSL / Linux 上 clone。不固定行尾的话，每次提交都会出现
"整个文件都变了"的假 diff，review 时根本看不出真实改动。

例外：`*.bat` / `*.cmd` 保持 CRLF（cmd 解析需要）。

Windows 用户建议同时设：

```powershell
git config --global core.autocrlf false
git config --global core.eol lf
```

### 什么不入库

见 `.gitignore`。重点是三条：

| 忽略 | 为什么 |
|---|---|
| `.venv/`、`.conda/` | 环境可由 `scripts/setup-*.ps1` 重建，不该进版本库 |
| `problems/**/raw/`、`**/*.xlsx`、`problems/**/*.csv` | 赛题原始数据体积大、可重新下载；只提交**处理脚本和结论** |
| `figures/*.png`、`figures/*.pdf`、`tables/*.csv` | 中间产物。定稿的图请放进 `problems/<年份>_<题号>/figures/` 再提交 |

**判断标准：这个东西能不能由仓库里的其他文件重新生成？**
能 → 不入库。

---

## 二、日常提交

```powershell
git add -A
git commit -m "feat(stats): 实现 bootstrap_ci"
```

提交信息建议带模块前缀，方便以后回溯"这个函数是哪次加的"：

| 前缀 | 用途 |
|---|---|
| `feat(<模块>)` | 新增函数 / 功能 |
| `fix(<模块>)` | 修 bug |
| `test(<模块>)` | 只改测试 |
| `docs` | 只改文档 |
| `env` | 环境、依赖、脚本 |
| `chore` | 其他杂项 |

提交前跑一遍：

```powershell
.\scripts\doctor.ps1
```

它会同时检查 venv 和 conda 两套环境并跑测试。

---

## 三、推到自己的 Gitea

### 1. 在 Gitea 上建空仓库

不要勾选"初始化仓库"（不要生成 README / .gitignore / LICENSE），
否则首次 push 会冲突。

### 2. 加远程并推送

```powershell
cd D:\MCM&ICM_Toolkit

# 换成你自己的 Gitea 地址
git remote add origin https://git.你的域名/用户名/mcm-icm-toolkit.git

# 如果 Gitea 用的是自签证书，先在浏览器里访问一次并信任，或：
# git config --global http.sslBackend schannel

git branch -M main
git push -u origin main
```

### 3. 用 SSH（推荐，免密）

```powershell
ssh-keygen -t ed25519 -C "guzhu@mcm-toolkit"
Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub" | Set-Clipboard
# 粘贴到 Gitea → 设置 → SSH/GPG 密钥

git remote set-url origin git@git.你的域名:用户名/mcm-icm-toolkit.git
git push -u origin main
```

### 4. 仓库归属注意（重要）

`.git` 必须是**你自己的账户**创建的。若用沙箱化的 AI agent 通道代跑 `git init`，
它可能以别的账户身份创建 `.git`，之后你自己跑 git 就会报：

    fatal: detected dubious ownership in repository

正确做法是删掉重建（以本人账户）：

    Remove-Item -LiteralPath .git -Recurse -Force
    git init -b main

**不要**用 `git config --global --add safe.directory` 绕过——那只是把问题藏起来，
而且会让 git 在真正的归属异常时也不再警告。

同理，沙箱通道写出的文件 Owner 会是沙箱账户，但权限继承自
`Authenticated Users`（Modify），读写不受影响，只有 git 的归属检查会误报。

### 5. 如果不想公开

Gitea 建仓库时选 **Private**。队友通过
仓库设置 → 协作者 → 添加成员 授权。

---

## 四、给队友的说明

队友 clone 后只需要：

```powershell
git clone <你的仓库地址>
cd mcm-icm-toolkit
.\scripts\setup-venv.ps1      # 零下载，复用他们自己的 Anaconda base
.\scripts\doctor.ps1
```

`setup-venv.ps1` 用的是 `--system-site-packages`，所以他们本机得先有 Anaconda。
如果队友没有 Anaconda，让他走 `scripts/setup-conda.ps1`。

---

## 五、回滚

环境升级出问题时的回退手段：

```powershell
# conda 自己保留了 revision 历史
conda list -n base --revisions
conda install -n base --revision <N>

# 代码回滚
git log --oneline
git revert <commit>
```