先交代一个背景我过去带过不少新人也帮团队做过几轮 Git 内训发现一个普遍现象——很多人并不是不努力而是被碎片化的教程带偏了。今天查一个命令明天搜一个报错遇到问题全靠搜索引擎结果 Git 用了两三年还是停留在add、commit、push、pull这四个命令上。一旦碰上分支合并冲突、提交信息写错、SSH 认证失效整个人就懵了。所以这篇内容我决定换一种写法不按命令列表堆砌而是把 Git 拆成两条线来讲一条是速成主线让你在半小时内建立起完整的操作闭环另一条是查用手册线按“我想干什么”来组织高频命令与排查思路遇到问题直接翻对应部分。内容会尽量贴近我实际写代码、带项目时的真实场景也会把容易踩的坑提前指出来。这篇内容适合谁刚接触 Git 的新人、用了 Git 但一直没系统梳理过的老手以及需要带着团队落地 Git 规范的负责人。如果你只是想搜单个命令直接翻到最后两章的速查表如果你想一次搞懂 Git 的运行逻辑建议从头顺序读下去。1. 先搞明白 Git 到底在折腾什么三个区、三个对象、一套指针很多人学 Git 觉得难不是因为命令多而是因为没理解它的核心模型。就像你学开车如果不知道油门刹车离合分别控制什么光背“起步挂一档”这种口诀换个车型照样熄火。Git 也一样它的设计其实非常简洁只是各种教程喜欢堆细节把简单的东西讲复杂了。1.1 Git 的底层不是“存差异”而是“存快照”这是一个最常被误解的点。SVN 那类集中式版本管理工具记录的是文件每次的差异而 Git 记录的是每个提交瞬间的完整快照——它会把当前所有被跟踪文件的内容做一个整体镜像。听起来很浪费空间但 Git 用了一个聪明的办法文件内容如果没变化新快照直接复用原来的存储块只有发生变化的文件才真正写入新数据。所以快照之间是共享存储的并不会无限膨胀。这个设计带来的直接好处是切换分支、回滚历史变得极其廉价且可靠。你随时可以把整个项目恢复到历史上任何一个提交点的状态而不需要像差异模型那样做一系列反向补丁运算。理解了这一点后面很多命令行为就顺理成章了。1.2 三个区的数据流工作区、暂存区、本地仓库Git 的操作模型可以用一句话概括文件从工作区流到暂存区再从暂存区流到本地仓库最后从本地仓库推到远程仓库。工作区Working Directory就是你磁盘上看到的文件你在这里改代码。暂存区Staging Area / Index一个隐藏的过渡区域存放你“打算纳入下一个提交”的文件快照。本地仓库Local Repository.git目录里的内容保存所有提交历史。对应的三个核心命令就是git add工作区 → 暂存区、git commit暂存区 → 本地仓库、git push本地仓库 → 远程仓库。为什么中间要隔一个“暂存区”这是 Git 最容易被新手忽略、但实际非常好用的设计。它让你可以把一次提交拆分成多个逻辑单元比如你同时改了一个 bug 和一个功能可以用git add分别挑选文件生成两个不同语义的提交历史就会非常清晰。这个习惯在团队协作里极其重要因为后面所有人查看历史、回滚代码时都是按提交单元来理解的。1.3 三个核心对象 引用指针Git 内部有三个核心对象理解了它们几乎就能看懂所有 Git 命令的运作逻辑对象作用类比Blob存文件内容不存文件名和路径硬盘上的一个文件实体Tree存目录结构记录哪个路径对应哪个 Blob一份文件清单Commit存一次提交的快照指向一个 Tree并记录作者、提交者、时间、父提交一条变更档案此外还有引用References最常见的引用就是分支。很多人以为分支是一系列提交的集合其实不对。分支本质上就是一个可移动的指针指向某一个 Commit。当你新建分支只是复制了一个指针当你切换分支只是把 HEAD 指向另一个指针。这就是为什么 Git 新建分支和切换分支快得惊人——它只是在移动指针而不是真的复制代码目录。还有一个经常被忽略的引用叫HEAD它指向“当前所在的分支”而分支又指向某个具体 Commit。所以整个 Git 的运行逻辑其实就是通过 HEAD 找到当前分支通过分支找到当前提交通过当前提交找到对应的目录快照。所有的分支切换、提交、合并、回滚本质上都是在操作这些指针。2. 从下载安装到跑通第一行命令环境准备与全局配置避坑说实话安装 Git 这件事本身不难但我在不止一台机器上见过配置出问题的情况后面 SSH 认证失败、提交用户信息错误、换行符警告满天飞根子都是安装后头几步没做对。所以这一章把安装和初始化配置完整走一遍。2.1 下载安装Windows 与 macOS 的路径选择Windows直接去 Git 官网下载 Git for Windows 安装包。安装时大部分默认项可以直接接受但有三个选项建议调整一下。第一默认编辑器如果你不熟悉 Vim强烈建议在安装引导里把默认编辑器切换为 VS Code 或 Notepad否则以后执行git commit时会进到 Vim 里出不来新人的第一记闷棍基本都挨在这里。第二PATH 环境变量那一步建议选“Git from the command line and also from 3rd-party software”这样其他终端工具也能直接调用。第三换行符转换那一步如果团队以 Windows 为主选第二个“Checkout as-is, commit as-is”最省心如果团队跨平台且不确定选第一项“Checkout Windows-style, commit Unix-style”也行但后面可能出现换行符警告心理要有数。macOS最省事的方式是装 Homebrew 后执行brew install git。不建议用 Xcode Command Line Tools 内置的 Git版本通常偏旧。装完验证一下git --version确保输出的版本号比较新。如果之前装过旧版 Git最好先确认which git指向的是你新装的路径而不是系统默认的/usr/bin/git。装好之后在终端里敲git不带参数能看到常用命令列表就说明环境没问题了。2.2 全局配置三件必须做的事通常安装完第一件事就是配置用户信息这个不做你连第一次 commit 都提交不了git config --global user.name Your Name git config --global user.email youexample.com邮箱务必使用你代码托管平台绑定的那个邮箱否则提交记录不会关联到你的账号头像和主页。最好把这两行写进备忘录因为它是全局配置决定你所有仓库里提交记录归属。想检查已设置的配置git config --global --list第二件必须做的事是把默认分支名统一成main省得每次创建仓库还要手动改git config --global init.defaultBranch main第三件是生成 SSH 密钥、配置托管平台的公钥这部分会在第五章讲认证问题时展开。这里先记住命令ssh-keygen -t ed25519 -C youexample.com密钥生成后把公钥.pub文件里的内容复制到 GitHub/Gitee/GitLab 的 SSH keys 设置里然后测试联通即可。2.3 容易被忽略的全局级配置项除了上面三件下面这几个配置项也算是我踩过坑之后额外加的配置默认编辑器git config --global core.editor code --wait这样以后编辑提交信息时会直接打开 VS Code。配置别名Alias我常配的是git config --global alias.st status、alias.co checkout、alias.ci commit、alias.br branch。用久了你会发现输入效率高很多。配置文件大小写敏感性Git 默认对文件名大小写敏感但 Windows/macOS 文件系统不敏感容易改文件名后没被记录到变更里。推荐给仓库设置git config core.ignorecase false。此外还有 HTTPS 的 credential helper。用 HTTPS 方式拉取私有仓库时每次都要输入账号密码很痛苦建议执行一次git config --global credential.helper store第一次输入密码后会被记住。但这也有安全风险个人电脑无所谓公用机器就不要开了改用 SSH key 方式更安全。3. 不背命令表按真实场景走一遍新建项目到首次推送命令表背是背不完的而且背了也容易忘。我自己的经验是把最常用的操作闭环练熟形成肌肉记忆其他命令遇到再查。下面按一个真实场景交付整个流程——从零新建一个本地项目推到远程仓库。3.1 场景一本地已有项目首次关联远程仓库假设你已经在本地建了项目目录里面有了一堆文件。进入目录后git init执行完这个目录就变成了一个 Git 仓库生成了隐藏的.git目录。然后检查一下当前状态git status你会看到所有未被跟踪的文件。这时要养成一个习惯先看看有没有需要忽略的文件比如node_modules/、dist/、.env、IDE 目录等。写一个.gitignore文件把不该进仓库的都排除掉# 依赖目录 node_modules/ # 构建产物 dist/ build/ # 环境变量与密钥 .env *.local # IDE 与系统文件 .idea/ .vscode/ .DS_Store.gitignore一定要在第一次git add之前创建好否则后面你git add了一大堆本该忽略的文件还得用git rm --cached把它们从暂存区挪出去很麻烦。然后分两步提交git add . git commit -m 初始提交搭建项目基础结构如果提交信息比较长也可以不加-m直接执行git commit进入编辑器写多行提交信息。规范的提交信息建议用type: subject的格式比如feat: 新增用户登录接口、fix: 修复首页白屏问题。这个习惯在团队协作里价值极高后面 git log 一眼就能看清历史。首次提交完成后去代码托管平台新建一个空仓库把仓库地址复制下来SSH 格式优先。然后关联远程地址并推送git remote add origin gitgithub.com:username/repo.git git branch -M main git push -u origin main-u参数的作用是把本地分支和远程分支建立跟踪关系之后直接敲git push就能推不需要每次指定远程和分支名。3.2 场景二远程已有项目首次拉下来开发这是更常见的场景也是热搜词里“IDEA 创建新项目拉取 Git”对应的场景。在终端里执行git clone gitgithub.com:username/repo.git这个命令会做三件事在当前目录下创建同名项目文件夹、初始化本地 Git 仓库、自动关联远程分支并设置跟踪关系。git clone完成之后不需要手动git remote add直接进入目录就可以开始开发。在 IDEA 里操作也很简单File - New - Project from Version Control粘贴仓库地址选好本地目录点 Clone 即可。IDE 背后执行的就是git clone所以你只需要知道这个命令在终端里长什么样就不容易被 IDE 的报错绕晕。3.3 日常开发循环改代码、提交、推送的正确姿势日常开发最核心的循环是重复这三步关键在顺序正确git status # 1. 看清当前改动 git diff # 2. 确认改过的内容细节 git add 有需要的文件 # 3. 挑选要提交的文件/全部 git commit -m feat: 完成XX功能 git push # 5. 推送到远程很多新手死磕git add .和git commit不会用是因为跳过了git status和git diff。这两个命令才是操作的基础——在提交之前你必须清楚自己动了哪些文件、改动是什么。我见过有人提交的时候把调试日志、临时测试文件、本机配置文件全提交上去了原因是从来没在git status前确认过。还有一段经验也值得分享小步提交一次提交只做一件事。不要憋到一整天结束才 commit那时你可能已经改了十几个文件提交信息根本写不清到底改了什么。我现在的习惯是完成一个逻辑单元就 commit 一次哪怕这个单元只有半小时的改动量。小提交的好处是git log看起来非常顺之后需要git revert或git cherry-pick时都很精准。3.4 .gitignore 的两种失效场景与补救办法.gitignore是个好东西但有两个常见坑。第一已经加入版本控制的文件改 .gitignore 不会让它被忽略。比如你先git add .env提交了后来才在.gitignore里加上.env再改.env文件时Git 依然会显示它被修改。正确的处理是先从版本控制中移除git rm --cached .env然后再提交一次文件就从仓库中移除了但本机磁盘上仍然保留。第二规则写错导致忽略失效。比如你写了dist/但如果某个dist路径前面有嵌套目录有些写法可能匹配不到。建议用git status --ignored查看当前哪些文件被忽略以及git check-ignore -v 文件路径来排查某条规则到底由哪一行触发。这比盲目试.gitignore写法高效得多。4. 分支合并从来不是“复制粘贴代码”merge 与 rebase 的使用边界分支是 Git 最强大的功能也是我自己早期最不敢碰的功能。说实话我见过很多团队因为不会安全地合并分支干脆全员只在 main 上开发结果一旦出现多人同时修改冲突直接爆炸。这里把分支用的核心场景和底层逻辑讲透。4.1 分支存在的意义让并行开发互不干扰分支的本质是一个标签指针指向某个 Commit。你创建分支后提交新代码只是在移动这个指针完全不影响其他分支的指针位置。这就是为什么并行的功能开发、紧急修复、实验性尝试都可以同时进行。实际项目里最常见的分支模型是主干分支main始终保持稳定可发布的版本开发分支从main拉出功能开发完成后再合并回去。紧急修复则从main单独开一条hotfix分支修完快速合回main同时也要合并回当前的开发分支防止主干和开发分叉越来越远。4.2 merge 的工作原理与三种合并结果很多人把git merge想成“把代码复制过来”其实不是。它做的是找到两个分支的共同祖先把两边从祖先以来的变更做一次三方合并生成一个新的合并提交。这个过程有三种结果快进合并Fast-forward目标分支自共同祖先以来没有任何新提交此时只需要把指针直接往前移到源分支的位置不会产生新的提交。三方合并Recursive Merge两侧都有新提交且改动互不冲突Git 自动完成合并生成一个 Merge Commit。冲突合并Conflict两侧改了同一处代码Git 无法判断哪边是正确的只能停下来让你手动解决。理解快进合并很重要。为什么团队规范里经常要求“合并代码前先 pull 最新 main”就是为了尽量避免大量三方合而产生的网状历史。如果你把远程最新代码拉下来、再合并自己的分支大概率走的是快进合并历史就是一条干净的直线后面查看、回滚都轻松。4.3 实际合并代码的完整流程与冲突处理假设你在feature/login分支上完成了登录功能想把代码合到maingit checkout main git pull origin main git merge feature/login切换到main并先更新到最新这是合并前的标准姿势。如果git merge中途提示冲突Git 会列出冲突文件。这时用git status查看冲突清单然后打开冲突文件你会看到类似这样的标记 HEAD 这里是 main 分支上的当前内容 这里是 feature/login 分支上的内容 feature/login和之间是当前分支HEAD的内容和之间是待合并分支的内容。你需要手动决定保留哪边或整合成一段新代码然后删掉所有冲突标记保存文件。逐文件处理完后执行git add . git commit -m merge: 合并 feature/login 到 main解决用户信息字段冲突注意提交时不需要再去指定两条分支——merge 冲突解决后的提交会自动带上两个父提交完成这次的合并。4.4 rebase另一种“合并”思路以及什么时候不该用git rebase的原理是把你当前分支的提交逐个“搬运”到目标分支的最新提交之上重放一遍。效果是历史变成了一条无分叉的直线。但它有个重要特点rebase 会改写提交历史因为提交的父节点变了每个提交的 hash 值都会变。所以有一条铁律不要对已经推送到远程的分支做 rebase尤其不要在共享分支比如 main、develop上做 rebase。一旦你 rebase 后强推覆盖了别人的提交团队历史就会错乱那是灾难级的操作。我的建议是个人开发分支上可以任意用 rebase 来整理提交让历史干净共享分支上只用 merge。举个例子你开发到一半发现 main 被人推送了新功能你想基于最新的 main 继续开发可以用git checkout feature/login git rebase main执行后你这条分支上的提交就会被重放到 main 最新的提交之上。这样等最终合回 main 时大概率是快进合并历史干净。但如果中途有冲突处理原则和 merge 一样解决冲突 -git add-git rebase --continue。如果中途发现问题想放弃用git rebase --abort回到 rebase 之前的状态。4.5 关于 cherry-pick 和临时分支的巧妙用法除了 merge 和 rebasegit cherry-pick是一个被低估的命令。它可以把任意一个 Commit 的变更“摘取”到你当前分支不合并整个分支git checkout main git cherry-pick a1b2c3d这个命令非常适合“线上有 bug但某个修复是在开发分支上做的只想把这个修复提交单独拿到主干”这种场景。它会把指定提交上的变更重新应用一次生成一个新的提交。另外提醒一个技巧尽量让主干的提交是以 merge 或 cherry-pick 方式进入的不要直接在主干上 commit 大量功能开发代码。这样主干的历史非常稳定每次合并进来就是一个完整的功能单元出事也方便回滚整个功能git revert -m 1 合并提交的hash。5. SSH 认证失败的完整排查链路从报错信息到密钥重装热搜词里有一条“ssh认证失败 git”这绝对是从踩坑一线来的真实痛点。我自己至少帮三个人解决过这个问题场景几乎都一样原本项目拉得好好的突然某天git push报错Permission denied (publickey)或者新换了电脑、换了代码托管平台后怎么都连不上。这里把整个排查链路写清楚照着走基本一遍就能定位。5.1 先看懂报错信息在告诉你什么SSH 认证失败最常见的报错有这么几句话gitgithub.com: Permission denied (publickey).或Could not read from remote repository. Please make sure you have the correct access rights and the repository exists.很多人到这里第一反应是“仓库地址是不是错了”但其实 95% 的这类报错跟仓库地址无关问题出在密钥匹配上。还有一个误区要澄清全局配置的user.name和user.email与 SSH 认证没有任何关系。你改这两行也解决不了Permission denied。SSH 认证只验证你的密钥是否被托管平台认可不验证姓名邮箱。5.2 第一个检查点本地是否存在密钥终端执行ls -al ~/.ssh如果看到id_ed25519和id_ed25519.pub或id_rsa、id_rsa.pub说明你曾经生成过密钥如果这个目录根本不存在或者只有known_hosts文件那就是密钥丢了。这种情况下直接重新生成ssh-keygen -t ed25519 -C youexample.com一路回车即可。生成的id_ed25519.pub就是公钥它的内容是公开的可以随意复制、添加到任意平台私钥id_ed25519绝不能外传它就是你的身份凭证。生成之后还有一个重要步骤——把密钥添加到 SSH agenteval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519如果不做这一步某些环境下即使公钥已经添加到了平台SSH agent 也不会自动找你本地私钥进行签名。macOS 用户如果重启后老遇到“每次都要重新加载私钥”的问题可以执行ssh-add --apple-use-keychain ~/.ssh/id_ed25519把密码记录到系统钥匙串里省得每次开机重新ssh-add。5.3 第二个检查点公钥是否放到了正确平台把公钥内容复制出来cat ~/.ssh/id_ed25519.pub然后登录你的代码托管平台GitHub / Gitee / GitLab进入Settings - SSH and GPG keys把这段公钥粘贴上去给它起一个容易识别的名字比如“我的工作电脑”。保存前注意确认平台名和端口——GitHub 是gitgithub.comGitee 是gitgitee.comGitLab 是gitgitlab.com不要把一个平台的公钥放到另一个平台去找地址对不上自然会报错。5.4 第三个检查点测试连通性与排除 URL 地址干扰配置完公钥后执行ssh -T gitgithub.com这条连接不会真的登录 shell它只是测试认证链路。成功的提示通常是Hi username! Youve successfully authenticated。如果这里成功说明 SSH 链路没问题那问题就出在当前仓库的远程地址上。git remote -v检查输出里远程地址是 SSH 格式还是 HTTPS 格式。如果你配置的是 SSH 公钥但远程地址用的是https://github.com/user/repo.gitSSH 认证根本不参与会一直提示输入账号密码或认证失败。解决办法是改成 SSH 格式git remote set-url origin gitgithub.com:user/repo.git5.5 排查链路的最后手段开启详细调试日志如果上面三步都排查过还是没解决就启动 SSH 调试模式GIT_SSH_COMMANDssh -vT git push origin main注意-v可以重复加-vvv信息更详细。输出的日志里重点看两处debug1: Offering public key: ...这行会显示 SSH agent 向服务器“展示”了哪些密钥路径。server accepts key或send_pubkey_test相关行则显示服务器端是否认可。如果日志里Offering public key的路径跟你本地私钥路径不一致说明 SSH agent 里加载了错误的密钥用ssh-add -D清空后重新ssh-add ~/.ssh/id_ed25519即可。这片排查链路我实测过多次按顺序走基本 10 分钟内能定位问题。还有一条经验要特别记牢更换电脑或重装系统后第一件事就是把原来平台的公钥删掉并重新添加新机器的公钥旧公钥留在平台上有安全风险而且你自己的新私钥也匹配不上旧公钥。平台对公钥的数量也有限制不及时清理会在未来埋雷。6. 放在手边的“查用速查表”按“想干什么”索引附高频疑问判读这一章是我自己坚持推荐给团队同事的内容——查手册时别按命令字母索引按“目的”索引。你想解决什么问题翻到对应位置命令自然全出来了。6.1 状态查看与日常提交速查我想干什么命令查看当前工作区与暂存区状态git status查看未暂存的改动、已暂存的改动git diff/git diff --cached查看提交历史git log --oneline --graph --all查看某个文件的修改历史git log --follow -- file暂存所有改动git add .只暂存指定文件git add src/main.py提交并写多行信息git commit不跟 -m修改上一次提交信息git commit --amend -m 新信息跳过暂存区直接提交只对已跟踪文件git commit -am description6.2 分支操作与合并速查我想干什么命令查看全部分支git branch -a新建并切换分支git checkout -b feature/xxx只新建分支不切换git branch feature/xxx切换分支git checkout feature/xxx或git switch删除本地分支git branch -d feature/xxx删除远程分支git push origin --delete feature/xxx合并某分支到当前分支git merge feature/xxx摘取一个提交git cherry-pick commit-hash把当前分支变基到某分支git rebase main6.3 撤销与回滚速查三类后悔药的使用边界撤销是新手最不敢碰的操作因为怕把代码搞丢。其实按对象区分命令并不复杂场景命令说明工作区改乱了想恢复到上次暂存/提交状态git restore file不保留工作区改动已经git add了想取消暂存git restore --staged file只是移出暂存区文件内容不变提交写错了想重新提交git commit --amend只在还没 push 时使用撤销某个提交保留历史git revert commit-hash生成一条反向提交安全彻底丢弃最近几次提交git reset --hard HEAD~3危险操作别在共享分支用误删/误重置后找回git reflog找到之前的操作记录再 reset 回去单独强调一下git reflog这是我最想安利给所有人的命令。它记录的是你本地仓库的每一次 HEAD 移动轨迹包括 reset、checkout、rebase、merge 等操作。很多所谓“代码丢了”的恐慌其实 90% 都能用git reflog找回。比如你git reset --hard丢了三天的提交执行git reflog看到之前分支指向的提交 hash再git reset --hard 那个hash就全部恢复了。它的存在相当于给 Git 上了一道保险但很多人根本不知道。6.4 远程仓库与团队协作速查我想干什么命令查看远程仓库配置git remote -v添加远程仓库git remote add origin url修改远程地址git remote set-url origin url拉取最新代码并合并git pull origin main只拉取不合并git fetch origin推送当前分支git push origin branch首次推送并设置跟踪关系git push -u origin branch强推慎用git push --force-with-lease6.5 高频疑问判读这几条是我被问过最多的问题问题 1git pull 报错“fatal: Not possible to fast-forward”原因是远程更新了代码而你本地也有提交两条线没有共同目标时 Git 想合并但策略上有冲突。解决方式执行git pull --rebase让 Git 把你的本地提交变基到远程最新代码之上再推送。问题 2切换分支时提示“Your local changes would be overwritten”说明当前有未提交的改动切换分支会造成覆盖风险。正确做法是git stash暂存起来切换分支做完事再git stash pop恢复。如果确认当前改动不需要了用git restore file丢弃。问题 3误把密码文件 push 上去了怎么办先删除远端文件git rm --cached .env提交并推送。但要注意提交历史里仍然保留着这个密码明文别人 clone 完整历史就能看到。规避的办法如果需要彻底清除历史得用git filter-repo这类工具重写历史并且强制推送到所有远端。这个操作对共享分支影响很大通常需要团队配合。所以最好的策略还是从一开始就做好.gitignore别让敏感信息上船。问题 4如何查看一个提交到底改了什么git show commit-hash这条命令会同时显示提交信息和变更内容是 code review 和排错时最高频的命令。7. 从速成到日常好用我实践后的几条建议到这里Git 的核心使用闭环已经完整了。如果让我把文章浓缩成几句话大概是理解三个区和指针模型把首次推送拉通一次分支合并按规范来认证出问题按链路排日常高频命令按“目的”索引。能做到这五件事Git 基本不会再给你添乱。最后再分享一点我在项目里用的具体习惯。我们团队现在统一规定主干分支永远不直接推代码一切改动都是功能分支 Merge Request / Pull Request 进主干。每个 MR 只对应一个明确的业务需求提交信息写清楚类型和摘要代码合并前必须由其他人过一遍。这样做了半年之后整个仓库的历史干净到可以用git log --oneline一口气按功能点读下来再往后做版本发布、线上回滚都变得出奇地稳。如果你刚学 Git不用急着把所有命令都记住先把本章速查表放在手边遇到操作需求再翻。最常见的那个循环——改代码、看状态、暂存、提交、推送——用一周左右形成习惯后你就不需要再回头查基础命令了。真正的进阶是在你遇到第一个冲突、第一次误操作、第一回需要找回代码时回头再读一遍本文对应的章节那时候你的理解会比第一次看深得多。