1. 环境准备装好Git配好第一行全局设置1.1 Windows、macOS、Linux三种安装方式速览做开发这几年我几乎每天都要跟Git打交道。很多刚入门的同学第一步就卡在安装上其实Git的安装并不复杂只是不同系统有不同的路子我先把最常见的三种方式捋一遍。Windows用户直接去Git官网下载安装包目前官方推荐的Windows版本是自带Git Bash的安装的时候一路Next就行但有几个选项值得注意安装路径建议保持默认不要放在带中文的目录组件选择页面勾选“Git Bash Here”和“Git GUI Here”这样右键菜单会多出两个入口后续操作会非常方便。装完之后打开命令行输入git --version能输出版本号就说明核心程序已经就绪。macOS用户我优先推荐用Homebrew安装一条brew install git搞定版本通常比系统自带的要新。如果你不想装Homebrew也可以直接下载官方dmg安装包但后续升级会麻烦一点。Linux用户则简单得多Debian/Ubuntu系用sudo apt install gitCentOS/RHEL系用sudo yum install git发行版仓库里的版本一般够用。安装完成之后不要急着走先做两件事第一确认终端能识别git命令第二确认git bash能正常打开。如果Windows下出现“无法将‘git’项识别为cmdlet、函数、脚本文件或可运行程序的名称”这个报错大概率是环境变量没配好这个坑我在后面的问题排查章节专门讲。1.2 为什么推荐用Git Bash而不是系统自带的cmd终端很多Windows新手会疑惑既然装好了Git为什么命令还老是报错一个重要的原因是cmd终端对Linux风格命令支持很差而Git相关的很多操作习惯都是围绕Unix风格命令展开的。Git Bash是Git for Windows自带的一个模拟终端它能让你在Windows环境里直接使用ls、cat、grep、find这些常用Linux指令配合git命令组合起来操作体验和macOS/Linux终端非常接近。我用Git Bash最直观的感受是路径处理省心很多。在cmd里输入Git命令涉及到带空格的目录常常要加引号或者处理反斜杠在Git Bash里正斜杠路径天然兼容复制粘贴路径也不用改来改去。而且Git Bash自带了一套完整的Unix工具链比如你想看看当前目录下有哪些文件被Git忽略了可以直接用cat .gitignore想查找某个历史提交里包含特定关键字的文件用git log --name-only | grep 关键字也很顺手。有一点需要提醒Git Bash虽然好用但它只是一个“模拟层”并不是真正的Linux系统。你在Git Bash里安装的Python、Node等工具和Windows系统级的环境变量是互通的但某些依赖系统动态库的操作可能会有细微差异。日常使用完全够别纠结。1.3 全局配置user.name、user.email、换行符与默认分支名装好Git之后的第一件事不是急着去clone仓库而是先配置全局身份。这一步很多人会跳过结果第一次提交的时候Git弹出一串提示告诉你“please tell me who you are”因为每一次提交都需要关联一个作者信息没有这个历史记录根本没法看。git config --global user.name 你的名字 git config --global user.email 你的邮箱为什么必须配想象一下团队合作时你看到一段代码是新写的想找人问一下上下文如果提交记录里只有一串hash和“update”这种信息根本不知道是谁写的、怎么联系。配置完身份之后每次commit就会带上你的名字和邮箱这才是Git协作的基本前提。除了身份信息还有两个全局配置我建议顺手做掉。第一个是换行符处理Windows和Linux/macOS的换行符不一样如果团队混合开发很容易出现整个文件被判定为“全部修改”的假象。在Windows上可以执行git config --global core.autocrlf true这个配置的意思是提交时自动把CRLF转成LF检出时再转回CRLF能在绝大多数场景下避免换行符引起的diff灾难。第二个是默认分支名现在GitHub、Gitee这些平台默认分支已经从master改成了main为了跟远端保持一致建议设置git config --global init.defaultBranch main这样你在本地git init出来仓库默认分支就是main不会出现本地master、远端main这种各叫各的混乱局面。配置完可以用git config --list检查一遍也可以单独查看某项比如git config user.name确认确实生效了。2. 本地仓库高频指令从初始化到提交、回退与diff比较2.1 初始化仓库与文件状态的完整流转环境配置好之后就可以开始真正用Git管理项目了。在项目根目录执行git init这个目录就会变成一个Git仓库。注意一个细节git init之后会生成一个隐藏的.git目录所有历史记录、分支引用、配置信息都存在这里。如果你哪天想把项目恢复成普通文件夹删掉这个.git目录即可但千万想清楚再删那意味着整个版本历史都没了。Git管理文件的核心逻辑是“三层结构”工作区你正在编辑的目录、暂存区通过git add放入的待提交区域、历史区通过git commit形成的提交记录。我从第一次用Git到彻底理解这套设计大概花了两个星期期间经常分不清add和commit的区别。后来用了一个生活化的类比才彻底想通工作区是你的办公桌暂存区是待寄出的信封历史区是已归档的档案柜。你写完一段代码办公桌上完成工作→git add相当于把文件装进信封 →git commit相当于贴好邮票投进邮局形成档案记录。在实际操作中最常用的状态查看命令是git status。它会把当前仓库的状态完整列出来哪些文件被修改了、哪些文件已经暂存、哪些文件还没被跟踪。新手最能获得安全感的习惯就是随时敲一下git status它永远会告诉你下一步可以做什么相当于一个贴身向导。2.2 提交与历史查看commit规范和log实用技巧git add之后就要git commit这是形成版本历史的关键一步。提交信息讲究简明扼要我见过太多“update”“修改”“111”这种完全无法追溯的提交信息半年之后回看完全不知道当时为什么改。一个比较通用的提交信息规范是第一行用一句话概括改动不超过50个字符如果需要补充背景空一行再写详细说明。git commit -m feat: 增加用户登录接口 git commit -m fix: 修复订单金额精度丢失问题 -m 原因是浮点数计算改用整数存储分想查看历史记录最基础的是git log但我几乎不裸用实际经验里最顺手的是这套组合git log --oneline --graph --decorate --all--oneline把每次提交压缩成一行显示hash和提交信息--graph用字符画出分叉合并的图形--decorate显示分支和标签指向--all把本地所有分支的历史都显示出来非常适合快速纵览整个项目的演进脉络。如果只想看某个人最近几次提交可以加--author用户名想按时间过滤就加--since和--until这些参数组合起来比任何GUI工具都灵活。查看某次提交具体改了什么用git show commit-hash。如果只要看某个文件在历史里的变化git log -p 文件路径直接列出这个文件每一次改动的diff。定位bug的时候这个命令比什么都好使。2.3 撤销与回退工作区、暂存区、历史区三层回退方法Git最劝退新手的操作就是回退因为“撤销”这件事分不同场景用错命令很可能把代码搞丢。我按三个层来拆解大家对照自己的场景选命令就好。第一层只想撤销工作区的修改把文件还原成暂存区里的状态。这个操作不影响暂存区也不产生历史记录适合改到一半发现改崩了想恢复原样。git checkout -- 文件名 # 或者新版Git推荐的写法 git restore 文件名第二层已经git add放进暂存区想取消暂存但保留工作区修改。最典型的场景是你同时改了三个文件结果手滑全add了现在只想提交其中一个。git reset HEAD 文件名 # 或者 git restore --staged 文件名第三层已经git commit提交了发现提交错了。这里还要再分情况如果是刚提交完还没有推送到远端且你想彻底丢到这个提交用git reset --soft HEAD~1可以撤销提交但保留所有改动在暂存区或者git reset --mixed HEAD~1保留改动但不暂存更猛的是git reset --hard HEAD~1连改动一起丢掉。很多人听到--hard就害怕确实要小心这条命令会直接丢弃工作区修改执行之前务必确认。如果提交已经推送到远端就不要用reset了因为reset本质上是“改写历史”一旦推上去再reset你本地和远端的历史就对不上了别人pull的时候会非常崩溃。这种场景应该用git revert commit-hash它的做法不是删掉那个提交而是新生成一个反向提交来抵消之前的改动旧提交完整保留在历史里远端也能正常合并。2.4 diff比较与文件删除、移动做代码评审或者自查改动的时候git diff是绕不开的命令。用途很简单查看工作区与暂存区的差异、暂存区与最后一次提交的差异。裸git diff显示的是工作区里还没add的改动git diff --staged或git diff --cached显示的是已经add但还没commit的改动。我每次提交前的习惯动作是git diff git diff --staged先看未暂存的改动再看暂存区的改动确认内容无误、没有调试代码、没有多余的日志输出然后才git commit。这一套习惯帮我挡住了许多次把临时调试代码提交出去的尴尬。文件删除和移动也尽量交给Git来管而不是在资源管理器里直接删。Git管理的文件如果直接在外部删了Git会发现工作区和历史不一致不如用git rm 文件它会同时删除工作区文件和暂存区记录一步到位。重命名用git mv 旧文件名 新文件名Git能识别为重命名操作历史追查的时候会更友好。当然如果你已经手动移动了文件再执行git add -AGit也能通过内容相似度自动识别出重命名只是提交信息里可能不够清晰。3. 远程仓库协作clone、push、pull与分支、tag全流程3.1 远程仓库关联与Gitee/GitHub密钥配置本地玩转了之后Git最大的价值其实在协作上——把仓库推送到远端团队其他人clone下来一起开发。目前国内用得最多的是Gitee国外是GitHub两者的操作逻辑一模一样。核心步骤分两步关联远程地址、配置SSH密钥。为什么推荐SSH方式而不是HTTPSHTTPS每次push都要输入账号密码虽然可以配置凭据缓存但频繁换电脑或清理缓存后非常烦SSH配一次密钥之后就不用反复登录了。配置流程我以Gitee为例ssh-keygen -t ed25519 -C 你的邮箱一路回车会在~/.ssh/目录生成一对密钥文件id_ed25519是私钥绝对不能外传id_ed25519.pub是公钥可以公开。然后查看公钥内容cat ~/.ssh/id_ed25519.pub复制输出的整段内容登录Gitee进入“设置”→“安全设置”→“SSH公钥”粘贴保存。验证是否配置成功ssh -T gitgitee.com出现“Hi 用户名! Youve successfully authenticated”之类的提示就说明SSH通道已经通了。检测项目关联远程仓库用git remote add origin gitgitee.com:用户名/仓库名.git git remote -v3.2 推送与拉取push、pull、fetch的区别远程仓库配置好之后最常用的两组操作是git push和git pull。git push把本地提交推送到远端第一次推送分支时带-u参数建立关联git push -u origin main-u的意思是设置上游分支以后在这个分支上直接敲git push就能推送不用再指明远端和分支名。git pull则是拉取远端更新并合并到本地当前分支它其实是两个命令的合成git fetchgit merge。新手最容易混淆的是git pull和git fetch。简单说fetch只负责把远端的提交下载到本地但不自动合并到你的工作代码里pull是下载之后直接帮你合并。为什么建议有时用fetch而不是直接pull因为在合并之前你可以先看看远端到底更新了什么再决定怎么合。git fetch origin git log --oneline HEAD..origin/main这一段命令会显示“远端main分支有、但本地没有”的提交确认内容之后再git merge origin/main比闭着眼睛git pull稳妥得多尤其在多人同时开发一个分支的时候。3.3 分支管理branch、checkout、merge与rebase分支是Git协作的灵魂也是很多新手觉得高深莫测的地方。我试着用最简单的话解释分支相当于平行宇宙你可以在不影响主世界的情况下随意实验实验成熟了再合并回来。日常操作中查看全部分支用git branch -a新建并切换分支用git checkout -b feature/xxx新版Git也支持git switch -c feature/xxx只切换已有分支用git checkout 分支名或git switch 分支名。分支合并有两种主要方式git merge和git rebase。merge的特点是保留完整的分支分叉历史会生成一个合并提交适合团队协作和需要保留真实开发轨迹的场景。rebase的特点是把当前分支的提交“搬”到目标分支的最新提交之后历史变成一条直线非常干净适合个人开发或开源项目提交前整理历史。但rebase是改写历史的操作一个铁律是绝对不要对已经推送到远端的提交执行rebase。一旦你重写了提交hash远端和本地对不上别人pull的时候会冲突到怀疑人生。我自己有次用rebase整理历史后强推远端结果另一位同事本地还停留在旧历史整个分支乱成一锅粥最后花了一下午才修复。从那以后我只有本地提交、且确定没人依赖时才用rebase。多人协作推送时最常见的报错是non-fast-forward意思是远端有本地没有的提交直接push会被拒绝。正确姿势一般是git pull --rebase origin main先把本地提交挪到远端最新提交之后再检查冲突解决后依次git add、git rebase --continue最后重新push。这套流程能避免无谓的合并提交历史也更线性。3.4 暂存工作区与打标签stash和tag开发过程中有一个高频场景你正在feature分支上做需求做到一半还没写完整、不方便提交但突然要切换到其他分支去修一个紧急bug。这时候如果直接git checkout切分支Git会阻止你因为工作区有未提交的改动。解决办法是git stash把当前的工作进度暂时“存起来”工作区恢复干净。git stash # 切到其他分支处理紧急任务 git stash popgit stash list可以查看所有暂存的进度git stash pop恢复最近一次暂存并删除记录git stash apply恢复但保留记录。注意stash并不会区分所属分支从A分支stash的进度切到B分支也能pop所以操作前确认一下自己在哪个分支避免把不相关的改动带过去。打标签主要用于标记发布版本比如v1.0.0、v2.1.0。轻量标签和附注标签的区别是附注标签带完整的打标签人、时间、说明信息更规范所以推荐用-agit tag -a v1.0.0 -m 发布1.0版本 git push origin v1.0.0之后想回退到某个发布版本用git checkout v1.0.0切过去看代码或者基于某个历史版本拉分支修bug都是很常见的操作。4. 常见报错与问题排查实录4.1 Windows下“无法将git项识别为cmdlet、函数、脚本文件”解决方案这个报错在热搜里反复出现几乎每个Windows新手都会遇到一次。原因很简单系统在PATH环境变量里找不到git.exe。解决办法有两种推荐第二种。第一种是重装时勾选“Add Git to PATH”选项最省事但有时候装完仍然报错因为当前终端没有重新加载环境变量关掉重开即可。第二种是手动添加环境变量。右键“此电脑”→“属性”→“高级系统设置”→“环境变量”在“系统变量”里找到Path点击编辑新增Git的bin目录路径通常是C:\Program Files\Git\bin同时建议加上C:\Program Files\Git\cmd。如果安装时改了路径按实际路径添加。保存后重开终端git --version能正常显示就成功了。这个话题多说一句很多人装了Git但没装Git Bash安装时取消了组件导致右键菜单没有Git Bash Here操作体验差很多。建议组件全选反正装一次一劳永逸。4.2 push被拒绝non-fast-forward的两种解决思路! [rejected] main - main (non-fast-forward)是我见过频率最高的push报错。含义很直白远端有本地没有的新提交你的push会覆盖远端历史所以被拒绝了。处理方案看场景选如果远端领先你的提交不多而且你的本地提交没有跟远端冲突之处用git pull --rebase把本地提交挪到远端最新之后再push。如果远端领先很多、且冲突复杂直接git pull会生成一个合并提交再push。这种方式在团队协作中更安全因为合并记录保留了真实的汇合过程。解决冲突的时候Git会标记出冲突文件格式像这样 HEAD 当前的代码 远端拉下来的代码 分支名你需要手动决定保留哪部分或者两边综合一下删除标记符号然后git add标记为已解决再继续rebase或merge流程。新手解冲突容易慌记住一个原则先看两边的代码意图再决定保留谁、怎么融合别贪快直接删一边。4.3 login failed. check api token or gitlab version报错排查这个报错多见于使用IDE插件、Git GUI工具或自动化脚本连接GitLab时提示信息大致是“Login failed. check api token or GitLab version. Log in via Git if the version is newer than 16.0.”。问题背后是GitLab新版本API认证策略收紧旧token格式或者旧的认证方式不被接受了。排查思路分三步。第一步确认token是否过期GitLab的token可以设置有效期过期后访问API会直接失败去GitLab个人设置里重新生成一个。第二步确认token权限范围某些插件需要至少read_repository和write_repository权限如果只勾了read_api可能不够。第三步检查是否涉及GitLab 16.0及以上版本这个版本之后部分接口从基础认证切换成了Bearer Token认证如果你用的Git GUI工具版本太老可能不支持新认证方式需要升级工具版本。如果用的是命令行配HTTPS方式访问GitLab推荐改用Personal Access Token作为密码来登录或者在远程地址里直接嵌入tokengit remote set-url origin https://oauth2:你的tokengitlab.com/用户名/仓库.git不过这属于应急手段token会明文存在.git/config里注意别把仓库分享出去。4.4 .git目录泄露如何查看与处理的应急流程“.git目录泄露”这个词听起来吓人但实际遇到的人不在少数。有些网站项目部署到服务器时把整个仓库目录包括.git文件夹一起拷贝到了Web根目录任何访客只要知道路径就能通过https:yourapp.com/.git/访问到Git对象文件利用工具下载历史记录从而还原整个项目的源码、配置甚至密码。检测方法很简单浏览器访问/.git/config如果返回了文件内容那么泄露基本坐实。应急视角下怎么查看泄露的代码如果只是自己临时想判断泄露范围可以在本地用Git命令尝试恢复git log --all --oneline如果能列出提交说明仓库对象基本完整。更详细的利用工具有GitHacker、git-dumper等不过这里只讨论防御层面——发现泄露后第一时间在Web服务器层禁止.git目录访问或者直接把.git目录从部署目录移除然后检查泄露的代码里有没有密钥、数据库账号等敏感信息如有立即轮换。这条要划个重点不要把敏感配置文件提交进Git仓库。开发环境用的密钥、秘钥文件都应该写进.gitignore只留一个.env.example模板供同事参考。就算仓库不泄露团队协作出让密钥扩散的风险也不小。4.5 reflog救回误删分支或丢失提交git reflog是Git里最强大的后悔药。它记录的是HEAD指针每一次移动的历史包括reset、checkout、commit、rebase等操作。哪怕你误删了分支、reset --hard之后又后悔了只要reflog里还留着记录就能找回来。git reflog输出会列出一串操作记录每一行有操作编号如HEAD{2}以及对应的提交hash。假如你刚git reset --hard丢掉了一个提交在reflog里找到你reset之前的那条记录执行git reset --hard HEAD{2}对应的hash就能回到那个状态。误删分支也一样用git branch 新分支名 被删分支最后一次提交的hash就能恢复。reflog默认只保留30天如果30天内没有操作旧记录会被清理所以误操作后越早发现越好。4.6 误提交大文件或敏感文件急救很多项目中期会犯一个错把几百MB的node_modules或者一个数据库备份文件提交进了仓库。后果是仓库体积爆炸clone越来越慢push频繁超时。这时候直接删文件再提交并不管用因为历史提交里还有这个文件仓库体积不会小。标准解法是用git filter-repo或者老旧的filter-branch重写历史把特定文件从所有提交中抹掉。以filter-repo为例git filter-repo --path 大文件路径 --invert-paths注意这条命令会重写整个仓库历史所有提交hash都会变所以只适用于尚未推到远端的本地仓库或者团队所有人愿意一起强制同步到新历史的场景。如果文件已经推送到远端还要处理远端历史复杂度成倍增加这就是为什么我一直强调提交之前先看git status和git diff重大仓库初次提交前一定要检查有没有把不该提交的文件放进去。5. 图形工具与指令组合TortoiseGit、Git Bash与我的实战习惯5.1 TortoiseGit小乌龟适合什么场景搜索量很高的“小乌龟”其实就是TortoiseGitWindows平台的Git图形客户端最大的特点是集成到了资源管理器右键菜单文件或文件夹上点右键就能看到显示日志、提交、拉取、推送、切换分支等操作。不需要额外打开工具视觉上直观尤其适合不想记命令行、或者刚开始接触版本控制的用户。以我用下来的感受小乌龟的优势在可视化的diff和提交选择。文件修改后用右键“比较差异”左边旧版本、右边新版本改动一行行高亮比命令行里黑白diff要容易读懂。而且小乌龟允许勾选性提交三个文件改了右键选中其中一个提交不会把另外两个带进去这个体验在命令行里需要精确到git add 具体文件名才能实现。但小乌龟也有明显短板——复杂的rebase、cherry-pick、交互式历史整理图形界面的操作反而比命令行繁琐而且界面上不少术语直译自英文新手容易看不懂。我的建议是日常查看状态、diff比较、简单提交可以右键点小乌龟遇到冲突解决、分支整理这类精细操作还是切回Git Bash两条腿走路才是最高效的。5.2 Git Bash里的Linux命令与Git配合Git Bash本身就是个宝库它自带的工具集让很多操作变得顺手。比如想找出当前项目里“存在但不在.gitignore里”的大文件可以这么干find . -type f -size 50M -not -path ./.git/*这个命令只输出超过50MB且位于.git目录之外的文件正好用来排查仓库体积问题。find指令在Windows cmd里可用性不高但在Git Bash里和Linux独立环境一致这也是我始终坚持用Git Bash做Git操作的原因之一。再比如快速统计代码行数git ls-files | xargs wc -lgit ls-files列出Git跟踪的所有文件xargs把文件列表传给wc -l数字出来了对估量项目规模很实用。搜索历史提交中的某个关键字git log --all --oneline | grep 关键字想查看某次提交改动了哪些文件用git show --stat 提交hash。日常输入命令老记不住参数git help 命令名可以打开完整帮助文档或者在命令后面加-h看精简版帮助。5.3 我的Git日常推荐姿势单人、小团队、开源项目三种场景根据这些年的实际经验我把Git使用分成三个场景每个场景的工作流略有差异。单人开发或学习阶段分支不用搞得太多main分支一根走到底明确的功能模块可以开feature分支开发完合并回来。提交信息尽量写清楚“做了什么、为什么做”因为没有人帮你review几个月后回看代码就只能靠提交记录。小团队协作2-10人建议遵循主干开发模式大家都拉main分支作为基础各自开feature/功能名分支开发完成后发合并请求让别人review。推送之前务必先git pull --rebase同步远端减少无谓的合并提交。合并请求前检查自己的diff不留调试代码、不提交无意义的格式化改动。开源项目参与这种情况下历史整洁度最重要。提PR之前先用git rebase upstream/main把分支同步到上游最新把多个临时提交用git rebase -i压缩成一个清晰的提交附带说明参考项目贡献指南。这个习惯能大幅降低维护者review的成本也更容易让项目接受你的贡献。5.4 实操过程中最值得养成的三个习惯最后分享三个我在无数次踩坑中养成的实操习惯。第一个是提交前必看diff不管多简单的一句话修改至少过一遍git diff能拦住一半以上的手滑。第二个是大改动拆小提交一次提交只做一件事不要三四个不相关的改动混在一起出问题时能精确回退到某一个点。第三个是定期备份远端本地仓库再怎么折腾只要远端有一份完整历史就永远有后悔药很多同学只push main分支其他分支全堆在本地一旦硬盘坏了全没至少把重要的开发分支也推到远端。Git的指令体系很庞大但日常工作高频的其实就这么多。把上面这些命令用熟配合自己习惯的图形工具你在版本管理上的效率已经能超过绝大多数同事。我经常跟身边人说Git不是背出来的是用出来的——每次遇到报错就查一次解决完顺手记一下积累几个月你就是团队里最会处理Git问题的那个人。
