---
name: git-branch-cleanup
description: 批量删除/重命名本地和远端 Git 分支，并同步远端仓库结构（含中文分支名、upstream 修复）
source: auto-skill
extracted_at: '2026-06-17T10:06:37.947Z'
---

# Git 分支批量清理与重命名

## 适用场景
需要删除多余的本地/远端分支、将分支重命名、并让远端结构与本地保持一致。

## 操作流程

### 1. 切换到安全分支
```bash
# 先 stash 未提交的更改
git stash --include-untracked

# 如果有 untracked 文件冲突，使用 -f 强制切换
git checkout -f master
```

> **坑点**：中文分支名之间的文件差异可能产生大量 untracked 冲突（如 FatFS 文档等），
> `git checkout` 会拒绝切换，需要 `-f` 强制切换，之后 `git stash pop` 恢复。

### 2. 删除本地分支
```bash
git branch -D "LAN口通讯"
git branch -D "新版4G模块1"
```

### 3. 重命名本地分支
```bash
git branch -m "旧版4G模块" develop
```

### 4. 删除远端分支（每个远端都要操作）
```bash
# 一次性删除多个远端分支
git push home --delete "LAN口通讯" "新版4G模块" "旧版4G模块"
git push origin --delete "LAN口通讯" "新版4G模块" "旧版4G模块"
```

> **注意**：远端可能认证失败（如内网地址不可达），先确认网络可达再操作。
> 远端分支名可能与本地不完全一致（本地有 `新版4G模块1`，远端只有 `新版4G模块`）。

### 5. 强制推送重命名后的分支到远端
```bash
git push home develop --force
git push origin develop --force
```

### 6. 修复上游跟踪分支
重命名后，分支仍跟踪旧的远端名（如 `origin/旧版4G模块`，已不存在）：
```bash
git branch --set-upstream-to=origin/develop develop
```

### 7. 恢复工作内容并切回开发分支
```bash
git checkout develop
git stash pop
```

### 8. 验证最终结构
```bash
git fetch --all --prune
git branch -a
```

## 常见问题

| 问题 | 解决方案 |
|------|----------|
| checkout 报 untracked files 冲突 | `git checkout -f <branch>` |
| 远端认证失败 | 检查网络/VPN，确认远端地址可达 |
| 重命名后 upstream 指向已删除的远端分支 | `git branch --set-upstream-to=origin/<new-name> <branch>` |
| 中文分支名在命令行中需加引号 | `git branch -D "旧版4G模块"` |
