Git Smart Update

---
name: git-smart-update
description: 智能 Git 更新工具，支持自动暂存、冲突解决和本地提交处理。当用户说"更新代码"、"拉取最新代码"、"git pull"、"更新当前分支"、"更新所有分支"、"保留本地修改并更新"时触发。自动处理 stash-update-restore 循环，智能解决冲突（优先采用远程改进，同时保留本地调试代码），支持 rebase 和 merge 两种模式。
metadata:
  category: Git 与协作
  tagline: "带 stash 循环的智能拉取，自动处理本地改动与冲突"
  example: "更新代码"
---

# Git 智能更新

智能更新 Git 仓库，同时保留本地修改。自动处理暂存-更新-还原循环，并智能解决合并冲突。

## 使用场景

当出现以下情况时使用此技能：
- 用户想更新/拉取代码，且有本地未提交的修改
- 用户说"更新代码"、"拉取最新"、"git pull 并保留我的修改"
- 用户提到更新分支（当前分支或所有分支）
- 你在 pull 操作前检测到未提交的修改
- 本地有已提交的代码，需要与远程同步

## 核心工作流程

### 步骤 1：分析当前状态

首先，了解当前的工作状态：

```bash
# 检查当前分支
git branch --show-current

# 检查未提交的本地修改
git status --porcelain

# 检查是否有 upstream 分支
git rev-parse --abbrev-ref --symbolic-full-name @{u}

# 检查本地是否有已提交但未推送的 commit
git log @{u}..HEAD --oneline
```

**判断点：**
- 无本地修改 → 直接进入更新流程
- 有未提交修改 → 进入暂存工作流
- 有本地 commit → 询问 rebase 还是 merge
- 无 upstream 分支 → 警告用户，询问处理方式

### 步骤 2：处理本地 Commit（如果存在）

检查本地是否有未推送的提交：

```bash
# 获取本地领先的 commit 数量
LOCAL_COMMITS=$(git log @{u}..HEAD --oneline | wc -l)
```

**如果有本地 commit（LOCAL_COMMITS > 0）：**

询问用户选择合并策略：

```
检测到你有 {N} 个本地提交尚未推送到远程。

你希望如何与远程更新合并？

1. **Rebase（变基）** - 推荐
   ✓ 提交历史更清晰线性
   ✓ 避免不必要的合并提交
   ⚠️ 会重写本地提交历史

2. **Merge（合并）**
   ✓ 保留原始提交历史
   ✓ 更安全的合并方式
   ⚠️ 会产生一个合并提交

请选择：rebase / merge
```

记录用户选择（`use_rebase`），用于后续的 pull 操作。

### 步骤 3：暂存本地修改（如果需要）

如果有未提交的本地修改：

```bash
git stash push -m "更新前自动暂存 - $(date '+%Y-%m-%d %H:%M:%S')"
```

记录 stash hash 以便后续验证。

### 步骤 4：获取远程更新

**重要：无论更新当前分支还是所有分支，都先 fetch 所有远程信息**

```bash
# 获取所有远程分支的更新信息
# 这样即使断网，也可以切换和合并其他分支
git fetch --all
```

这步的好处：
- 所有远程分支信息缓存到本地 `refs/remotes/origin/`
- 断网后仍可查看其他分支状态、切换分支、合并分支
- 只下载引用信息，不下载完整代码，速度快

### 步骤 5：合并远程更新到本地

**根据用户选择的策略执行：**

**当前分支**（默认）：

```bash
# 如果用户选择了 rebase
git rebase @{u}

# 如果用户选择了 merge 或未选择（默认）
git merge @{u}
```

**所有分支**（如果用户请求）：

```bash
# 遍历所有分支并更新
for branch in $(git branch -r | grep -v HEAD | sed 's/origin\///'); do
  git checkout $branch
  if [ "$use_rebase" = true ]; then
    git rebase @{u}
  else
    git merge @{u}
  fi
done

# 返回原分支
git checkout <original-branch>
```

**如果 pull 失败：**
- 清晰显示错误信息
- 立即还原暂存的修改：`git stash pop`
- 询问用户如何处理（网络问题？合并冲突？权限问题？）

### 步骤 6：还原本地修改

```bash
git stash pop
```

这可能会触发合并冲突，这是预期的，下一步会处理。

### 步骤 7：处理冲突

执行 `git stash pop` 后，检查冲突：

