附录A　Git命令与状态速查

本附录按工程场景组织命令。执行恢复、删除分支、回滚和历史操作前，先确认仓库、分支、提交和差异。

A.1 确认当前项目

git rev-parse --show-toplevel
git remote -v
git branch --show-current
git status
git log -1 --oneline

用途：

确认位于正确仓库；
检查远程地址；
确认当前分支；
查看工作区和暂存区；
固定当前提交。

A.2 取得仓库和远程更新

git clone <仓库地址>
git fetch origin
git fetch --tags
git pull --ff-only

clone建立本地仓库和远程关系；
fetch取得远程对象但不改变当前工作区；
pull --ff-only只允许快进更新，避免意外产生合并提交。

A.3 切换标签和分支

git switch --detach <标签>
git switch main
git switch -c issue-12-short-description
git branch --show-current
git branch -vv

从标签分离检出适合运行固定基线；开始修改前建立分支。

A.4 查看变化

git status --short
git diff
git diff --staged
git diff --stat
git diff -- <文件>
git diff <提交1>..<提交2>
git diff main...HEAD

命令	比较对象
`git diff`	工作区与暂存区
`git diff --staged`	暂存区与当前提交
`git diff main...HEAD`	当前分支相对共同起点的变化

AI完成修改后，至少查看status、diff --stat和完整diff。

A.5 选择提交内容

git add <文件>
git add -p
git diff --staged
git commit -m "<类型>(<范围>): <变化>"
git show --stat
git show

交互式暂存常用选择：

输入	作用
`y`	暂存当前补丁块
`n`	不暂存
`s`	尝试拆分
`q`	退出

A.6 查看历史和定位变化

git log --oneline --decorate --graph --all
git log -- <文件>
git show <提交>
git blame <文件>
git grep -n "<文本>"

blame用于定位某一行最近的提交，不用于简单判断个人责任；应继续阅读提交、议题和合并请求。

A.7 推送任务分支

git push -u origin <分支>
git push

推送只把提交发送到远程，不等于合并或发布。受保护主分支通过合并请求进入。

A.8 合并主分支更新

git fetch origin
git switch <任务分支>
git merge origin/main

发生冲突时：

git status

逐个解决文件，删除冲突标记，运行受影响测试，再执行：

git add <已解决文件>
git commit

无法继续且尚未提交合并结果时：

git merge --abort

A.9 恢复未提交变化

查看后再恢复：

git diff -- <文件>
git restore <文件>

取消暂存但保留修改：

git restore --staged <文件>

交互式恢复：

git restore -p <文件>

这些命令可能使未保存变化消失，执行前必须确认差异。

A.10 撤销已共享提交

git revert <提交>

revert新增一个反向提交，保留原历史。撤销合并提交需要识别主线父提交，应由维护者根据实际历史处理。

不要用改写公共历史的方法处理已经被团队取得的提交。

A.11 临时保存未完成工作

git stash push -m "<说明>"
git stash list
git stash show -p
git stash apply <stash>

应用后先检查差异，确认无误再删除暂存记录。

A.12 标签和版本

git tag -a v0.1.0 -m "<版本说明>"
git show v0.1.0
git push origin v0.1.0
git tag --list

已发布标签不移动。修正使用新版本。

A.13 文件是否被忽略

git check-ignore -v <文件>
git status --ignored

本地秘密、构建目录和可再生成日志通常忽略；测试样例、配置模板和发布证据按项目规则进入Git。

A.14 常见状态符号

git status --short的两列分别表示暂存区和工作区：

示例	含义
`M file`	工作区修改，未暂存
`M file`	修改已暂存
`MM file`	已暂存后又继续修改
`A file`	新文件已暂存
`?? file`	未跟踪文件
`D file`	删除已暂存
`UU file`	合并冲突未解决

A.15 安全检查顺序

在不确定Git状态时执行：

1. 确认仓库根目录
2. 确认当前分支
3. 查看status
4. 查看工作区diff
5. 查看staged diff
6. 查看最近提交
7. 再决定恢复、提交、合并或回滚

不要通过删除整个项目目录或使用破坏性重置来回避状态判断。

附录A Git命令与状态速查