外观
工具速记手册:Git 与 Mermaid
摘要
Git 用于管理工作区、暂存区和历史,Mermaid 用文本表达结构与交互。前者先确认改变的是哪一层,后者先确认读者需要看什么关系。命令以现代 Git 为范围;Mermaid 图形能力与嵌入平台版本有关。
快速入口
可执行流程、结果分支与模板:高频问题。
Git 状态、合并、撤销、Mermaid 图形选择:知识速记。
提交遗漏、冲突、远程拒绝、图不渲染:常见问题排查。
status、diff、log、reflog、图形语法:工具与参数。
知识速记
| 知识点 | 核心结论与条件 |
|---|---|
| 三层状态 | 工作区是当前文件,index 是拟提交快照,HEAD 指当前历史位置;commit 不自动包含所有修改 |
| add | 暂存执行 add 时的内容;之后继续编辑,需要再次 add 才会提交最新内容 |
| 分支与提交 | 分支是移动的引用,不是复制目录;提交记录快照及父关系 |
| fetch 与 pull | fetch 更新远程跟踪信息;pull 还要整合,具体 merge/rebase 行为依配置 |
| merge 与 rebase | merge 保留合并关系,rebase 重放并生成新提交 ID;已共享历史重写会影响协作者 |
| 冲突 | Git 无法自动决定某些组合,需要按业务语义解决,不是只删除标记就完成 |
| restore / reset / revert | 分别用于文件恢复、引用/索引等调整及新增反向提交,影响层不同 |
| reflog | 记录本地引用移动线索,可辅助找回近期提交;不是远程备份,过期和对象清理会影响恢复 |
| stash | 临时保存工作,不自动覆盖全部未跟踪或忽略文件;应用时仍可冲突 |
| Mermaid 渲染 | 文本需被宿主平台支持,代码围栏通常标注 mermaid;能解析不等于图表达正确 |
| 流程图 | flowchart 表达节点与路径,方向 TD/LR 决定基本布局;节点 ID 与显示文本分开 |
| 时序图 | sequenceDiagram 表达参与者与事件顺序;箭头关系不自动证明真实系统同步语义 |
| 类图与状态图 | classDiagram 描述类型关系,stateDiagram-v2 描述状态转移;按问题选图 |
Git 状态和提交:按影响层记命令
| 操作 | 比较或改变什么 | 使用场景 |
|---|---|---|
| git diff | 工作区相对暂存区 | 看尚未暂存的修改 |
| git diff --cached | 暂存区相对 HEAD | 看下一次提交内容 |
| git diff HEAD | 已跟踪工作区相对 HEAD | 看整体已跟踪文件差异 |
| git add -- 路径 | 将此时的内容放入 index | 后续编辑还需再 add |
| git commit | 将 index 写成提交 | 不自动提交未跟踪/未暂存内容 |
| git fetch origin | 下载并更新适用远程跟踪信息 | 不自动合并工作区 |
短状态两列:X 表示 index,Y 表示工作区;M 修改,A 新增,D 删除,?? 未跟踪,MM 暂存后继续修改,UU 等表示未合并状态。子模块和冲突有例外。普通 diff 不展示普通未跟踪文件。
正常提交、远程同步与冲突步骤
Git switch 和 restore 需要 Git 2.23+;本节命令按目的选用,不是必须依次执行的脚本。恢复与丢弃前先确认工作保存范围。
先 status 和 diff,选目标路径 add,然后 diff --cached 和必要测试,commit 后确认分支/远程再 push。下列命令是各自用途的模板,不是要连着执行的脚本,路径与分支需替换。
bash
git status --short
git diff --cached
git add -- path/to/file
git commit -m "说明最终行为变化"
git fetch origin
git log --oneline --graph --decorate -20
git push origin branch-namepush 非快进拒绝时先 fetch,查看双方提交,再按团队策略 merge 或 rebase;不要直接 force。merge 保留合并关系,rebase 重放成新 ID,对共享历史会影响其他人。冲突时读双方业务意图,解决文件、测试、add,再按操作继续;放弃用对应 merge --abort 或 rebase --abort,不混用不同恢复命令。
撤销和找回:具体影响是什么
| 目的 | 常用命令形状 | 影响与前提 |
|---|---|---|
| 仅取消暂存 | git restore --staged -- 路径 | 保留工作区内容,从基准恢复 index |
| 丢弃未暂存改动 | git restore -- 路径 | 工作区恢复到 index,当前修改会丢失,先确认有备份 |
| 撤销已共享提交 | git revert 提交ID | 新增反向提交,不删除旧历史;合并提交需指定并理解主线 |
| 临时保存工作 | git stash push -u | -u 包含未跟踪,不包含所有忽略文件;apply 可能冲突 |
| 查看近期引用移动 | git reflog -20 | 本地恢复线索,有保留期限,不是永久备份 |
| 保留找回的提交 | git branch rescue 提交ID | 新引用保住对象,随后再检查内容与整合 |
reset --soft 移动引用但保留 index/工作区;--mixed 还重置 index;--hard 还会重置相关工作区内容,是丢失改动风险高的操作。选择前先确认保留对象,不能把三种 reset 都叫“撤销提交”。密钥误提交应先轮换撤销凭证,revert 不移除旧历史里的密钥,历史清理也不代替轮换。
Mermaid:图类型与可直接用的模板
flowchart 表达流程/关系,sequenceDiagram 表达事件顺序,classDiagram 表达类型关系,stateDiagram-v2 表达状态转移。ID 是稳定标识,显示文本另写;LR 左到右,TD 上到下。复杂标签放引号,不把特殊词和标点机械当普通 ID。
图表将在阅读到此处时加载…
图表将在阅读到此处时加载…
时序图用 participant 声明参与者,->> 表示消息,-->> 常用响应,alt/else/end 表示分支,loop/end 表示循环。箭头样式只是图示语法,真实系统同步、事务与重试责任必须靠含义说明,不靠箭头自行推导。
不渲染、解析错、图太大怎么解决
显示成代码先查围栏 mermaid 与宿主支持;解析错误缩到最小图,查报错行、类型语法、节点标签与版本;新语法在旧平台不一定支持。布局太宽先缩短标签、减少交叉边或拆图,不要把大量步骤塞到一个节点。图旁保留核心文字关系,手机上检查横向滚动与可读性。
Git 故障报告保存仓库、分支、版本、准确命令、状态与最小 diff;Mermaid 保存宿主/渲染器版本和最小图。命令成功不证明合并业务正确,图解析成功也不证明关系正确。
常见问题排查
| 现象 | 检查顺序 | 证据与下一步 |
|---|---|---|
| commit 没包含最新改动 | status → diff → diff --cached → 查 add 后是否继续编辑 | 先确认工作区与 index 差异,再只暂存目标文件,不直接 add 全仓库。 |
| push 被拒绝 | 确认分支与远程 → fetch → 查双方新增提交 → 按团队策略整合 | 分叉不能用 force 无条件覆盖;先保留本地工作,整合后验证再推送。 |
| 合并冲突 | 查未合并文件 → 理解双方意图 → 解决并测试 → 暂存 | 检查全部冲突及业务结果;放弃操作使用对应 abort,而非混用其他历史命令。 |
| 撤销后想恢复提交 | 查看 reflog 与 log → 找目标提交 → 先建立保留引用 | 先确保对象还存在,避免继续破坏引用;工作区未提交内容恢复能力不同。 |
| 误提交密钥 | 立即撤销/轮换凭证 → 评估传播范围 → 按团队流程清历史 | 删除文件或新增 revert 不清除旧历史中的密钥,历史清理也不代替轮换。 |
| Mermaid 显示为代码 | 检查宿主支持 → 检查围栏语言 → 查版本与插件 → 最小图复现 | 不先改完整图;区分未启用渲染与解析失败。 |
| Mermaid 解析失败 | 保留报错行 → 缩小输入 → 查节点 ID、引号、箭头与版本 | 复杂标签用引号隔离,避免把保留字当无条件可用 ID;新语法需平台版本支持。 |
| 图太大或方向误导 | 明确一个问题 → 减参与者与交叉边 → 拆图 → 检查手机宽度 | 流程、时间和数据关系分开画;不要用颜色代替全部语义。 |
高频问题:操作与结果判断
以下 Git 示例适用于 Git 2.23+;branch-name、提交 ID 和文件路径需替换。命令按场景执行,不能把不同场景连成一段脚本。
提交遗漏:检查的是暂存快照
bash
git status --short
git diff
git diff --cachedMM 表示同一文件既有已暂存修改又有后续未暂存修改:commit 只包含前者。?? 表示未跟踪,普通 diff 不会显示。确认目标内容后 git add -- path/to/file,再看 diff --cached。若文件不出现,用 git check-ignore -v -- path/to/file 检查忽略来源;不要为了提交业务文件强行加入缓存和凭证。
提交后 git show --stat HEAD 及 git show HEAD -- path/to/file 核对最终快照,不能只看 commit 返回成功。
推送拒绝:看双方各多了哪些提交
bash
git fetch origin
git status -sb
git rev-list --left-right --count HEAD...origin/branch-name
git log --left-right --oneline HEAD...origin/branch-name例如计数 2 3:本地独有 2 个、远程独有 3 个。仅本地独有通常可快进推送;仅远程独有且工作区干净,可按团队规则快进更新;双方独有则需 merge 或 rebase。工作区有未提交内容先保存,再整合。
共享历史优先采用团队约定的整合方式,不能因拒绝直接 force。验收比较本地与远程目标分支提交,并核对 diff/测试,确认双方修改都保留。计数语义见 git rev-list。
冲突:继续和放弃对应当前操作
bash
git status
git diff --name-only --diff-filter=U按冲突文件理解双方业务意图,编辑后 git add -- path/to/file,再执行当前操作的 git merge --continue 或 git rebase --continue。想放弃则使用当前操作的 --abort;不要混用。rebase 中 ours/theirs 的含义容易与直觉不同,不应批量选一边代替检查。
解决文本标记后仍要检查方法重复、调用签名、配置兼容与测试。验收 status 没有未合并文件,历史包含预期修改,必要功能检查通过。
误删与误撤销:先保住对象再整合
未提交的丢弃内容通常不能指望 reflog 找回;先查编辑器本地历史和备份。已提交内容可 git reflog -20 找旧位置,再 git branch rescue 提交ID 为它建立保留引用,随后 git show 检查内容、决定 cherry-pick 或其他整合。
撤销共享普通提交用 revert 新增反向提交;revert 合并提交需明确 mainline,不能照抄普通提交用法。恢复过程中先建立 rescue 引用和保存工作区,避免 reset --hard 把另一批修改一起丢掉。
Mermaid 不渲染:解析、宿主、表达分别检查
先用最小图确认宿主支持:
图表将在阅读到此处时加载…
最小图也失败:查 Markdown 围栏、插件启用和构建日志。最小图成功、原图失败:按片段缩小范围,检查节点 ID、引号、箭头和版本支持。解析成功但图很难读:拆分独立问题,减少交叉边,调整 LR/TD;不继续堆节点。
验收必须在目标站点构建和页面中观察标签、箭头与布局;在线编辑器支持的语法不保证宿主使用相同 Mermaid 版本。
工具与参数
以下 Git 命令在目标仓库内执行。路径、分支及远程名需替换成实际值;本节以只读检查为入口,改变状态的撤销操作先确认影响层。短状态字段依据 git-status 官方文档。
| 命令或语法 | 查阅用途 | 重点边界 |
|---|---|---|
git status --short | 两列状态及未跟踪文件 | 通常 X 对应 index,Y 对应工作区;冲突状态和子模块另有规则 |
git diff | 工作区相对 index 的变化 | 不等于将要提交的内容,默认不展示普通未跟踪文件 |
git diff --cached | 拟提交内容相对 HEAD 的变化 | 提交前必看,防止暂存旧内容或不相关文件 |
git diff --check | 空白问题与冲突标记线索 | 不验证逻辑,也不替代编译或测试 |
git log --oneline --graph --decorate -20 | 有界查看提交与引用 | 只显示当前可达历史,查丢失引用另看 reflog |
git remote -v、git branch -vv | 远程地址及跟踪关系 | 跟踪状态基于最近 fetch,并非实时远程状态 |
git reflog -20 | 本地引用移动 | 有保留期限,恢复前确认目标内容,不盲目 reset --hard |
git show 提交ID | 提交内容与元数据 | 替换真实 ID,检查变更并不等于批准部署 |
flowchart LR / sequenceDiagram | 声明 Mermaid 图形类型 | 不能混用不同图形语法,宿主需支持该类型 |
A[处理] --> B[完成] | 流程图节点与有向边 | ID 保持唯一,显示文本复杂时使用引号;边表示的因果要有说明 |
最小图形参考
以下为交互顺序示意,不包含失败、重试与事务保证。模板可按实际关系调整。
语法基线可查 Mermaid 时序图文档,宿主平台可能支持较旧版本。
图表将在阅读到此处时加载…
易错点与记忆提示
- 改文件看工作区,交提交看 index,找历史看 HEAD。
- fetch 是获取,整合是另一件事:不要把本地跟踪状态当远程实时状态。
- 共享历史慎重写,普通撤销优先反向提交:具体遵循团队分支策略。
- reflog 是线索,不是永久备份:未提交内容和已提交对象恢复能力不同。
- 图先选关系,再选语法:流程、顺序、类型与状态不要揉成一张。
- 图能渲染不等于图正确:检查箭头、条件、参与者和失败路径是否符合真实行为。
原理与完整示例
需要原因、源码或完整实验时再阅读: