说起来有点不好意思，我第一次真正需要Git不是在公司项目里，而是有一次自己在家写个小工具，连着一个星期改了五六版，到第三天发现代码被自己改得乱七八糟，想找回前一天还能稳定运行的那一版，翻遍文件夹也找不到旧版本，只能靠回忆一点点重写。我到现在还记得那天晚上的心情。也就是从那时候开始，我意识到版本控制不是大厂流程的专利，而是任何一个对自己代码负责的人都该掌握的基本功。这篇我就把Git及其基本操作整理成一份“个人用”的版本，不讲企业级评审、合并策略那些复杂套路，只讲一个独立开发者在日常写代码、传代码、改代码时最常用的命令和思路。刚装好Git不知道从哪下手的，或者已经用了一阵子但老遇到奇怪报错的，这篇都能帮你把基础补扎实。
1. 为什么每个开发者都要过Git这一关
1.1 直观理解Git：一个能回到任何过去的存档系统
如果你是第一次接触Git，我建议先丢掉那些关于“分布式版本控制系统”“DAG图”“指针树”之类的术语，用打游戏的心态来理解它。打单机游戏的时候，我们会存进度，打boss之前存一档，过了某个剧情节点再存一档，翻车了就读旧档重来。Git做的事情就是给代码文件夹做这种“存档”，而且做得比游戏存档还强：它可以记录每一次你主动保存的快照，可以随时查看任意一次保存版本里的文件内容，可以把当前代码恢复到任意历史节点，甚至可以把保存过的历史“改写成另一个版本”。
但Git和普通存档最大的不同在于：游戏的存档往往只有一条主线，而Git的历史天然是分叉的。你今天上午在实验一个新方案，下午又想修一个不影响主流程的小bug，两条改动线完全可以同时存在、互不干扰，最后再决定哪条合并进正式版本。这个“分叉”能力是Git协作模型的核心，也是个人开发者也必须掌握它的理由——你不需要等团队需求，一个人的小项目同样能从分支结构里获得巨大的安全感。
还有一点值得提前说：Git的所有操作几乎都在本地完成，记录历史、创建分支、查看差异都不需要联网。只有当你准备把代码分享给别人的时候，才需要和“远程仓库”打交道。这意味着哪怕你的网络状况再差，你也一样能享受版本控制带来的全部便利。
1.2 掌握三个区域：工作区、暂存区、版本库的关系
Git的操作之所以让新手困惑，很大程度是因为同一个文件在不同阶段有“好几份状态”。理解这三块区域的关系，比背命令重要得多。
- 工作区（Working Directory）：就是你日常写代码的文件夹，你在这里新建、编辑、删除文件，改动直接发生在磁盘上。
- 暂存区（Staging Area / Index）：可以理解成一个“候车室”。你改动了一堆文件后，可以先挑选其中一部分文件放进暂存区，告诉Git“下一班车我只想带上这些”。
- 版本库（Repository）：也就是Git真正保存历史快照的地方。一旦执行commit，暂存区里的内容就被打包成一个不可变的快照，永久记录在历史中。
这三块区域对应着三条最基础的状态迁移路径：工作区文件用git add进入暂存区，暂存区内容用git commit进入版本库，版本库里的历史又可以用git reset或者git checkout拉回到暂存区或者工作区。生活在Git里的文件始终在这三者之间流动，搞清楚当前文件在哪、要去哪，大多数报错你都能自己猜出解决方向。
我见过不少朋友刚开始用Git时，觉得add和commit是“多余的仪式”，索性每次都git add .然后顺手commit。这在小项目里当然能用，但我还是建议从第一天起就养成“按逻辑单元提交”的习惯。逼自己在提交前想一想“这次改动到底完成了什么”，会让你的历史记录变成一本清晰的工程日志，而不是一个流水账收纳箱。这对后续排查问题、回退版本、写周报，都是实实在在的帮助。
2. 装好Git并配到顺手：安装、全局配置与免密登录
2.1 Windows / macOS / Linux 的安装方式与验证
装Git本身没什么技术含量，但不同平台的安装细节还是有点差别的。
- Windows：建议直接从官网下载官方安装包，安装时一路用默认选项即可，唯一值得留意的是“调整PATH环境变量”那一屏，一定要选“Git from the command line and also from 3rd-party software”，这样你在cmd、PowerShell里也能直接敲
git命令。装完之后打开Git Bash，输入git --version，能输出版本号就说明装好了。 - macOS：如果你装过Homebrew，一条
brew install git就搞定，更新也方便很多。你也可以用Xcode自带的git，但那版本通常比较老，还是建议自己装一份干净的。 - Linux / Debian系：
sudo apt install git，完成之后同样验证一下版本号和官方新版本差距大不大。多数发行版仓库里的Git版本不会特别新，但不影响日常使用。
装完之后有一个细节容易被忽略：Git默认的文本编辑器可能是vim。在Linux和macOS上这倒无所谓，但在Windows的Git Bash里，如果不会用vim，commit时万一弹出了vim界面，你会陷入“怎么都退不出去”的窘境。我个人的做法是提前配置成Notepad或VS Code，命令是：
git config --global core.editor "code --wait"用VS Code当编辑器还有个额外好处：commit信息可以写多行，适合写详细的变更说明，养成好习惯会非常省事。
2.2 第一件事：设置用户名、邮箱，顺便解决CRLF
安装好Git之后，你做的第一个全局配置一定是在终端里设置你的身份信息：
git config --global user.name "your-name" git config --global user.email "your-email@example.com"这两条信息会被写入每一次commit里，相当于你在Git历史上的签名。需要注意：邮箱并不一定要用真实邮箱，GitHub、Gitee这类平台会用它关联你的账号，但如果你只是想在本地管理代码，随便填一个能区分出“这是你提交的”的邮箱就足够了。想确认当前配置，执行git config --list即可。
另一个值得一提的配置是换行符。Windows里文本文件的换行是CRLF，Linux和macOS里是LF。如果团队成员用的系统不一致，每次提交都会出现“整个文件都被标记为已修改”的错觉。个人开发也会遇到：你在Windows上写完代码推到远程，又在macOS上拉下来改两笔，再推上去，Git会认为所有行的换行符都变了，diff极其难看。通用的配置策略是：
- Windows上执行：
git config --global core.autocrlf true - macOS / Linux 上执行：
git config --global core.autocrlf input
这样Git在提交时会自动把CRLF转换成LF存进版本库，在Windows工作区需要的时候再换回CRLF。关于换行符的更多坑，我在后面第6章继续展开。
2.3 配置SSH密钥：完成一次就再也不用输密码
使用GitHub、Gitee或者自建的代码托管平台时，最常见的连接方式有两种：HTTPS和SSH。HTTPS很直观，第一次clone或push会让你输账号密码或访问令牌，但日子一长你就会觉得烦，尤其每次push都要输，非常打断思路。我个人强烈建议配置SSH密钥，一劳永逸。
第一步，生成密钥。在Git Bash（Linux和macOS直接终端）里执行：
ssh-keygen -t ed25519 -C "your-email@example.com"一路回车，默认存放路径~/.ssh/id_ed25519就好，如果没特别需求，不设置密钥口令也行。然后需要把公钥内容复制到托管平台的密钥设置里：
cat ~/.ssh/id_ed25519.pub在Gitee或GitHub的个人设置里找到“SSH Keys”，粘贴保存。之后你仓库的远程地址使用git@开头的SSH格式，push、pull就不再需要输入任何密码了。测试连接可以执行ssh -T git@gitee.com，看到欢迎语就说明密钥配对成功。
这里提醒一句：私钥文件id_ed25519千万不要泄露，也不要贴到聊天窗口或者上传到别人给的服务器上，它是你代码仓库的第一道锁。
3. 本地提交、撤销与改历史：个人使用最频繁的高频命令
3.1 从 init 到 commit：提交代码的基本流程与提交信息规范
在一个已经存在的项目文件夹里初始化Git，只需要：
git init这个命令会在文件夹里生成一个.git目录，它就是整个版本库的核心所在。从这一刻起，这个文件夹里的所有文件变更，Git都开始“盯着”了。然后正常写代码，写完一批想要存一个档，按三步走：
git add . git commit -m "完成用户登录模块的接口开发"git add .是把当前目录下所有改动加入暂存区，如果你想只提交几个文件，就把.换成具体的文件名或目录名，比如git add src/auth/login.js src/auth/verify.js。
在提交信息这件事上，我见过太多次fix、update、aaa这样的 commit message，每次看到都头大。个人项目没有人要求你写规范，但既然是给自己看的，更应该写出能一眼看懂的内容。我自己的习惯是“动词+对象+做了什么”，比如：
feat: 新增用户注册接口fix: 修复注册接口密码为空时报错的问题refactor: 抽取通用日期格式化方法
这种习惯养成之后，过三个月再翻历史，你还能快速定位某个功能是哪个提交引入的。除了commit信息，还有一个命令值得记：git status。它是你随时可以照的镜子，会清晰地告诉你当前哪些文件被修改了、哪些已经被加入暂存区、哪些还没被Git追踪。
3.2 查看状态与差异：status / log / diff 的实用姿势
日常开发里最常用的查看命令有三个：git status看工作区整体状态，git log看提交历史，git diff看具体改了什么。
先说说git log。默认输出会把每个commit的哈希值、作者、时间、提交信息都列出来，历史一多就刷屏。我个人更喜欢用带参数的简版：
git log --oneline --graph --decorate -10--oneline让每条commit只显示一行简写哈希和提交信息，--graph用简单的字符图形画出分支走向，-10只显示最近10条。这个组合是我日常最常用的历史查看姿势，分支结构一目了然。
再看git diff。不带任何参数时，它显示的是工作区和暂存区之间的差异，也就是你“还没add的改动”。当你执行了git add之后，想看看暂存区和上一个commit之间有什么差别，用：
git diff --cached这三个命令配合起来，你可以随时回答“我改了什么”“我上一次提交了什么”“当前分支长什么样”这三个问题。它们是Git世界里最朴素的导航工具。
3.3 三种后悔药：restore、reset、amend 的适用场景
写代码不可避免地会后悔，Git提供了好几种“撤销”的姿势，但它们的侧重点完全不同，选错了甚至会加重后悔。
第一种后悔：文件改乱了，想恢复到最近一次提交的状态。
git restore file.txt这条命令只影响工作区，把你对某个文件的未提交改动全部丢弃，恢复到最近一次commit的状态。如果你已经git add了，想从暂存区退回工作区（但保留改动内容），则用：
git restore --staged file.txt第二种后悔：想彻底抛弃最近N笔提交，让分支整体回退。
git reset --hard HEAD~1HEAD~1表示前一个版本，HEAD~3表示前三个版本。这个命令会在瞬间把当前分支指针移回指定位置，并同步重置工作区和暂存区。它非常危险，因为被丢弃的提交在普通操作里很难找回，我只建议在你确信“这些改动都不要了”的时候使用。
第三种后悔：最近一次commit写错了信息，或者忘记包含某个文件。
git commit --amend执行之后会打开编辑器让你修改上一条commit的信息；如果你只是想把某个遗漏的文件补进上一条提交，可以这样：
git add forgotten-file.txt git commit --amend --no-edit--no-edit的意思是保留原有提交信息，只是把新文件并进去。amend会在原地生成一个新提交，历史里看不出曾经补过文件，很适合个人开发时的小补救。不过要记住：如果这条commit已经被推到远程，而且别人可能基于它做了工作，就不要随意amend，否则历史会对不上。个人项目单分支环境里，这个问题不大。
4. 分支与合并：个人开发也能用上的工程化操作
4.1 分支是什么：一个快速移动的指针
你每执行一次commit，Git就会生成一个新的提交对象，同时让当前分支指针自动指向它。分支不是“复制一份代码”，它只是一个“指向某次提交的指针”。你可以把每个分支理解为一条独立的思路线：master或者main是稳稳当当的主线，你在上面开一个叫feature/login的分支，就是为了在一段时间里专心做登录功能而不用打扰主线。
创建并切换分支的最快写法是一个组合命令：
git switch -c feature/login老版本Git里人们更习惯git checkout -b feature/login，两者作用相同，只是switch语义更清晰。我在个人项目里的典型流程是：主线保持稳定，需要尝试新功能时从主线开一个功能分支，做完、测好、合并回主线，然后删掉功能分支。整个过程代码干净，主线历史非常规整。
平时想看一眼当前在哪个分支、有哪些分支，用：
git branch -v带-v参数会同时显示每个分支最近一次提交的信息，很方便。
4.2 合并与冲突处理：merge 的实操细节
分支之间的合并命令是：
git switch main git merge feature/login这条命令会把feature/login分支上的改动合并到当前所在的main分支上。如果两条分支改动的是不同文件，Git会非常聪明地自动合并，甚至不用你操心。但如果你在main里改了一行代码，而那个文件在feature分支里也被改了，Git就不知道该听谁的，这时它会停下来说“有冲突了”，并在冲突文件里插入类似下面这样的标记：
<<<<<<< HEAD 这里是当前分支的代码 ======= 这里是合并进来的分支的代码 >>>>>>> feature/login处理冲突是个人开发者必须亲自动手练一遍的环节。你自己的项目里冲突概率比大团队小，但要真出现了，记住三个步骤：第一，打开冲突文件，把<<<<<<<、=======、>>>>>>>这几行标记连同不需要的内容一起删掉，只留下你真正想要的内容；第二，执行git add告诉Git这个冲突已处理完；第三，继续执行git merge --continue完成这次合并。全程不要慌，冲突只是Git在提醒你“这里有歧义，需要人做决定”，它不是错误。
合并到一半如果忽然觉得不应该合并，可以用git merge --abort原样退回到合并前的状态，这一点很实用，新手通常不知道还有后悔药可吃。
4.3 个人场景的分支玩法：临时功能分支与版本标签
别看单人项目没有团队协作，分支操作同样能给工作流带来巨大好处。比如你平时在main分支上写项目，突然来了个优先级更高的临时需求，你不需要把当前写到一半的代码“硬塞”回主线，只需要：
git switch -c wip/temp-fix然后在这条临时分支上完成应急修复，提交，切回主线合并，再删掉临时分支。原先写到一半的功能稳稳地留在它自己的分支里，完整保留，继续切回去接着写就行。这种“手头活儿不丢，临时插队也能不乱”的体验，是用文件夹复制粘贴无法替代的。
另一个值得养成习惯的操作是打标签。在项目做到某个重要节点，比如发布一个可用版本，执行：
git tag v1.0.0标签会像书签一样永久记住这个提交。以后想复盘当时版本或快速切换，直接git checkout v1.0.0就能跳过去。发布新版本后打上标签，配合远程push标签，你就拥有了一条完整可回溯的项目版本线。
5. 远程仓库协作：clone、fetch、pull、push 全流程
5.1 关联远程仓库：从已有项目到Gitee/GitHub
“远程仓库”听起来很玄，其实就是一个放在服务器上的Git仓库，充当你的代码托管中心。本地仓库和远程仓库之间的同步用四个命令就能概括：clone、fetch、pull、push。
如果是在Gitee或GitHub上新建一个空仓库之后，想把自己本地的已有项目推上去，过程是这样的：
git remote add origin git@gitee.com:yourname/yourproject.git git branch -M main git push -u origin mainremote add是在本地仓库注册远程地址的别名，origin只是约定俗成的名字，纯属惯例。-u参数表示把本地main分支和远程main分支建立“默认关联关系”，做到一次配置、从此以后push或pull都不必再写远程名称和分支名。第一次推送之后，远程仓库就有了你本地全部的历史提交。
反过来，如果你想从别人或者自己的远程仓库开始工作，一条git clone就能把远程仓库完整复制到本地：
git clone git@gitee.com:yourname/yourproject.git5.2 常规同步流程：clone、fetch、pull、push的日常节奏
使用一个已经克隆到本地的仓库时，我的日常节奏是：先pull，再写代码，最后push。这“三步曲”看起来很简单，但里面有一个值得说的细节。
git pull其实等于做了两件事：先git fetch从远程下载最新的提交记录，再自动执行一次git merge把它们合并到当前分支。在个人项目里，因为我们自己基本只在一台电脑上操作，pull通常分分钟就完成。如果哪天你用了两台电脑或者改了网页端，远程有变化而本地也有未提交的改动，pull时会提示冲突或要求你先stash，这时你再执行：
git stash git pull git stash popgit stash会把当前未提交的改动临时收进一个“小仓库”，等pull完成之后再stash pop恢复现场，这是最稳的“同时应对本地改动和远端更新”的操作。
push就更简单了：
git push只要本地和远程的历史线没有分歧，这条命令三秒钟完成。如果push被拒绝，说明远程存在本地没有的提交，解决方案就是先pull一次完成合并，再重新push。
5.3 远程分支、标签与release：让协作有迹可循
本地分支和远程分支是两套体系，但通过关联可以互相追踪。执行git push时如果希望远程创建同名分支，写法是：
git push -u origin feature/login把本地功能分支推到远程，可以让另一台电脑也能看到、拉取这条分支。在个人多设备场景下，这个操作非常实用：你在台式机上开了一条分支，笔记本上git fetch之后执行git switch feature/login，Git会自动基于远程分支创建对应的本地分支。
远程标签的推送和本地稍微不同，普通push不会自动带上标签，需要单独执行：
git push origin v1.0.0或者一次推送所有本地尚未推送的标签：
git push --tags把这些操作配合起来，你就能在一个远程仓库里同时管理代码、版本标签和功能分支，整个过程没有一条命令是多余的。
6. 个人使用高频踩坑与排查实录
6.1 clone报错“connection refused”：端口冲突的真凶
最近和朋友交流时，好几个人都遇到过同一个报错：
git clone failed to connect to 127.0.0.1 port 7890: connection refused看到127.0.0.1这个地址就该明白，问题根本不在远程服务器，而在你的本机。这个报错的意思是Git在连接本机某个监听在7890端口的服务，但那个服务没有正常响应。换句话说，Git配置里残留着“本机端口转发”的设置，而你机器上对应的监听程序偏偏没在运行，于是连接直接失败。
如果你不在自己的电脑上开任何端口监听，但Git还是往本机地址去连，这几乎可以肯定是Git配置项里写了本地端口地址。解决办法是把这两个配置直接移除：
git config --global --unset http.proxy git config --global --unset https.proxy如果你用的是系统级或仓库级的配置文件，也可以带上--system或--local再unset一次。做完再试git clone，恢复正常。这个案例给我们的教训是：clone连不上时，第一反应应该看报错里的IP，如果是局域网或本机IP，先从自己机器上找原因，而不是怀疑托管平台出了问题。
6.2 .gitignore不生效：缓存才是罪魁祸首
很多人在项目里新建了.gitignore文件，写入了node_modules/或.env，但执行git status时发现这些文件依然显示为已修改或待添加。原因很简单：.gitignore只对“尚未被Git追踪过的文件”生效，如果某个文件之前已经被git add或git commit进来了，它就进入了Git的追踪名单，此后无论你如何更新.gitignore都没法让它自动消失。
解决方法是把那些已经在仓库里却不该被追踪的文件从版本库中移除，但保留工作区文件：
git rm -r --cached node_modules执行完后把这些变更提交，之后再修改.gitignore才会真正生效。每次新增忽略规则之后，想检查效果是否准确，最直观的方法就是执行git status确认相关目录是否消失。记住这句话：先把生米煮成熟饭的文件移除追踪，再谈忽略规则。
6.3 CRLF换行符问题：同一份代码在不同系统上的格式战争
前面第2章提过换行符配置，这里展开讲一次我真实踩过的坑。有一段时间我在Windows和macOS上交替写同一个项目，每次从macOS提交后再回到Windows，git status都会把大量文件标记为“modified”，但打开文件看不出任何肉眼可见的变化。原因就是Windows和macOS的换行符不同，Git在对比内容时把整行都当成改过了。
解决思路分两层。第一层，前文配置过的core.autocrlf能解决“进入版本库统一存LF、Windows工作区自动转CRLF”的问题；第二层，如果历史已经被大量换行符混入了，最省事的办法是让每个系统都按统一的换行符重新提交一遍。不要像我当初那样试图手工整理文件，那是自己给自己制造无穷的diff。原则就是：提交进Git仓库的文本统一用LF，Windows本地需要CRLF时让Git自动转换，而不要两边都用自己的原始格式硬灌进仓库。
6.4 SSH认证失败排查：从密钥权限到端口逐一过
SSH认证失败是个大类，报错五花八门。我遇到过的情况主要有三种。
第一种是权限问题。私钥文件权限过宽，SSH会拒绝使用。Linux和macOS下执行：
chmod 600 ~/.ssh/id_ed25519这个命令把私钥设为仅当前用户可读写，是SSH喜欢的安全状态。Windows上用Git Bash也一样可以执行。
第二种是双方密钥不匹配。把公钥贴到了托管平台，但本地用的私钥不是和它配对的那一把。排查方式很简单，重新生成密钥并重新配置公钥，或者检查~/.ssh目录下有没有多个密钥文件，确认是否用了非默认文件名的密钥并需要在~/.ssh/config里指定。
第三种是端口或防火墙问题。GitHub的SSH默认走22端口，有些网络环境对22端口有限制。遇到这类情况可以试试SSH连接用443端口，替换远程地址前缀：ssh://git@ssh.github.com:443/...。报错信息里如果出现“Connection timed out”或“Operation timed out”，多半就是网络访问层面的问题，而不是Git本身的问题。
6.5 提交大文件的正确姿势：为什么Git会拒绝超限文件
有时候你项目里放进了一个几百MB的数据库文件或者一个压缩包，push时会看到类似这样的拒绝：
remote: error: File xxx.pak is 150.00 MB; this exceeds GitHub's file size limit of 100.00 MB托管平台对单个文件大小有硬性限制，因为Git本身就不是为超大文件设计的。它的每次提交都包含文件快照，大文件会让仓库急剧膨胀，clone一次慢到怀疑人生。
解决思路有两个。其一，如果文件需要进入版本控制但确实很大，可以考虑使用像Git LFS这类扩展工具，它会把大文件内容放到独立存储里，仓库里只保存轻量引用。其二，如果大文件只是构建产物或本地缓存，根本不该进版本库，那就把它列入.gitignore，并按照前面6.2节的方法清理已追踪的历史引用。我在个人项目里的优先选择永远是第二种，尽量从源头上不让大文件污染仓库。
6.6 目录权限泄露提醒：一条关于“个人用”的安全底线
最后说一个很多个人开发者都没注意过的安全常识：.git目录是整个仓库的大脑，里面存着所有历史、远程地址、用户信息。如果你把一个项目直接部署到公网服务器上，而服务器的Web服务把.git目录也当普通静态文件暴露了，别人就可以通过特定请求把你的源代码历史下载下来，后果比只泄露当前代码严重得多。
所以我的红线建议是：部署时确保Web服务器禁止访问任何.git开头的路径；如果实在对自己的部署配置没把握，就直接把一个不含.git目录的干净副本放到线上环境。Git本身是让你安心的工具，可别让它的元数据成为反向伤害你的窗口。
把这些内容串起来看，Git的基本操作其实就三件事：在本地把代码安稳地存成一段段历史，用分支把不同思路和工作流隔离开，再用远程仓库让代码能在不同设备之间平稳流转。大家在网上总能看到各种压缩成一张图的命令速查表，但真正遇到问题的时候，速查表帮不了你，能帮你的只有你对“文件在三个区域之间如何流动”的理解，以及多踩几次坑后积攒下来的手感。我现在每天用到的Git命令，翻来覆去也不超过十五个，但就是这十五个，让我再也没体验过“代码丢得莫名其妙”的绝望。如果你也是一个人写项目，真心建议从今天起就建立起自己的Git使用习惯，它回报你的不是某一次华丽的合并，而是每一天写代码时那种踏踏实实“坏不了”的底气。
