---
name: git-submit
description: 仓库代码提交规范，覆盖状态检查、提交、同步远程、推送及常见冲突处理
---

## 适用范围

用于将当前仓库的本地代码安全提交到远程仓库。执行前必须确认用户明确要求提交或推送；仅查看代码、开发功能或运行测试时，不主动执行提交和推送。

当前项目约定：

- 默认分支：`main`
- 远程名称：`origin`
- 远程地址：以 `git remote -v` 的实际输出为准，不重复添加已存在的 `origin`
- 提交信息：使用简洁、准确的中文描述，说明本次变更目的

## 标准提交流程

### 1. 确认仓库位置和当前状态

在项目根目录执行：

```powershell
git rev-parse --show-toplevel
git status --short --branch
git branch --show-current
git remote -v
```

检查以下内容：

- 是否位于目标仓库根目录
- 当前分支是否为预期分支，默认应为 `main`
- 是否存在未提交修改、未跟踪文件或冲突文件
- `origin` 是否已配置，以及拉取和推送地址是否正确

如果 `origin` 已存在，不要执行 `git remote add origin`。需要修正地址时使用：

```powershell
git remote set-url origin <仓库地址>
```

### 2. 审阅变更内容

提交前查看文件变更和差异：

```powershell
git status
git diff
git diff --stat
```

确认：

- 没有误改、敏感信息、密钥、日志或临时文件
- 修改范围与用户需求一致
- 不应提交的文件已通过 `.gitignore` 排除
- 若发现不属于本次任务的修改，不要擅自删除或覆盖；只暂存确认过的文件

如需查看某个文件的差异：

```powershell
git diff -- <文件路径>
```

### 3. 暂存需要提交的文件

优先按文件或目录精确暂存：

```powershell
git add <文件路径>
git add <目录路径>
```

仅当确认工作区所有修改都属于本次任务时，才使用：

```powershell
git add .
```

暂存后复核：

```powershell
git status

git diff --cached
git diff --cached --stat
```

如果误暂存文件，可取消暂存，不会丢失文件修改：

```powershell
git restore --staged <文件路径>
```

### 4. 提交本地变更

确保暂存区内容正确后提交：

```powershell
git commit -m "<简洁明确的提交说明>"
```

提交信息建议：

- 使用中文描述业务目的或技术变更
- 避免使用“修改一下”“临时提交”等无信息内容
- 一次提交尽量只包含一个完整主题

提交后检查：

```powershell
git status --short --branch
git log -1 --oneline
```

如果提示 `nothing to commit`，说明当前没有新的已暂存变更；先检查状态和最近提交，不要重复创建空提交。

### 5. 推送到远程仓库

首次推送当前分支或需要建立跟踪关系时：

```powershell
git push -u origin main
```

已有跟踪关系时：

```powershell
git push origin main
```

不要在未确认目标分支的情况下直接推送其他分支。推送后核验：

```powershell
git status --short --branch
git log -1 --oneline
```

状态应显示本地 `main` 与 `origin/main` 同步，且没有意外的未提交修改。

## 远程同步与冲突处理

### 推送被拒绝：远程包含本地没有的提交

不要直接强制推送。先获取并以变基方式同步：

```powershell
git pull --rebase origin main
```

同步无冲突后再次推送：

```powershell
git push origin main
```

### 变基过程中出现冲突

1. 查看冲突文件：

```powershell
git status
```

2. 打开冲突文件，保留正确内容并移除冲突标记：

```text
<<<<<<<
=======
>>>>>>>
```

3. 逐个标记已解决的文件：

```powershell
git add <已解决的文件路径>
```

4. 继续变基：

```powershell
git rebase --continue
```

5. 变基完成后推送：

```powershell
git push origin main
```

如果无法安全解决，保留现场并中止变基：

```powershell
git rebase --abort
```

中止后先向用户说明冲突文件和原因，不要擅自覆盖远程或本地内容。

### 工作区有本地未提交修改，无法同步

先查看状态和差异，确认这些修改是否属于当前任务。未经确认不要使用 `git reset --hard` 或其他会丢失修改的命令。必要时可在用户确认后暂存并同步，或先创建临时提交。

### 只有确认远程历史应被覆盖时才使用强制推送

默认禁止使用：

```powershell
git push --force
```

如果用户明确确认覆盖远程历史，优先使用更安全的方式：

```powershell
git push --force-with-lease origin main
```

执行前再次核对远程地址、目标分支和将被覆盖的提交。

## 禁止事项

- 不重复执行已存在远程名的 `git remote add origin`
- 不使用 `git push --force` 绕过推送拒绝
- 不使用 `git reset --hard`、清理命令或覆盖操作来隐藏问题
- 不提交密钥、密码、个人配置、构建产物和临时文件
- 不跳过变更审阅直接执行 `git add .`、`git commit`、`git push`
- 不在未确认分支和远程地址时推送

## 提交检查清单

- [ ] 已确认项目根目录和当前分支
- [ ] 已确认 `origin` 的实际远程地址
- [ ] 已查看工作区状态和差异
- [ ] 已排除无关修改及敏感文件
- [ ] 已精确暂存目标文件
- [ ] 已复核暂存区差异
- [ ] 已使用清晰的提交信息
- [ ] 已确认提交成功
- [ ] 已同步远程历史或处理冲突
- [ ] 已推送到预期的 `origin/main`
- [ ] 已确认本地分支与远程分支同步