li旭旭新同事是过了试用期的第二天来跟我搭项目的，来之前我拍着胸脯说"讲一次 Git，半小时，保证你上手"，结果那个下午我们在会议室待到晚上七点，白板上画满了箭头和方块，中途还拉了另外两个同事进来旁听。我承认，讲一次 Git 这件事，我彻底低估了。半小时能讲掉的无非是几条命令的用法，而新人真正缺的，是一套能解释"代码为什么会变成这样"的心智模型——没有模型，命令背得再熟，遇到报错该慌还是慌。
这篇文章就来自那次经历。我不会给你整篇 Git 命令大全，而是把当时"讲崩了、又重新讲"的过程拆开给你看：新人为什么学不会、重新讲的时候我换了什么方法、以及讲完之后我被问得最多、也最值得收藏的五个排查坑。对准备带新人的老手来说，这套讲法可以直接复用；对还在自己啃 Git 的新人来说，这篇也能帮你少走一段弯路。
1. 想用半小时讲完 Git，是我太高估新人了
1.1 我原本的"半小时速成"备课思路
说实话，我一开始是有备课的。提纲写得很简单：给新人装好 Git，开一个仓库，git add、git commit、git push、git pull 走一遍，输出一个"本地写代码→推到远程仓库"的完整闭环。我当时的逻辑是，日常开发大概率用到的高频命令就这些，新人照猫画虎跑通一次，剩下的问题遇到了再查。
这个思路听起来没毛病，但它埋伏着一个致命前提：我把 Git 理解成了"一套需要记住的指令"，而新人把 Git 理解成了"一个上传代码的文件夹"。两套认知完全不在一个维度上，他点头不代表他懂了，他只是记住了"我输入了这几行，然后成功了"。果然，一进入真实操作，问题一串串往外冒。
1.2 当晚的翻车现场：新同事的问题一个接一个
小A同学是那种很认真的新人，听讲时不玩手机，还做了笔记。可一到自己动手就开始卡壳，我印象最深的是这几个问题：
第一个，"我改完文件，git add 之前不是已经保存了吗，为什么还要再 add 一次？"——这句听起来简单，但背后藏着一个很深的误解。他以为提交就是"把文件上传到某个云端备份"，所以不理解暂存区存在的意义。
第二个，"我 commit 了，为什么同事的代码还是不在我本地？"——他把 commit 理解成了"同步"，觉得提交就等于把所有人的代码拉到自己机器上。解释了半天 push 和 pull 是两件事，他才勉强接受。
第三个最要命，git pull 的时候报了一串英文，大概是 Updates were rejected，他盯着屏幕看了几十秒，然后问我"代码是不是坏了"。我说没有坏，只是远程有更新、本地也有更新，需要合并一下，他一脸茫然地问：合并是啥？
那一瞬间我就明白了，半小时根本不可能讲完。他缺的不是命令，是概念地图。他不知道 commit 是什么、分支是什么、远程是什么，自然没法把报错信息放进任何一个已知的框架里去理解。
1.3 复盘：新人学不会 Git，问题出在哪三个地方
那天晚上我把小A的提问全部过了一遍，发现所有困惑都能归到三类问题里。
第一类，把 Git 当成网盘。这是新人最普遍的误解。网盘的逻辑是"文件同步"，你把文件放进去，别的设备就能拿到同样的一份。但 Git 的逻辑是"提交历史的积累"，你要先产生一个提交，再把手里的提交推给别人。带着"网盘思维"学 Git，会产生一连串伪问题：为什么这个文件还没同步过去、为什么我保存了但别人看不到、为什么删了一个文件历史里还能找回。这些问题的根源都不在命令，而在「版本库到底存的是什么」这个底层认知。
第二类，脑子里没有"提交链"和"分支指针"的模型。很多人把 commit 想象成"一份文件备份"，把分支想象成"一套文件夹副本"。可实际上，Git 里的提交是带有父提交引用的快照节点，分支只是指向某个节点的指针。没有这个模型，新人看到 merge 的冲突标记会当成代码被覆盖了，看到 rebase 会以为历史被删除了，遇到任何异常都不敢动。
第三类，遇到报错没有排查路径。老手看到报错，第一反应是"先看 git status，确认自己在什么状态"，或者"打开 git log 看看最近提交"，这是一种自动化的排查链路。但新人拿到报错，只会一字一句去翻译英文，翻译完了也不知道下一步做什么。我当时只教了命令，没教"怎么读状态"，等于把人丢进黑森林还不给地图。
这三类问题叠加在一起，结论很清楚：第一次讲 Git 不能从命令开始，要从模型开始；不能追求一次讲完，要允许新人边操作边建立路径。这才是那次翻车之后我最大的收获。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 换一种讲法：从提交记录的时间线理解 Git
2.1 先不谈命令，先画懂这张"三层地图"
第二次讲的时候，我没让新人碰键盘，先在白板上画了三层结构。最底下是工作区，就是你在编辑器里看到的文件；中间是暂存区，可以理解成打包台；最上面是版本库，相当于档案室的货架。
git add 是把文件从工作区放进打包台，git commit 是把打包台上的一整批文件拍成一张快照，存进档案室。我特意强调了一句：commit 存的不是"这次改动了哪些文件的差异备份"，而是"这一瞬间整个项目长什么样的完整快照"。
新人一旦接受了"每次提交就是拍一张快照"这个设定，很多问题会自然消解。比如他问"为什么 commit 之后删掉文件还能找回"——因为档案室里保留的是那一整张快照，不是最新副本；又比如他问"为什么我 commit 了同事还是看不到"——因为档案室在本地，你得先把快照推到别人的档案室才算数。快照模型比差异模型容易懂太多了，后来的新人我再没费劲解释过"为什么 Git log 能看到历史"。
我还给他做了一个小实验：随便建个文件，git add 后提交，然后删掉，再提交一次，接着用 git show HEAD~1 看上一版内容，文件还在。他当时"哦"了一声，我知道，这比讲十遍概念都管用。
2.2 分支不是文件夹，是可以随便移动的指针
很多新人天然把分支想象成"一份独立的代码文件夹"，理由是"切了分支之后代码确实变了啊"。这是第二个认知大山。
我给小A画了一条时间线，然后把一个便签贴在上面，告诉他：分支就是一个贴在某个提交上的标签，这个标签会随着新提交自动往前移动。HEAD 也是一张标签，但它永远贴在"我当前所在的分支"上。一张时间线可以有多个便签，它们指向同一个提交的时候，两个分支暂时内容一致；某个分支上新增了两个提交，它就比另一个分支跑得更远，仅此而已。
然后我们一起敲了几条命令制造分叉：用 git branch feat-demo 原地开一个分支，切过去改一行，提交，再切回 main，用 git log --oneline --graph --all 看时间线。看到两个分支真的分道扬镳之后，小A问了一句："所以开分支这么便宜？"我说对，便宜到可以随便开、随便丢，因为本质上只是在某次提交上贴一张便签。
把"分支是指针"这个模型种进脑子里之后，再讲 merge 就好办了：把另外一个分支的提交接回来，让当前分支的指针往前追一段。就算出现冲突，也只是时间线上两段提交改到了同一行，Git 拿不定主意，请你来定，而不是代码被搞坏了。
2.3 本地与远程：不用天天想的同步模型
第三个讲清楚的是远程仓库。我跟他说，别把远程仓库想成云端网盘，它就是另一台机器上的另一个档案室。git clone 是把你机器上搭一个一模一样的档案室，同时把远程那张标签也记下来；git push 是把本地新增的快照传过去，然后动用你本地的权限，把远程仓库的那张标签往前推；git pull 则是把对方多出来的快照拿下来，合并到自己的分支上。
这里有一个特别容易让新人懵的点：origin/main 到底是什么？很多人以为它可以像普通分支一样随便切换，其实它是远程分支在本地的一个只读镜像，本地不能直接写。你所有的日常操作，都在本地分支上完成，origin/main 只是一个提醒你"远程那个仓库此刻长什么样"的坐标。新人一开始不需要深入理解 fetch 和 pull 的微妙的区别，先把"远程是另一台机器的另一条时间线"立住，后面的报错就好解释了。
比如那次 Updates were rejected，换成这套模型解释就是：两个档案室各自多了一段记录，你想推送，Git 发现两边历史出现了分叉，先拒绝你，让你把对方的记录拿下来对齐再推。
2.4 讲完后让新同事干的第一个练手任务
光听概念是不够的，我给他设计了一个一小时能走完的闭环任务，分成四步。
第一步，克隆一个练习仓库，执行 git log --oneline --graph --all 看历史；第二步，创建功能分支 git switch -c feat/register-page，改一个文件后提交；第三步，切回 main 分支，执行 git pull 更新，然后 git merge feat/register-page；第四步，自己制造一次冲突：先在 main 上改一行并提交，回到功能分支把同一行改成不同内容再提交，然后合并，亲眼看看冲突标记长什么样。
这个任务的顺序是有讲究的。先看历史，是为了让他第一次接触"快照时间线"；中途切分支，是为了让他体会工作区跟着分支指针变化；最后制造冲突，是为了在他心里把"冲突=灾难"这个印象抹掉。那次他真撞上冲突标记的时候，我说：别看报错，先看文件，三行标记把两边的答案都写在里面了，你决定留哪边，删掉标记，再提交一次。他照着做完了，长出一口气说"原来就这么回事"。
对，就是这么回事。Git 的大部分操作没有想象中那么难，难的是在动手之前脑子里有没有那张模型图。
3. 我自己攒的 Git 排查清单：新人最容易踩的五个坑
教了小A一周之后，他在群里问的问题明显变少了，但高频踩坑点也暴露得比较明显。下面五个坑不是拍脑袋总结的，都是他自己或者同期同事真实踩过、我来处理时顺手记下来的。每个坑我都按"现象—判断—处理"的顺序写，方便照抄。
3.1 坑一：合并冲突——新同事第一反应是"代码是不是没了"
现象很典型。小A在功能分支上改完代码，合并到 main 的时候屏幕上跳出一段带 CONFLICT 的英文，他第一反应是"我刚才写的代码是不是被打没了"，碰都不敢碰。
处理链路是这样的：先执行 git status，看列出的文件里哪些标记了 both modified，这就是冲突文件。打开文件，会看到三段式的标记：<<<<<<< HEAD 下面是当前分支版本，======= 以下到 >>>>>>> 之间是另一个分支的版本。接下来不是删代码，而是和另一个提交的人商量，同一行到底该用哪边，把最终结果留下来，把 <<<<<<<、=======、>>>>>>> 这些标记行全部删掉，然后重新 git add、git commit，冲突解决。
我给小A的提醒是：冲突永远不是"代码丢失"，而是"同一行出现了两份答案，Git 没有资格替你拍板"。真正危险的时刻恰恰是你看到报错之后开始乱敲命令的时刻。稳住，先读文件，比急着搜解决方案重要得多。
3.2 坑二：commit 写完发现漏了文件，不敢改历史
小A有次提交完才注意到一个配置文件没加进去，但又不敢补提交，怕把历史弄脏。我告诉他，本地提交还没推出去之前，改全是安全的。
补漏文件的正确姿势是：先把漏掉的文件 git add，然后执行 git commit --amend。这个命令会把当前暂存区的内容和上一次提交合并，生成一个新提交替换掉原来那个，之前的提交记录会被顶掉，但改动都在。如果你想顺手改一下提交信息，可以用 git commit --amend -m "新的提交信息"。
我特意划了一条边界：已经推送到远程、而且别人可能已经拉取的提交，不要 amend。因为你改掉的是公共历史，别人本地还留着旧版本，一拉一推就分叉了。自己还没推出去的提交，随便改；已经推出去的，只准往上叠新的提交。
3.3 坑三：把临时改动提到了 main 分支
这是新手最容易出的事故：改到一半，脑子一热，在 main 上 git add . 加 git commit -m "wip"，然后突然反应过来——不该在 main 上留这种草稿。
如果这个提交还没推送到远程，我的处理方案是三步。先 git branch wip-fix，这一步会在当前提交上建一个分支指针，等于把"草稿提交"稳稳拖住；再 git reset --soft HEAD~1，main 分支指针回退一格，但改动保留在暂存区；最后 git switch wip-fix，切到刚才新建的分支上继续干活。整个过程之后，草稿就安全落在 wip-fix 分支上了。
这里要给新人提个醒：不许一上来就用 git reset --hard。--hard 会把工作区、暂存区一起回退，没提交过的文件可能直接没影。我知道事后可以用 git reflog 捞回来，但新手乱用 --hard 的心态很容易崩。正确路径永远是先想着怎么保全改动，再想怎么收拾分支。
3.4 坑四：pull 时报错 refusing to merge unrelated histories
有次小A在一个新目录里 git init，然后自己提交了一版，又 git remote add origin 关联了一个已经存在代码的远程仓库，结果 git pull 直接报 fatal: refusing to merge unrelated histories。他截图给我，语无伦次地说"是不是仓库废了"。
这个报错翻译成人话就是：你本地仓库和远程仓库的提交历史完全没有公共祖先，Git 觉得它们是两个八竿子打不着的项目，拒绝对接。出现这个报错，首先要反思的不该是怎么绕过去，而是当初为什么要 git init，而不是老老实实 git clone。
如果确实需要把两段历史接起来，比如本地有大量没推过的代码，可以用 git pull origin main --allow-unrelated-histories 强行合并。但我当时的建议是：直接放弃本地那个 git init 出来的仓库，把需要保留的文件拷出来，重新 git clone 远程仓库，再拷进去提交。这样历史干净，也不会埋下乱七八糟的根。
3.5 坑五：文件改名或调整大小写后，Git 状态对不上
这个问题比较隐蔽。小A在 Windows 上把 README.md 改成 Readme.md，结果 git status 什么都显示，他以为自己没改对。在同一天他又重命名了一个文件，Git 却又显示成了"删除旧文件加一个未跟踪新文件"。
前一个现象跟系统大小写不敏感有关，Git 默认的 core.ignorecase 在大小写不敏感的系统上是 true，所以只看大小写的改动会被忽略。处理方式有两个：要么把 core.ignorecase 改成 false，让 Git 能感知到大小写变化；更稳妥的是用两次 git mv，先把文件改成临时名，再改成目标大小写，比如 git mv readme.md readme.md.tmp 再接 git mv readme.md.tmp README.md。
至于重命名文件显示成删除加新增，本质上是 Git 从来没存储过"重命名"这个动作，它只认快照，git diff 时会根据内容相似度猜出来。为了避免历史记录被误读，建议用 git mv old new 来做重命名，这个命令会同时把移动动作加进暂存区，比手动 git rm 再 git add 直观得多。
我把这五个坑整理成了一个小表格贴在团队文档里，新同事自查起来非常方便：
| 坑 | 典型报错或现象 | 第一反应 | 推荐处理 |
|---|---|---|---|
| 合并冲突 | CONFLICT 标记 |
以为代码没了 | 读文件、商量、删标记、重新提交 |
| 漏文件提交 | 历史缺东西 | 想写假提交 | 本地未推送用 commit --amend |
| 误提 main | 项目主干变脏 | 想 reset --hard |
branch 先拖住，再 reset --soft 切走 |
| 历史不相容 | refusing to merge unrelated histories |
想强行合并 | 检查初始化路径，优先重新 clone |
| 改名失效 | Git 状态无变化 | 反复重试 | 调整 ignorecase 或用 git mv 两步改 |
4. 团队 Git 约定该从哪几条开始立
4.1 分支命名：让新人自己一眼看懂
新同学最怕的不是做错，而是看不懂别人在做什么。我们团队现在的分支名很简单，统一用前缀加描述：feat/ 代表新功能，fix/ 代表修问题，docs/ 代表文档变更，chore/ 代表杂务，refactor/ 代表重构。示例就是 feat/login-page、fix/user-password-typo 这种。
命名约定最大的价值不是好看，而是让新人从远程分支列表里一眼判断"这条分支大概在干什么"。如果分支名全是 dev、test、xiaoa/2024-06-01 这种含糊的名字，合代码的时候排查起来非常痛苦。我还加了另一条规矩：一个分支只装一件事。做到这条之后，回滚、评审、回归定位都会轻松很多——因为一个分支的历史是单一且可解释的。
4.2 提交信息：从"改了点东西"到 feat/fix
我要求团队提交信息统一用 type(scope): subject 的格式，比如 feat(login): 增加手机号登录、fix(order): 修复订单列表分页丢失。scope 是可选的小范围，type 明确这次提交的类型。给新人的最低要求就三条：说清楚改了哪里、说清楚为什么改、不写废话。
我最反感的一句话提交信息是"update"，因为它什么都没说。另一个建议是提交尽量保持"单次逻辑完整"，别把一个功能拆得七零八落，也别把调试代码混进正式改动。新人起初觉得这麻烦，但等到用 git log 往回找某个改动是为什么引入的时候，就会感谢当初多花的那几秒钟。
我还教会了小A一个动作：git add 之前先看一眼 git diff。只凭记忆往里 git add .，经常会把不想提交的调试内容一起带进去。这个习惯比任何规范都管用。
4.3 合并流程：什么时候 merge、什么时候 rebase
这个问题的答案取决于团队怎么定义历史。我们团队的方式很明确：功能分支在合回 main 之前，先用 git pull --rebase origin main 把本地提交"叠"到最新 main 之后，保持功能分支的提交是一条直线；合回 main 时用 git merge --no-ff feat/xxx，留一个明确的合并节点，标出"这次合并把什么功能带了进来"。
需要给新人单独解释的是 rebase 的边界：只允许处理还没推送出去的本第提交。已经推到公共分支、可能被别人拉取的提交，一律禁止再 rebase。这不是技术限制，而是协作底线——你改写一段别人已经引用的历史，会造成一堆无谓的分叉。
我给团队的共识可以浓缩成这么几句：本地随便整理，公共分支不搞历史改写；合入主干要保留合并节点；遇到需要紧急统一的场景，优先讨论而不是各搞各的。
4.4 保护与回滚：给新人兜底的最后一道网
如果说前面是"怎么做"，这节就是"万一做坏了怎么办"。第一件事，在托管平台上把 main 分支设成保护分支，不允许直接 push，所有改动必须走评审流程合入。这样就算新同学误操作，也推不进主干，问题只会被挡在门外。
第二件事，给新人两条保命口诀。任何状态下都先看 git status，先确认自己在哪，再动手；误操作之后先想 git reflog，不要慌着搜 git reset --hard 教程。尤其是 reflog，很多新人压根不知道它存在，其实它记录了你在本地做过的每一次 HEAD 移动，普通误操作几乎都能从这里找回。
第三件事，已经推出去的坏提交，用 git revert 生成一个反向提交来"撤销"，而不是改写历史。虽然 reset 也能达到目的，但一旦涉及公共分支，改写历史会给所有人带来额外负担。我还在团队手册里贴了一段标准的 revert 操作示例，遇到"昨夜提交的代码今天要撤掉"这种典型情况，新人直接用就是。
这些约定的本质不是限制，而是给所有人兜底。新人知道摔了有人接住、坏了有办法回滚，才敢放心大胆去操作、去进步。
5. 教完新人之后，我突然明白的事
5.1 讲一遍之后，我对 Git 的理解反而更清晰了
有句话说得很对：想看一个人是不是真的懂，就让他去教一遍。备课那几天我把自己以为理所当然的概念全部倒出来重新过了一遍，才发现很多地方我以前也是"会用，但说不清"。比如"commit 是快照不是差异"这件事，我天天用，但从来没过脑子；比如分支为什么这么轻，我也没认真想过。给新人讲一遍，等于强迫自己把隐性知识变成显性知识。
小A后来能独立处理冲突、能主动 rebase 整理历史的时候，我比他还有成就感。帮别人建立起模型这件事，比自己多学一个新命令有意思得多。
5.2 把"教别人"当成团队资产来维护
讲完之后我做的第一件事，是把白板上的图和口头讲的流程整理成一份内部文档。后来又有新人入职，直接先看文档、跑练手任务，老同事再也不用从零讲一遍。文档解决不了所有问题，答疑依然存在，但它能保证新人做的第一遍练习是同一套流程，而不是听某个老同事随机发挥。
另一个我觉得很值得的做法是"踩坑日报"。新人每解决一个问题，就记录一条：什么现象、什么命令、最后怎么处理的。日积月累，这份文档比任何教程都宝贵，因为它记录的是我们团队真实被绊倒过的每一块石头。反正是自己的仓库，多记录一点不会亏。
5.3 给带新人的同学几个实在建议
第一，别一上来就对着一份命令大全讲。先让新人跑通"改代码—提交—推送—合并"的最小闭环，再回头解释模型，不然概念和场景对不上号。
第二，别怕第一次花的时间长。我花了整整一下午加后来一周的答疑，换来的是一个基本能独立干活、还能教别人的同事。这笔时间省不掉的，越省后面越费。
第三，演示的时候故意制造报错。让新人看到你遇到 CONFLICT、遇到 rejected 之后的第一步是什么。动手修给自己看，比一百句"不要怕"都管用。
第四，给新人一个可以随便折腾的沙盒仓库。reset、rebase、amend 全都可以在沙盒里试错，反正 reflog 能兜底。只有在低风险的田地里练习过，遇到真仓库的高风险时刻才能稳住。
回到标题这句话。我原本只想讲一次 Git，结果那一次讲了整整一个下午，后来还讲出几十次答疑、一份团队文档和一堆约定。如果再来一个新人，我大概还是会叹口气、打开白板笔记，但这次我知道该从哪一张图开始画了——从那条带着便签的时间线开始，而不是从第一行 git init 开始。