增加兼容性

2026-02-17 18:05:30 +08:00
parent e78e33731b
commit 3af0c0dcc8
7 changed files with 440 additions and 59 deletions
--- a/README.md
+++ b/README.md
@@ -1,26 +1,31 @@
 # QuickGit - 萌芽一键Git管理工具

-一个纯 Python 3.6+、零外部依赖的彩色 CLI 工具，用模块化方式把常用 Git 操作“一键化”，支持 Windows / Linux / macOS。
+一个纯 Python 3.6+、零外部依赖的彩色 CLI 工具，用模块化方式把常用 Git 操作"一键化"，支持 Windows / Linux / macOS。
+
+**⚠️ 重要说明：** 本工具目前仅支持通过 **SSH 方式**连接 GitHub 和 Gitea 远程仓库，不支持 HTTPS 方式。使用前请确保已配置 SSH 密钥。

 ## 1) 项目简介与核心卖点
 - 模块化架构，功能职责清晰，易扩展。
 - 无三方依赖，直接随 Python 运行。
 - 跨平台路径与编码适配，默认分支 `main`。
 - 彩色输出 + ASCII 分隔线，兼顾可读性与兼容性。
+- **SSH 优先策略**：仅支持 SSH 连接，更安全、更便捷。

 ## 2) 功能清单
 - [x] 灵活目录选择（启动时可管理任意仓库）
 - [x] 初始化仓库（创建分支、生成 `.gitignore`）
 - [x] 提交更改（提交到本地仓库）
- [x] 推送更改（推送到远程仓库，支持多远程选择）
- [x] 从远程拉取
- [x] 远程仓库管理（GitHub / Gitea，SSH 优先）
+- [x] 推送更改（推送到远程仓库，支持多远程选择，**仅支持 SSH**）
+- [x] 从远程拉取（**仅支持 SSH**）
+- [x] 远程仓库管理（GitHub / Gitea / 自建 Git 服务器，**仅支持 SSH 方式**）
+- [x] **可配置 Gitea 服务器**（自定义主机地址和端口）
+- [x] **自建 Git 仓库支持**（GitLab、自建 Gitea、Gogs 等）
 - [x] 状态查看（工作区状态 + 最近提交）
 - [ ] 分支管理
 - [ ] 标签管理
 - [ ] 冲突解决辅助
- [ ] 自定义配置文件
 - [ ] 批量处理多个仓库
+- [ ] HTTPS 支持（未来版本）

 ## 3) 项目结构
 ```
@@ -40,7 +45,33 @@ QuickGit/
 ```

 ## 4) 快速开始
-前置要求：已安装 Git，Python 3.6+；已配置 SSH 密钥（推荐用 SSH 访问远程仓库）。
+
+### 前置要求
+1. **必需**：已安装 Git 和 Python 3.6+
+2. **必需**：已配置 SSH 密钥并添加到 GitHub/Gitea 账户
+3. **推荐**：使用支持 ANSI 颜色的终端（Windows Terminal、PowerShell、iTerm2 等）
+
+### SSH 密钥配置指南
+如果你还没有配置 SSH 密钥，请按以下步骤操作：
+
+```bash
+# 1. 生成 SSH 密钥（如果还没有）
+ssh-keygen -t ed25519 -C "your_email@example.com"
+
+# 2. 查看公钥内容
+cat ~/.ssh/id_ed25519.pub    # Linux/macOS
+type %USERPROFILE%\.ssh\id_ed25519.pub    # Windows
+
+# 3. 将公钥添加到远程仓库
+# - GitHub: Settings -> SSH and GPG keys -> New SSH key
+# - Gitea: 设置 -> SSH/GPG 密钥 -> 添加密钥
+
+# 4. 测试连接
+ssh -T git@github.com                           # 测试 GitHub
+ssh -T git@git.shumengya.top -p 8022           # 测试 Gitea
+```
+
+### 启动程序

 **Windows**
 ```bash
@@ -73,13 +104,81 @@ python3 quickgit.py
 ```

 ## 6) 常用操作示例
