242 lines
5.4 KiB
Markdown
242 lines
5.4 KiB
Markdown
---
|
|
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`
|
|
- [ ] 已确认本地分支与远程分支同步
|