简介一份面向Git入门者的本地仓库操作学习文档适配备开发者、计算机专业学生以及刚接触版本控制工具的初学者。文档从Git的分布式架构、SHA-1数据完整性等核心概念切入与SVN集中式版本控制系统展开对比帮助读者理解为何Git更适合并行开发与团队协作。随后围绕本地仓库高频操作展开分步骤讲解git init初始化仓库、git config全局配置用户信息、git add添加暂存、git commit创建提交等命令每个环节都有命令行示例和逐行解释便于读者边看边练、快速建立操作流程感。资源包内包含1个docx文件整体大小约26KB内容以文字讲解和代码示例为主小巧轻量可随时打开查阅。截至目前已有114人学习下载适合作为自学笔记、课堂补充材料或日常查阅的速查参考。1. Git 初始化与本地仓库操作这份文档能帮你把「乱糟糟的目录」变成「可回溯的工程」Git 入门最容易踩的坑不是命令记不住而是把 Git 当网盘用——只知道 push 和 pull本地仓库里到底发生了什么完全是个黑匣子。这份《Git初始化与本地仓库操作》文档恰恰是把最容易被忽略的本地动作拆开讲透从git init那一刻起目录如何被 Git 接管文件如何进入暂存区分支怎么切怎么合以及误操作之后怎么吃后悔药。它面向的是刚开始接触 Git 的 Web 开发者和想系统补一遍 Git 基础的一线从业者。文档不绕弯子直接对着命令行讲你照着敲一遍就能把本地仓库的整套操作串起来。接下来我把文档里的关键节点和实际执行时容易翻车的地方逐一拆给你看。2. 先把 Git 装对三平台安装与全局配置的细节2.1 三平台安装方式与安装后的第一道验证无论是 Windows、macOS 还是 Linux装 Git 这件事本身不难难的是装完之后的验证和路径习惯。Windows 用户我一般建议直接去 Git 官网下载安装包安装时注意几个选项默认编辑器选 Notepad 或 VS Code 都行但别选 vi——新手在 vi 里退出都能折腾十分钟PATH 环境变量那一项务必选「Git from the command line and also from 3rd-party software」否则后面在 VS Code 终端里敲git会提示找不到命令换行符转换那一项先选默认的Checkout Windows-style, commit Unix-style line endings这个选项后面会引出 CRLF 的经典玄学但初期按默认走问题最小。macOS 用户分两种情况装了 Homebrew 的brew install git一行搞定没装 Homebrew 的直接装 Xcode Command Line Toolsxcode-select --install会连带把 Git 装上。Linux 用户更简单apt install git或yum install git按发行版来。装完第一件事不是急着git init而是验证安装结果git --version which git git config --list --system第一行确认版本号第二行确认 Git 可执行文件的路径第三行看系统级配置是否正常加载。如果在 Windows 上which git指向了某个奇怪的路径多半是安装时 PATH 选项没选对。这三条命令跑完没问题再进入下一步配置。很多新手跳过验证直接配 SSH结果后面git clone时报错排查半天发现是 Git 本身没装干净这种低级翻车完全可以用 10 秒钟避免。2.2 全局配置user.name、user.email 与换行符策略Git 提交记录里每一行都带着作者信息这个信息来自user.name和user.email两个配置项。不配的话提交时会报Please tell me who you are的错误。配置命令是三条git config --global user.name 你的名字 git config --global user.email 你的邮箱 git config --global core.autocrlf input第一条和第二条很好理解写你自己的名字和邮箱。第三条core.autocrlf是换行符处理策略Windows 上建议设为truemacOS 和 Linux 上建议设为input。原因在于 Windows 用 CRLF 换行Unix 系用 LF 换行如果混用团队协作时每次 diff 都会把整个文件标记为修改——你只改了一行代码Git 却认为你动了全文件这就是 CRLF 乱象的根源。true的意思是检出时转 CRLF、提交时转 LFinput的意思是检出时不动、提交时转 LF。配置完成后建议立刻验证一下git config --global --list这条命令会列出所有全局配置确认三项都写进去了再继续。这里是配置 Git 的「开源」基础后面所有提交记录都靠它背书。配置错了也不可怕git config --global --replace-all user.name 新名字随时能改但如果一个仓库已经产生了提交记录改配置只影响后续提交历史提交里的作者信息不会变。SSH 密钥配置属于「一次性配置、长期受益」的部分。ssh-keygen -t ed25519 -C 你的邮箱生成密钥对然后cat ~/.ssh/id_ed25519.pub查看公钥内容复制到代码托管平台的 SSH Keys 设置里。这就是常说的 Git 免密配置——配好之后 clone 和 push 都不用再输密码。密钥生成后可以用ssh -T gitgithub.com测试连通性看到Hi xxx! Youve successfully authenticated就说明通了。这一步配好后面操作本地仓库时就不用反复输密码了。3. git init 到首次提交把普通目录变成可回溯的仓库3.1 git init 的默认分支与初始化后的目录结构git init是一条看起来简单、实际上有不少隐藏细节的命令。执行它之后当前目录下会生成一个.git子目录这个目录里装着仓库的全部元数据对象库、索引、分支引用、配置、日志。很多新手会问这个.git目录能不能删答案是不能——删了它仓库历史就全没了。常见的做法是项目根目录执行git init然后ls -a查看你会看到.git目录安静地躺在那里。默认分支名是初始化时的一个关键选择。Git 新版2.28 以上默认分支名是master但很多代码托管平台已经把默认分支改成了main。我一般会在git init之后立刻执行git init git branch -m main git status第一行初始化仓库第二行把当前分支改名为main第三行查看当前状态。为什么要改因为现在新建仓库如果不改名后续 push 到 GitHub 或 Gitee 时远端默认分支是main本地却是master第一次推送就得手动指定git push -u origin main多一步操作不说还容易在分支名上造成混淆。如果你更习惯master也可以不改但团队协作时最好和远端保持一致。初始化之后还有一个容易被忽略的细节git init本身不会把任何文件加入版本管理它只是创建了仓库骨架。此时git status会显示所有项目文件都是未跟踪状态。这符合 Git 的设计哲学——仓库只跟踪你明确git add过的文件。有些新手以为 init 完就万事大吉了直接改文件结果 Git 没有任何反应其实是文件从未被跟踪过。3.2 首次提交的完整动作add、commit 与 .gitignore首次提交是每个 Git 用户都要走通的第一条完整链路。标准动作是git add . git status git commit -m feat: init projectgit add .把当前目录下所有未被忽略的文件加入暂存区git status确认哪些文件被暂存了git commit把暂存区内容固化成一次提交。这里有个很多人不理解的误区git add .不是「保存文件」而是「把文件标记为将要提交」。你改了一个文件必须重新git add再git commit这个文件的新版本才会进入历史记录。如果只改了文件不 addcommit 时 Git 会提示nothing to commit——你以为提交了其实没有。.gitignore文件应该在首次提交之前就写好。常见的 Web 项目里node_modules、dist、.env这些目录和文件绝对不能进版本库。node_modules几万个文件提交进去仓库体积直接爆炸.env里是密钥和数据库地址提交上去等于把密码公之于众。我的习惯是在git init之后立刻创建.gitignorenode_modules/ dist/ .env *.log .DS_Store每行一个忽略模式node_modules/带斜杠表示只忽略目录*.log匹配所有日志文件。.gitignore自己也要提交进仓库这样团队每个人拉下来都有同样的忽略规则。写完之后用git status验证确认node_modules没有出现在未跟踪列表里再执行 add 和 commit。首次提交的意义在于给项目打一个「起点基线」。之后任何改动、任何回滚都是相对于这个基线的差异。没有首次提交的仓库git log是空的各种回滚操作全都无从谈起。所以第一次提交不要急着git add .一把梭先把该忽略的忽略掉再执行提交——这一步的认真程度直接决定后面仓库的干净程度。4. 本地分支与历史回滚reset、revert、amend 的选择题4.1 分支的创建、切换与合并分支是 Git 本地仓库操作里最核心也最容易出问题的部分。刚初始化完的仓库只有一条主干分支日常开发时我习惯为每个功能单独拉一条分支git branch feature/login git checkout feature/login git branch第一行创建分支第二行切换过去第三行列出全部分支并高亮当前分支。也可以直接用git checkout -b feature/login一条命令完成创建加切换。分支的本质是一个指向某次提交的指针创建分支的代价几乎为零所以好的习惯是「一个功能一条分支」不要在主分支上直接改代码。合并分支时常见做法是git mergegit checkout main git merge feature/login先切回主分支再执行合并。如果两个分支各自修改了不同的文件Git 会自动合并不会打扰你如果修改了同一文件的同一处就会产生冲突。冲突文件里会插入、、标记手动编辑保留需要的部分然后重新 add 和 commit 即可完成合并。这里有一个血泪经验合并前先git status确认工作区是干净的否则合并时容易把未提交的改动卷进冲突里处理起来非常被动。4.2 回滚三兄弟git reset、git revert 与 git commit --amend本地仓库操作里回滚是最考验理解深度的一环。三个命令解决三类不同的问题选错就翻车。git reset用于撤销提交它有三种模式见下表模式作用范围HEAD 移动暂存区工作区--soft撤销 commit保留 add 结果是保留保留--mixed默认撤销 commit 和 add是清空保留--hard完全回退是清空清空git reset --soft HEAD~1是撤销最近一次提交但保留代码改动git reset --hard HEAD~1是把代码完全回退到上一次提交的状态。这里要特别强调--hard会丢弃工作区的所有未提交改动执行前必须确认这些改动确实不需要了否则后悔药都吃不上。我见过不止一个人git reset --hard之后发现改的代码全没了整晚都在用数据恢复工具找文件。git revert的语义和 reset 完全不同。reset 是「把历史抹掉」revert 是「生成一次反向提交来抵消历史」。协作分支上永远用 revert 而不是 reset因为 reset 会改写历史别人的本地仓库同步时会产生分叉。revert 的命令是git revert HEAD~1它会生成一个新的提交内容和被撤销的提交相反历史记录里保留两条提交痕迹。代价是历史看起来多了几条记录但协作安全性高得多。git commit --amend是修改最近一次提交信息的命令。本地提交完发现注释写错了或者漏了一个文件用这个命令git add 漏掉的文件 git commit --amend -m 修正后的提交注释它把当前暂存区的内容和上一次提交合并成一次新提交替换掉原来的记录。注意--amend同样会改写历史所以只能用在还没推送的本地提交上。已经 push 到远端的提交再用 amend 会产生和远端不一致的提交下次 push 就会被拒绝这种场景下应该用新的提交来修正而不是 amend。本地回滚还有一类「后悔药」场景是撤销 add 但保留改动git reset HEAD 文件名可以做到。还有git checkout -- 文件名可以把工作区某个文件恢复到最近一次提交的状态。这两个命令解决的是「还没 commit 但想反悔」的情况配合git status的提示操作基本不会出错。5. 本地仓库高频翻车五个现象与对应的排查思路5.1 git clone 连不上 127.0.0.1:7890网络设置残留现象执行git clone报错failed to connect to 127.0.0.1 port 7890: Connection refused看起来 Git 在尝试连接本机某个端口但那个端口根本没有服务在监听。原因系统网络设置或 Git 配置里残留了一条指向本机 127.0.0.1:7890 的端口转发规则但对应的本地转发软件并没有运行。Git 通过这条规则去连远端结果端口拒绝连接。这是典型的「本地环境配置残留」问题多半是之前装过某个网络工具后卸载不干净或者环境变量里还留着它的设置。还有一种可能是git config --global http.proxy里被手动写过这条地址。解决先执行git config --global --list | grep -i proxy查看有没有代理相关配置如果有就用git config --global --unset http.proxy和git config --global --unset https.proxy删掉。如果没有检查系统环境变量里的HTTP_PROXY和HTTPS_PROXYWindows 上可以在「系统属性 → 环境变量」里看macOS/Linux 上在~/.bashrc或~/.zshrc里搜。确认没有残留后重新执行 clone 就正常了。这个问题和 Git 本身的配置无关纯粹是网络环境没收拾干净排查思路是「先看 Git 配置再看系统环境变量」。5.2 CRLF 警告刷屏换行符规则没定好现象提交或检出时终端反复出现warning: LF will be replaced by CRLF或反向警告文件内容没变但 diff 显示整个文件都变了。原因Git 的换行符自动转换规则和仓库里已有的换行符不一致。Windows 上core.autocrlf设为true但仓库里某些文件是 LF 换行Git 检出时把它转成 CRLF提交时又打算转回 LF于是每次都提示。更麻烦的是如果团队有人用 Windows、有人用 macOS规则不统一每次切换平台都会触发大规模 diff。解决统一规则在项目根目录添加.gitattributes文件并提交进仓库* textauto *.js text eollf *.json text eollf *.md text eollf这段配置的含义是所有文本文件按自动检测处理JavaScript、JSON、Markdown 文件强制使用 LF 换行。配置之后Windows 用户检出时依然会拿到 CRLF如果core.autocrlftrue但提交时全部转成 LFdiff 就干净了。.gitattributes进仓库后历史遗留的换行符问题可以用git add --renormalize .批量修正一次。这个问题的本质是规则没提前定修起来不难但需要全团队统一。5.3 git open /dev/null or dup failed现象在 IDE 或终端里执行 Git 操作时报git open /dev/null or dup failed: No such file or directory有时候伴随error: cannot open /dev/null。原因这通常是 Git 在 Windows 上运行时找不到/dev/null设备常见于安装了某些终端模拟器或 IDE 集成的 Git 环境路径映射没做好。还有一个诱因是系统临时目录权限不对Git 无法在临时目录里创建管道文件。解决先确认是不是终端环境的问题。如果在 Windows 自带的 cmd 里正常执行 Git 命令但在某个第三方终端里报错那就是终端的环境变量TMP和TEMP指向了一个不存在或没权限的目录。Windows 上检查环境变量 → 系统变量 → TMP/TEMP确保指向的目录存在且有写权限。另外有一种可能性是杀毒软件拦截了 Git 对临时文件的创建把 Git 的可执行目录加入白名单试试。这个问题比较玄但核心排查路径就两条终端环境变量和系统临时目录权限。5.4 .gitignore 不生效文件已经被跟踪现象在.gitignore里写了node_modules/但git status里依然显示node_modules下的文件被跟踪或者git add .还是把它们加进去了。原因.gitignore只对未被跟踪的文件生效。如果某个文件在.gitignore被创建之前就已经通过git add进入了暂存区甚至提交进了仓库Git 会一直跟踪它忽略规则对它无效。这是 Git 新手最容易踩的坑把.gitignore当成「不想提交的文件清单」实际上它是「请 Git 不要跟踪这些文件的清单」且只在首次 add 之前有约束力。解决如果文件已经被跟踪先把它从 Git 索引中移除但保留在磁盘上git rm -r --cached node_modules git commit -m chore: remove node_modules from git tracking--cached表示只从索引中移除不删除物理文件。执行完这次提交之后.gitignore里的规则就对node_modules生效了。如果文件还没提交过只是被 add 了git reset就能解决。之后新增的文件只要符合忽略规则就不会再被跟踪。这是 .gitignore 的边界问题理解了「跟踪状态」这个前提就不会再被坑。5.5 .git 目录被提交到远端仓库信息泄露现象项目里有隐藏的.git目录执行git add .时把整个.git目录一并提交了push 到远端后别人可以下载到你的完整仓库元数据。原因正常来说git add .不会把当前仓库的.git目录加进去因为 Git 会自动忽略自身元数据目录。但有一种情况例外你在一个嵌套目录里执行了git init而这个嵌套目录位于另一个 Git 仓库的内部——此时外层仓库会把内层仓库的.git目录当作普通文件跟踪起来。另外如果在仓库目录里手动把.git复制到别的位置再 add也会触发这个问题。解决如果只是本地刚 add 还没提交git rm -r --cached .git就能脱险。如果已经提交并且推送到了远端需要git rm -r --cached .git echo .git .gitignore git commit -m chore: remove .git from tracking git push这三步分别是把.git移出索引、把.git加入忽略规则、提交并推送。注意历史提交记录里的.git目录并没有被抹掉需要重写历史才能彻底清除但至少当前版本的仓库是干净的。这个问题的本质是「嵌套仓库」的边界认知不清我的建议是避免在已有 Git 仓库的目录内再执行git init环境初始化时先规划好仓库边界。6. 让本地仓库更好用commit 规范与 Git 别名的一次性配置本地仓库操作熟练之后真正拉开效率差距的是提交规范和命令别名。提交信息写得好不好直接影响后面git log和git blame的可读性。我常用的提交格式是类型前缀加简述feat:表示新功能fix:表示修 bugchore:表示构建或工具改动docs:表示文档变更refactor:表示重构。这种规范的好处是git log --oneline扫一眼就能知道这次提交做了什么回滚定位到具体功能点时效率会高很多。文档里也提到了提交规范的重要性实际执行时可以在仓库根目录创建.git/COMMIT_EDITMSG模板但更轻量的做法是记住几个前缀每次提交时自觉带上。Git 别名是另一个值得一次性配置的项目。经常敲的命令用别名替代手腕能省不少力气。我配置了这么几条git config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.cm commit -m git config --global alias.lg log --oneline --graph --all --decorate配置之后git st就是git statusgit cm 提交说明就是git commit -m 提交说明git lg能以图形化方式查看分支合并历史。别名配置在~/.gitconfig文件里随时可以编辑调整。这套配置的验证方式很简单执行git lg看提交历史是否以树状图展示执行git st看状态是否正常显示。如果别名不生效检查是否写进了[alias]段以及有没有被仓库级配置覆盖。验证本地仓库是否健康的最终手段是一组组合命令git status git log --oneline -5 git branch -a git remote -v第一条看工作区状态第二条看最近五条提交记录第三条看所有分支第四条看远端地址如果有的话。四条命令全部输出正常说明仓库的基本健康度没问题。从那以后我每次接手一个新项目第一件事就是跑这组命令先摸清仓库的状态再动手改代码——这个习惯帮我避开了无数次因为分支混乱、提交记录缺失而导致的低级事故。希望这篇拆解能帮你在本地仓库操作上少走几步弯路。本文还有配套的精品资源点击获取