- 初始化仓库：选择目录 → 选 1 → 自动创建 `.gitignore`（含前端/后端通用规则）并尝试首提。
- 提交更改：选 2 → 查看更改 → 输入提交信息（留空自动填入时间戳）→ 提交到本地仓库。
- 推送更改：选 3 → 选择远程（可多选）→ 推送到远程仓库。
- 拉取更新：选 4 → 选择远程 → 拉取当前分支。
- 远程管理：选 6 → 支持添加/删除远程；URL 模板  
-  - GitHub: `git@github.com:shumengya/{repo}.git`  
-  - Gitea : `ssh://git@git.shumengya.top:8022/{user}/{repo}.git`
+
+### 场景0: 选择工作目录
+- 启动时输入要管理的仓库路径
+- 支持绝对路径、相对路径、`~` 路径
+- 直接回车使用当前目录
+
+### 场景1: 初始化新仓库
+1. 选择 [1] 初始化Git仓库
+2. 自动创建 `.gitignore`（含前端/后端通用规则）
+3. 自动创建 `main` 分支并进行首次提交
+4. 选择 [6] 管理远程仓库 → 添加 GitHub 或 Gitea 远程仓库（**仅 SSH**）
+
+### 场景2: 日常提交工作流
+1. 选择 [2] 提交更改到本地
+   - 查看更改的文件
+   - 输入提交信息（留空自动填入时间戳）
+   - 代码提交到本地仓库
+2. 选择 [3] 推送到远程仓库
+   - 选择远程仓库（可多选）
+   - 通过 SSH 推送到远程
+
+### 场景3: 拉取远程更新
+1. 选择 [4] 从远程仓库拉取
+2. 选择远程仓库（单选）
+3. 通过 SSH 拉取当前分支的更新
+
+### 场景4: 管理远程仓库
+
+选择 [6] 管理远程仓库，提供以下功能：
+
+#### 4.1 添加 GitHub 远程仓库
+SSH 格式：`git@github.com:shumengya/{repo}.git`
+
+#### 4.2 添加 Gitea 远程仓库
+SSH 格式：`ssh://git@git.shumengya.top:8022/{user}/{repo}.git`
+
+默认使用配置的 Gitea 服务器地址和端口，可通过"配置 Gitea 服务器"修改。
+
+#### 4.3 添加自建 Git 仓库
+支持添加自定义 Git 服务器（GitLab、自建 Gitea、Gogs 等）：
+1. 输入远程仓库名称（如：`gitlab`、`mygit`）
+2. 输入完整的 SSH URL
+3. 支持的 URL 格式示例：
+   - `git@gitlab.com:user/repo.git`
+   - `ssh://git@your-server.com:port/user/repo.git`
+
+#### 4.4 配置 Gitea 服务器
+自定义 Gitea 服务器的主机地址和 SSH 端口：
+- 默认主机：`git.shumengya.top`
+- 默认端口：`8022`
+- 配置保存在：`~/.quickgit_config.json`
+
+#### 4.5 其他功能
+- **查看所有远程仓库** - 显示已配置的远程仓库列表
+- **删除远程仓库** - 移除不需要的远程仓库
+
+**⚠️ 注意：** 本工具不支持 HTTPS URL 格式（如 `https://github.com/user/repo.git`），仅支持 SSH 格式。
+
+### 场景5: 配置文件
+
+QuickGit 的配置文件保存在：`~/.quickgit_config.json`
+
+**配置内容：**
+```json
+{
+  "gitea_host": "git.shumengya.top",
+  "gitea_port": "8022",
+  "github_user": "shumengya",
+  "default_branch": "main"
+}
+```
+
+**修改方式：**
+- 通过菜单：[6] 管理远程仓库 → [5] 配置 Gitea 服务器
+- 或手动编辑配置文件（需重启工具生效）

 ## 7) 跨平台与终端要求
 - `run.bat` 自动设置 UTF-8；Windows 使用 `python` 命令。
@@ -99,18 +198,41 @@ python3 quickgit.py
 - 默认分支 `main`；`.gitignore` 自动写入成功。

 ## 10) 常见问题 / 故障排查
- 推送失败：确认 SSH 密钥已添加且远程地址正确。
- 终端乱码：设置 UTF-8（Windows 可 `chcp 65001`；Linux/macOS 确保 `LANG/LC_ALL` 为 UTF-8）。
- 颜色不显示：使用支持 ANSI 的终端（Windows Terminal/PowerShell 等）。
- 找不到 `python3`：在 Linux/macOS 安装或创建软链接；Windows 使用 `python`。
+
+### SSH 相关问题
+- **推送/拉取失败 "Permission denied (publickey)"**：
+  - 确认 SSH 密钥已生成：`ls ~/.ssh/id_*.pub` (Linux/macOS) 或 `dir %USERPROFILE%\.ssh\id_*.pub` (Windows)
+  - 确认公钥已添加到 GitHub/Gitea 账户
+  - 测试 SSH 连接：`ssh -T git@github.com` 或 `ssh -T git@git.shumengya.top -p 8022`
+  
+- **"Could not resolve hostname"**：
+  - 检查网络连接
+  - 确认远程仓库地址格式正确（SSH 格式，非 HTTPS）
+  
+- **端口被防火墙拦截**：
+  - GitHub 使用标准 SSH 端口 22
+  - Gitea 使用自定义端口 8022，确保防火墙允许此端口
+
+### 远程仓库相关
+- **不支持 HTTPS URL**：本工具仅支持 SSH 方式，如果你的远程仓库使用 HTTPS URL（如 `https://github.com/user/repo.git`），请手动改为 SSH 格式或使用 `git remote` 命令修改。
+
+### 终端显示问题
+- **终端乱码**：设置 UTF-8（Windows 可 `chcp 65001`；Linux/macOS 确保 `LANG/LC_ALL` 为 UTF-8）。
+- **颜色不显示**：使用支持 ANSI 的终端（Windows Terminal/PowerShell 等）。
+- **找不到 `python3`**：在 Linux/macOS 安装或创建软链接；Windows 使用 `python`。

 ## 11) 路线图
 - [x] 模块化架构重构
+- [x] SSH 方式支持（GitHub + Gitea）
+- [x] 可配置 Gitea 服务器
+- [x] 自建 Git 仓库支持（GitLab、自建 Gitea 等）
+- [x] 配置文件持久化
+- [ ] HTTPS 方式支持
 - [ ] 分支管理
 - [ ] 标签管理
 - [ ] 冲突解决辅助
- [ ] 自定义配置文件
 - [ ] 批量操作多个仓库
+- [ ] 更多 Git 托管平台支持（Bitbucket 等）

 ## 12) 许可证与作者
 - 许可证：MIT