Git核心操作全解析：add、commit、push的原理与实战

只要你写过几天代码，就应该听过Git那句经典口诀：add、commit、push。很多教程把它叫作“向仓库提交代码三步走”，听起来简单到不能再简单，可真到了实际项目里，我见过太多人在这一步上栽跟头。有人习惯性git add .，把密钥、日志、node_modules一股脑塞进仓库；有人 commit 信息随手写个“update”，三个月后翻 log 完全看不懂当时改了什么；还有人一到 push 就被no upstream branch之类的报错卡住，现场百度半天也搞不明白问题出在哪。

这篇文章我就围绕 add、commit、push 三个命令，把各自背后的设计逻辑、标准用法、高频报错和实操习惯一次性说清楚。适合刚接触 Git 的初学者把底子打牢，也适合用了一段时间但总被各种小问题折腾的开发者查漏补缺。文章里涉及的命令我都会解释“为什么要这么写”，不绕弯子，都是实际工作里能直接用上的东西。

1. 为什么说 add、commit、push 是Git的黄金三步

1.1 先搞懂Git的四个核心区域

很多人学 Git 学不明白，根源不在命令背不下来，而是脑子里没有一个清晰的“区域模型”。Git 处理代码的方式，本质上是文件在四个区域之间流转：工作区（Working Directory）、暂存区（Staging Area / Index）、本地版本库（Local Repository）、远程仓库（Remote Repository）。

工作区是你编辑器里正在改动的真实文件目录，你写代码、删文件、改配置，影响的全是工作区。暂存区则是 Git 给你开辟的一块临时缓冲区，用来收集你打算一起打包提交的文件快照。本地版本库在你机器的.git文件夹里，保存着项目从初始化到现在的所有提交历史。远程仓库则托管在服务器上，比如 Gitee、GitHub 或者你们公司内部的 GitLab，是团队协作时大家共享代码的地方。

如果觉得抽象，可以把它想象成投稿一本书的流程。工作区是你电脑里正在写的 Word 草稿；暂存区是你桌子上那个“准备寄出”的文件袋；本地版本库是你自己的档案柜，里面整齐摆着每一版的定稿；远程仓库是出版社总部的资料库。add 就是把草稿放进文件袋，commit 是把文件袋里的内容正式归档到自己的档案柜，push 是派快递把档案寄到出版社总部。这个类比基本能覆盖三步操作的全部含义。

1.2 为什么顺序必须是 add → commit → push

这三个命令的顺序不是随便定的，每一步都对应一个区域间的迁移，跨不过去，也跳不了级。add 负责把工作区的改动放入暂存区，commit 负责把暂存区的内容固化成一次本地提交，push 负责把本地提交同步到远程仓库。

为什么不能跳过 add 直接 commit？因为 Git 需要你明确告诉它：这次提交到底包含哪些改动。比如你一个下午改了五个文件，其中三个是登录功能的，两个是购物车功能的，你希望分成两次逻辑清晰的提交，就得先 add 那三个文件，commit 一次，再 add 剩下两个，commit 一次。如果没有暂存区这个设计，Git 就只能把工作区所有改动一股脑打成一次提交，想控制提交粒度就完全没戏了。

为什么不能跳过 commit 直接 push？因为 push 的本质是“把本地版本库中的某些提交传输到远程仓库”。本地如果没有生成任何 commit，那就没有东西可以推送。有些新手以为 push 是把工作区文件直接传上去，这是误解。push 的起点必须是 commit，commit 的起点必须是 add，这条链是环环相扣的。

1.3 暂存区到底带来了什么价值

暂存区这个设计，是 Git 比很多早期版本管理工具高明的地方。它给了你一个“反悔”和“挑选”的空间。你在工作区改了一堆文件，经过一天的高强度编码脑子已经不清醒了，这时候如果直接全部提交，很容易把临时调试代码、无用日志、甚至密钥文件一起提交上去。有了暂存区，你可以先git status看看到底有哪些改动，再决定哪些进入本次提交。

