git-smart-update

Smart Git Update

Intelligently update a Git repository while preserving local changes. Automatically handle the stash-update-restore cycle and intelligently resolve merge conflicts.

Use Cases

Use this skill when the following situations occur:

The user wants to update/pull code and has local uncommitted changes
The user says "update code", "pull the latest", "git pull and keep my changes"
The user mentions updating branches (current branch or all branches)
You detect uncommitted changes before a pull operation
There is locally committed code that needs to be synchronized with the remote

Core Workflow

Step 1: Analyze the Current State

First, understand the current working state:

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

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

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

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

Decision points:

No local changes → go directly to the update process
Uncommitted changes → enter the stash workflow
Local commits → ask whether to rebase or merge
No upstream branch → warn the user and ask how to handle it

Step 2: Handle Local Commits (if any)

Check whether there are local unpushed commits:

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

If there are local commits (LOCAL_COMMITS > 0):

Ask the user to choose a merge strategy:

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

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

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

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

请选择：rebase / merge

Record the user's choice (use_rebase) for the subsequent pull operation.

Step 3: Stash Local Changes (if needed)

If there are uncommitted local changes:

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

Record the stash hash for later verification.

Step 4: Fetch Remote Updates

Important: whether updating the current branch or all branches, first fetch all remote information

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

Benefits of this step:

All remote branch information is cached locally refs/remotes/origin/
After disconnecting from the network, you can still view other branch statuses, switch branches, and merge branches
Only reference information is downloaded, not the full code, so it is fast

Step 5: Merge Remote Updates into Local

Execute according to the strategy chosen by the user:

Current branch(default):

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

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

All branches(if requested by the user):

# 遍历所有分支并更新
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>

If pull fails:

Clearly display the error message
Immediately restore the stashed changes:git stash pop
Ask the user how to handle it (network issue? merge conflict? permission issue?)

Step 6: Restore Local Changes

git stash pop

This may trigger merge conflicts, which is expected and will be handled in the next step.

Step 7: Handle Conflicts

After executing git stash pop , check for conflicts:

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

If there are no conflicts: Great! Clean up the stash and finish.

If conflicts are detected: enter the intelligent conflict resolution process.

Conflict Resolution Strategy

The goal is to preserve both the remote improvements and the local intent.

Automatic Resolution Rules

Prefer remote configuration improvements
- If the remote changed hardcoding to a configuration call → use the remote version
- Example:bucket_name = "pdf" → bucket_name = config_manager.get_value(...)
Preserve local debugging/testing code
- If the local version commented out production code → keep it commented out
- If the local version disabled cleanup/upload/external calls → keep them disabled
Merge complementary changes
- The remote added new imports/features + the local version commented out the usage part → keep both
- The remote refactored the structure + the local version modified the logic → try to merge

Resolution process

For each conflicted file:

Read conflict markers

<<<<<<< Updated upstream
# 远程版本
=======
# 本地版本
>>>>>>> Stashed changes

Analyze semantic differences
- Is it configuration vs hardcoding? → Prefer the remote configuration
- Is it active vs commented out? → Prefer keeping the local comment (debug mode)
- Is it conflicting logic? → Ask the user
Apply the resolution
- Use the Edit tool to replace conflict markers with the resolved version
- Explain the reasoning to the user
Verify the resolution
```
git add <resolved-file>
```

When to ask the user

The following situations cannot be resolved automatically:

Both versions modified the same logic in different ways
It is unclear which version preserves the user's intent
Structural changes affect multiple lines of code

Question format:

在 <文件> 的第 <N> 行发现冲突：

远程版本：
<显示代码>

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

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

Cleanup work

After successfully resolving conflicts:

# 删除已应用的 stash
git stash drop

Special case handling

No local modifications

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

Only unstaged modifications

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

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

Has local commits

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

Pull failed

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

No upstream branch

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

Output format

Always provide clear feedback:

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

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

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

准备就绪！

Branch update mode

Important: offline operation support

Whether updating the current branch or all branches, this skill will first execute git fetch --all

This means:

✅ All remote branch information is cached locally .git/refs/remotes/origin/
✅ After disconnecting from the network, you can still operate freely：
- Switch to another branch:git checkout other-branch
- View the status of other branches:git log origin/other-branch
- Merge other branches:git merge origin/other-branch
- Compare branch differences:git diff origin/main..origin/develop
✅ Only downloads reference information (a few KB), not the full code, so it is fast
✅ Minimal impact on network bandwidth

