From c286aed1d9b0899e9847033992f5901097684b01 Mon Sep 17 00:00:00 2001
From: wangruiguo <wangruiguo@example.com>
Date: Thu, 3 Sep 2026 17:57:55 +0800
Subject: [PATCH] =?UTF-8?q?=E6=96=87=E6=A1=A3:=20=E6=96=B0=E5=A2=9E=20Git?=
 =?UTF-8?q?=20=E4=BD=BF=E7=94=A8=E8=AF=B4=E6=98=8E?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 docs/Git使用说明.md | 74 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 74 insertions(+)
 create mode 100644 docs/Git使用说明.md

diff --git a/docs/Git使用说明.md b/docs/Git使用说明.md
new file mode 100644
index 0000000..4326712
--- /dev/null
+++ b/docs/Git使用说明.md
@@ -0,0 +1,74 @@
+# Git 版本管理使用说明（Gitea）
+
+> 代码已托管在 Gitea，Web 界面可看历史、diff、回滚。
+> **仓库地址**：https://git.ruiguo.wang/wangruiguo/OnebotCatalog.git
+> **Web 界面**：https://git.ruiguo.wang
+
+---
+
+## 一、日常提交（改动后存一版）
+
+```bash
+git add -A
+git commit -m "说明这次改了什么"
+git push
+```
+
+三步搞定：暂存 → 提交（本地留档）→ 推送（上传到服务器备份）。
+
+## 二、看历史 / 看改了啥
+
+```bash
+git log --oneline          # 提交列表（短格式）
+git log -p                 # 每次提交的详细改动
+git status                 # 当前有哪些文件改动未提交
+git diff                   # 具体改了什么内容
+```
+
+**更直观**：直接浏览器打开 https://git.ruiguo.wang 看，图形化看历史、diff、每个文件。
+
+## 三、回滚（改坏了想退回）
+
+```bash
+# 1. 查看历史，找到要退回的版本号（commit 前 7 位）
+git log --oneline
+
+# 2. 退回到某个版本（保留后续改动在工作区）
+git checkout <版本号> -- <文件名>
+
+# 3. 整个仓库回到某个版本（危险，会丢弃之后所有提交，慎用）
+git reset --hard <版本号>
+```
+
+**最安全**：在 Web 界面找到旧版本的某个文件 → 直接下载覆盖，再 commit。
+
+## 四、新电脑拉取代码
+
+```bash
+git clone https://git.ruiguo.wang/wangruiguo/OnebotCatalog.git
+```
+
+之后改代码提交推送即可，和上面的日常提交一样。
+
+---
+
+## ⚠️ 重要：哪些文件不入 git（.gitignore 已配好）
+
+以下大文件**不会**上传到 Gitea（版本管理只存代码和文档）：
+
+- PDF、Excel、报价单
+- STEP/STP/IGES/STL 数模文件（4138 个，体积大）
+- exe/dll 编译产物、.opc 数据包
+- 图片（手册页 PNG 等）
+
+**这些大文件靠其他方式备份**（如直接拷盘/群晖同步），git 只管"代码 + 文档 + 配置"。
+
+---
+
+## 五、常见问题
+
+| 问题 | 解决 |
+|---|---|
+| push 报认证失败 | 用 Gitea 账号密码登录，或用 SSH 地址 `ssh://git@git.ruiguo.wang:40846/wangruiguo/OnebotCatalog.git` |
+| 提示 ROOT_URL 不匹配 | 用 `https://git.ruiguo.wang` 访问，不要用 IP 访问 |
+| 忘了提交了哪些 | `git status` + `git log` |