暂存区也让“分阶段提交”成为可能。一个文件里改了两处逻辑，一处是修 bug，一处是加功能，使用git add -p可以交互式地选择到底暂存哪一块。这种精细控制对代码 review 和后期排查非常有帮助。另外，误 add 了文件也有后悔药，git restore --staged <file>就能把文件从暂存区撤回到工作区，内容不会丢。

2. 环境准备：装好Git才能动手

2.1 Git安装和初始化配置

工欲善其事，必先利其器。先确保你的电脑上装好了 Git。Windows 用户可以直接去 Git 官网下载安装包，一路默认安装即可；也可以用包管理器，比如winget install --id Git.Git。macOS 用户执行brew install git，Linux 用户根据发行版执行sudo apt install git或sudo yum install git。有些朋友比较习惯图形界面，可以装一个 TortoiseGit，也就是常说的“小乌龟”，装完以后在资源管理器里右键就能完成大部分 Git 操作，对新手很友好。

安装完 Git 之后，第一件必须做的事是设置用户名和邮箱。这一步不是可选项，因为每次 commit 都会把作者信息写入提交记录，团队协作时全靠它定位“这段代码是谁写的”。

git config --global user.name "Tomy" git config --global user.email "tomy@example.com"

--global表示对当前系统用户全局生效。如果某个仓库需要单独的身份信息，可以在那个仓库目录下不加--global设置，仓库级配置会覆盖全局配置。查看当前配置用git config user.name和git config user.email。

2.2 SSH密钥配置与免密提交

如果你不想每次 push 都输一遍账号密码，SSH 免密是必须做的。原理很简单：你在本地生成一对公私钥，把公钥放到代码托管平台的账户里，之后 Git 通过 SSH 协议连接服务器时会自动完成身份验证，不再需要输入密码。

生成密钥最推荐用 ed25519 算法，密钥短、安全性高，新版 OpenSSH 都原生支持：

ssh-keygen -t ed25519 -C "tomy@example.com"

一路回车，默认保存到~/.ssh/id_ed25519。然后查看公钥内容：

cat ~/.ssh/id_ed25519.pub

把输出的一整行内容复制，登录 Gitee 或 GitHub，在设置里找到“SSH Keys”或“SSH公钥”入口，粘贴保存。验证是否配置成功，执行：

ssh -T git@gitee.com

看到类似Hi Tomy! You've successfully authenticated的输出，说明免密已经生效。这一步对应很多人在网上搜的“git免密”“git配置gitee密钥”，操作一次就能解决。注意，clone 仓库时要用 SSH 地址，也就是git@gitee.com:xxx/xxx.git这种格式，而不是https://开头的地址，否则仍然会走密码登录。

如果 SSH 密钥失效或者换了电脑，常见报错是Permission denied (publickey)。排查方向就两个：一是看本地密钥有没有加载（ssh-add -l），二是看托管平台上的公钥是否和本地私钥匹配。把这两个点检查一遍，基本都能解决。

3. 核心操作：add、commit、push一步步来

3.1 git add的多种姿势与选择

git add的核心作用是把改动放入暂存区，但它有多个变体，用法不同，影响范围也不同，我按实用频率给你梳理一遍。

最常用的是git add .，表示把当前目录下的所有改动加入暂存区，包括修改和新增文件。注意，它不会处理已被删除的文件（这个细节后面说）。git add -A比.更彻底，会把整个工作区的所有改动，包括删除操作，都纳入暂存区。git add -u则只更新已被 Git 跟踪的文件，新文件不会加进来，适合你只想提交已有文件的修改时用。如果只是想提交某个或某几个文件，直接写文件名：git add src/login.js docs/readme.md。

还有一个进阶神器git add -p，交互式暂存。你改了一个大文件，里面既有重构代码又有新功能，可以用它一块一块地选择哪些 hunk 进入暂存区。它会逐段问你Stage this hunk?，按 y 暂存、按 n 跳过、按 s 拆分更细的块。这个命令我几乎每天都会用到，对控制提交粒度帮助极大。

注意：不要把git add .当成肌肉记忆。我见过有开发者把.env文件一并提交到仓库，里面写着数据库密码和第三方密钥，直接把内部系统暴露了。正确的做法是先看好git status输出，确认没有敏感文件混入，再执行 add。

