简介：一份面向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 Tools，xcode-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 上建议设为true，macOS 和 Linux 上建议设为input。原因在于 Windows 用 CRLF 换行，Unix 系用 LF 换行，如果混用，团队协作时每次 diff 都会把整个文件标记为修改——你只改了一行代码，Git 却认为你动了全文件，这就是 CRLF 乱象的根源。true的意思是检出时转 CRLF、提交时转 LF，input的意思是检出时不动、提交时转 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 git@github.com测试连通性，看到Hi xxx! You've 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 project"git add .把当前目录下所有未被忽略的文件加入暂存区，git status确认哪些文件被暂存了，git commit把暂存区内容固化成一次提交。这里有个很多人不理解的误区：git add .不是「保存文件」，而是「把文件标记为将要提交」。你改了一个文件，必须重新git add再git commit，这个文件的新版本才会进入历史记录。如果只改了文件不 add，commit 时 Git 会提示nothing to commit——你以为提交了，其实没有。
.gitignore文件应该在首次提交之前就写好。常见的 Web 项目里，node_modules、dist、.env这些目录和文件绝对不能进版本库。node_modules几万个文件提交进去，仓库体积直接爆炸；.env里是密钥和数据库地址，提交上去等于把密码公之于众。我的习惯是在git init之后立刻创建.gitignore：
node_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 merge：
git 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_PROXY，Windows 上可以在「系统属性 → 环境变量」里看，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文件并提交进仓库：
* text=auto *.js text eol=lf *.json text eol=lf *.md text eol=lf这段配置的含义是：所有文本文件按自动检测处理，JavaScript、JSON、Markdown 文件强制使用 LF 换行。配置之后，Windows 用户检出时依然会拿到 CRLF（如果core.autocrlf=true），但提交时全部转成 LF，diff 就干净了。.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:表示修 bug，chore:表示构建或工具改动，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 status，git cm "提交说明"就是git commit -m "提交说明"，git lg能以图形化方式查看分支合并历史。别名配置在~/.gitconfig文件里，随时可以编辑调整。这套配置的验证方式很简单：执行git lg看提交历史是否以树状图展示，执行git st看状态是否正常显示。如果别名不生效，检查是否写进了[alias]段，以及有没有被仓库级配置覆盖。
验证本地仓库是否健康的最终手段是一组组合命令：
git status git log --oneline -5 git branch -a git remote -v第一条看工作区状态，第二条看最近五条提交记录，第三条看所有分支，第四条看远端地址（如果有的话）。四条命令全部输出正常，说明仓库的基本健康度没问题。从那以后我每次接手一个新项目，第一件事就是跑这组命令，先摸清仓库的状态再动手改代码——这个习惯帮我避开了无数次因为分支混乱、提交记录缺失而导致的低级事故。希望这篇拆解能帮你在本地仓库操作上少走几步弯路。
本文还有配套的精品资源，点击获取
