Git版本管理命令

# Git 版本管理常用命令

适用项目：SopFast。日常在 `feature` 开发，验证后合入 `main`；推送代码与部署是两个步骤。

本文是便于查阅的独立参考文档，不修改仓库规范；项目操作以根目录 `SKILL.md` 为准。

## 1. 先理解这几个概念

| 名称 | 含义 | 例子 |
|---|---|---|
| 工作区 | 当前正在编辑的文件 | 修改一个 Vue 页面 |
| 暂存区 | 选好、准备提交的修改 | `git add 文件路径` |
| 本地提交 | 保存到本机 Git 历史的版本 | `git commit` |
| 远端仓库 | 团队共享的代码仓库 | `git push origin feature` |
| `feature` | 日常开发分支 | 开发、修复、测试 |
| `main` | 准备发布的分支 | 接收验证后的开发代码 |
| `origin/main` | 本机记录的远端 main 位置 | 用 `git fetch origin` 更新该记录 |

**日常顺序：修改 → 查看差异 → 暂存 → 提交 → 推送。**

以下命令在仓库目录内执行。代码块中的文件名、分支名和提交 ID 示例，执行前替换成实际值。

## 2. 查看状态：不确定时先执行这些

| 命令 | 用途 |
|---|---|
| `git status` | 查看当前分支、修改、暂存及冲突情况 |
| `git status --short` | 简洁查看文件状态；无输出表示工作区干净 |
| `git branch` | 查看本地分支；`*` 表示当前分支 |
| `git branch -vv` | 查看分支、最后提交及远端跟踪情况 |
| `git diff` | 查看未暂存的修改 |
| `git diff --cached` | 查看已暂存、准备提交的修改 |
| `git log --oneline --graph -15` | 查看最近 15 条提交及合并关系 |
| `git show 提交ID` | 查看某次提交的具体修改 |

提示：`git diff` 默认不显示未跟踪文件的内容，新增文件需要结合 `git status` 检查。

## 3. 日常开发：最常用的一套流程

### 第一步：开始前，检查并同步代码

```bash
git status
git switch feature
git pull --ff-only origin feature
```

切换和同步前先处理已有修改：要么验证后提交，要么按第 6 节临时保存。不要覆盖未提交的工作。

`--ff-only` 只允许快进更新；若提示无法快进，先查看双方提交，不要强制覆盖。

### 第二步：修改代码并完成项目要求的验证

根据修改范围执行项目 `SKILL.md` 中的检查和测试。Git 提交成功不代表代码功能正确。

### 第三步：检查、提交、推送

```bash
git status
git diff
git add 文件路径
git diff --cached
git commit -m "fix: 修复订单筛选问题"
git push origin feature
```

`git add` 可以添加多个文件：`git add 路径1 路径2`。优先指定路径，避免误带环境文件、日志、业务数据或无关修改。

常见提交说明：

| 类型 | 示例 |
|---|---|
| 新功能 | `feat: 增加库存筛选条件` |
| 修复 | `fix: 修复历史出库月份筛选` |
| 文档 | `docs: 更新开发操作说明` |
| 重构 | `refactor: 合并重复的渠道转换逻辑` |

## 4. 开发完成：把 feature 合入 main

**前提：工作区干净，feature 的修改已经提交、验证并推送。**

### 第一步：更新 main，再合并 feature

```bash
git switch main
git pull --ff-only origin main
git merge feature
```

`git merge feature` 的意思是：**把 feature 合入当前所在分支**。因此，执行前必须确认当前在 `main`。

### 第二步：验证合并结果，再推送 main

按项目要求检查和测试合并后的结果，通过后执行：

```bash
git push origin main
```

### 第三步：把 main 的结果同步回 feature

```bash
git switch feature
git merge main
git push origin feature
```

推送 `main` 只更新远端代码。本项目的部署需要另行执行 `SKILL.md` 中的发布流程，不能把推送成功视为部署生效。

## 5. 远端更新与分支管理

