入行这些年我经手的项目不敢说上百个几十个总是有的。不管团队用什么框架、什么语言有一样东西从来没有缺席过那就是 Git。Git 是我见过最强的版本管理工具也是新手最容易踩坑的工具之一。今天这份笔记就是我从装好 Git 拉下第一个仓库到日常提交、分支合并、免密配置再到各种报错排查的完整记录希望能让刚接触 Git 的人少走弯路也让有一定经验的人查漏补缺。这份笔记覆盖的内容不算高深但绝对够日常开发用。包括 Git 的安装与配置、每天高频使用的命令、多人协作时的提交规范、远程仓库的免密登录以及一批我真实遇到过的疑难杂症和排查思路。不管是刚把 Git 装在电脑上的新手还是被各种报错折磨到怀疑人生的进阶用户这份笔记里应该都有你需要的东西。1. 从零装好 Git版本选择与初始配置1.1 各平台安装方式在哪下载Git 在 Windows、macOS、Linux 上都有对应的安装方式。Windows 用户直接去 Git 官网下载安装包注意区分 32 位和 64 位版本现在的机器基本都是 64 位下载对应的 exe 双击安装就行。macOS 用户可以永 Homebrew 安装一条命令brew install git搞定也可以直接下载官方 pkg 安装包。Linux 用户就更简单了Ubuntu/Debian 用sudo apt install gitCentOS/RHEL 用sudo yum install git或者sudo dnf install git。安装完之后在命令行输入git --version能看到类似git version 2.40.0的输出说明装成功了。很多人在这一步会碰到 git 不是内部或外部命令 的报错这个放到后面排查部分专门说。这里先提一个细节Windows 下安装 Git 时安装向导会问你要不要调整 PATH 环境变量一定要选择 Git from the command line and also from 3rd-party software 这个选项否则装完以后在 CMD 和 PowerShell 里无法直接使用 git 命令。同时如果遇到 git 命令不识别建议在 Git Bash 里操作这是 Git 自带的终端环境里面可以直接运行所有 git 命令与常用的 Linux 指令。1.2 装完第一件事配置身份信息Git 安装完成后第一件事不是急着拉代码而是配置用户信息。这一步很多人会跳过结果第一次提交后被记成一个奇怪的名字或者在别人的电脑上提交时用错了身份非常尴尬。配置命令非常简单git config --global user.name 你的名字 git config --global user.email 你的邮箱--global参数表示全局生效也就是说这台机器上的所有 Git 仓库都默认使用这套身份信息。如果不加--global则只对当前仓库生效。实际项目中如果同时维护公司仓库和个人仓库建议在各自的仓库目录下单独配置 user.name 和 user.email仓库内的配置优先级高于全局配置这样能避免把私人邮箱提交到公司项目里。此外还有几个全局配置我建议一起做掉。第一个是行尾符配置Windows 下建议执行git config --global core.autocrlf truemacOS/Linux 下建议执行git config --global core.autocrlf input目的是消除跨平台换行符差异导致的一堆无意义 diff。第二个是文件路径显示配置执行git config --global core.quotepath false避免中文文件名被转义成八进制编码。这两个配置属于不配也不报错配了才知道有多舒服的类型强烈建议一次性完成。1.3 Git Bash 常用小技巧Git for Windows 自带的 Git Bash 是个被低估的宝贝。它模拟了 Linux 的 Bash 终端环境让你在 Windows 上也能用ls、cd、grep、cat这些命令跟 Mac 和 Linux 的开发体验保持一致。我见过很多同事装了 Git 之后依然在 CMD 里敲命令满屏的乱码和路径反斜杠看着就难受。实际上 Git Bash 里支持自动补全输入命令的时候按 Tab 键能补全命令名、分支名和文件名这个特性用熟了之后效率提升非常明显。在 Git Bash 里还有一个快捷键可以极大提升体验Ctrl L清屏Ctrl C中断当前命令或退出交互界面。如果你需要对比文件差异git diff在 Git Bash 里会显示彩色输出红绿对比非常直观。不过要注意的是Git Bash 默认不支持复制粘贴的Ctrl C/Ctrl V组合复制用鼠标选中即可粘贴用鼠标右键或Shift Insert这个习惯需要适应一下。2. 每天高频使用的 Git 命令从提交到分支合并2.1 本地仓库操作路径先理清 Git 的工作思路。一个本地仓库有三个区域工作区、暂存区、版本库。你改代码是在工作区git add把修改扔进暂存区git commit把暂存区的内容固化到一个版本记录。整套流程用三条命令串起来git add . git commit -m 提交说明 git pushgit add .会把当前目录下所有变更新增、修改、删除都加到暂存区如果你只想提交某个文件可以写git add 文件名。git commit是生成一个版本节点-m后面跟的是提交说明。git push是把本地提交推到远程仓库。这三连几乎就是日常工作循环的全部了。需要提醒的是git add .会把隐藏文件、临时文件一并加进来。如果你的项目里有些文件不想被 Git 跟踪必须提前在仓库根目录创建.gitignore文件。我通常会在里面写上.idea/、.vscode/、node_modules/、dist/、*.log、.DS_Store这类内容避免把本地工具配置和依赖包提交到仓库里。见过太多新人把 IDEA 的配置目录提交上去然后每次换电脑拉下来全是乱码和冲突。2.2 分支管理与合并策略分支是 Git 的精髓。一个项目通常有main或master主分支功能开发在独立分支上进行完成后再合并回主分支。分支相关的核心命令git branch # 查看本地分支列表 git branch 新分支名 # 创建新分支 git checkout 分支名 # 切换分支 git checkout -b 新分支名 # 创建并切换 git branch -d 分支名 # 删除分支分支合并用git merge。举个例子我在feature/login分支上开发完登录功能想合到main上git checkout main git pull git merge feature/login git push合并的时候如果两个分支修改了同一个文件的同一行Git 会提示冲突。解决冲突的方法是打开提示的文件找到、、标记手工选择保留哪边内容然后重新git add、git commit。冲突不可怕可怕的是不看提示瞎合并导致代码丢失所以合并前一定要git pull先把远程最新的代码拉下来。git rebase是另一个合并相关命令。它的作用是把自己的提交搬到目标分支的最新节点上让提交历史变成一条直线看起来更干净。但 rebase 会重写提交历史所以切忌在多人协作的分支上随意 rebase否则会把同事的提交搞乱。我的建议是推送之前多 commit、少 push推送之后多 merge、少 rebase。2.3 撤销与回滚的正确姿势撤销是 Git 里面最容易迷糊的部分因为针对不同场景有不同的撤销命令。我整理了几个最常用的场景场景命令说明文件还没 add改乱了想还原git restore 文件名把工作区文件还原到暂存区或版本库的状态文件已经 add想退出暂存区git restore --staged 文件名把文件从暂存区移回工作区内容不变提交后想撤销提交但保留改动git reset HEAD~1回退到上一个提交改动留在工作区提交后想彻底撤销连改动一起丢掉git reset --hard HEAD~1危险操作慎用提交后想新增一个反向提交git revert commit号不修改历史适合已经 push 的提交git reset --hard是极其危险的操作因为它会把工作区和暂存区的所有未提交内容全部丢弃。我在实操中唯一会用它的情况是本地分支被自己弄乱了而远程分支代码是对的这时执行git reset --hard origin/main可以强制对齐远程。除此之外宁可多敲几条命令也不轻易使用--hard。如果要查看提交历史用git log --oneline --graph它能以图形方式展示分支合并历史。加上--all参数可以看到所有分支的最新提交。git stash这个命令也值得单独说两句它能把当前工作区未提交的改动暂存起来让你先切换到其他分支干活。存放后使用git stash pop恢复特别适合突然要我改个紧急 bug但我手上的活还没干完这种场景。3. 提交规范与协作流程让历史记录真正可用3.1 为什么提交信息要规范说到 Git 提交规范不少初学者觉得这是形式主义反正代码能提交能推送不就行了吗写那么详细干什么我过去也觉得无所谓直到有一次线上出问题需要靠git log定位是哪个提交引入的结果看到一堆 update、fix bug、修改 这种信息瞬间崩溃。提交信息是团队协作的接口之一它承担的是事后追溯的价值——三个月后回来看你能从提交信息里快速理解当时做了什么、为什么这样做。规范提交还直接关联到自动化工具。现在很多团队的 CI/CD 管线会根据提交信息自动生成变更日志Change Log、自动决定版本号升级的语义化规则甚至自动触发对应环境的发布。如果提交信息写得乱七八糟这些自动化流程全部都会抽风。3.2 一套可以直接抄的提交格式社区里最主流的提交规范是 Conventional Commits约定式提交。核心格式如下type(scope): subject其中type是提交类型scope是影响范围可选subject是简洁的提交说明。常见的 type 有以下几种feat: 新增功能fix: 修复缺陷docs: 只改文档style: 不影响代码逻辑的格式修改如调整空格、缩进refactor: 既不是修 bug 也不是加功能的代码重构perf: 性能优化test: 增删测试用例chore: 构建过程、辅助工具类变更举个例子如果我为用户登录模块增加了一个记住我的功能提交信息可以这样写feat(login): 增加记住我的功能如果修复了首页在移动端的样式问题可以写fix(home): 修复移动端首页样式错乱问题scoep不写也可以但建议小团队统一约定有经常维护的模块就写上。subject尽量用动词开头控制在 15 个汉字以内一句话说清楚做了什么而不是做了什么及为什么。为什么留在body里写也可以在需要额外说明时用git commit -m 标题 -m 描述分两段提交。3.3 分支模型怎么选分支模型最出名的是 Git Flow它的核心思路是设置长期分支和短期分支的组合main分支永远保持可发布状态develop分支用于日常集成功能分支、发布分支、修复分支临时创建用完即删。这种模型适合发版节奏明确的传统项目。对于互联网产品那种每天可能发多次的小步快跑团队我推荐 GitHub Flow所有功能从main拉分支开发完提 Pull Request代码评审通过后合并回main合并后立即部署上线。它的核心就一条main永远是稳定的任何代码变更都必须通过评审和测试才能进main。这套流程简单粗暴、可执行性强小团队用起来压力很小。不管选哪种分支模型我建议团队至少要约定三件事第一禁止直接往main分支推代码所有变更走合并请求第二功能分支从最新的远端main拉出避免基于过时代码开发第三合并策略选择 squash merge压缩合并或 rebase merge让主分支的提交历史保持线性、干净。最后这个细节非常关键它决定了你的git log是清晰的一条线还是一团乱麻。4. 免密配置与远程仓库操作告别每次输入账号密码4.1 SSH 免密登录配置全过程如果你厌倦了每次git push都要输入账号密码SSH 免密就是你的解药。它的原理可以简单理解为你在本地生成一对钥匙公钥和私钥把公钥放到 Git 服务商的账户设置里之后本地通过 HTTPS 向远端认证时服务商会用这把公钥来验证你的私钥验证通过就不再要求输入密码了。配置步骤如下。第一步在本地生成密钥对ssh-keygen -t ed25519 -C 你的邮箱如果你用的是比较旧的系统或 Git 版本可能不支持 ed25519就用ssh-keygen -t rsa -b 4096 -C 你的邮箱。执行后会提示你设置存放路径和口令直接一路回车也可以不过设置一个 passphrase 会多一层安全保护。第二步查看公钥内容cat ~/.ssh/id_ed25519.pub复制输出的整段内容。第三步登录你的 Git 服务商管理后台找到 SSH Keys 设置把公钥粘贴保存。最后验证一下在命令行执行ssh -T gitgithub.com如果看到类似 Hi username! Youve successfully authenticated 的提示说明配置成功。之后用 SSH 协议的仓库地址形如gitgithub.com:用户名/仓库.git克隆或推送就不再需要输入账号密码了。4.2 HTTPS 方式的凭据管理与 Token 登录很多人习惯用 HTTPS 地址操作仓库因为复制起来直观方便不需要额外生成 SSH key。但是 HTTPS 每次 push 都要输账号密码这就比较烦了。Git 为此提供了凭据缓存机制。最简单的配置是启用 store 模式git config --global credential.helper store这样 Git 会把密码明文写入~/.git-credentials文件以后就不再询问了。但这个方案安全性相对差一些因为密码是明文保存的。更稳妥的做法是使用 manager 模式Windows 默认就是 Git Credential Manager它会弹窗让你完成图形化登录然后密钥信息加密存储在系统凭据管理器中。还要提醒一点现在各大 Git 平台基本都已经不再支持 HTTPS 密码直接登录了改用 Token 或者 SSH Key。如果你使用密码推送被拒绝先去平台的个人设置里生成一个 Personal Access Token然后用这个 Token 作为密码使用。复制仓库地址时注意看一下仓库地址使用含 user 的 account/仓库 形式与纯 https 链接形式按平台要求处理即可。4.3 clone 之后配置远程地址有时我们需要修改已有仓库的远程地址比如从 GitHub 迁移到 GitLab或者公司更换了新的 Git 服务器。查看远程地址的命令是git remote -v修改远程地址可以用git remote set-url origin 新地址如果你在 clone 时选择的是 HTTPS后续想切换到 SSH也可以用这条命令替换地址。另一个相关操作是给仓库增加多个远程源比如同时推送到两个平台做备份用git remote add backup 地址然后推送时指定源名称。不过日常开发中多远程源用得少我更推荐只保留一个 origin避免推送混淆。5. 疑难杂症排查实录遇到报错别慌5.1 fatal: not a git repository 与 git 命令找不到fatal: not a git repository (or any of the parent directories): .git这个报错核心原因只有一个当前目录不是 Git 仓库或者在父目录中找不到.git目录。解决方案也很直接先git init初始化仓库或者cd到正确的仓库目录里再执行命令。如果你是 clone 之下想切换分支记得先cd仓库名。还有一个高频报错是git : 无法将“git”项识别为 cmdlet、函数、脚本文件或可运行程序的名称。这个错误出现在 Windows 的 PowerShell 或 CMD 中根本原因是系统 PATH 环境变量没有配置 Git 的 bin 目录。解决办法分两步先找到git.exe所在路径一般默认安装位置是C:\Program Files\Git\bin然后打开系统环境变量设置把这个路径追加到 PATH 变量的末尾重启终端即可。如果你装 Git 时没有修改默认选项自动配置已经完成大概率不会出现这个报错。如果是在 IDE 内置终端出现检查 IDE 的终端配置是否继承系统环境变量。5.2 证书验证类错误排查一类非常折磨人的报错和 HTTPS 证书相关。典型的报错长这样error setting certificate file: d:/git/mingw64/etc/ssl/certs/ca-bundle.crt意思是 Git 在尝试加载 CA 证书时失败。这种问题的常见诱因有三个一是 Git 安装路径变动导致证书文件路径失效二是所在网络环境有代理服务器劫持了 HTTPS 流量三是系统时间不对导致证书验证失败。排查思路先检查 Git 当前的证书配置路径git config --global --list重点看http.sslCAInfo这个配置项。如果它指向了不存在的文件把它改回 Git 安装目录下正确的路径即可git config --global http.sslCAInfo C:/Program Files/Git/mingw64/etc/ssl/certs/ca-bundle.crt如果配置没问题但 clone 依然报错就要考虑是不是临时网络环境的问题。可以试着临时关闭 SSL 验证git config --global http.sslVerify false但这个方法我强烈不建议在生产环境使用它会让你暴露在中间人攻击的风险中只适合临时绕过某个公司自签名证书的场景。正常情况下正确导入企业证书或者等待网络恢复正常才是长久之计。5.3 其他高频报错及解决方案速查表报错信息原因解决思路Permission denied (publickey)SSH 公钥未配置或不对重新执行 ssh-keygen 并新增公钥到平台fatal: Authentication failed账号或密码错误改用 Token 或检查用户名拼写fatal: refusing to merge unrelated histories合并两个没有共同祖先的仓库确认后执行git pull origin main --allow-unrelated-historieserror: failed to push some refs to本地落后于远程先git pull再推送或者检查分支保护规则fatal: remote origin already exists已经配置过远程源用git remote set-url origin修改不要重复 addYou have divergent branches本地和远程提交历史分叉git pull --rebase把自己的提交垫在远程提交之后排查 Git 报错最重要的不是背住每个错误信息的字符串而是养成两个习惯。第一认真读报错信息Git 的报错已经设计得很友好了大多数时候它已经告诉你该怎么解决第二用git status和git log先搞清楚当前仓库的变化状态再决定执行什么操作。很多人的问题是把git pull和git push当成刷新一下的按钮盲目执行结果越搞越乱。6. 效率工具把 Git 用得顺手一些6.1 Git 小乌龟与图形化工具纯命令行用久了偶尔打开图形界面反而更舒心尤其是做代码评审和分支可视化的时候。Windows 上最有名的 Git 图形工具之一是 TortoiseGit大家习惯叫小乌龟。它集成在右键菜单里选中文件直接就能看 diff、提交、切换分支对刚接触 Git 的朋友非常友好。不过小乌龟有一点要注意它依赖单独的 Git 安装不能在装它的时候选择自带 Git否则命令行和图形界面的 Git 版本可能不一致。它最大的优点是文件级别操作直观缺点是功能相对固定复杂 rebase 或 cherry-pick 操作不如命令行灵活。我个人建议小乌龟作为图形辅助工具使用核心操作仍然以命令行和 IDE 集成为主。6.2 VSCode 里的 Git 插件VSCode 是目前很多前端工程师的主力编辑器它内置的 Git 体验其实已经很不错了左侧栏可以看到变更文件列表输入提交信息后一键提交点击文件名可以直接对比 diff。在此基础上安装一个 Git Graph 插件就能在编辑器里可视化提交历史和分支关系比命令行里的--graph好看太多。还有个插件叫 GitLens它能在代码行上直接显示这行是谁在什么时候提交的鼠标悬停可以看到完整的提交信息和相关分支。团队协作时用这个插件追责或者理解历史代码逻辑非常方便。唯一要注意的是 GitLens 功能虽然强大但免费版和付费版有功能差异日常使用免费版完全够了。6.3 在 IDE 里避免的坑在 IntelliJ IDEA 或 VSCode 里使用 Git最大的坑是IDE 自动 commit 带来的误操作。比如 IDEA 的 commit 窗口默认会带着Optimize imports和Reformat code选项很多人没注意就顺手提交了结果这次提交除了你的代码改动还带了一堆格式化 diff严重干扰代码评审。建议在 IDE 的 Git 设置里关闭这些自动操作让提交只包含你自己做的代码变更。另一个坑是 IDE 自动执行的update project相当于git pull如果它默认使用 merge 策略会在本地产生一个从远程拉取产生的 merge 提交长期下来提交历史会乱七八糟。配置 VCS 的 update 策略为 rebase 可以避免这个情况。这些配置看起来很小但就是这些小细节决定了你三个月后回头看提交历史时是心旷神怡还是头皮发麻。我个人在实际操作中的体会是Git 的学习曲线确实有点陡但它那些概念和命令真的不算多只需要把add、commit、push、pull、merge、rebase、reset这七个命令吃透日常工作的八成场景都能覆盖。剩下两成遇到报错再查边用边积累慢慢就内化了。这份笔记记录下来的是我踩过坑之后沉淀下来的操作习惯最后再分享一个小技巧每次新项目开始前把.gitignore先写好把你所在团队的提交规范贴到项目根目录的CONTRIBUTING.md里后面整个协作过程都会顺畅很多。Git 本身不复杂复杂的是团队的协作习惯而好习惯是从第一次提交就开始养成的。