写Git本地基础操作的文章标题本身看起来平淡但如果你真的在命令行里摸爬滚打过一段时间就会明白“本地”这两个字才是真正的主角。绝大多数新手一上来就急着搞远程仓库、SSH密钥、推代码结果本地分支乱成一团提交历史改得不成样子最后只能靠删仓库重新clone来“修复”。我也经历过那个阶段所以这篇文章不做面面俱到的Git百科就围绕日常开发里真正高频的本地操作把每个命令背后的逻辑讲清楚附上我踩过的坑和现在还在用的习惯。先介绍一下这篇文章能解决什么问题。无论你用的是Windows、macOS还是Linux只要想在本地用Git管理代码或者你已经在用但总被各种报错卡住这篇都适合你。内容从Git安装、初始化仓库、文件状态流转到分支合并、撤销回退最后聊几个常见但容易误导人的排查场景。看完之后你可以不看文档就能处理绝大多数本地开发场景。1. Git安装与初始配置第一道门槛没你想的那么顺1.1 各平台的安装方式和版本选择Git的安装在不同平台上体验差异挺大先说Windows。现在官方推荐的安装包是Git for Windows直接去官网下载64-bit版本就行。安装过程中有几个选项很多教程没说清楚我重点讲三个Adjust your PATH environment一定要选“Git from the command line and also from 3rd-party software”默认选项是“Use Git from Git Bash only”如果选了它你在CMD或PowerShell里敲git会提示找不到命令。Line ending conversions建议选“Checkout as-is, commit as-is”也就是不做换行符转换。默认的“Checkout Windows-style, commit Unix-style”容易导致整个项目的换行符被改来改去尤其在多人协作时会出现大量无意义的diff。Terminal emulator默认的MinTTY体验还行但如果你习惯用Windows Terminal选“Use Windows default console window”更舒服避免每次打开自带终端时窗口风格不一致。macOS这边如果你装了Homebrew一条命令的事情brew install git。如果你不想装Homebrew直接用官方安装包也可以但要注意macOS自带的Git版本可能比较老某些指令的行为和输出格式跟新版有差异。Linux用户直接走系统包管理器Ubuntu/Debian是sudo apt install gitCentOS/RHEL是sudo yum install git。安装完之后在终端输入git --version如果输出了版本号说明安装成功。没有输出的话先检查PATH配置再看看终端有没有重新打开——这点经常被忽略老的终端窗口里不会加载新安装的PATH。1.2 初始化必须做的两步配置很多人装完Git就急着干活结果第一次提交时看到一堆带颜色的英文报错最常见的就是Please tell me who you are. Run git config --global user.email youexample.comGit要求每个提交必须关联用户和邮箱这是提交记录里身份信息的来源。如果没配置Git会拒绝提交。所以安装之后第一件正事就是git config --global user.name 你的名字 git config --global user.email 你的邮箱这里用--global意味着这台机器上所有仓库都默认使用这个身份。如果某个项目需要单独身份可以去掉--global重新配置优先级上仓库级配置会覆盖全局配置。这个机制在区分个人项目和公司项目的提交身份时非常实用。配置完之后用git config --list确认一下或者直接查单个配置项git config --global user.name git config --global user.email还有几个配置项也建议顺手搞定。git config --global core.editor设置默认编辑器遇到需要输入多行提交信息时会用到git config --global init.defaultBranch main把默认分支名从master改成main避免后续每次都用-M重命名。我不是说master一定不好但新项目用main已经很普遍提前设好省一步操作。1.3 为什么全局配置和代理设置容易踩坑图片不少人不理解为什么git config还有http.proxy这类配置。当你所在网络环境需要代理才能访问某些资源时Git并不会自动读取系统代理需要手动指明。但本地操作和走HTTP协议拉取远程仓库时这个配置可能带来负面影响。如果你明确知道当前网络不需要代理但配置里残留了一些杂项设置常见表现就是clone或pull操作时一直卡住或SSL报错。遇到这种情况先检查配置而不是反复重装Git。git config --global --list看到http.proxy或https.proxy不在预期内可以删除它们git config --global --unset http.proxy git config --global --unset https.proxy这条排查经验我加粗强调一下绝大多数Git远程连接的诡异问题先查config再找网络问题顺序不要反。2. 仓库初始化与文件状态流转理解这三个区是省钱的关键2.1 git init只做了一半的工作git init这条命令在项目目录下执行会生成一个.git文件夹。很多人以为执行完这一步仓库就算建好了其实只完成了一半。.git目录内部保存的是对象库、引用、配置等核心数据你平时操作的其实是工作区里的文件它们还没有被Git跟踪。我第一次带新人的时候经常看到他们git init之后直接git commit -m init然后报错“nothing to commit”。这个流程没错但缺了最关键的一步git add。还有一部分人分不清git init和git clone的差异。git init是从零创建一个新的本地仓库git clone是把已有的远程仓库完整复制到本地。本地基础操作讨论的范围绝大部分场景是git init这条路线。建好仓库之后推荐立刻看一眼.git目录里有没有东西ls -la .git如果能看到HEAD、config、objects、refs这些文件和目录基本可以确认初始化成功。之前遇到过用户把git init跑到了错误的目录层级比如home目录下然后后续所有操作都在错误的仓库范围内进行。判断方法很简单git rev-parse --show-toplevel会输出仓库根目录路径如果输出不是你认为的项目根目录恭喜你仓库建错地方了。2.2 工作区、暂存区、版本库之间的关系Git本地有三个核心区域工作区、暂存区index/staging area、版本库repository。用一个生活化的类比工作区是你做饭的厨房所有菜料都摊在操作台上暂存区是已经洗好切好并装盘的部分版本库则是已经拍好照片的成品菜谱记录每按一次快门就是一个commit。工作区你当前目录里看到的文件可以被修改。暂存区通过git add把工作区的修改放进来表示“我准备要提交这些”。版本库通过git commit把暂存区内容永久记录成一个版本。这个设计的价值在于你可以对多个文件分别操作选择性地提交某些文件而不是一次把所有变动都扔进历史。比如你改了A文件修复bug、改了B文件加新功能就可以分两次提交让历史记录更清晰。这个习惯在后续回溯问题时能省大量时间。2.3 文件的四种状态转换Git官方把文件状态分成四类Untracked未跟踪新文件Git不知道它的存在。Modified已修改文件被改过但改动还没进暂存区。Staged已暂存改动已经加到暂存区等待被提交。Committed已提交改动已经写入版本库成为历史的一部分。同一个文件在不同阶段会呈现出不同状态。比如新建一个app.py用git status会看到它在Untracked列表里执行git add app.py后变成Staged执行git commit后git status就干净了。改一次app.py内容后状态又变成Modified但此时可能有两个app.py版本概念一个是暂存区里上次add的版本一个是工作区里最新修改的版本。这里有一个容易混淆的概念如果你修改了文件但没有git add然后又执行git commit提交的内容是暂存区里的版本不是工作区的最新版本。我在实操中见过有人连续改文件却不add最后commit完发现改动的文件根本没进提交就是这个原因。所以提交前养成git status和git diff --cached双重确认的习惯很重要。2.4 实战完成你的第一次本地提交还是用项目初始化来走一遍完整的流程mkdir my-project cd my-project git init echo # My Project README.md git add README.md git commit -m docs: init project with README这几条命令做完项目目录就有了第一个提交。用git log查看能看到类似这样的记录commit 3a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b (HEAD - main) Author: your name youexample.com Date: ...HEAD - main表示当前处于main分支的最新提交。这里多说一句HEAD是Git的指针它总是指向当前分支的最新提交。理解了HEAD的含义后续看分支切换和回退操作都会容易很多。3. 高频命令实战git status、log、diff的合理使用姿势3.1 git status不只是看有没有变化git status是最常被低估的命令。新手会觉得它无非就是显示“nothing to commit, working tree clean”或一堆红色文件名但它的输出其实包含了非常丰富的信息量。不带参数的git status显示的是简洁状态git status -s则用单行缩写显示每行一个文件左侧两个字符分别代表暂存区和工作区的状态。比如$ git status -s M README.md A new_file.txt ?? untracked_dir/M注意空格在M前面工作区有修改暂存区没有。AA在后面加空格已暂存的新文件。??未跟踪的文件。这个缩写模式在批量处理文件改动时非常好用能直观看出哪些文件已经add、哪些没有。配合git diff使用更顺畅不带参数时git diff比较的是工作区和暂存区git diff --cached比较的是暂存区和最近一次提交。这两个diff场景很多人搞混记住一句话就行git diff看的是“还没add的改动”git diff --cached看的是“已经add但还没commit的改动”。3.2 git log学会过滤你才能真正看懂历史git log默认输出的是一长串提交记录信息包括哈希值、作者、日期、提交信息。信息多的时候很乱所以我会习惯用git log --oneline --graph --decorate --all--oneline每条提交只显示一行包括短哈希和提交信息。--graph用ASCII字符显示分支历史图分支分叉合并一目了然。--decorate显示分支名和HEAD位置。--all显示所有分支的提交而不是只有当前分支。这几个参数组合起来基本就是我日常的默认log命令了。如果只想看某个文件的修改历史后面加文件名git log --oneline -- app.py想统计某段时间的提交情况可以用--since和--until比如git log --oneline --since2 days ago搜索提交信息里的关键词git log --grepfix这些过滤技巧对排查问题非常有效尤其是项目大了之后提交数量成百上千一句log不加参数直接输出能刷屏几十页。3.3 git diff的三种比较对象diff看似简单但三种比较对象的组合逻辑值得好好梳理命令比较内容git diff工作区 vs 暂存区git diff --cached暂存区 vs 最近一次提交git diff HEAD工作区 vs 最近一次提交第三种组合其实等同于前两种的合并视图能一次看到所有未提交的改动。我遇到过大把人在git diff里看不到预期结果仔细一查发现改动其实已经add过了得用--cached才能看到差异。如果你不确定改动到底处于哪个阶段直接跑git status看一眼状态明确了再用对应的diff命令。还有一个容易忽略的场景git diff默认不比较二进制文件只显示“Binary files differ”。想强制看二进制文件的文本化变化得加--text参数不过实际意义不大因为内容基本不可读。本质上diff命令是让你在提交前做一次自查避免把调试日志、临时配置等杂物带进提交历史。3.4 文件删除与重命名的正确处理方式你在工作区手动删除文件后git status会显示该文件为deleted。想让删除操作进入暂存区常见做法是git rm。它实际上做了两件事删除工作区文件并把删除操作暂存。如果你已经手动删了文件再执行git rm也行Git会识别当前状态并把删除同步到暂存区。如果只想从版本控制中移除文件但保留本地文件比如误提交了配置文件希望它不再被跟踪用git rm --cached config.ini这个操作很实用不会动你磁盘上的文件只是把它从追踪列表里拿掉。重命名操作不需要特殊命令git mv old_name.py new_name.py或者直接mv然后git add new_name.py; git rm old_name.pyGit都能识别为rename。识别靠的是内容相似度不是文件名严格对应所以大大重命名之后内容改太多也可能被判定为“删除新增”但这种差异在功能上没有影响不用纠结。4. 分支管理与本地合并从新建分支到冲突解决4.1 分支的本质和创建切换的底层逻辑分支在Git里不是目录的物理拷贝而是指向提交对象的引用指针。创建分支就是创建一个新的可移动指针切换分支就是让HEAD指向另一个分支名。创建并切换分支最常用的写法git checkout -b feature/login或者新版Git推荐git switch -c feature/login两者的效果完全一样switch是后来为单职责设计的新命令可读性更好。我个人从checkout习惯了但其实switch更不容易误操作因为checkout还兼任恢复文件的功能switch只专注分支切换语义清晰。git branch列出所有本地分支当前分支前会有一个星号和绿色高亮。查看分支和提交的关系可以用git branch -v它显示每个分支最近一次提交的哈希和提交信息。分支多了之后这个命令能帮你快速判断哪个分支比较新、哪个分支落后了。4.2 合并操作的两种方式与适用场景本地合并最常见的两种方式git merge和git rebase。标题热词里出现的“git分支合并”指的大概率是merge操作这里先讲merge。merge有两种模式普通merge和--no-ffno fast-forward。当被合并的分支基于当前分支最新提交直接超前时Git默认执行fast-forward合并只是把当前分支指针向前移动到目标分支不会生成额外的合并提交。这种模式历史是一条直线很干净。但某些场景下你想保留“这里发生过一次合并”的痕迹比如合并一个feature分支进main希望回看历史时能明确知道功能是从哪合入的。这时用git merge --no-ff feature/login它会强制生成一个merge commit即使可以fast-forward。项目协作中很多团队会规定主线分支只接受--no-ff合并原因就是保留合并信息和分支结构方便追溯。普通merge模式下如果两个分支修改了不同文件合并过程直接完成修改了同一文件但不同位置Git通常也能自动合并只有修改了同一文件的同一区域才会出现冲突。4.3 冲突生成与解决的完整过程冲突是本地操作绕不过去的一关。我先构造一个最简单的冲突场景git init conflict-demo cd conflict-demo echo line 1 app.py git add app.py git commit -m initial git checkout -b feature echo line 1 edited by feature app.py git commit -am feature version git checkout main echo line 1 edited by main app.py git commit -am main version现在执行git merge feature几乎一定会收到冲突提示Auto-merging app.py CONFLICT (content): Merge conflict in app.py Automatic merge failed; fix conflicts and then commit the result.打开app.py会看到类似这样的标记 HEAD line 1 edited by main line 1 edited by feature feature HEAD到之间是当前分支的内容。到 feature之间是被合并分支的内容。这里要求你手动决定保留哪种内容或者两者取一个折中。修改完冲突标记后git add app.py最后git commit生成合并提交。注意合并提交不需要你重新写-m提交信息Git会打开默认的合并信息编辑器直接保存退出即可。我处理冲突时还有一个习惯先把冲突文件在编辑器里改完再用git diff确认diff里没有冲突标记残留最后add和commit。有些人改完忘记删标记提交出来的文件里还留着这些代码非常影响后续开发。另外提示一句git merge --abort可以放弃本次合并把仓库恢复到merge前的状态。当你觉得冲突处理起来太复杂或者合并方向选错了用这个命令安全退出不会丢数据。4.4 合并后分支的清理与状态确认合并完成后如果不再需要feature分支可以删除git branch -d feature/login-d在分支未完全合并时会拒绝删除防止误删未合入的内容。如果确定不要了用-D强制删除。这个设计我很喜欢相当于Git给了你一层后悔药保护。想看哪些分支已经合并进当前分支、哪些还没有git branch --merged git branch --no-merged这个信息的价值在于安全清理长期不用的分支避免误删还有独立提交的分支。5. 撤销操作与版本回退搞懂reset和revert的区别再动手5.1 工作区改动的撤销checkout/restore撤销还没add的改动git checkout -- app.py或者新语法git restore app.py执行后工作区文件恢复到暂存区的状态。这条命令会把你对文件的所有未暂存修改全部覆盖掉不可逆所以我只在明确不需要那些改动时才使用。如果改动里有不小心写的代码先备份一下再说。git restore还可以带--staged参数用来把文件从暂存区移回工作区但保留改动内容git restore --staged app.py这个操作跟git reset app.py效果一样但语义更清晰我推荐新手统一用restore来理解这两个场景。5.2 撤销已暂存的修改如果你已经git add了但还没git commit发现改动有问题有两种选择把改动从暂存区放回工作区git restore --staged app.py然后继续编辑。彻底丢弃这些改动git restore --staged app.py git checkout -- app.py。第二种做法其实就是组合命令先把暂存区状态取消再恢复工作区文件最终效果是让文件回到上一次提交的状态。我见过有人遇到这种情况动不动就用git reset --hard HEAD对单个文件来说太重了容易把其他文件的暂存状态也搞乱。优先用restore精准且安全。5.3 已提交版本的撤销reset与revert的选择当commit已经产生撤销操作就进入了“修改历史”的范畴要格外谨慎。git reset移动的是分支指针和HEAD有三种模式--soft只移动HEAD和分支指针暂存区和工作区都不动。--mixed默认移动HEAD和分支指针重置暂存区但工作区不动。--hard移动HEAD和分支指针同时重置暂存区和工作区所有未提交的改动全部丢失。实际中最常见的组合是git reset --soft HEAD~1这会撤销最近一次提交但把变更保留在暂存区方便你修改后重新提交。如果你完全不要这次提交了用git reset --hard HEAD~1但要想清楚这会彻底销毁这次提交以及工作区里对应的改动无法从Git历史中找回。git revert则是反向提交它生成一个新的提交来“抵消”指定提交带来的变化历史记录里会保留一条“revert xxx”的提交信息。它不改动已有历史只是追加一条新记录。两者怎么选一个简单判断标准如果这个commit已经推送到共享远程仓库永远优先用revert如果只是本地未推送reset更干净。因为把共享历史回退会破坏其他开发者的克隆副本造成大量合并冲突和混乱。本地操作阶段没有远程时reset用起来轻松很多但一旦涉及协作要有敬畏心。5.4 实操演练回到某个指定commit回到指定commit前先用git log找到目标提交的哈希值比如a1b2c3d。然后git reset --hard a1b2c3d这会让当前分支指向a1b2c3d之后的提交从当前分支历史中消失。但这些提交真的“消失”了吗没有。Git的reflog会记录HEAD移动的历史你依然可以通过git reflog找到它们git reflog这是Git的万能恢复工具尤其适合在reset之后发现自己回退错了想找回原本的提交哈希时使用。我在实战中救过不止一次所以强烈建议每个Git使用者都养成查看reflog的习惯。6. 本地操作中常见的坑从SSH认证失败到大小写误判6.1 SSH认证失败关键不在远程而在于本地密钥热词里出现了“ssh认证失败 git”这个坑在本地操作阶段其实也有体现。SSH认证失败的报错长这样gitgithub.com: Permission denied (publickey).排查思路按顺序走检查本地是否生成SSH密钥ls ~/.ssh看看有没有id_ed25519或id_rsa文件。没有就生成ssh-keygen -t ed25519 -C 你的邮箱一路回车。把公钥id_ed25519.pub内容添加到远程仓库的SSH Keys设置里。用ssh -T gitgithub.com测试连接看到成功提示说明通了。如果这些步骤都做了还是失败检查SSH agent是否在运行并加载了密钥eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519Windows上如果用的是Git Bash还需要确保~/.ssh目录权限不是everyone可读否则SSH会拒绝使用密钥。权限问题很容易忽略也是认证失败的经典原因之一。6.2 文件大小写与文件名错误在Windows和macOS默认不区分大小写的文件系统上Git对文件大小写的追踪有坑。假设你有一个文件readme.md你把它改成README.mdgit status可能不显示任何变化因为文件系统认为它们是同一个文件。强制让Git识别大小写变化git mv readme.md README.md如果mv做不了可以分两步先git mv readme.md tmp.md再git mv tmp.md README.md。这个操作在项目从Windows迁移到Linux时会变得非常重要因为Linux严格区分大小写一旦大小写不一致代码引用可能直接崩溃。还有一种情况是误提交了巨大的临时文件或者不小心把密码文件提交了。对于本地操作来说前者可以用排除法避免。创建.gitignore文件把构建产物、日志、依赖目录排除掉node_modules/ dist/ *.log *.env注意.gitignore只影响未跟踪的新文件已经纳入版本控制的文件不受影响。想忽略一个已经跟踪的文件得先git rm --cached再添加到ignore。6.3 误删文件与误清暂存区的恢复本地操作中误删文件是常见的悲剧。比如你手动删了一个还没提交的源文件或者执行了git checkout --覆盖了不该覆盖的改动而且没提交历史可以还原。这时第一反应是看refloggit reflog你会发现虽然工作区文件被覆盖了但Git可能仍然记录着对应的对象数据。用git fsck --lost-found扫描没有引用的对象有时能找回丢失的内容git fsck --lost-found找回的文件会出现在.git/lost-found/other目录里虽然文件名已经丢失但内容还在。这个场景不常遇到但遇到的时候几乎等于救命。6.4 误用--hard导致工作区大改丢失git reset --hard是危险系数最高的命令之一因为它会把工作区所有改动与索引全部重置到指定提交。执行前我强烈建议养成一个习惯先git status确认没有需要保留的改动或者先git stash把改动临时储藏起来。储藏后如果反悔了可以随时恢复git stash push -m 临时保存的改动 git stash list git stash applystash是本地操作里最被低估却能有效避险的功能。它尤其适合在需要临时切换分支处理紧急任务、又不希望把半成品提交到历史上的场景。用它做重置前的安全网比事后从reflog里捞数据轻松得多。7. 用alias和习惯打造高效的本地Git工作流7.1 把常用命令变成短命令Git支持为子命令设置别名配置文件在~/.gitconfig。我用的几个常用aliasgit config --global alias.st status git config --global alias.co checkout git config --global alias.br branch git config --global alias.ci commit git config --global alias.lg log --oneline --graph --decorate --all git config --global alias.unstage restore --staged配置完之后git st、git co、git br用起来顺手很多。git lg尤其推荐——一个命令就能看到所有分支的完整历史拓扑日常排查非常够用。别小看这些alias敲命令容易出错的小而繁琐缩短之后错误率自然下降。7.2 遵循可读性更好的commit风格本地提交信息的质量直接影响后续log检索的效率。我倾向于用类似conventional commits的写法简洁干练git commit -m fix: 修复登录模块超时问题 git commit -m feat: 新增用户资料导出功能fix和feat作为前缀让log过滤时一眼识别改动类型。再配合上面提到的git log --grep排查某类变更会非常方便。提交信息写清楚的是“为什么改”而不是“改了哪些文件”——后者diff里都有前者才是真正有价值的历史信息。7.3 本地提交流程的一个自我检查清单我在本地执行每一步操作前心里都有一个小清单按此操作即可git status看看有哪些改动确认哪些是要提交的。git diff检查工作区改动确认内容符合预期。git add精确添加需要的文件避免用git add .把无关文件一起带进去。git diff --cached观察暂存区内容和期望一致后再提交。git commit提交并写好信息。git log --oneline -1确认提交已生成。这个流程虽然多几个步骤但每一步都很轻习惯了就成自然反应。相比提交错了之后再去reset或者revert前置确认是成本最低的防错方式。把时间花在事前的确认上比花在事后的清理上划算得多。我在实际项目里见过太多因为少了这一步确认把临时调试代码、日志文件、甚至敏感信息直接提交进历史的案例这比功能写得慢更让人头疼。Git本地操作本身不复杂复杂的是养成正确的习惯。掌握了这套基础打底的操作逻辑后面接远程协作、多人分支管理时才不会手忙脚乱。