| 场景 | 命令 | 说明 |
|---|---|---|
| 获取远端记录 | `git fetch origin` | 不修改当前工作区代码 |
| 更新当前 feature | `git pull --ff-only origin feature` | 必须先确认当前在 feature |
| 从当前位置创建分支 | `git switch -c fix/问题名称` | 新分支基于当前提交 |
| 首次推送新分支 | `git push -u origin fix/问题名称` | 设置远端跟踪，之后可以用 `git push` |
| 查看已合入 main 的分支 | `git branch --merged main` | 帮助判断哪些本地分支可以清理 |
| 删除本地分支 | `git branch -d 分支名` | 先切换到其他分支；小写 `-d` 保留合并检查 |
| 删除远端分支 | `git push origin --delete 分支名` | 影响共享仓库，确认团队不再使用后执行 |
| 清理失效远端跟踪记录 | `git fetch --prune origin` | 不删除本地开发分支 |

删除前，可以查看目标分支是否还有未进入 main 的提交：

```bash
git log --oneline main..分支名
```

有输出表示存在尚未被 main 包含的提交，需要先检查。若分支被其他 worktree 占用，不要强删；用 `git worktree list` 查看，具体清理流程见第 9 节。

## 6. 开发到一半，需要临时切换任务

### 保存当前修改

```bash
git stash push -u -m "临时保存当前开发"
git stash list
```

`-u` 包含未跟踪文件，不包含被 `.gitignore` 忽略的文件；stash 保存在本地，不会随 `git push` 上传。

### 回到原分支并恢复

```bash
git switch feature
git stash apply 'stash@{0}'
git status
```

确认文件恢复完整、冲突已解决，再删除对应的临时记录：

```bash
git stash drop 'stash@{0}'
```

`stash@{0}` 指当前最新一条记录；如果期间新增过 stash，先执行 `git stash list`，确认要恢复和删除的是哪一条。

## 7. 撤销修改：先分清要撤销哪一层

| 需求 | 命令 | 结果 |
|---|---|---|
| 只是取消暂存 | `git restore --staged 文件路径` | 文件修改保留，可重新选择后提交 |
| 丢弃文件未暂存的修改 | `git restore 文件路径` | 工作区文件恢复到暂存区版本，未暂存修改会丢失 |
| 撤销已经提交的普通提交 | `git revert 提交ID` | 新建一条撤销提交，保留原历史；可能需要解决冲突 |

已经推送并共享的提交，优先使用 `git revert`。合并提交的撤销需要选择主线，不要直接照搬普通提交的命令。

不要把以下命令当作日常清理方式：

- `git reset --hard`：可能丢弃未提交修改，并移动当前分支位置。
- `git clean -fd`：会删除未跟踪文件和目录。
- `git push --force`：可能覆盖远端其他人的提交。

## 8. 合并冲突怎么处理

当 `git merge` 提示冲突时：

```bash
git status
```

打开冲突文件，检查 `<<<<<<<`、`=======`、`>>>>>>>` 标记，结合业务逻辑保留正确内容并删除标记。完成验证后：

```bash
git add 冲突文件路径
git merge --continue
```

若要放弃这次尚未完成的合并：

```bash
git merge --abort
```

上述命令用于 merge 冲突；stash apply 或 rebase 的冲突不能照搬 `git merge --continue`。

## 9. Worktree 管理：一个仓库，多个工作目录

### 9.1 Worktree 是什么

Worktree 让同一个 Git 仓库拥有多个工作目录，各自检出不同分支，方便同时处理不同任务。提交历史与分支由仓库共享，各目录的工作文件和暂存区独立。

同一个本地分支通常不能同时在两个 worktree 中检出。

执行 `git branch` 时：

| 显示 | 含义 |
|---|---|
| `* feature` | 当前目录检出的分支 |
| `main` | 未被其他工作目录检出的普通分支 |
| `+ rollback/login-autofill` | 被另一个 worktree 检出的分支；默认常显示为蓝色 |

### 9.2 查看所有工作目录

```bash
git worktree list
```

例如：

```text
/home/rudy/projects/work/SopFast                                5daa219 [feature]
/home/rudy/projects/work/SopFast/.worktrees/trainer-transit-http  56f3cbe [rollback/login-autofill]
```

三列分别是：工作目录、该目录当前提交、检出的分支。以上是本次问题中的示例，不代表仓库以后一直保持这个状态。

### 9.3 创建一个临时工作目录