Example scenarios:

# 有网络时
更新代码  # fetch --all，所有分支信息缓存到本地

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

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

Current branch only (default)

Fast and safe
Only merges into the branch you are on
But all branch information has already been fetched for offline use

All branches (if the user requests it)

Iterate through and update all branches that have an upstream
More time-consuming, may trigger multiple conflicts

Warning: Updating all branches is more complex and may trigger multiple conflicts. Consider asking for confirmation first.

Rebase vs Merge detailed explanation

Rebase mode

Advantages:

Commit history is linear and clear
No unnecessary merge commits
git log is easier to read

Disadvantages:

Rewrites local commit history
If already pushed to remote, it may cause problems (usually used when local commits have not been pushed)

Use cases:

Local commits not pushed
Want to keep history clean
Team recommends using a rebase workflow

Run command:

git pull --rebase

If there are conflicts during rebase:

# 解决冲突后
git add <resolved-files>
git rebase --continue

# 或放弃 rebase
git rebase --abort

Merge mode

Advantages:

Preserves the original commit history
Safer, does not rewrite history
Suitable for collaborative development

Disadvantages:

Creates merge commits
History may have multiple branches

Use cases:

Conservative choice, safer
Team uses a merge workflow
Choose this when unsure

Run command:

git pull

Best practices

Always explain what you are doing - The user should understand the whole process
Show diffs when helpful - Especially when resolving conflicts
Preserve user intent - Debug code, commented-out parts, work in progress
Fail gracefully - If something goes wrong, restore the state and ask
Clean up the environment - Do not leave stale stashes
Offer choices - Let the user decide between rebase/merge
Verify the result - Ensure the final state matches expectations
Support offline work - Via git fetch --all cache all remote branch information, so other branches can still be operated on after going offline

Examples

Example 1: Simple update + debug code

User: "Update the code"

Process:

Detected that app.py has uncommitted changes (commented-out upload function)
Stash and add a message
Fetch all remote branch information (supports subsequent offline operations)
Merge updates for the current branch (remote improved config handling)
Pop stash → conflict appears in app.py
Resolve automatically: keep the remote config_manager, keep the local commented-out upload function
Success!
Tell the user: even if offline, they can now switch to and merge other branches

Example 2: No local changes

User: "Pull the latest code"

Process:

Check status → working tree clean
Fetch all remote branches
Merge updates for the current branch
"✓ Updated to the latest version, all remote branch information has been cached (supports offline operations)"

Example 3: Has local commits

User: "Update the current branch"

Process:

Detected 2 local commits
Ask the user: rebase or merge?
User chooses rebase
Stash uncommitted changes
Fetch all remote branches
git rebase @{u}
Conflict occurs during rebase
Automatically resolve conflicts that can be handled
For the remaining ones: "Found 2 conflicts that need your help..."
Get user input
Complete the update
Inform the user: other branches can now be operated on offline

Example 4: Complex conflict

User: "Update the code"

Flow:

Stash changes
Fetch all remote branches
Merge updates
Pop stash → multiple conflicts
Automatically resolve what can be handled
For the rest: "I found 2 conflicts that need help..."
Get user input
Complete the update
Remind the user of offline capability

Remember: The goal is to make the stash-update-restore loop transparent to the user while keeping their local work safe. Be proactive, explain clearly, and handle edge cases gracefully. Provide choices so the user feels in control, but smart defaults keep the flow smooth.

About this skill

Use Cases

Core Workflow

Step 1: Analyze the Current State

Step 2: Handle Local Commits (if any)

Step 3: Stash Local Changes (if needed)

Step 4: Fetch Remote Updates

Step 5: Merge Remote Updates into Local

Step 6: Restore Local Changes

Step 7: Handle Conflicts

Conflict Resolution Strategy

Automatic Resolution Rules

Resolution process

When to ask the user

Cleanup work

Special case handling

No local modifications

Only unstaged modifications

Has local commits

Pull failed

No upstream branch

Output format

Branch update mode

Important: offline operation support

Current branch only (default)

All branches (if the user requests it)

Rebase vs Merge detailed explanation

Rebase mode

Merge mode

Best practices

Examples

Example 1: Simple update + debug code

Example 2: No local changes

Example 3: Has local commits

Example 4: Complex conflict