配合.gitignore文件能拦截掉绝大多数不该入库的内容。项目根目录新建.gitignore，把常见忽略项写进去：

.DS_Store node_modules/ dist/ *.log .env .env.local

这样就算你手滑执行git add .，这些文件也不会被加入暂存区，相当于多了一道保险。

3.2 git commit：把暂存区固化成一次提交

add 完成之后，下一步是 commit。基本命令是：

git commit -m "feat(login): 增加手机号登录接口"

-m后面跟提交信息。提交信息不是随便写写就行的，我强烈推荐使用 Conventional Commits 规范，格式是type(scope): subject。type 表示提交类型，最常用的包括 feat（新功能）、fix（修复bug）、docs（文档改动）、style（格式调整，不影响逻辑）、refactor（重构）、perf（性能优化）、test（测试相关）、chore（构建或工具链变动）。scope 是这个改动影响的范围，比如 login、cart、api。subject 是一句清晰的描述，说清楚“做了什么”，必要时可以再加正文说明“为什么这么做”。

例如：

git commit -m "fix(cart): 修复购物车数量为0时页面报错的问题" git commit -m "refactor(auth): 抽取token校验逻辑为公共方法"

为什么提交信息要这么讲究？因为 Git 的每个提交都是项目历史的“日志”。出 bug 的时候，你会打开git log --oneline查看最近几次提交，如果每一条都是“update”“fix”“aa”，你根本分不清哪个提交引入了问题。反之，规范的提交信息配合git blame能快速定位到具体行是哪次提交改的，找责任人、做回滚都会非常高效。

git commit还有一些实用参数。git commit -a可以跳过 add，直接提交所有已跟踪文件的改动，但注意它不会包含新文件，所以新文件仍然要先 add。git commit --amend可以修改上一次提交，比如漏提交了文件或者信息写错了，都可以用它补救。git commit --allow-empty允许生成一次空白提交，偶尔用于触发 CI 流程时会用到。

3.3 git push：把提交同步到远程仓库

commit 完成之后，代码还只存在你本地，队友看不到，云端的备份也没有。这一步就要靠git push把本地提交推送到远程仓库。

最基本的用法是：

git push origin master

这里origin是远程仓库的默认别名，master是你当前的分支名，也可能是main，具体看仓库初始化时的默认分支设置。如果是第一次往一个远程仓库推代码，很可能会遇到下面这条经典报错：

fatal: The current branch master has no upstream branch. To push the current branch and set the remote tracking branch, use git push --set-upstream origin master

意思是当前分支还没有和远程分支建立追踪关系，Git 不知道它该对应远程的哪个分支。解决方案就是按提示执行：

git push -u origin master

-u等价于--set-upstream，它会把当前分支的上游分支设置为origin/master，从今往后你在这个分支上直接执行git push就够了，不用每次都写完整命令。如果是自己创建的新仓库，还需要先关联远程地址，方法是：

git remote add origin git@gitee.com:用户名/仓库名.git git remote -v

第二条命令用来确认关联是否成功。push 的时候如果远程分支和本地分支名字不同，可以显式指定：git push origin dev，这样会把本地的 dev 分支推送到远程的 dev 分支。

注意：git push --force会强制覆盖远程分支的历史，非常危险。团队协作时千万不要随意使用。如果确实需要覆盖，优先用--force-with-lease，它会在覆盖前检查远程分支是否发生了变化，比裸--force安全得多。

push 过程中经常会遇到! [rejected] master -> master (fetch first)的提示，这说明远程仓库有本地没有的提交，你的 push 被拒绝了。正确的处理方式是把远端改动先拉下来，合并完成后再推送，具体步骤在下一章的冲突处理里详细讲。

4. 常见报错与排查技巧实录

4.1 fatal: not a git repository 的几种可能

这个报错大概是 Git 新手最先遇到的一个。报错信息是：

fatal: not a git repository (or any of the parent directories): .git