先确保起点分支正确，再从本地 feature 创建新分支和工作目录：

```bash
git worktree add -b fix/临时任务 .worktrees/临时任务 feature
```

命令含义：以本地 `feature` 当前提交为起点，在 `.worktrees/临时任务` 中检出新分支 `fix/临时任务`。目录和分支名称需要替换；新分支名称不能已经存在。

若要检出一个已经存在、且未被其他 worktree 占用的分支：

```bash
git worktree add .worktrees/临时任务 已有分支名
```

目录内开发、提交和验证仍按项目要求执行。环境配置、依赖及业务数据不会自动准备好；创建工作目录也不会隔离数据库和服务端口。

### 9.4 清理顺序：先检查，再移除目录，最后删除分支

以下命令在主工作目录 `/home/rudy/projects/work/SopFast` 中执行，以本次遇到的分支为例。

**第一步：确认有哪些 worktree，以及目标分支是否还有未合入 main 的提交。**

```bash
git worktree list
git log --oneline main..rollback/login-autofill
```

日志有输出时，先检查这些提交是否还需要合并或保留。移除 worktree 不会自动合并代码。

**第二步：检查目标目录的修改和本地文件。**

```bash
git -C .worktrees/trainer-transit-http status --short
git -C .worktrees/trainer-transit-http status --short --ignored
```

第一条查看修改和未跟踪文件，第二条还显示被忽略的文件。即使第一条没有输出，也要确认忽略文件中没有需要保留的环境配置、业务文件或其他本地数据。

发现修改时，先提交或临时保存；需要保留的本地文件先备份。确认这个工作目录不再使用，并停止从该目录启动的服务，再继续。

**第三步：移除 worktree，再删除本地分支。**

```bash
git worktree remove .worktrees/trainer-transit-http
git branch -d rollback/login-autofill
```

这两个动作不同：

| 操作 | 作用 |
|---|---|
| `git worktree remove 路径` | 删除该工作目录并解除登记；保留分支 |
| `git branch -d 分支名` | 删除本地分支名称；保留其他 worktree |

**第四步：确认清理结果。**

```bash
git worktree list
git branch
```

### 9.5 常见报错怎么处理

| 提示或情况 | 原因 | 处理 |
|---|---|---|
| `cannot delete branch ... used by worktree` | 分支被其他工作目录占用 | 按上面的步骤先检查并移除对应 worktree，再删分支 |
| worktree 有修改或未跟踪文件，无法移除 | Git 在保护尚未保存的文件 | 先保存需要保留的内容，不使用强制删除绕过 |
| 分支未完全合并，无法用 `-d` 删除 | Git 的合并检查未通过 | 查看未合入提交，确认合并或保留策略，不直接改用 `-D` |
| 目录已被手动删除，但仍出现在列表中 | worktree 登记尚未清理 | 确认目录确实不再需要后，按下面步骤清理失效登记 |

仅当目录已经不存在时，先预览失效登记：

```bash
git worktree prune --dry-run --verbose
```

确认预览列出的记录都已失效且不再需要后，再执行：

```bash
git worktree prune --verbose
```

`prune` 用于清理符合清理条件的失效登记，不用于删除仍存在的正常工作目录。正常清理应使用 `git worktree remove`，不要直接用文件管理器或 `rm -rf` 删除目录。

## 10. 快速选择：现在该用哪个命令

| 你现在想做什么 | 用什么 |
|---|---|
| 看看改了哪些文件 | `git status` |
| 看改动内容 | `git diff` |
| 选中本次要提交的文件 | `git add 文件路径` |
| 保存一个本地版本 | `git commit -m "说明"` |
| 上传当前分支的提交 | 设置远端跟踪后执行 `git push` |
| 下载远端记录但不改工作区 | `git fetch origin` |
| 把 feature 合入 main | 先切到 main，再 `git merge feature` |
| 临时保存手头修改 | `git stash push -u -m "说明"` |
| 撤销一次已共享的普通提交 | `git revert 提交ID` |
| 清理已合并的本地分支 | `git branch -d 分支名` |
| 查看全部工作目录 | `git worktree list` |
| 移除不再使用的工作目录 | 保存文件后执行 `git worktree remove 路径` |