```bash
git status --porcelain | grep '^UU\|^AA\|^DD'
```

**如果无冲突：** 太好了！清理 stash 并完成。

**如果检测到冲突：** 进入智能冲突解决流程。

## 冲突解决策略

目标是同时保留远程的改进和本地的意图。

### 自动解决规则

1. **优先采用远程配置改进**
   - 如果远程将硬编码改为配置调用 → 使用远程版本
   - 示例：`bucket_name = "pdf"` → `bucket_name = config_manager.get_value(...)`

2. **保留本地调试/测试代码**
   - 如果本地注释掉了生产代码 → 保持注释状态
   - 如果本地禁用了清理/上传/外部调用 → 保持禁用状态

3. **合并互补的修改**
   - 远程添加了新导入/功能 + 本地注释掉了使用部分 → 保留两者
   - 远程重构了结构 + 本地修改了逻辑 → 尝试合并

### 解决流程

对于每个冲突文件：

1. **读取冲突标记**
   ```python
   <<<<<<< Updated upstream
   # 远程版本
   =======
   # 本地版本
   >>>>>>> Stashed changes
   ```

2. **分析语义差异**
   - 是配置 vs 硬编码？ → 优先使用远程配置
   - 是激活 vs 注释？ → 优先保留本地注释（调试模式）
   - 是冲突的逻辑？ → 询问用户

3. **应用解决方案**
   - 使用 Edit 工具将冲突标记替换为解决后的版本
   - 向用户解释推理过程

4. **验证解决方案**
   ```bash
   git add <resolved-file>
   ```

### 何时询问用户

以下情况无法自动解决：
- 两个版本以不同方式修改了相同的逻辑
- 不清楚哪个版本保留了用户的意图
- 结构性变更影响多行代码

**询问格式：**
```
在 <文件> 的第 <N> 行发现冲突：

远程版本：
<显示代码>

你的本地版本：
<显示代码>

两者都修改了 <修改内容>。你希望如何处理？
- 使用远程版本（并解释原因）
- 使用本地版本（并解释原因）
- 显示更多上下文
- 让我手动编辑
```

## 清理工作

成功解决冲突后：

```bash
# 删除已应用的 stash
git stash drop
```

## 特殊情况处理

### 无本地修改
```
✓ 未检测到本地修改
→ 直接拉取更新
✓ 更新成功
```

### 仅有未暂存修改
```
✓ 检测到 3 个文件的未提交修改
✓ 已暂存修改
✓ 已从 origin/develop 拉取更新
✓ 已还原本地修改
✓ 未发现冲突

摘要：
- 更新文件：5 个
- 保留你的调试代码：✓
```

### 有本地 Commit
```
✓ 检测到 2 个本地提交
? 选择合并策略：rebase / merge
→ 用户选择：rebase
✓ 已暂存未提交修改
✓ 已通过 rebase 拉取更新
✓ 已还原未提交修改
✓ 自动解决 1 个冲突
```

### Pull 失败
```
✗ 拉取失败：<错误信息>
→ 正在还原你的本地修改
✓ 本地修改已还原
? 你希望如何处理？
```

### 无 Upstream 分支
```
✗ 当前分支没有 upstream
? 你希望：
  - 设置 upstream 并拉取
  - 跳过此分支
  - 显示所有远程分支
```

## 输出格式

始终提供清晰的反馈：

```
📦 Git 智能更新
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

✓ 检测到 3 个文件有本地修改
✓ 检测到 2 个本地提交，使用 rebase 模式
✓ 已暂存修改
✓ 已获取所有远程分支信息（可离线操作）
✓ 已从 origin/develop 合并更新
✓ 已还原本地修改
✓ 自动解决 2 个冲突
✓ 已清理暂存

摘要：
- 更新文件：5 个
- 解决冲突：2 个
- 保留你的调试代码：✓
- 支持离线操作：✓

准备就绪！
```

## 分支更新模式

### 重要：离线操作支持

**无论更新当前分支还是所有分支，此 skill 都会先执行 `git fetch --all`**

这意味着：
- ✅ 所有远程分支信息被缓存到本地 `.git/refs/remotes/origin/`
- ✅ **断网后仍可自由操作**：
  - 切换到其他分支：`git checkout other-branch`
  - 查看其他分支状态：`git log origin/other-branch`
  - 合并其他分支：`git merge origin/other-branch`
  - 比较分支差异：`git diff origin/main..origin/develop`
