我一直觉得Git 入门最该做的第一件事不是去搭远程仓库也不是背一堆命令而是先在本地把“提交”这件事记熟。无论你用的是 GitHub、Gitee还是公司自建 GitLab底层逻辑都一样你先在本地完成一次提交然后才谈得上推送和拉取。所以这篇只聊 Git 本地基础操作把安装配置、首次提交、分支合并、修改提交信息、撤销回退这些动作全部过一遍顺便把网上常搜的那几个报错——比如fatal: not a git repository、SSH 认证失败、git 不是内部命令——一并说明白。如果你是刚接触 Git 的开发者跟着做一遍会非常有代入感如果你已经被本地提交、分支合并搞得有点晕这篇文章也可以当作一次快速复盘。我不会给你列几百条命令只会把日常真正会用到的几十条挑出来讲清楚每条命令在干什么、为什么这么用。1. 为什么先学 Git 本地操作把代码放进去之前先想清楚1.1 Git 到底是什么用快照代替复制粘贴备份简单讲Git 是一个分布式版本控制系统核心概念是“快照”。每次 commit 时它会把当前项目目录的状态整理成一次新版本保存文件内容对应的对象同时记录这次提交的作者、时间、提交信息和父提交。正因如此仓库里的历史是一条有向链任何时间点都可以被回溯。我经常用这个类比过去我做备份时习惯把文件夹复制成项目_最终版_20230101一星期后文件夹里全是最终版(2).zip。Git 的做法是提供无数个带标签的抽屉每次提交就是一个抽屉它还自动告诉你抽屉之间哪份文件变了。更重要的是这个动作完全可以在本地完成——不需要服务器没有网络也能提交。这一点是很多人没想明白的“Git 不是远程仓库工具吗”其实远程仓库只是在本地仓库之上加了一层对象交换协议而已。1.2 为什么从本地操作开始不直接学远程协同不少同学一上来就搜git pull、git push觉得不涉及远程就不是 Git。但 pull 和 push 只是把本地 commit 和远程 commit 做交换push 是把本地新提交上传pull 是把远端新提交拉下来合并。如果你不会在本地正确 commit在远端操作就如同空中楼阁。本地操作最大的优势是可以随时试错提交信息写错了可以用git commit --amend修改分支合错了可以用git reset回去甚至被覆盖掉的工作区内容也能靠git reflog找回来。学这些动作既不影响别人也不影响服务器完全可以在一个空目录里反复练。顺带一提Git 和 SVN 的差别也在这里。SVN 必须连接中央服务器才能提交离线基本无法保存版本Git 则是每个本地目录都是一个完整仓库先提交再选择时机推送。理解了这一点再看“git 和 svn 区别”这种搜索词时会更有实感不只是命令不同而是工作模式完全不同。你用 IDE 创建新项目并选择 Git 拉取本质上也是在背后执行git init加git pull没有什么神秘魔法。2. 环境准备安装、配置、让命令找得到2.1 Windows 下安装 Git推荐勾选哪些选项在 Windows 上装 Git我建议去官网下载对应系统版本的安装包。安装时一路 Next 没问题但这几个选项值得停留一下1. 安装路径尽量选纯英文路径不带空格以后少很多奇怪问题。 2. 默认编辑器可以暂时选 Notepad之后改 VSCode 也不迟。 3. 调整 PATH务必选择 “Git from the command line and also from 3rd-party software”。 4. 换行符转换Windows 用户建议选 “Checkout Windows-style, commit Unix-style line endings”。 5. 终端模拟器选 MinTTY用起来比默认控制台舒服。很多人把 Git Bash 当成 Git 本身其实 Git Bash 只是一个自带 bash 环境的终端工具。装好 Git 后在任意目录右键选择“Git Bash Here”就能进入一个类 Linux 的 shell可以使用git、ssh、vim等命令。日常办公想用图形界面也有 TortoiseGit俗称“小乌龟”但它并不会替你安装命令行 git。如果只装小乌龟而不安装 Git 核心运行git时很容易提示找不到命令。Linux 和 macOS 用户安装更简单Ubuntu 上用apt install gitmacOS 上可以用 Homebrew 安装后面所有配置和命令都一样。2.2 解决“无法将 git 项识别为 cmdlet”或者“git 不是内部或外部命令”这个报错出现频率极高。本质是 Windows 在执行命令时到 PATH 环境变量里找git.exe没找到。原因通常是安装时没有把 Git 加入 PATH或只装了图形客户端而未装 Git 核心或安装后没有重新打开终端。在 PowerShell 里可以先排查一下比如终端里敲Get-Command git -ErrorAction SilentlyContinue没有输出就说明 PATH 里确实没有 git。我一般会手动把安装目录加进 PATH因为很多人不想重装。步骤是# 示例路径改成你的实际安装位置 $gitPath C:\Program Files\Git\cmd [Environment]::SetEnvironmentVariable(Path, $env:Path ; $gitPath, User) # 立即刷新当前会话 $env:Path ; $gitPath git --version注意这种改法只影响当前用户。无论 PowerShell 还是 CMD改完都要重新开一个窗口因为新进程才会读最新的 PATH。如果不想手动配置最简单的方案是重新运行 Git 安装包在 PATH 页面改成推荐项覆盖修复即可。2.3 第一次提交前必须配置 user.name 和 user.email如果你直接执行git commit大概率会看到一段红色提示说需要设置身份。这不是 Bug而是提交记录需要注明作者。基本配置命令是git config --global user.name yourname git config --global user.email youremailexample.com--global表示当前系统用户下所有仓库生效你也可以在某个仓库内去掉--global用--local只为当前仓库配置不同的名字。公司项目和个人项目如果混着用我建议公司目录下的仓库用--local单独配置避免把私人邮箱提交到工作仓库中。配置完成后用git config --list查看整个配置链。还有一个容易被忽略的配置项是core.autocrlf。在 Windows 上我一般设成true这样提交到仓库时自动转成 LF检出到本地时转成 CRLF能减少不同操作系统引起的“每行都变红”问题。如果团队统一用 Linux/macOS也可以设为input但一定不要一台机器true、一台机器input乱用换行符会来回变化。2.4 顺手配置 SSH 免密免得每次都输账号密码本地基础操作本不一定要配 SSH但既然很多人会搜“git 配置 gitee 密钥”“ssh 认证失败”我就放在这里。原理是生成一对公私钥公钥放在代码托管平台的设置页私钥留在本地。以后走gitgithub.com:xxx/repo.git这种 SSH 地址Git 自动拿私钥做身份认证。# 生成 Ed25519 密钥一路回车即可 ssh-keygen -t ed25519 -C youremailexample.com # 查看公钥内容复制后去 GitHub/Gitee 添加 cat ~/.ssh/id_ed25519.pub # 测试连接 ssh -T gitgithub.com # 如果是 Gitee 则换成 ssh -T gitgitee.com我推荐 Ed25519因为生成的密钥短、性能好目前主流环境都支持。老教程喜欢用 RSA如果你使用 RSA 且新服务器拒绝可以检查~/.ssh/config是否指定了旧的密钥算法。配置好之后推送再也不用一次次弹 Windows 安全凭据框省去很多麻烦。3. 本地版本库从 init 到第一次 commit 的完整流程3.1 工作区、暂存区、版本库是怎么协作的在本地开一个仓库很简单mkdir demo cd demo git init执行完其实只是创建了一个.git隐藏目录。当前项目文件所在目录叫工作区.git里保存的提交历史叫版本库中间还有一层操作系统看不见的“暂存区”index你可以把它理解成“准备提交的购物车”。使用git status可以随时看到三者的关系。第一次打开 status 输出时看到Untracked files说明文件在工作区但从未被 Git 跟踪过。我见过不少人git init完直接git commit -a其实并不保证把所有文件都提交进去。更稳妥的习惯是新项目先建一个.gitignore然后git add指定文件或目录再git status确认差异最后才git commit。第一次提交前稍微多看一眼后面会少很多头疼时刻。3.2 add / commit 为什么是两步不小心暂存了怎么撤销Git 强制你把“做修改”和“保存快照”分开git add把当前内容放进暂存区git commit会基于暂存区里的内容生成一次新提交。这样带来的好处很实际你可以在同一次提交里只加入想要一起发布的内容某一个文件里有多个改动也可以用git add -p分块挑选。常用的两条路# 添加所有改动 git add . # 只添加某个文件 git add README.md # 查看暂存区里已经有什么 git status git diff --cached如果不小心把不该提交的文件 add 了不需要慌# 新版 Git 推荐写法 git restore --staged file # 老版本写法 git reset HEAD file上面这条路只把文件从暂存区撤回来工作区内容完全不动。很多人以为这会“删掉”改动其实只是让文件重新变成未暂存状态。记住这个区别能避免一次无谓的删除误操作。3.3 .gitignore哪些文件不该进仓库在提交第一个 commit 之前最好先把.gitignore建好。否则你可能把node_modules/、编译产物、本地方案配置、日志文件都提交进去仓库会变得像垃圾场而且后面想清理还得挨个移除。基础写法示例# 依赖目录 node_modules/ vendor/ # 编译产物 dist/ build/ *.class # 环境变量与密钥 .env *.local # 日志 logs/ *.log # 系统文件 .DS_Store Thumbs.db遇到明明在.gitignore里但 status 还显示未跟踪的情况多半是这个文件已经被记进了版本库你可以用git check-ignore -v path/to/file看具体是哪条规则生效再用git rm --cached file把文件从版本库中移除但保留本地文件。我自己的习惯是宁可让仓库瘦身也不要为了省事把一堆垃圾文件带进去。3.4 看历史log、show、diff 的日常用法本地操作的核心之一是查看自己的版本历史。三条命令最常用# 一行模式看提交历史 git log --oneline --graph --all -20 # 看某条提交做了什么 git show commit-id # 查看还没暂存的改动 git diffgit log --oneline是宝藏建议写成一行模式加上--graph可以直观看到分支脉络。git show的对象不一定是 commit也可以执行git show HEAD~2:file.txt来查看某个历史版本中某文件的内容。git diff主要用于 commit 之前检查正要提交哪些逻辑但我会更推荐git diff --cached它可以只看暂存区和上一个提交之间有哪些差异这样更精准。4. 分支与合并修改时不用害怕搞乱主分支4.1 分支的本质与常用分支命令要理解 Git 的分支先记住一句话分支就是一个指向某个提交的指针它本身不包含文件。所以创建分支的成本很低不会复制整个项目目录这也是 Git 鼓励你多开分支的原因。日常开发里我一般会让main或master分支保持稳定每次新需求都从主干拉一个功能分支做完再合回去避免直接在主分支上做半成品。# 查看所有分支 git branch # 创建分支基于当前 HEAD git branch feature/login # 切换到该分支 git switch feature/login # 创建并切换一步到位 git switch -c feature/payment # 删除已合并分支还没合并时用 -D 强制 git branch -d feature/login需要注意git checkout和新版git switch到底什么关系。checkout 身兼多职既能切分支又能恢复工作区文件。Git 2.23 之后官方把“切分支”抽成了switch避免新人在同一条命令上犯错。如果环境版本允许我建议直接用switch语义更清楚。4.2 合并分支fast-forward、三方合并与冲突处理合并是本地操作里最容易出状况的环节但原理并不复杂。我在main分支执行git switch main git merge feature/login这里实际出现三种情况。第一种目标分支就是从 main 长出来的main 在分叉后没有任何新提交Git 直接把 main 的指针挪到 feature这叫 fast-forward 合并。第二种main 在分岔后有了新提交Git 会找两个分支的共同祖先加上两边各自的改动做三方合并如果两边改的区域没有重叠哪怕都改了同一个文件的不同段落Git 也能自动合并成功。第三种两边在同一处做了不同修改Git 不知道谁对就停下并提示冲突。冲突出现后有冲突的文件里会打出类似 HEAD的分隔标记上半段是当前分支的版本下半段是对方分支的版本。解决办法不是急着写 Git 命令而是先打开文件把最终想保存的代码留下来再删掉标记然后git add 冲突文件 git commit这里给新人的最重要建议是冲突不是 Bug是 Git 在保护你。千万别用git checkout --theirs这种“谁赢了听谁的”的粗暴方式尤其刚入门时人肉读一下两边逻辑更可靠。如果 merge 到一半发现合不下去想退出本次合并可以用git merge --abort回到合并前状态。4.3 rebase让历史更线性但下手要分清场景网上聊分支合并一定会出现 rebase。rebase 做的事情是把当前分支的提交“挪”到另一个分支的最新提交之上重新排列让历史变成一条直线。常用姿势git switch feature/login git rebase main git switch main git merge feature/login这样 main 上看到的历史更干净没有杂乱的分叉。但它有个硬约束不要对已经推送过、别人可能也在使用的共享分支做 rebase。因为 rebase 会重写提交的哈希别人再用旧历史同步会对不上。我自己的习惯是本地私有分支随便 rebase团队共享分支只用 merge。如果你在团队里需要统一历史风格要先商量好再执行。4.4 一次开两处工作区git worktree如果你经常需要同时看两个分支可以试试git worktree。它能在一台机器上为另一个分支另建一个工作目录和当前目录同时打开而不必反复切换git worktree add ../demo-other feature/other # 用完后移除 git worktree remove ../demo-other注意同一个仓库再建 worktree 不能同时 checkout 同一个分支因为两个工作区对应一个仓库的状态。日常场景是主分支在干活另一个分支想临时改一行并提交开一个 worktree 就不会互相干扰。5. 撤销与重写本地最常用的几招后悔药5.1 git commit --amend改提交信息或补上漏掉的文件git commit --amend是很多新手想搜但不敢搜的命令它的字面意思是“修改上一个提交”。最常见的两个用途改错别字、把忘了暂存的文件补进上一个提交或者想把两条过于琐碎的提交合并成一条。# 补一个漏掉的改动到上一个 commit不修改提交说明 git add forgotten.py git commit --amend --no-edit # 直接修改上一条提交信息 git commit --amend -m fix: 修复登录时的入参校验这里必须强调--amend会在原提交之上生成一个全新提交原提交会被替换掉。所以只适合还没推送或只存在于本地的提交。如果已经推送到公共分支再 amend 会让同事的本地历史和你产生分叉。换句话说如果你还没把这段直播推流出去可以随意改发布出去了就得谨慎。5.2 git resetsoft / mixed / hard 到底回到哪里git reset是本地操作的重锤。它可以把 HEAD 移动到一个指定提交同时按模式决定是否动暂存区和工作区。模式HEAD暂存区工作区使用场景--soft回退保留保留只想重做提交信息--mixed回退清空保留想重新 add 一次--hard回退清空清空彻底丢弃改动比如最近两个提交里混入了一个不该提交的文件你可以git reset --soft HEAD~2 git add . git commit -m 把两次提交合并成一次如果是--hard则意味着工作区里未提交的内容会被覆盖使用之前必须确认没有值得保留的改动。我建议任何强制动作前先git stash或者把目录复制一份。别等到无法补救再想起还有git reflog。5.3 git revert保留历史的安全撤销如果你已经和同事共享分支但想撤销某个提交别用 reset用revert。git revert commit-id会创建一个新提交它的内容是把那个提交的改动反向应用一遍相当于说“上一句话我说错了现在发一条新公告修正”而不是把上一句话从会议记录里撕掉。# 撤销最近一次提交 git revert HEAD # 撤销指定提交 git revert a1b2c3d因为不重写历史revert 适合用在公共分支上。本地基础操作里它常和--amend放一起对比改没推送的用 amend改已推送的用 revert。规则就一条先判断这条提交是否已经“公开”。5.4 reflog重新找回“我以为我删掉”的东西很多人在git reset --hard之后才后悔但其实本地仓库保存了每个引用更新的日志这就是git reflog。它记录了 HEAD 和其他引用的历史移动过程哪怕你在 reset 之前显示的提交已经被“丢掉了”也能通过 reflog 找回那个提交的哈希。git reflog # 找到目标提交哈希后重新切换/重置回去 git switch -c recovery hash这一招能救本地仓库自己的操作gc 之后另说但“找回丢失提交”这个能力确实很让人放心。因此如果你不确定刚才那次 reset 会不会丢东西先看一眼 reflog 再继续。而且它不需要服务器完全属于本地基础操作里的救命储备。6. 常见问题与排查技巧实录6.1 fatal: not a git repository (or any of the parent directories): .git这个报错大概率不是仓库损坏而是你当前目录根本不在仓库里。Git 在执行命令时会从当前目录逐级向上找.git找不到就报这个错。处理顺序pwd ls -a git rev-parse --show-toplevel如果当前位置不是仓库进入仓库根目录再执行命令即可。还有一种情况是在某个系统临时目录里执行了git init后又把.git删除导致目录是“空壳仓库”此时你可以重新git init或者干脆把目录切走。我遇到过很多次都是因为新开了终端后忘了 cd第一反应不是怪 Git而是先看路径。6.2 SSH 认证失败全新机器、旧密钥和多重身份Permission denied (publickey)这类问题可能不是网络问题而是本地密钥没有被正确使用。我常用的排查步骤# 1. 看当前有没有密钥 ls -la ~/.ssh # 2. 加 -v 看详细输出 ssh -vT gitgithub.com # 3. Gitee 则换成 ssh -vT gitgitee.com如果显示公钥未注册就去托管平台设置页添加公钥。如果机器上有多把密钥单靠默认路径找不到目标私钥可以在~/.ssh/config里为不同 host 指定不同密钥。最简单可靠的方式仍是生成新密钥把公钥贴到托管平台确认本地私钥路径正确再测试连接。6.3 清除 Windows 上保存的 Git 账号密码很多 Windows 用户会遇到凭据管理器里存了错误的账号密码导致 push 时提示认证失败但又没有重输弹窗。这时候可以把旧凭据删掉强制重新认证。cmdkey /list | findstr git cmdkey /delete:LegacyGeneric:targetgit:https://github.com然后在仓库里使用git push触发一次新的认证。也可以用git credential-manager erase但 Windows 环境下先看cmdkey /list更直观。VSCode 里如果反复要账号密码多半也是这个原因方式同样适用。删除凭据不会影响本地提交放心操作。6.4 合并冲突的速查清单场景现象解决merge 过程冲突文件出现冲突标记打开文件改好后 add 并 commit想放弃本次 merge终止合并git merge --abort误合并分支已生成合并提交git reset --hard 合并前哈希未推送才用误把 A 提交合并到 B不想留合并历史git revert -m 1 merge-commit或咨询老手这个表格不是让你背下来而是遇到报错时先对照看看。平时可以把git status当作向导因为它会告诉你下一步该执行什么操作比如“所有冲突已解决用 git commit 完成合并”这种提示是可靠的方向标。6.5 “git 目录泄露”是什么开发时应如何避免搜索词里有一个“git 目录泄露如何下载”我把它理解为 Web 部署事故而不是攻击技巧。有些开发把网站目录直接作为静态站点发布结果把.git整个暴露到公网他人理论上可以拿到源码历史。要避免这个问题本质上不是研究怎么下载而是不要提供下载途径。防范措施很直接部署时不要把仓库的.git目录复制到 Web 根目录服务器端配置禁止访问/.git/路径发布前用扫描工具自查一下是否可访问。更稳妥的做法是设置 CI/CD 只产出构建后的静态文件而不是把整个仓库同步到服务器。Git 本身没有错责任在部署管理。这也是本地基础操作之外最值得提前养成的安全意识。回头看我刚学 Git 的日子最怕的不是报错而是不敢动手。其实本地基础操作就像是给代码仓库装了摄像机每一次 commit 都是一帧分支是你用来尝试的道具。遇到fatal: not a git repository时先冷静看一下当前路径遇到合并冲突别急着选边站把两边都读一遍再写最终版本。真正把这个流程跑顺之后不用再背几百条命令——把 add、commit、switch、merge、reset、log 这六个动作玩熟绝大多数日常开发就够用了。如果你正好卡在某个报错上把命令行输出贴给身边同事看很多人一眼就能猜到问题出在哪。