git-push

# 一键推送 GitHub

## 功能说明

把当前项目一键推送到 GitHub，覆盖完整生命周期：

- **首次推送** — 新项目从零到 GitHub
- **日常更新** — 改了文件，推一下（commit + push）
- **版本发布** — 打 tag + 创建 Release，可附带下载文件

核心原则：**安全第一**。宁可多问一句，不能把不该推的东西推上去。

---

## 工作流程

### 第0步：环境检查 + 模式判断

依次检查前置条件，任一不满足就终止并给出指引：

**1. git 是否安装**
- ❌ → 提示：`brew install git`，终止
- ✅ → 继续

**2. gh CLI 是否安装**
- ❌ → 提示：`brew install gh`，终止
- ✅ → 继续

**3. gh 是否已登录 GitHub**
- 执行 `gh auth status` 检查
- ❌ 未登录 → 提示：`gh auth login`，终止
- ✅ 已登录 → 记录账号名，告诉用户"当前登录账号：[xxx]"，继续

**4. git 用户信息是否配置**
- 执行 `git config user.name` 和 `git config user.email` 检查
- ❌ 未配置 → 提示用户设置：
  ```
  git config --global user.name "你的名字"
  git config --global user.email "你的邮箱"
  ```
  终止
- ✅ 已配置 → 继续

**5. 当前目录是否已是 git 仓库 → 决定走哪条路**

```
不是 git 仓库 → 【首次推送】从第1步开始
是 git 仓库，无 remote → "本地有 git 但没关联远程"
    → 先执行第1步的大文件扫描（确保安全）
    → 再跳到第2步关联远程
是 git 仓库，有 remote → 【已有仓库】进入模式选择：
    ├── "推日常更新" → 跳到第3B步（日常更新）
    ├── "发新版本"   → 检查是否有未提交的变更
    │   ├── 有变更 → 先走第3B步，再走第4步
    │   └── 无变更 → 直接跳到第4步（只打 tag + Release）
    └── "重新来"
        → ⚠️ 警告："这将删除所有 Git 历史记录（包括所有提交、分支、tag），不可恢复。"
        → 用户二次确认后删除 .git，从第1步开始
```

---

### 第1步：项目扫描 + .gitignore 生成

> **⚠️ 铁律：.gitignore 必须在第一次 `git add` 之前就位。绝不能先提交再排除——Git 历史里的大文件删不干净，会导致仓库臃肿、推送失败。**

#### 1.1 扫描目录大小

用 `du -sh` 扫描所有顶级目录和文件，按大小排序。

**大文件分级处理：**

| 大小 | 处理方式 |
|------|----------|
| **>10MB** | 列出，逐个问用户"要推吗？" |
| **>50MB** | 额外警告"较大，推送会比较慢" |
| **单文件 >100MB** | **必须排除**，GitHub 硬限制，推不上去 |

**展示格式**（示例）：

```
扫描发现以下内容超过 10MB：

  1. 109MB  slides/   （PPT + 大图片）
  2.  12MB  assets/   （视频文件）

⚠️ 其中 slides/ 超过 50MB，推送会很慢。
❌ 其中 recording.mp4 (150MB) 超过 GitHub 100MB 单文件限制，必须排除。

要排除哪些？（输入序号，或 "全部排除" / "全部保留"）
```

#### 1.2 敏感内容扫描（仅公开仓库）

如果用户选了公开仓库，额外扫描：

- `.env` / `.env.*` — 环境变量/密钥
- `*secret*` / `*credential*` / `*token*` — 密钥文件
- `*.pem` / `*.key` — 证书文件
- `memory/` / `MEMORY.md` — AI 工具记忆文件
- 任何看起来像私人内容的文件

列出建议排除项，让用户逐项确认。

#### 1.3 生成或更新 .gitignore

**如果不存在 .gitignore**：基于扫描结果生成新文件。

**如果已存在 .gitignore**：读取现有内容，将新增排除项合并进去，展示差异让用户确认。不覆盖用户已有的规则。

基础模板：

```gitignore
# macOS
.DS_Store
.AppleDouble
.LSOverride
._*

# Editor
*.swp
*.swo
*~
.vscode/
.idea/

# [以下根据扫描结果动态生成]
# 大文件（用户确认排除）
[路径1]
[路径2]

# 敏感内容（仅公开仓库时）
[路径3]
```