- ✅ 只下载引用信息（几 KB），不下载完整代码，速度快
- ✅ 对网络带宽影响极小

**示例场景：**
```bash
# 有网络时
更新代码  # fetch --all，所有分支信息缓存到本地

# 断网后
git checkout feature-branch
git merge origin/feature-branch  # ✅ 成功！信息已在本地

# 甚至可以
git log origin/main..origin/develop  # 查看两个远程分支的差异
```

### 仅当前分支（默认）
- 快速且安全
- 只合并到你所在的分支
- 但已 fetch 所有分支信息供离线使用

### 所有分支（如果用户请求）
- 遍历并更新所有有 upstream 的分支
- 更耗时，可能触发多个冲突

**警告：** 更新所有分支更复杂，可能触发多个冲突。考虑先询问确认。

## Rebase vs Merge 详细说明

### Rebase 模式

**优点：**
- 提交历史线性清晰
- 没有不必要的合并提交
- git log 更易读

**缺点：**
- 会重写本地提交历史
- 如果已推送到远程，可能造成问题（通常本地 commit 未推送时使用）

**适用场景：**
- 本地 commit 未推送
- 希望保持历史整洁
- 团队推荐使用 rebase 工作流

**执行命令：**
```bash
git pull --rebase
```

如果 rebase 过程中有冲突：
```bash
# 解决冲突后
git add <resolved-files>
git rebase --continue

# 或放弃 rebase
git rebase --abort
```

### Merge 模式

**优点：**
- 保留原始提交历史
- 更安全，不会重写历史
- 适合协作开发

**缺点：**
- 会创建合并提交
- 历史可能有多个分叉

**适用场景：**
- 保守选择，更安全
- 团队使用 merge 工作流
- 不确定时选择此项

**执行命令：**
```bash
git pull
```

## 最佳实践

1. **始终解释你在做什么** - 用户应该理解整个流程
2. **在有帮助时显示差异** - 特别是冲突解决时
3. **保留用户意图** - 调试代码、注释部分、进行中的修改
4. **优雅失败** - 如果出现问题，还原状态并询问
5. **清理环境** - 不要留下过期的 stash
6. **提供选择** - rebase/merge 让用户决定
7. **验证结果** - 确保最终状态符合预期
8. **支持离线工作** - 通过 `git fetch --all` 缓存所有远程分支信息，断网后仍可操作其他分支

## 示例

### 示例 1：简单更新 + 调试代码

用户："更新代码"

流程：
1. 检测到 `app.py` 有未提交修改（注释掉的上传函数）
2. 暂存并添加消息
3. Fetch 所有远程分支信息（支持后续离线操作）
4. 合并当前分支的更新（远程改进了配置处理）
5. Pop stash → app.py 出现冲突
6. 自动解决：保留远程的 config_manager，保留本地的注释上传函数
7. 成功！
8. 告知用户：即使断网，现在也可以切换和合并其他分支

### 示例 2：无本地修改

用户："拉取最新代码"

流程：
1. 检查状态 → 工作区干净
2. Fetch 所有远程分支
3. 合并当前分支更新
4. "✓ 已更新到最新版本，所有远程分支信息已缓存（支持离线操作）"

### 示例 3：有本地 Commit

用户："更新当前分支"

流程：
1. 检测到 2 个本地 commit
2. 询问用户：rebase 还是 merge？
3. 用户选择 rebase
4. 暂存未提交修改
5. Fetch 所有远程分支
6. `git rebase @{u}`
7. Rebase 过程中出现冲突
8. 自动解决能处理的冲突
9. 对于剩余的："发现 2 个冲突需要你的帮助..."
10. 获取用户输入
11. 完成更新
12. 告知用户：现在可以离线操作其他分支

### 示例 4：复杂冲突

用户："更新代码"

流程：
1. 暂存修改
2. Fetch 所有远程分支
3. 合并更新
4. Pop stash → 多个冲突
5. 自动解决能处理的
6. 对于其余的："我发现 2 个冲突需要帮助..."
7. 获取用户输入
8. 完成更新
9. 提醒用户离线能力

---

**记住：** 目标是让 stash-update-restore 循环对用户透明，同时保持他们的本地工作安全。要主动、解释清晰，并优雅处理边缘情况。提供选择让用户感到掌控，但智能默认值让流程顺畅。