含义很简单：当前目录不是 Git 仓库，或者从当前目录往上找，都找不到包含.git的仓库目录。解决办法也直白：如果你是想在现有项目里用 Git，先确认路径对不对，是不是真的进入了项目目录；如果你是想把当前目录初始化为 Git 仓库，执行git init；如果项目是从远程 clone 下来的，正常情况不会出现这个错，出现的话多半是.git文件夹被误删了，那就只能重新git init，但历史记录也就随之丢失了。

我在实际工作中还碰到一种情况：在仓库的子目录里操作 Git 没问题，但切到系统用户目录或者别的无关目录执行 Git 命令，就会报这个错。记住一个判断原则：能执行git status且不报错，说明你处于某个仓库范围内；报错了，优先考虑目录层级和.git是否存在。

4.2 commit提交后发现写错了怎么办

这个问题出现频率极高，解决办法也很成熟。如果你的提交还没 push 到远程，用git commit --amend直接修改即可。

只想改上次的提交信息：

git commit --amend -m "feat(order): 修正订单超时判断逻辑"

上次提交漏了文件，先 add 再 amend：

git add 漏掉的文件 git commit --amend

不写-m时会自动打开编辑器，保留上一次的信息，你只需要确认或者修改一下，保存退出就行。amend 的本质是生成一个新的提交来替换原来的提交，所以它只适合“还没有推送远端”的场景。如果该提交已经被 push 并且队友已经拉取，就不要再 amend 了，否则会导致你们两个人的提交历史分叉，后续每次 pull/push 都是冲突。如果实在必须改，改完之后需要git push --force-with-lease，并且一定要提前和团队成员打招呼。

还有一个比较隐蔽的坑：commit 之后发现提交里包含了大文件或者被 A 忽略的文件，此时 amend 只能改信息，没法把文件从历史里真正抹掉。想彻底删除历史里的大文件，需要用到git filter-branch或者 BFG Repo-Cleaner，这属于高级操作，日常开发中如果遇到，建议先备份仓库再动手。

4.3 push被拒绝与冲突处理

push 被拒绝是团队协作中很难避免的情况。报错信息大概长这样：

! [rejected] master -> master (fetch first) error: failed to push some refs to 'git@gitee.com:xxx/xxx.git' hint: Updates were rejected because the remote contains work that you do hint: not have locally. This is usually caused by another repository pushing hint: to the same ref.

核心原因就是远程仓库有本地没有的提交，如果 Git 允许你直接 push，会把队友的提交覆盖掉，所以 Git 会直接拒绝。解决方案是先拉取远程改动，合并后再推送。

我个人推荐的做法是：

git pull --rebase origin master

--rebase的意思是把你本地的提交临时摘下来，等远程的新提交应用完成后，再把你的提交放到最前面。这样得到的历史是一条干净的线性记录，没有多余的 merge 提交，git log --graph看起来会非常清爽。如果不用--rebase，默认会生成一个 merge commit，长此以往提交历史会越来越乱，review 代码时非常痛苦。

pull 的过程中如果两边改了同一个文件的同一个位置，Git 就会提示冲突。打开冲突文件，你会看到类似这样的内容：

<<<<<<< HEAD 当前分支（或远程）的代码 ======= 你本地的代码 >>>>>>> feature/xxx

手动整理成最终想要的代码，删掉<<<<<<<、=======、>>>>>>>这些标记行，然后执行：

git add 冲突解决后的文件 git rebase --continue

最后再git push，问题就解决了。冲突本身不可怕，它只是 Git 在保护大家的代码不被互相覆盖。养成“push 前先 pull --rebase”的习惯，遇到冲突的概率会小很多。

4.4 其他几个高频报错速查

我整理了一个高频报错速查表，可以直接收藏备用：

另外提醒一下，线上项目如果部署到服务器时把.git目录暴露在了 web 根目录下，攻击者可以直接访问/.git/config获取仓库元数据，甚至可能下载到完整源码。这是很多安全事故的源头。排查方法是在 Nginx 配置里对/.git路径做访问限制，或者干脆部署时把.git目录从项目目录里隔离出去。作为开发者，更重要的是守好.gitignore，敏感文件坚决不进版本库。

5. 进阶技巧与实操心得

5.1 让大模型帮你生成规范commit信息