展示给用户确认后写入文件。

---

### 第2步：用户决策

**1. 仓库名**（默认：当前目录名）

**2. 描述**（一句话，可留空）

**3. 公开 / 私有**
- 公开 → 二次确认："公开仓库所有人可见，确认 .gitignore 已排除敏感内容？"
  - 不确认 → 回到第1.2步（敏感内容扫描）重新审查，完成后回到本步骤继续

**4. 检查同名仓库**
- 执行 `gh repo view [账号]/[仓库名]` 检查
- ❌ 不存在 → 继续
- ✅ 已存在 → 告诉用户，问：
  - "换个名字" → 重新输入
  - "用这个已有仓库" → 跳过创建，直接关联 remote（记录仓库 URL 供第3步使用）
  - "删掉重建" → 需用户二次确认

---

### 第3步：推送

#### 3A. 首次推送（新项目）

按以下顺序严格执行：

```
1. git init + git branch -m main
2. git add -A
3. git commit -m "init: 初始化 [仓库名]"
4. 创建远程仓库（如果第2步中仓库不存在）：
   gh repo create [仓库名] --private/--public --description "[描述]" --source=. --remote=origin
   （如果第2步中用户选了"用已有仓库"，跳过创建，直接：git remote add origin [已有仓库URL]）
5. git push -u origin main
```

#### 3B. 日常更新（已有仓库）

```
1. 扫描变更：git status 查看改了什么
2. 检查新增大文件：
   - 新增文件中有 >10MB 的 → 问用户确认
   - 新增文件中有单文件 >100MB → 必须排除，加入 .gitignore
   - 如果修改了 .gitignore，确保 .gitignore 本身也在后续的 git add 范围内
3. git add -A
4. git commit -m "[根据变更内容自动生成提交信息]"
   - 提交信息规则：简洁明了，一句话概括主要变更
   - 示例："update: 新增用户模块 + 修复登录 bug"
5. git push
```

#### 推送失败处理

| 错误 | 原因 | 处理 |
|------|------|------|
| `rejected (fetch first)` 或 `non-fast-forward` | 远程有本地没有的提交 | 默认执行 `git pull --rebase` 后重试 |
| 仍然失败 / 远程有冲突 | 历史不兼容 | 问用户"是否强制覆盖远程？" ⚠️ 告知："这将覆盖远程所有内容，仅在确认远程内容可以丢弃时使用"→ `git push --force` |
| 超时/卡住 | 网络或仓库太大 | 检查仓库大小，建议排除大文件后重试 |
| 认证失败 | token 过期 | 提示 `gh auth login` |
| `file exceeds 100MB` | 单文件超限 | 提示具体文件名，加入 .gitignore，重新提交推送 |
| `git add` 或 `git commit` 失败 | 文件异常/配置缺失 | 显示错误信息，引导用户排查 |

---

### 第4步：可选 — 版本发布（Release）

#### 触发时机

- 首次推送后，主动问一次"需要打版本吗？"
- 日常更新后，**不主动问**（避免打扰）
- 用户主动说"发版本"、"打 release"、"打 tag"

#### 流程

**1. 确定版本号**

```
读取当前已有的 tag（git tag --sort=-v:refname | head -5）

├── 没有任何 tag → 建议 v0.1.0
└── 已有 tag → 显示最近的版本，建议下一个（默认 minor +1）
    - v0.1.0 → 建议 v0.2.0
    - v1.2.3 → 建议 v1.3.0
    - 用户可自定义输入任意版本号

版本号说明（供用户参考）：
- v0.1.0 → v0.2.0  小更新（加了功能、改了内容）
- v0.2.0 → v1.0.0  大里程碑（首次正式发布、重大重构）
- v1.0.0 → v1.0.1  修修补补（修了个 bug）
```

**2. Release 说明**
- 自动读取自上个 tag 以来的 commit 记录（`git log [上个tag]..HEAD --oneline`）
- 生成变更摘要，让用户确认或修改
- 如果是第一个版本（无历史 tag），用所有 commit 生成摘要

**3. 是否附带下载文件**

