Git_Gogs代码下载完整指南.md

@@ -0,0 +1,276 @@
+# Git Gogs 代码下载完整指南
+
+> 仓库地址: https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync  
+> 最后更新: 2026-10-08
+
+---
+
+## 一、当前仓库状态
+
+```
+最新提交: ddf5039 init: 初始化项目，添加 README 和自动同步方案文档
+分支: main
+文件:
+  ├── README.md
+  └── Git代码自动同步详细说明.md
+```
+
+---
+
+## 二、下载方式总览
+
+| 方式 | 命令/操作 | 适用场景 | 是否需要 Git |
+|------|-----------|----------|-------------|
+| **git clone（HTTPS）** | `git clone <url>` | 日常开发，需后续修改和推送 | ✅ 需要 |
+| **git clone（SSH）** | `git clone git@...` | 已配置 SSH Key 的开发机 | ✅ 需要 |
+| **下载 ZIP 归档** | 浏览器点击下载 | 快速查看，不需要提交 | ❌ 不需要 |
+| **API 下载** | `curl` + Access Token | 服务器/脚本自动化 | ❌ 不需要 |
+| **wget 直接下载** | `wget` 指定分支/标签 | CI/CD 流水线 | ❌ 不需要 |
+
+---
+
+## 三、方式 1：git clone（HTTPS）—— 最常用
+
+### 3.1 基本克隆
+
+```bash
+# 克隆整个仓库（默认拉取 main 分支）
+git clone https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+
+# 克隆到指定目录
+git clone https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git my-project
+
+# 克隆时指定分支
+git clone -b main https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+```
+
+### 3.2 认证方式
+
+**方式 A：URL 中嵌入用户名密码**
+```bash
+git clone https://steven_roc:你的密码@git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+```
+
+**方式 B：URL 中嵌入 Access Token**
+```bash
+git clone https://steven_roc:你的Access_Token@git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+```
+
+**方式 C：使用 Git Credential 缓存（推荐，不用每次输入）**
+```bash
+# 首次克隆时会提示输入用户名和密码（填 Access Token）
+git clone https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+
+# 缓存凭证 1 小时
+git config --global credential.helper 'cache --timeout=3600'
+
+# 或永久存储（写入 ~/.git-credentials）
+git config --global credential.helper store
+```
+
+### 3.3 克隆后目录结构
+
+```
+git_gog_code_sync/
+├── .git/                          # Git 元数据
+├── README.md                      # 项目说明
+└── Git代码自动同步详细说明.md       # 完整技术方案
+```
+
+---
+
+## 四、方式 2：git clone（SSH）
+
+### 4.1 前提：配置 SSH Key
+
+```bash
+# 生成密钥（如果还没有）
+ssh-keygen -t ed25519 -C "steven_roc@zhonjin.com"
+
+# 查看公钥并添加到 Gogs
+cat ~/.ssh/id_ed25519.pub
+# → 登录 Gogs → 设置 → SSH 密钥 → 添加密钥
+
+# 测试连接
+ssh -T -p 40717 git@git.zhonjin.com
+```
+
+### 4.2 SSH 克隆
+
+```bash
+git clone git@git.zhonjin.com:steven_roc/git_gog_code_sync.git
+```
+
+---
+
+## 五、方式 3：浏览器下载 ZIP
+
+### 5.1 操作步骤
+
+1. 打开浏览器访问：https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync
+2. 点击分支选择器（默认显示 `main`）
+3. 点击 **「下载存档」** 按钮
+4. 选择 `ZIP` 格式下载
+
+### 5.2 直接下载链接
+
+```
+# main 分支 ZIP
+https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync/archive/main.zip
+
+# main 分支 TAR.GZ
+https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync/archive/main.tar.gz
+```
+
+> ⚠️ 浏览器访问需要登录 Gogs 账号
+
+---
+
+## 六、方式 4：API + Access Token 下载
+
+### 6.1 下载 ZIP 归档
+
+```bash
+# 使用 Access Token 下载 main 分支 ZIP
+curl -sk -o git_gog_code_sync.zip \
+  -H "Authorization: token 你的Access_Token" \
+  "https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync/archive/main.zip"
+
+# 解压
+unzip git_gog_code_sync.zip
+```
+
+### 6.2 通过 API 获取文件列表
+
+```bash
+# 查看仓库根目录文件列表
+curl -sk -H "Authorization: token 你的Access_Token" \
+  "https://git.zhonjin.com:40717/api/v1/repos/steven_roc/git_gog_code_sync/contents/"
+
+# 获取某个文件内容（base64 编码）
+curl -sk -H "Authorization: token 你的Access_Token" \
+  "https://git.zhonjin.com:40717/api/v1/repos/steven_roc/git_gog_code_sync/contents/README.md"
+```
+
+### 6.3 获取指定 commit 的代码
+
+```bash
+# 先查看提交历史，获取 commit SHA
+curl -sk -H "Authorization: token 你的Access_Token" \
+  "https://git.zhonjin.com:40717/api/v1/repos/steven_roc/git_gog_code_sync/commits?sha=main&limit=5"
+
+# 下载指定 commit 的代码
+curl -sk -o specific_commit.zip \
+  -H "Authorization: token 你的Access_Token" \
+  "https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync/archive/<commit_sha>.zip"
+```
+
+---
+
+## 七、方式 5：wget 直接下载
+
+```bash
+# 下载 main 分支 ZIP（需要认证）
+wget --no-check-certificate \
+  --user=steven_roc --password=你的Access_Token \
+  -O git_gog_code_sync.zip \
+  "https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync/archive/main.zip"
+```
+
+---
+
+## 八、克隆后获取最新代码
+
+克隆完成后，后续更新到最新代码：
+
+```bash
+cd git_gog_code_sync
+
+# 拉取最新代码（推荐 rebase 方式，保持提交历史干净）
+git pull --rebase origin main
+
+# 或传统 merge 方式
+git pull origin main
+
+# 查看更新日志
+git log --oneline -5
+```
+
+---
+
+## 九、下载指定版本/标签
+
+```bash
+# 查看所有标签
+git ls-remote --tags https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+
+# 克隆并切换到特定标签
+git clone https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+cd git_gog_code_sync
+git checkout v1.0.0
+
+# 或一步到位
+git clone --branch v1.0.0 --depth 1 \
+  https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+```
+
+---
+
+## 十、浅克隆（加速下载大仓库）
+
+```bash
+# 只下载最新 1 次提交（速度快，适合只看最新代码）
+git clone --depth 1 https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+
+# 如果后续需要完整历史
+cd git_gog_code_sync
+git fetch --unshallow
+```
+
+---
+
+## 十一、各场景推荐方案
+
+| 场景 | 推荐方式 | 命令 |
+|------|----------|------|
+| 开发机日常开发 | git clone HTTPS | `git clone <url>` |
+| 树莓派/服务器 | git clone SSH | `git clone git@...` |
+| 快速查看代码 | 浏览器下载 ZIP | 直接访问仓库页 |
+| CI/CD 自动化 | API + Token | `curl -H "Authorization: token ..."` |
+| 只看最新代码 | 浅克隆 | `git clone --depth 1` |
+| 下载特定历史版本 | API 获取 commit SHA | `archive/<sha>.zip` |
+
+---
+
+## 十二、常见问题
+
+### Q: 克隆时提示 SSL 证书错误？
+```bash
+# 临时跳过 SSL 验证（自签名证书场景）
+GIT_SSL_NO_VERIFY=true git clone https://git.zhonjin.com:40717/steven_roc/git_gog_code_sync.git
+
+# 或永久配置（不推荐，仅内网环境使用）
+git config --global http.sslVerify false
+```
+
+### Q: 克隆后看不到其他分支？
+```bash
+# 查看所有远程分支
+git branch -r
+
+# 切换到远程的某个分支
+git checkout -b local-branch origin/remote-branch
+```
+
+### Q: 下载速度太慢？
+```bash
+# 使用浅克隆减少数据量
+git clone --depth 1 --single-branch <url>
+
+# 或使用 SSH（通常比 HTTPS 快）
+git clone git@git.zhonjin.com:steven_roc/git_gog_code_sync.git
+```
+
+---
+
+*文档维护: 每次下载方式变更时更新本文档*