何为自律入行这么多年，带过的新人基本都会先在 Git 上栽几个跟头。不是没见过有人把项目文件夹改成 v2_final_改改 这种名字，手动维护几十份压缩包，最后连自己都分不清哪个才是能跑的最新版本；也不是没见过多人同时改一份代码，互相覆盖之后一群人围在白板前对着一堆 commit 记录手足无措。Git 要解决的，从来不只是“保存一下”这个表面问题，而是给整个项目的每一次变化建立一个可追溯、可回滚、可协同的结构化历史。这篇文章面向所有想把 Git 真正用起来的人，从安装配置、常用命令、commit 修复到高频报错排查，我会把真实项目里踩过的坑和验证过的写法一次性讲透，尽量不搞术语轰炸，用最直白的方式把每个动作背后的逻辑说清楚。
1. 先想明白：Git 到底解决的是哪一类麻烦
1.1 “文件夹版本管理”的死亡螺旋
我刚工作的前两年，项目组还没有引入版本控制。代码备份靠什么？靠压缩包。每个人的电脑上都会出现一串名字：project_v1.zip、project_v1.1_final.zip、project_final_new.zip、project_真的最终版.zip。到了第五版以后，没人说得清 final 和 真的最终版 之间到底差了什么。
这个状态的问题不只是命名混乱，而是“信息丢失”。你只知道当前这个文件能用，但不记得它从哪个版本改过来的，谁改的，为什么改。如果某天发现一个隐蔽 bug 是两周前引入的，你只能瞪着眼睛看代码，没有任何一条路径能帮你快速定位到那次变更。
Git 解决的第一个问题，就是给每一次修改留下结构化的痕迹。在你执行一次 commit 之后，仓库里的项目状态就形成了一个“快照”，快照之间按时间顺序串成一条链。任何一次提交，都可以被你随时调出来对比、回溯、甚至恢复。
1.2 三个小概念：工作区、暂存区、版本库
很多人刚学 Git 时，被 add、commit、push 这些动词搞晕，根本原因是没有建立“三个区域”的模型。
- 工作区：就是你电脑上看到的项目文件夹，你在这里改代码。
- 暂存区：一个临时存放区，你执行
git add之后，改动就从工作区进入暂存区，表示“我打算让这些改动进入下一次提交”。 - 版本库：本地仓库，里面保存着每一次 commit 的完整快照和全部历史记录。
这个“两步提交”设计，最初看起来有点多余，但实际用起来非常有用。你可以只把一批改动中的一部分加入暂存区，另一部分留在工作区继续实验，这样每次提交就是一个逻辑完整的单元。比如你同时改了登录接口和首页样式，完全可以把登录相关改动先提交，样式改动留着或者下一次再提交。
1.3 分支不是文件夹，是指向提交的指针
传统思维里，分支很容易被理解成“两份代码副本”。但实际上，Git 里的分支只是一个指向某个 commit 的指针，它本身不复制文件。创建一个新分支的成本几乎为零，因为你的代码文件已经在版本库里了，新分支只是多了个可以移动的标签。
这意味着你可以非常便宜地进行“实验性开发”。开个分支试一种实现，不行就删掉；行就合并回主分支。因为每个分支都指向一条独立的提交链，你在分支 A 上的提交不会影响主分支，反之亦然。这也是 Git 团队协作效率高的一个底层原因：并行开发不需要锁定文件，更不需要等别人改完。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 环境准备：Git 安装与初始化配置全流程
2.1 Windows 安装：三个容易踩坑的选项
Windows 上装 Git 很简单，去官网下载 .exe 安装包，一路下一步就行。但有几个选项，安装时一定要看清楚。
第一个是“默认编辑器”。默认值是 Vim，很多新手在 git commit 弹出来 Vim 界面之后直接原地发懵，不知道怎么保存退出。建议在安装第三步直接把编辑器改成 VSCode 或者 Notepad++，或者保持为 Nano 也可以。如果已经装完了也不用慌，后面可以用命令改。
第二个是 PATH 环境变量。安装向导默认选项是“Git from the command line and also from 3rd-party software”，这个建议保留。如果你选了“use Git from Bash only”，那在 CMD 或 PowerShell 里就敲不了 git 命令，会非常麻烦。
第三个是换行符转换。Windows 默认是 Checkout Windows-style, commit Unix-style line endings，也就是 core.autocrlf=true。如果你在 Windows 上组队开发，这个选项能避免大量“整文件都显示被修改”的问题。具体原理在第 6 节我会单独讲。
安装完成后，打开 CMD 或者 PowerShell，输入 git --version，能看到版本号就说明装好了。
2.2 macOS 与 Linux：命令能搞定的事就不折腾
macOS 用户如果装了 Xcode Command Line Tools，其实系统里已经自带 Git 了。在终端里执行：
bash复制xcode-select --install
git --version
如果没装，用 Homebrew：
bash复制brew install git
Debian/Ubuntu 系的 Linux：
bash复制sudo apt update
sudo apt install git -y
CentOS / RHEL / Fedora：
bash复制sudo yum install git -y
# 或者
sudo dnf install git -y
Linux 这边基本没有需要特殊注意的安装选项，装完就能用。
2.3 全局配置：身份、换行符、中文显示一次配齐
Git 提交时会记录作者信息，所以第一件必须做的事情是配置你的名字和邮箱。这一步不配置，之后 commit 十有八九会报错，或者留下一堆 user.name 缺失的垃圾提交。
bash复制git config --global user.name "你的名字"
git config --global user.email "you@example.com"
把 init.defaultBranch 设置成 main 也是我强烈建议的一条配置。Git 默认分支名是 master，但如今很多远程平台默认主分支都叫 main，提前统一能避免后期执行 push 时出现一堆 master 和 main 不匹配的困惑。
bash复制git config --global init.defaultBranch main
Windows 上强烈建议配置 core.autocrlf true，而 macOS/Linux 用户设置 input 即可：
bash复制git config --global core.autocrlf input
另外，很多人在命令行里看到的中文文件名显示成一堆转义编码 \346\265\213\350\257\225，这是因为 Git 默认对非 ASCII 字符做了转义。执行：
bash复制git config --global core.quotepath false
之后再查看 git status，就能正常显示中文文件名了。
做完全部配置后，用 git config --list 可以查看当前所有配置，确认没有遗漏。
3. 高频 Git 命令：按场景而不是按字母表拆解
3.1 看状态、看改动、看历史：status / diff / log
git status 是我使用频率最高的命令，没有之一。它告诉你当前处于哪个分支、工作区有哪些文件改动、暂存区里有哪些待提交内容。每次动手之前先跑一下，基本不会迷路。
想知道具体改了哪些内容，用 git diff。这个命令默认比较的是工作区和暂存区的差异，也就是“还没 add 的改动”。想看暂存区与上一次提交的差异，加参数 git diff --cached。
想翻历史，用 git log。默认输出会很长，我一般用这个组合：
bash复制git log --oneline --graph --all
--oneline 压缩成一行，--graph 用字符画出分支合并走势，--all 包含所有分支。一眼就能看出整个项目的历史主脉络。
3.2 提交三件套：add / commit / restore
日常开发最稳定的循环是：改代码 → git status 看变更 → git add 选文件 → git commit 写提交说明 → git log 确认提交成功。
关于 git add，我建议多用 git add <具体文件> 而不是无脑 git add .。无脑全部添加，很容易把调试日志、临时配置、本地方案之类的杂项混进同一个提交里，后面的历史会很难看。分组提交的经验，等真正翻阅历史排查问题时会感到非常值。
git restore 是我后来才习惯用的命令，它取代了老教程里的 git checkout -- <file>，作用是丢弃工作区的改动，把文件恢复到上一次提交的状态。操作之前确认一下，这个命令会直接覆盖你的修改，没有后悔药。
bash复制git restore 文件名
3.3 分支操作：branch / switch / merge
创建分支、切换分支、合并分支，这三件事构成了 Git 分支开发的主要节奏。
bash复制git branch feature-login # 创建分支
git switch feature-login # 切换分支
git switch -c feature-login # 创建并切换
老教程里会用 git checkout -b 实现创建并切换，Git 2.23 之后官方推荐的是 git switch，语义清晰很多，也更安全。
开发完成后，切回主分支，执行合并：
bash复制git switch main
git merge feature-login
如果当前主分支已经有别人提交过，而你的分支是从旧代码上拉出来的，合并时可能会发生冲突。处理方式在第 6 节详细讲。
3.4 远程同步：clone / fetch / pull / push
git clone 是从远程仓库拷贝完整项目到本地。git push 把本地提交推送到远程。git fetch 只是把远程的提交下载到本地“隐身区域”，不会动你的工作区。git pull 等于 git fetch + git merge，会直接把远程分支合并到当前分支。
这里最想提醒的是：git pull 之前，尽量先看一眼当前状态。如果本地有未提交的改动，pull 冲突时处理起来会比较痛苦。我自己的习惯是：git status 确认干净 → git pull → 继续干活。这个流程可以规避大部分拉取冲突。
日常代码提交流程可以浓缩成这张速查表：
| 命令 | 常用参数 | 一句话用途 |
|---|---|---|
git status |
-s |
查看工作区和暂存区状态 |
git diff |
--cached |
查看改动差异 |
git add |
<file> / . |
把文件加入暂存区 |
git commit |
-m "说明" |
创建提交快照 |
git restore |
<file> |
丢弃工作区改动 |
git branch |
-a |
查看/管理分支 |
git switch |
-c |
切换分支 |
git merge |
<branch> |
合并分支 |
git push |
origin main |
推送本地提交到远程 |
git pull |
--rebase |
拉取并合并远程提交 |
git clone |
<url> |
克隆远程仓库 |
4. 从零跑通一个完整项目：初始化到发布的实操流程
4.1 init 和第一个 commit
新建一个项目目录，进入后执行：
bash复制git init
这一步只是创建一个 .git 隐藏目录，并不会自动跟踪任何文件。然后编写代码，或者直接放一个 README.md，再执行：
bash复制git add README.md
git commit -m "初始化项目结构"
第一个 commit 就产生了。这里要提一件事：第一次 commit 的提交信息建议写得规整一点，后面很多操作（比如生成 changelog、触发 CI、定位回归）都依赖提交历史的清晰度。
4.2 提前写好 .gitignore 会省一万个麻烦
.gitignore 文件的作用是告诉 Git 哪些文件“永远不要纳入版本管理”。最常见的忽略内容：依赖目录 node_modules/、编译产物 dist/、build/、IDE 配置 .vscode/、.idea/、日志文件 *.log、环境变量 .env、以及操作系统的 .DS_Store 之类的杂项。
如果项目刚开始没有写 .gitignore，又已经误提交了一堆 node_modules，后面处理起来非常费劲。而且 node_modules 里文件数量巨大，每次改点东西 git status 都刷几百条记录，影响效率也容易掩盖真实变更。
我习惯在 git init 之后、写第一行业务代码之前，就先把 .gitignore 建好提交掉。这个动作成本极低，收益却覆盖整个项目生命周期。
4.3 分支开发再合并：一个完整的例子
假设项目要加一个“用户反馈”功能，我会这样操作：
bash复制git switch -c feature/feedback
在这个分支上开发，提交几次。开发完自测通过后，切回主分支：
bash复制git switch main
git pull origin main
git merge feature/feedback
先 pull 再 merge 的顺序很关键。如果本地主分支已经落后远程很多，直接 merge 功能分支可能会产生大量冲突；先把主分支更新到最新，冲突范围会小很多。
合并完成后，把合并结果推到远程：
bash复制git push origin main
4.4 推远程和发起合并请求的配合
在团队开发中，push 并不总是直接推到主分支。更常见的模式是：把自己开发的分支推送到远程，然后在平台上发起合并请求，由同事 review 之后合入主分支。
bash复制git push origin feature/feedback
这条命令会把本地 feature/feedback 分支推送到远程，并自动建立同名远程分支。之后在代码托管平台上发起 merge request（或者 pull request），确认没冲突、CI 通过，再由负责人合入。
这里有个实操经验：协作分支的命名越清晰越好。feature/用户反馈、fix/登录超时 这种名字，看到就懂；test123、branch111 这种名字，过两周再看根本不知道当时在干什么。
4.5 打 tag 做发布标记
每当项目完成一个可发布的版本，我都会打一个 tag。tag 就是给某个 commit 起一个固定的名字，方便以后准确回到这个版本。
bash复制git tag v1.0.0
git push origin v1.0.0
之后无论项目怎么迭代，只要 checkout 这个 tag 就能拿到当时完整的代码状态。线上出了问题，先用 tag 快速定位对应版本，再配合前面的历史记录查改动，效率会高很多。
5. git commit --amend 怎么用：修改最近一次提交的正确姿势
5.1 amend 到底做了什么
git commit --amend 直译过来是“修订上一次提交”。它不会真的“删除”那个旧提交，而是用一个新的提交把它替换掉。新提交的内容，是旧提交的内容，加上你在 amend 之前补充进去的改动，同时你可以顺手修改提交说明。
执行 git log 时，旧提交的哈希会消失，取而代之的是一个新的哈希。这个机制要记住，因为理解这一点，才能明白为什么 amend 已经推送的分支是有风险的。
5.2 两个最常见的 amend 场景
第一种场景，提交完之后发现信息写错了。比如刚才写的是 修复登录 bug，实际你还顺手修了个图标显示问题。可以执行：
bash复制git commit --amend -m "修复登录 bug 和图标显示异常"
第二种场景，提交完发现漏了一个文件。先补上，再合并到上一次提交：
bash复制git add 漏掉的配置文件
git commit --amend --no-edit
--no-edit 表示保留原有的提交说明，直接修订。这两个场景是我日常用得最多的。
需要注意的是，amend 会改变提交时间。如果团队有人在做基于提交时间的统计或检查，这个行为有时候会被注意到，但一般不算大问题。
5.3 进阶：配合 rebase 修改更早的提交
如果想改的不是最近一次，而是三次前的提交，单纯 amend 就不行了。这里用到 git rebase -i（交互式变基）。
bash复制git rebase -i HEAD~3
执行后会打开一个交互界面，列出最近三条提交。把想要修改的那一行，把 pick 改成 edit，保存退出。Git 会停在那个提交上，此时你可以补充文件或者修改信息，然后执行：
bash复制git commit --amend
git rebase --continue
这个过程中如果其他提交之间有依赖关系，可能会产生冲突，解决完冲突再 git rebase --continue 即可。这个操作威力很强，但只推荐在本地、没有推送到远程的分支上使用。
5.4 禁区：已经推送到公共分支的提交
这是整个 Git 协作里最容易被新手踩爆的雷之一。假设你已经 git push origin main，分支在远程和同事那边都存在。这时候你执行 amend 修改了提交，然后想推送，必须用：
bash复制git push --force
因为 amend 之后本地提交的哈希变了，远程的旧提交还在，两者历史链不一致，普通 push 会被拒绝。而强推之后，远程分支被本地覆盖，其他人的本地历史就会和远程“分叉”，下一次他们 pull 时会产生一堆莫名其妙的冲突，甚至丢提交。
所以我的铁律是：已经推送到公共分支、并且可能有别人拉取的提交，永远不要 amend，也永远不要 reset 之后再强推。如果已经做了，团队只能通过协调来解决，场面不会太愉快。
5.5 推错了、改不了，用 revert 来补救
如果一条错误的提交已经推送到远程，正确的修法不是 amend，而是 git revert。revert 的作用是生成一个“反向提交”，把之前某次提交的改动全部回退掉，同时保留完整的历史记录。
bash复制git revert <commit哈希>
执行后 Git 会自动创建一个新提交，内容是把那个 commit 的改动撤销掉。因为 revert 是在“后面”追加一个新的提交，历史链没有任何改动，所以可以正常 push，不影响其他同事。
这个方案虽然会让历史里同时存在“错误提交”和“撤销提交”两条记录，看起来不如 delete 干净，但它是公共分支上唯一安全的选择。
6. 高频报错与排查实录：这些坑我都替你踩过了
6.1 合并冲突：看到一堆 <<<<<<< 别慌
执行 git merge 时如果提示冲突，打开冲突文件，你会看到类似这样的标记：
code复制<<<<<<< HEAD
当前分支的代码
=======
被合并分支的代码
>>>>>>> feature-login
关键字就是两层尖括号和中间的 ======= 分隔线。你需要做的事很简单：保留正确的代码，删掉这些标记行，然后保存文件，执行：
bash复制git add 冲突文件
git commit -m "解决合并冲突"
人在冲突现场，最重要的是分清楚哪部分是谁的。因为网上很多教程会直接告诉你“保留你要的那份”，但你得先结合上下文判断，不能盲目删。稳妥的做法是先看两种写法各自的完整上下文，再决定怎么合并，必要时和相关同事确认。
6.2 detached HEAD：你不在任何分支上
如果执行 git switch 切到了某个 commit 的哈希，而不是分支名，Git 会提示你进入了 detached HEAD 状态。意思是当前指针没有挂在任何分支上，如果你在这个状态下提交，之后切走分支，这些提交会变成“孤儿提交”，常规操作根本找不到。
我的处理方式：如果是临时过来看电影一样查看代码，看完直接 git switch main 走人。如果是误入，自己心里清楚就行。如果不小心在这个状态下做了提交又没法找回，可以记住那次提交的哈希，用 git branch tmp <哈希> 把它挂到一个新分支上保住。
6.3 refusing to merge unrelated histories：强行合并不是好主意
这个报错新手遇到特别多。常见场景是：本地已经存在一个仓库，远程也建了一个空仓库，然后执行 git pull origin main，Git 因为两边没有公共历史而拒绝合并。
解决方式有两种。第一种是逻辑上最合理的：如果远程仓库本来就应该包含本地历史，先把本地先 push 上去，或者用 --allow-unrelated-histories 参数允许合并不同根的历史。但要注意，如果两边其实都有大段互不相同的代码，强行合并会产生严重冲突。
我的建议是：遇到这个报错先别急着加上 --allow-unrelated-histories 冲过去，认真思考一下两个仓库的关系。最省事的方式通常是把远程仓库内容清空，让本地直接推上去。
6.4 push 被拒绝：非快进更新
报错一般长这样：! [rejected] main -> main (fetch first) 或者 non-fast-forward。原因是远程 main 分支已经有了你本地没有的提交，你试图覆盖它。
正确做法是先把远程内容拉下来合并：
bash复制git pull origin main
# 或者用 rebase 方式
git pull --rebase origin main
然后重新运行 push。pull --rebase 会比默认的 merge 方式让提交历史更线性，主观上更干净，但遇到复杂冲突时，merge 方式反而更容易解决。看具体情况选。
6.5 CRLF 警告刷屏，怎么根治
Windows 开发者在 clone 项目时，经常看到 warning: LF will be replaced by CRLF 之类的提示。问题根源在于不同系统的换行符：Windows 用 CRLF，Linux/macOS 用 LF。如果没做统一，git diff 可能把没改过的文件也标记为有变更。
根治方案有两步。个人层面，Windows 全局配置 core.autocrlf true，提交到远程时统一转成 LF。团队层面，在仓库根目录放一个 .gitattributes 文件，显式指定关键文件的换行规则：
bash复制* text=auto
*.sh text eol=lf
*.bat text eol=crlf
这样所有成员都遵守同一套规则，不依赖本地个人配置。
6.6 提交了不该提交的东西：大文件、依赖包、敏感信息
如果只是提交了不该进版本库的文件，但还没推到远程，可以直接用 git rm --cached 把它从版本控制中移除，同时保留本地文件：
bash复制git rm --cached node_modules -r
然后把这个路径加入 .gitignore，再提交一次。历史里的记录还在，但对后续开发已经没有影响了。
如果已经推到了远程，就比较麻烦。大文件还能通过底层的 git filter-repo 或 BFG 工具重写历史，但涉及团队协调，代价高。敏感信息（密码、密钥、token）一旦推上去，第一反应应该是立刻去平台侧轮换密钥，不要天真地以为删掉提交就万事大吉，因为历史是可以被别人翻到的。
我的底线是：commit 之前多看一眼 staged 文件列表，该忽略的一开始就忽略，比自己后面擦屁股省一万倍功夫。
最后再分享一个我个人一直保持的习惯：提交代码之前，一定要看 git status 和 git diff 确认无误，提交信息写清楚“做了什么”和“为什么”。这套动作看起来基础，但坚持下来，你的 Git 使用体验会远超身边大多数人。工具说到底只是习惯的外壳，真正有价值的是每一次操作背后清醒的判断。