```
需要附带可下载文件吗？（如 App 安装包、工具压缩包等）

├── 不需要 → 只打 tag + 创建 Release 页面
└── 需要 → 用户提供文件路径
    └── 检查文件是否存在 → 不存在则提示重新输入
```

**4. 执行**

```
git tag [version]
git push origin [version]
gh release create [version] --title "[仓库名] [version]" --notes "[Release 说明]"
# 如果有附件：
gh release upload [version] [文件路径]
```

**Release 失败处理：**
- tag 已存在 → 提示用户"这个版本号已被使用"，让用户换一个
- 附件文件不存在 → 提示重新输入路径
- 其他错误 → 显示错误信息

---

### 完成输出

```
✅ 推送完成！

- 仓库：[URL]
- 可见性：私有 / 公开
- 文件数：[N] 个
- 仓库大小：[X]
- 排除项：[列出被 .gitignore 排除的内容]
- Release：[版本号 + URL] / 未创建
```

---

## 核心原则

### 1. 扫描先于一切

.gitignore 在第一次 `git add` 之前就位。大文件一旦进入 Git 历史，即使后来删除，仓库体积也不会缩小，会导致推送失败或极慢。已有 git 但未关联远程的项目，也要先扫描再推送。

### 2. 大文件主动拦截

10MB 以上主动问用户。50MB 以上警告慢，100MB 单文件是 GitHub 硬限制必须排除。**日常更新时也要检查新增文件大小。**

### 3. 公开仓库双重检查

公开仓库额外扫描敏感内容（密钥、AI 记忆文件、私人文档），并在推送前二次确认。

### 4. 不破坏已有内容

如果项目已有 .git 或 .gitignore，默认不覆盖，先问用户。删除 .git 等破坏性操作必须明确警告后果并二次确认。

### 5. 每一步可中断

用户随时可以说"停"或"回到上一步"。不要一口气跑完不给用户反应的机会。

### 6. 日常更新要轻

日常更新不问 Release、不问仓库名、不重新扫描全项目。只检查新增大文件，commit + push，快进快出。

---

## 使用示例

### 场景1：新项目首次推送

```
用户：帮我推到 GitHub

Skill：
→ 检查环境：git ✅ gh ✅ 已登录 ✅ git 用户已配置 ✅ 不是 git 仓库
→ 扫描项目...发现超过 10MB 的内容：
  - 85MB slides/ → 用户确认排除
  - 15MB images/ → 用户确认保留
→ 生成 .gitignore，用户确认
→ 仓库名：my-project，私有
→ 初始化 + 推送成功
→ "需要打 Release 吗？" → 跳过
→ ✅ 完成
```

### 场景2：日常更新

```
用户：推一下

Skill：
→ 检测到已关联远程仓库
→ 扫描变更：修改 3 个文件，新增 2 个文件（均 <10MB）
→ 提交信息："update: 新增用户模块 + 更新配置文件"
→ 推送成功
→ ✅ 完成
```

### 场景3：发版本

```
用户：打个 release

Skill：
→ 当前最新 tag：v0.1.0
→ "建议下一个版本号 v0.2.0，可以吗？"
→ 自动生成变更摘要（基于 commit 记录）
→ "需要附带下载文件吗？" → 不需要
→ 创建 tag + Release
→ ✅ Release v0.2.0 发布成功！
```

### 场景4：推送时发现大文件

```
→ git push 失败：file recording.mp4 exceeds 100MB
→ "recording.mp4 (150MB) 超过 GitHub 限制，需要排除"
→ 加入 .gitignore，重新提交推送
→ ✅ 成功
```

### 场景5：日常更新时新增大文件

```
用户：推一下

→ 扫描变更...发现新增文件：
  - demo.pptx (25MB)
→ "这个文件 25MB，确认要推吗？"
→ 用户确认排除 → 加入 .gitignore
→ 推送成功
→ ✅ 完成
```

### 场景6：发版本但没有新变更

```
用户：打个 release

→ 当前没有未提交的变更，直接进入版本发布
→ 当前最新 tag：v0.2.0
→ "建议 v0.3.0，可以吗？"
→ 用户自定义输入 v1.0.0
→ 生成变更摘要 + 创建 Release
→ ✅ Release v1.0.0 发布成功！
```