现在写代码用上大模型已经是很常态的操作了，连 commit 信息也能让模型代劳。我的习惯是先把已暂存的改动内容取出来，再丢给大模型去生成符合规范的提交信息。命令如下：

git diff --cached

把输出内容复制给大模型，附加一句提示：“请根据以下 diff 内容，按照 Conventional Commits 规范生成一条简洁的 commit 信息，包含 type、scope 和 subject。”模型会返回类似feat(user): 增加用户昵称修改接口这样的结果，自己校验一遍没有问题再执行 commit。

如果是大型重构，或者涉及 Vue 项目里多个组件同时改动的情况，diff 输出往往非常长，一股脑全塞给模型既浪费 token 又容易让它抓不住重点。我建议先执行git diff --cached --stat看哪些文件改动量最大，再挑出核心文件的具体 diff 给模型分析。这样做下来的 commit 信息往往比随手敲的update、fix强太多，至少它能把这次改动的“背景”写清楚，回头看的时候能省很多时间。

5.2 提交前的自检清单

踩过太多次“手滑”的坑之后，我现在每次提交前都会有一整套自检流程，熟练之后也就一两分钟，但能避免掉绝大多数低级事故。

第一步，git status看当前工作区的状态，有哪些文件被修改、哪些文件是新增的。第二步，git diff看未暂存的改动内容，重点确认没有把调试代码、临时日志、本地环境相关的改动混进去。第三步，git diff --cached看即将被提交到暂存区的内容，这一步相当于提交前的最终确认。第四步，检查 commit 信息是否写清楚了“做了什么”和“为什么”，而不是单纯描述文件路径。第五步，判断这次提交的粒度是否合适。一次提交最好只做一件逻辑完整的事，如果你发现这次提交里既有登录功能又有购物车修复，强烈建议拆分。

我印象最深的一次事故，是急着下班，执行git add .之后没有看状态就直接 commit push，结果把一个本地测试用的临时配置文件带上去了，同事 pull 下来之后整个项目启动报错。那天晚上我在群里公开道歉，从此以后“push 前检查”就成了肌肉记忆。

5.3 git stash 与 git worktree 的妙用

在“三步走”的基础上，还有两个命令非常值得掌握，它们解决的是“手头工作没做完，但又不得不切分支”的窘境。

git stash可以把当前工作区的改动暂时保存起来，让工作区回到干净状态。比如你正在 dev 分支开发功能，线上突然报了个紧急 bug，需要立刻切换到 master 分支修复。直接切分支会报错，因为工作区有未提交的改动。这个时候执行git stash，切分支、修 bug、提交、push，再切回 dev 分支，执行git stash pop，之前没做完的工作就原样回来了。

git worktree更厉害，它允许一个仓库同时存在多个工作目录。同样上面那个场景，不想打断当前开发进度，可以直接执行：

git worktree add ../hotfix -b hotfix/xxx

然后在新目录里切换分支、修 bug，和原来的工作区互不干扰。这个命令对“需要同时维护多个分支”的场景特别实用。等 bug 修完，git worktree remove ../hotfix就能清理掉多余的工作目录。

5.4 分支策略与提交习惯的个人建议

最后聊点软性的东西。add、commit、push 是命令层面的基本功，但放在真实项目里，还需要一套分支策略和提交习惯来支撑。我的个人建议是：main/master 分支始终保持可用，任何未经测试的新功能都不要直接推到主分支；新功能在单独的分支上开发，合并回主分支前至少自己在本地跑一遍测试；合并时优先用--no-ff保留一个合并记录，方便以后知道哪些功能合入了主分支。

写到这里，我发现很多所谓“Git 很难”的恐惧，其实来自对底层的无知和对报错的不理解。把 add、commit、push 吃透，再配合git status、git diff、git log这三个查看命令，日常开发 90% 的场景你都能游刃有余。真正决定一个开发者 Git 水平的，不是熟练用了多少高级技巧，而是能不能在每一次提交时都保持“这个提交是清晰、完整、可追溯的”这样一种习惯。代码写得快不算本事，写出来的东西别人能接得住、查得清，那才是真功夫。