guzhujushi
bcdbdd35a3
- STATUS.md：Gitea 接入标记完成，补充远端/分支/推送通道信息； 新增决策 19（SSH 走 Tailscale 内网）与 20（首次推送 force-with-lease 的取舍） - docs/05-git-workflow.md：第三节改写为实际拓扑（公网 22 被过滤、 走 Tailscale + ~/.ssh/config 域名别名），补自检、日常推送、换机步骤， 并保留仓库归属注意、补充可见性与协作者说明； 回滚一节记录被覆盖提交的恢复命令
191 lines
5.6 KiB
Markdown
191 lines
5.6 KiB
Markdown
# 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 网页 | https://code.guzhujushi.cn/guzhujushi/MCM-ICM_Toolkit |
|
||
| 服务器公网 IP | `8.145.36.108`（实测只开了 443，**22 被防火墙过滤**） |
|
||
| 服务器 Tailscale IP | `100.115.86.48`（22 开放） |
|
||
| 本机 Tailscale IP | `100.124.243.30` |
|
||
| git 远端 | `git@code.guzhujushi.cn:guzhujushi/MCM-ICM_Toolkit.git` |
|
||
|
||
### 为什么走 Tailscale
|
||
|
||
公网 22 端口连不上（`ssh: connect to host code.guzhujushi.cn port 22: Connection timed out`），
|
||
但同一台机器的 Tailscale 地址 22 端口是通的，且 `git@` 认证直接通过 Gitea。
|
||
所以 `~/.ssh/config` 里加了一条别名把域名指到内网地址：
|
||
|
||
```sshconfig
|
||
Host code.guzhujushi.cn
|
||
HostName 100.115.86.48
|
||
User git
|
||
IdentityFile ~/.ssh/id_ed25519
|
||
```
|
||
|
||
这样 remote 里写的是域名，换机时只改这一段 config，不用动仓库配置。
|
||
|
||
**推送前先连上 Tailscale**，否则 `git push` 会一直等到超时。
|
||
|
||
### 自检
|
||
|
||
```powershell
|
||
ssh -T git@code.guzhujushi.cn
|
||
# 期望输出：Hi there, guzhujushi! You've successfully authenticated with the key named ...
|
||
```
|
||
|
||
### 日常推送
|
||
|
||
```powershell
|
||
cd D:\MCM&ICM_Toolkit
|
||
git add -A
|
||
git commit -m "feat(stats): 实现 bootstrap_ci"
|
||
git push
|
||
```
|
||
|
||
### 换一台机器 / 加一个协作者
|
||
|
||
```powershell
|
||
# 1) 装 Tailscale 并加入同一个 tailnet
|
||
# 2) 生成并上传密钥
|
||
ssh-keygen -t ed25519 -C "your@email"
|
||
Get-Content "$env:USERPROFILE\.ssh\id_ed25519.pub" | Set-Clipboard
|
||
# 粘贴到 Gitea → 设置 → SSH/GPG 密钥
|
||
# 3) 写上面的 ~/.ssh/config 别名
|
||
# 4) 克隆
|
||
git clone git@code.guzhujushi.cn:guzhujushi/MCM-ICM_Toolkit.git
|
||
```
|
||
|
||
不想用 Tailscale 的话，也可以用 HTTPS + Gitea 访问令牌，
|
||
代价是每次推送要输凭据（或交给凭据助手缓存）：
|
||
|
||
```powershell
|
||
git remote add origin https://code.guzhujushi.cn/guzhujushi/MCM-ICM_Toolkit.git
|
||
```
|
||
|
||
> 注意：`git config --global http.proxy` 目前指向 UniClash（`127.0.0.1:7993`），
|
||
> HTTPS 方式会被代理绕一圈；SSH 方式不受该配置影响。
|
||
|
||
### 仓库归属注意（重要）
|
||
|
||
`.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 的归属检查会误报。
|
||
|
||
### 可见性与协作者
|
||
|
||
匿名 `git ls-remote` 实测可读 → 仓库当前是 **Public**。要改私有：
|
||
仓库设置 → 基本设置 → 可见性。加队友：仓库设置 → 协作者 → 添加成员。
|
||
|
||
## 四、给队友的说明
|
||
|
||
队友 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
|
||
# 远端被覆盖过一次（首次推送），那个提交仍在本机对象库里：
|
||
# git push origin 1c683cf:refs/heads/restore-initial
|
||
|
||
# conda 自己保留了 revision 历史
|
||
conda list -n base --revisions
|
||
conda install -n base --revision <N>
|
||
|
||
# 代码回滚
|
||
git log --oneline
|
||
git revert <commit>
|
||
```
|