前两天帮新同事排查问题他一脸委屈地指着终端我执行 git pull 它说 fatal: not a git repository。我走过去看了一眼文件夹里连 .git 目录都没有典型的还没初始化就在跑仓库命令。这个场景太熟悉了几乎每个学 Git 的人都栽过同样的跟头。Git 这东西日常开发绕不开尤其是团队协作、版本溯源、代码备份全都靠它扛着。但它真不是靠背命令能学会的得先理解它到底在做什么事再上手操作。这篇内容我按自己的学习路径和多年实操经验来写从安装、配置到提交、分支、合并再到各种疑难杂症把 Git 基本操作里最容易卡住的环节都捋一遍。通篇拿 Windows 环境为主讲macOS 和 Linux 只差安装方式配置和命令完全通用。适合刚接触 Git 的新手通读也适合给用了几个月但总在报错边缘试探的老同学当查漏补缺手册。1. Git 究竟解决了什么问题从文件名日期的噩梦说起1.1 没有版本管理的日子在讲命令之前先想想没有 Git 时我们是怎么过的。项目改到第三版文件夹里躺着一堆项目_最终版.doc、项目_真最终版_改2.doc代码更惨main.py、main_new.py、main_20240115.py、main_final.py最后发现别人改的是main_new你改的是main_最终版合并的时候对着一堆文件人麻了。更可怕的是覆盖。上午改了十个文件下午发现改错了想回到中午的状态系统没有撤销自己没有备份只能对着屏幕叹气。多人协作的时候老办法是拿 U 盘或者聊天工具互传压缩包传完解压、替换、冲突、谁改的哪个版本全凭脑子和口头约定。时间一久代码状态混乱到项目都不敢重构。1.2 Git 的底层思路与核心概念Git 做的核心事情只有三件记录每次改动、随时回到任意历史状态、让多人并行修改而不互相覆盖。它和你熟悉的游戏存档非常像。每次git commit就像打游戏时拍一次存档照片这个存档不是只记录你改了哪几行而是整个项目在当时的一个完整快照。只要你存了档哪怕后面把代码改得稀烂也能瞬间回到存档点。而且这份存档在本地就是你自己的.git目录不依赖于任何在线平台断了网也能提交、回滚、查历史。Git 有三个区域需要先分清工作区你正常写代码的目录、暂存区一个临时放改动的地方commit 之前先在这集合、本地仓库真正生成存档的地方。日常改动流就是工作区改代码 →git add把修改放进暂存区 →git commit把暂存区内容变成一次正式存档。这个三步走是后续一切操作的地基。1.3 Git 与 SVN 的区别很多老项目还在用 SVNGit 和它的核心差异值得多说几句。对比项GitSVN架构分布式每人本地都有完整历史集中式历史只在中央服务器离线能力提交、分支、回滚全部本地完成提交必须连服务器分支成本极低创建切换开分支几乎无压力分支目录复制成本高大家习惯不开分支速度本地操作极快远程操作依赖网络学习曲线概念多上手偏陡简单直观但后期处处受限用生活类比的话SVN 像是大家共用一台公共电脑谁改都要联网上去改网络一断就啥也干不了。Git 像是每个人手里都有整台电脑的完整备份你离线改完有空了再把修改同步给别人。分布式带来的自由度是 Git 这些年成为主流的根本原因。2. 环境准备三平台安装与初始化配置一步不踩坑2.1 各平台 Git 安装指南Windows 安装 Git 最常规的方式是下载官方安装包。官网地址我不用背搜索引擎搜 Git for Windows 就能找到。不过官网在部分地区下载速度不稳定国内一般也有镜像站下载速度会快很多。看到2.4x.x这类版本号直接拿新版本对存储格式和性能都有优化别抱着老版本不撒手。安装向导里的选项多数保持默认即可。有两个地方我会特地改一下PATH 环境变量建议选 Use Git from the Windows Command Prompt这样你在 PowerShell 或 CMD 里也能直接敲git而不只是 Git Bash 里能用。行尾转换建议选 Checkout as-is, commit as-is。这个选项关系到换行符问题后面第五章还会细讲现在先记住这个选项能省掉一堆莫名其妙的警告。macOS 用户如果有 Homebrew一行brew install git就完事懒一点装官方 dmg 也行。Linux 用户更简单Debian/Ubuntu 系用sudo apt install gitCentOS/RHEL 系用sudo yum install git。装完统一验证git --version如果输出类似git version 2.4x.x.windows.1这样的内容说明安装成功。2.2 安装后的三件套配置安装完不等于能用了。第一次真正提交代码之前必须告诉 Git 你是谁否则 commit 会直接拒绝执行。需要配置的是一个用户名和邮箱git config --global user.name 你的名字 git config --global user.email youexample.com这个--global的意思是对当前电脑上的所有仓库生效。如果你某个项目要用不同身份比如公司项目和个人项目分开可以在那个项目的目录下不带--global再执行一次只覆盖当前仓库。我还会顺手刷两个配置git config --global init.defaultBranch main git config --global core.autocrlf input第一个把默认分支名从master改成main现在新项目基本都统一用main了省得后面还要手动改。第二个是行尾符的全局兜底策略同样是为了避开换行符警告。查配置用git config --list能把你所有的设置一次列出来改错了就重复执行对应项覆盖。2.3 SSH 密钥与免密登录热词里有一堆git 免密git 配置 gitee 密钥这是每个连远程仓库的人都会碰到的事。远程仓库平台常见的有 Gitee、GitHub、GitLab 等免密方式主流有两种SSH 密钥和HTTPS 凭据缓存。SSH 方式是我的首选一次配置长期省心。先生成密钥ssh-keygen -t ed25519 -C 你的邮箱一路回车就行生成的公钥默认在用户目录下的.ssh/id_ed25519.pub。然后用文本编辑器打开这个 pub 文件把内容复制到 Gitee 或 GitHub 的SSH 公钥设置里。测试连通性ssh -T gitgitee.com看到提示successfully authenticated之类的字样就代表通了。之后git clone尽量用仓库提供的 SSH 地址形如gitgitee.com:用户名/项目名.git推送拉取全程不再输密码。如果坚持用 HTTPS 地址Windows 上一般会弹出凭据管理器记忆密码Linux 上可以启用缓存git config --global credential.helper cache这个方式有时间限制缓存过期还得再输一次。长期用还是 SSH 省心。2.4 配置验证与常见坑配置完建议做一次体检git config --list git config user.name git config user.email每一条都能正常输出就说明 Git 的环境部分没有问题了。这里有个高频坑注册 SSH 密钥后测试仍然提示Permission denied (publickey)。八成原因是密钥没注册对或者注册的和你当前电脑生成的不是同一份公钥。检查思路很简单确认.pub文件内容和平台里粘贴的是完全一致的换行符和多余空格都会导致失败。另一个可能是你指定了自定义密钥文件名那么需要额外配置~/.ssh/config把密钥路径指给 Git新手遇到这种情况直接删掉重新生成一份默认名字的最省事。3. 日常基本操作从 git init 到 commit --amend3.1 初始化仓库与首次提交环境搞定接下来真正上手。在准备管理的项目根目录执行git init执行完你会发现目录里多了一个.git文件夹这就是仓库的档案室所有历史记录都存在这里面。注意这个目录平时不需要进去也别随便删删了等于毁掉全部历史。第一次提交我的习惯是先建一个 README再建一个.gitignore下面会讲然后走一遍完整流程git add README.md git commit -m feat: init project看到输出里有1 file changed和一行短哈希说明第一个存档已经生成。以后每完成一个功能点、每修完一个 bug都可以用同样的路径去做一次提交。有个小点值得提一下现在默认分支名如果是maingit init后你可以用git branch -m main在旧版本上改过来。代码的第一次提交质量不高没关系重点是养成小步提交的习惯每次提交只包含一个逻辑完整的改动和写文章分段是一个道理。3.2 暂存区add 的三种姿势与撤销很多新手对git add的理解是把改动存起来这个理解不对。它更像是在购物车面前挑货你先把要买单的商品一个一个放进购物车最后git commit才是统一付款。git add的常见姿势有三类git add . # 添加当前目录所有改动到暂存区 git add -u # 只添加已跟踪文件的修改和删除不添加新文件 git add -A # 所有改动包括新文件、已跟踪文件的修改、删除这里有个真实教训git add .看起来省事但会把不该提交的临时文件、日志文件、本地方案文档全都加进去。建议项目一开始就配置好.gitignore把node_modules/、target/、.idea/、*.log这类东西全部排除掉否则一次误操作就能把几百 MB 的依赖包推上远程仓库。加错了也有后悔药git reset HEAD 文件名 # 把文件从暂存区撤回来 git restore --staged 文件名 # 新版 Git 推荐的等价命令撤回之后工作区里的文件还在只是不参与这一次的 commit 了。3.3 日志查看与版本回退存档已经拍了想回顾历史就用 loggit log --oneline git log --oneline --graph --all --decorate第一条能看简洁的提交历史第二条能把分支走向画成 ASCII 图是所有排查历史问题的利器。我每次想搞清楚这个分支到底长了什么样都会先跑后面这条命令。回退是 Git 最让人有安全感的功能git reset有不同的模式git reset --soft HEAD~1 # 撤销最近一次提交改动保留在暂存区 git reset --mixed HEAD~1 # 撤销提交和暂存改动留在工作区 git reset --hard HEAD~1 # 彻底撤销提交和本地改动改动直接丢失--hard就好比把存档覆盖成更早之前的状态谨慎用因为工作区里新的修改会全部消失。进入--hard前先git status看清楚有没有没保存的改动也可以先git stash把当前改动推到一边。如果你要撤销的不是最近一次提交而是中间某次已经推送到远程的提交git reset不是好选择。用git revert生成一个反向的新提交历史不会被改写远程仓库也能安全接受git revert HEAD # 生成一次反向提交撤销上一步的改动关于回退我的建议是本地没推过的提交随便 reset已经推给别人的提交老老实实用 revert。3.4 修改提交信息git commit --amend热搜词里有git commit --amend怎么使用这里单独讲讲。--amend的作用是修改最近一次提交两个高频场景场景一提交信息写错了想改提交说明。git commit --amend -m fix: correct typo in config场景二提交时漏掉了一个文件想补进同一个提交里。git add 漏掉的文件 git commit --amend --no-edit--no-edit表示保留原有的提交信息只把新文件补进去。这个操作非常顺手我每次发现刚提交完就漏了一个文件都是这个流程。但有一条红线必须说清楚--amend本质是一次改写历史的操作它会生成一个新的提交对象来替代旧的。如果你提交的内容已经推到远程、别人已经基于它开始工作了这时候再 amend 会让两边历史对不上别人 pull 的时候直接冲突。所以只能对还没推送的提交使用 amend推送过的请另开一个新提交。4. 分支管理与协作开发合并、推送、现场保护4.1 分支是什么常用命令怎么记分支这个概念我形象地解释过很多次它像平行宇宙。你在main分支上开发的稳定版同时拉出来一个feature分支去尝试新功能两边互不干扰等新功能验证通过了再把feature宇宙合并回main宇宙。常用命令git branch # 查看所有本地分支 git branch feature/new-page # 创建新分支 git switch feature/new-page # 切换到已有分支 git switch -c feature/new-page # 创建并切换最常用 git branch -d feature/new-page # 删除已合并的分支分支名我用得比较多的是feature/前缀加上描述比如feature/login-page、fix/payment-bug一眼就知道这个分支在干什么。配合 IDE 的话现在 IntelliJ IDEA 和 VSCode 对分支操作都做了图形化支持点几下鼠标就能创建和切换但命令行依然是排查问题和理解底层的最可靠手段。切分支前养成的习惯先git status看一眼工作区干不干净。工作区有未提交的改动时直接切分支如果没有冲突 Git 会带过去但为了心理安全感我通常先把改动提交或 stash。4.2 合并与冲突处理合并分支用的是git switch main git merge feature/new-page如果main在这段时间没有任何新提交Git 会把分支直接往前移动这叫 fast-forward 合并历史是一条直线。如果两边都有新提交Git 就会生成一次新的合并提交把两条历史接起来。冲突是合并的常态不必害怕。冲突发生时 Git 会在冲突文件里写上特殊标记 HEAD 当前分支的内容 被合并分支的内容 feature/new-page说白了就是 Git 把它们两个分支在这同一个位置各改了各的没法自己判断留哪个。你需要打开文件把冲突标记和不要的内容删掉留下最终想要的版本。然后git add 冲突文件 git commit -m merge: resolve conflict整个过程不难难的是心理上接受冲突不是灾难而是流程必经的一段。合完发现不对想反悔可以用git merge --abort回到合并前状态前提是还没有提交。还有一种合并思路是 rebase它会把当前分支的提交拔掉再挪到目标分支的最新位置历史更干净。但它的风险在于同样改写历史新手阶段不建议在公共分支上使用先熟练 merge 再说。4.3 远程仓库协作push、pull、fetch本地玩的再花最终都要和远程仓库交互。关联一个远程地址git remote add origin gitgitee.com:用户名/项目名.gitorigin是默认的远程仓库别名你可以改成别的名字但业界习惯就是这个。推送和拉取的命令姿势git push -u origin main # 首次推送-u 记住关联关系 git push # 后续推送 git pull # 拉取远程最新代码并合并到当前分支 git fetch origin # 只拉取远程更新不自动合并fetch和pull的区别一定要分清。pull是fetch加merge两步合一快捷但有副作用如果你当前分支有大量未提交或本地新提交自动合并经常会引发冲突。我自己的习惯是先用fetch再用git log origin/main..main之类的命令看清差距心里有数了再决定 merge 还是 rebase。协作中常见的推送失败信息是non-fast-forward意思是远程有别人已经提交的代码你本地的仓库落后了。处理流程先git pull拉下来合并冲突解决完冲突再推送。4.4 现场保护git stash 的用法还有一个基本操作特别容易被忽略就是 stash。它的价值在于工作区改到一半突然有急事要切分支。比如你正在feature-a写着登录功能线上突然报了个 bug必须马上切到main去修。直接切分支工作区里的改动会被带过去混在一起很危险不切又没法解决问题。这时候 stash 就像把你的半成品推到仓库的临时储物间git stash push -u -m wip login page # -u 连未跟踪的新文件一起藏起来 git stash list # 查看储物间有啥 git stash pop # 恢复最近一次藏起来的改动 git stash drop stash{0} # 丢掉不要的存档我自己的习惯是切换分支前如果工作区不干净一律先 stash清清爽爽切过去。等回到原分支再stash pop恢复半成品原模原样还在。很多人把 stash 当高级技巧其实它就是临时存草稿是很基础必备的能力。5. 疑难杂症速查fatal、凭证、clone 与换行符5.1 fatal: not a git repository 的成因与解决热搜词里躺着这条报错说明踩的人很多。出现它的原因九成是在当前目录执行 git 命令但这个目录本身没有被git init也没有任何一个父目录是 Git 仓库。排查顺序执行pwd看自己在哪。执行ls -a看当前目录有没有.git。往上级目录走找到真正的仓库根目录再执行 git 命令。还有一种隐蔽情况是 IDE 的项目根目录和实际仓库根目录不一致。比如在 IntelliJ 里打开的是子文件夹Terminal 默认位置在子文件夹里直接敲 git 就会报这个错。解决方式是切换到项目根目录或者检查.git文件是否因为特殊操作被误删。补充一点如果看到fatal: not a git repository (or any of the parent directories): .git的完整版后面那句话就是在提示你往上找也没找到仓库不用慌路径问题而已。5.2 账号密码清除与凭证管理换电脑、换账号、改了密码之后Git 缓存着旧凭据就会一直报认证失败。清除凭证的路径分平台Windows 上最简单粗暴的方法是打开系统凭据管理器在 Windows 凭据里找到git:https://gitee.com或git:https://github.com这类条目直接删除。下次访问远程仓库时会重新弹出登录窗口输入新账号密码即可。命令行方式也有git config --global --unset credential.helper git config --system --unset credential.helper如果用过 Git Credential Manager可以在终端执行git credential-manager uninstall之类的命令移除。我踩过这个场景的坑之后干脆统一改用 SSH 方式彻底告别账号密码轮换带来的认证问题。5.3 clone 与 TLS 相关报错git clone报错的场景千奇百怪常见的两类一类是fatal: unable to access后面跟着目标地址。优先确认仓库地址有没有拼错、用户名带没带对。我遇到这个报错时脑子里第一个念头就是先浏览器打开这个地址看能不能访问这比盯着终端瞎猜效率高得多。企业内网环境下有时需要走内网 GitLab 地址公网地址自然连不通。另一类是各种 OpenSSL 或 TLS 报错SSL certificate problem或error setting certificate verify locations。这一类多数是网络环境里的安全软件或网关设备造成的也可能是本机证书库出问题。我的建议是先换网络环境试一次如果公网直连正常说明钥匙和锁的问题出在外层设备如果依旧报错检查系统时间是否准确证书校验对时间非常敏感。操作上不建议通过关闭证书校验来绕过问题那等于把门锁拆了隐患太大。5.4 换行符警示LF 和 CRLF 的战争Windows 上第一次提交时你大概率见过这种警告warning: LF will be replaced by CRLF这不是错误是 Git 在提示你换行符不统一。Windows 习惯用 CRLF回车加换行Linux/macOS 习惯用 LF只有换行。Git 在 checkout 和 commit 时会按照配置做转换转换过程就会冒出这种警告。处理思路是团队统一策略。我的建议是团队用一个.gitattributes文件钉死规则比每个人各自调core.autocrlf靠谱得多。比如* textauto *.sh text eollf *.bat text eolcrlf* textauto让 Git 自动判断哪些是文本文件对纯文本统一按 LF 存入仓库。这块比较冷门但一旦团队跨 Windows 和 macOS 协作这是少数的一劳永逸解法。5.5 多目录并行git worktree 的另类用途热词里有git worktree这个不算基本操作但常用场景下特别好用。它允许一个仓库同时拥有多个工作目录每个目录可以检出不同的分支。比如我手头有一个仓库main分支线上要紧急修 bugfeature分支的功能正开发到一半。我既不想把 main 合进 feature又不想把 feature 的改动挪来挪去。这时候git worktree add ../hotfix -b hotfix/urget-fix就会在仓库相邻的hotfix目录里拉出一棵新工作树默认检出新分支hotfix/urget-fix。我可以在主目录继续写 feature在hotfix目录里修线上问题两不耽误还能各自 add、commit、push。用完记得清理git worktree list git worktree remove ../hotfix git worktree prune注意一点同一个分支不能同时被多个工作目录检出Git 会直接拒绝。worktree 更适合那种一个仓库要多线并行的场景日常小项目用不上但知道有这个东西遇到场景不会抓瞎。5.6 误删、误提交的补救方案Git 最让人安心的一点是它默认不会轻易销毁历史误删了文件、误提了敏感信息都有补救路线。误删工作区文件还没提交git checkout -- 文件名 git restore 文件名误删后已经提交过直接从历史里拿回来git checkout HEAD~1 -- 文件名reset --hard 之后发现想找回被丢弃的提交用git reflog查看所有分支的移动历史找到那个提交的哈希然后以它为准创建分支捡回来git reflog git branch recover-branch 哈希值reflog 是我的后悔药之王几乎可以说只要 Git 仓库里发生过的事总有办法翻回来。误提交了敏感信息比如密码、密钥文件要是还没推远程直接--amend或者 reset 掉即可已经推了远程需要改写历史可以用 filter-repo 或 BFG 这类工具再配合强制推送。但这条链路比较长而且 push 之后别人可能已经拉取过敏感数据所以最好的策略永远是提交前的.gitignore和提交时的自查而不是提交后的补救。最后分享一个实测心得这篇文章里的命令我全部在 Windows 和 macOS 上实测过Windows 环境下推荐优先使用 Git BashPowerShell 在部分命令上有引号和编码的小坑。我个人现在拿到任何新项目第一件事永远是git init、建一个靠谱的.gitignore、写一个像样的 README再完成第一次提交。很多新手最容易犯的毛病是把 Git 当成上传工具经常稀里糊涂地改了文件就往远程推。实际上 Git 是一个完整的历史管理工具提交、分支、stash、reflog 这些基础能力练扎实了后面看什么高级玩法都不慌。最后再送一个我自己反复使用的习惯——在需要做危险操作reset --hard、push -f之前先花三十秒看一眼git status和git log --oneline -3这个小小的自查动作帮我躲掉了至少五六次本可以避免的灾难。