Git实用操作指南：从安装配置到日常协作的避坑手册

写git基本使用这个题目其实挺有意思。网上铺天盖地都是“git从入门到精通”之类的教程但大多数要么太浅讲完add、commit就没了要么太深一上来就是rebase、cherry-pick把新手直接劝退。我这篇打算换个路子按我自己这些年实际用的经验来讲什么场景下用什么命令为什么要这么用哪些命令有坑别踩。不管你是刚装好git还没配过还是已经用了几个月但总感觉哪里不对这篇基本够用了。git是什么三句话能说清一个分布式版本控制系统能记录你项目里每个文件的每次改动能让你在不同版本之间随意穿梭能让多个人在同一项目上并行干活而不互相踩脚。它的出现彻底改变了软件开发的协作方式现在的开源社区、企业内部开发几乎都跑在git之上。适合谁看刚接触git的初学者用了一段时间但命令还没形成体系的人还有那些clone下来就只会pull、push的“命令复读机”。1. Git安装与初始配置1.1 各平台安装方式别在这个环节浪费太多时间git的安装没太多技术含量但不同平台的坑不太一样我挨个说。Windows用户直接去git官网下载安装包或者更省事的办法是用包管理器。用winget的话一行命令搞定winget install --id Git.Git -e --source winget装的时候有几个选项值得注意。安装向导里默认的“Git from the command line and also from 3rd-party software”别改这保证你在cmd、PowerShell、还有那些图形化工具里都能直接调git命令。行结束符转换那里如果只在自己Windows上写代码选“Checkout as-is, commit as-is”就行如果会和Linux、macOS的同事协作我建议选“Checkout Windows-style, commit Unix-style line endings”这是默认值也能少很多换行符引起的无谓diff。macOS用户如果你已经装了Homebrew一句话brew install git没装Homebrew也可以从官网下pkg包或者直接用系统自带的Xcode Command Line Tools——系统会提示你安装虽然版本可能不是最新的但日常使用完全没问题。Linux用户更简单Debian系用apt install gitRedHat系用yum install git基本上一条命令。装完验证一下任何平台都一样git --version能正常输出版本号就说明安装成功了。我看到很多人卡在这一步之后很久才发现自己的git其实没装上而是在用什么IDE自带的简化版所以这个验证别省略。1.2 用户信息配置这个懒偷不得装完git之后做的第一件事不是急着建仓库而是配置用户名和邮箱。这个配置为什么重要因为git的每个提交都会把这两个信息写进历史记录里而且这个记录是很难改的。你要是在团队里用错了邮箱提交别人看提交记录都不知道是你干的排查问题的时候特别尴尬。全局配置的方式git config --global user.name 你的名字 git config --global user.email 你的邮箱--global的意思是对这台机器的所有仓库生效。如果你想对某个特定仓库用不同的身份可以在那个仓库目录下不加--global再配一次这样局部配置会覆盖全局配置。检查配置是否生效git config --list这个命令会把你所有的配置项列出来包括后面的别名、代理之类的。有些新手会遇到一个问题配置完user.name和user.email之后第一次commit还是报错提示让你配置。这种情况多半是你配置的时候多打了空格或者值没加引号导致没有正确写入。你可以用git config user.name单独看一个配置项的值确认到底写进去没有。我个人的习惯是把core.editor也顺手配了默认的Vim对新手不友好git config --global core.editor code --wait这样以后提交需要写补充说明的时候会直接用VS Code打开编辑器比在终端里用Vim舒服多了。老手可以根据自己习惯配成其他编辑器。2. SSH密钥配置与远程仓库对接2.1 为什么要用SSH而不是HTTPS配置完本地身份接下来要解决的是怎么和远程仓库安全地通信。最常见的远程仓库有GitHub、Gitee、GitLab这些连接方式主要有两种HTTPS和SSH。HTTPS的缺点是每次push都要输入用户名密码虽然现在很多平台支持用token代替密码但还是麻烦。SSH的优势是你只要把公钥放到平台上以后所有的push和pull都是无感的不用反复输入凭据而且传输全程加密安全性更好。我现在所有项目都是用SSH方式省心。生成密钥的命令ssh-keygen -t ed25519 -C 你的邮箱注意这里推荐的是ed25519算法不是RSA。ed25519密钥更短、生成更快、安全性也不输RSA。如果你的系统比较老不支持ed25519可以用ssh-keygen -t rsa -b 4096。这个命令执行完会问你密钥存放位置和密码。存放位置我建议直接用默认的~/.ssh/id_ed25519一路回车就行除非你有特殊需求要区分多个密钥。密码那一项我建议设置一个。虽然多输一次密码麻烦但私钥文件一旦泄露密码就是最后一道防线。你可以在最后——找一个地方比如终端里执行一条ssh-add把私钥加进agent并设置超时时间这样就不用每次都用输入密码又保有基本的安全感。生成完之后查看公钥内容cat ~/.ssh/id_ed25519.pub把输出的那串ssh-ed25519开头的内容复制下来。2.2 把公钥配到Gitee上并测试连通性以Gitee为例登录网页版之后找到“设置”-“安全设置”-“SSH公钥”把你的公钥粘贴进去起个名字保存就行。GitHub的位置在Settings - SSH and GPG keysGitLab在Preferences - SSH Keys路径都差不多大同小异。配完之后测试一下连通性ssh -T gitgitee.comGitee会返回一个欢迎语类似“Hi xxx! Youve successfully authenticated, but GITEE.COM does not provide shell access.”看到这个就说明密钥配好了。GitHub会返回类似“Hi xxx! Youve successfully authenticated...”的信息。这里有一个很容易踩的坑如果你配了对gitlab.com的密钥也配了公司内网GitLab的密钥而它们都用了默认文件名id_ed25519那就会互相覆盖。解决方法是生成时给不同平台指定不同文件名然后在~/.ssh/config里配一下Host github.com HostName github.com IdentityFile ~/.ssh/github_ed25519 Host gitee.com HostName gitee.com IdentityFile ~/.ssh/gitee_ed25519这样git会根据你连的目标主机自动选对应的私钥互不干扰。新手在配完之后另一个常见问题是测试SSH时提示“Permission denied (publickey)”。这个90%的情况是公钥没复制全。cat显示的时候注意看结尾有没有换行或者空格复制的时候别漏了最后几个字符。还有一小部分情况是系统里启动了ssh-agent但它加载不到你的新密钥跑一句ssh-add ~/.ssh/id_ed25519就能解决。3. 日常操作命令全解析3.1 本地仓库的初始化与提交把基础打扎实配置搞定接下来是真正使用git的核心命令。先说在本地新项目的场景。进入项目目录运行git init这是把当前目录变成一个git仓库。执行之后目录下会多一个.git隐藏文件夹这里存着整个仓库的所有版本历史。你可以把.git理解为git的“数据库”平时不需要去动它。然后在项目根目录建一个.gitignore文件这是一个很多人忽略但极其重要的操作。它的作用是告诉git哪些文件不需要纳入版本管理。对于不同语言的项目对应有各自的模板Python项目要忽略__pycache__和.venvNode项目要忽略node_modulesJava项目要忽略target。我见过太多人把node_modules也提交上去了那仓库体积飙升pull下来慢到怀疑人生。提前配好.gitignore能省掉后面大量清理麻烦。接下来看文件的三种状态这是理解git的钥匙。任何文件在git眼里都有三种状态已跟踪、已修改、已暂存。已跟踪是git知道有这文件并且已经记录过它的内容已修改是你改了但还没告诉git已暂存是你把改动放进了暂存区准备提交。git的本质操作就是让文件在这几种状态之间流转。查看当前状态git status这个命令必须养成高频使用的习惯。它会清楚告诉你哪些文件是未跟踪的哪些是修改过的哪些是已经暂存等待提交的。你不需要记住仓库当前是什么状态git status会告诉你一切。看输出信息的时候红色的文件说明是“已修改未暂存”绿色的是“已暂存”。一开始记不住也没关系多跑几次就自然懂了。暂存和提交git add . # 把所有修改加入暂存区 git commit -m 提交说明我建议是不要用git add .一把梭尤其在一个PR做了多件事的时候。更好的习惯是分开暂存比如git add src/utils/date.ts git commit -m fix: 修复日期格式化时区错误 git add src/api/user.ts git commit -m feat: 新增用户详情接口每个commit只做一件完整的事commit信息说清楚这一件事是什么。这样以后翻历史或者做回滚定位会非常精准。3.2 分支管理与远程仓库协作多人开发的核心分支是git最强的功能。你可以把分支理解为平行宇宙你在自己的宇宙里随便改改好了再并回主线。查看分支git branch # 查看本地分支当前分支前面有*号 git branch -a # 查看所有分支包括远程的新建并切换分支git checkout -b feature/login这条命令等于git branch feature/login加git checkout feature/login两步。新版本git还提供了更语义化的git switch -c feature/loginswitch和checkout功能类似但switch只做切换分支这一件事指令更清晰不容易误用。我个人的习惯已经全面切到switch了但如果你团队其他人还在用checkout也是完全兼容的。把分支推到远程git push -u origin feature/login这个-u参数的意思是“记住上游分支”相当于告诉git本地的feature/login对应远程的origin/feature/login以后在这个分支上直接git push或git pull就行不用再写完整参数。拉取远程代码有两条命令容易混git fetch和git pull。fetch只会把远程的更新下载到本地但不改动你当前的工作区pull等于fetch加上merge两步它会直接把你当前分支和远程更新合并。我的建议是在干净的工作区用pull没问题但如果本地有没提交的改动先fetch看看远程改了什么东西再决定怎么合避免产生一堆乱七八糟的冲突。合并分支git checkout main # 先切到目标分支 git pull origin main # 先把目标分支更新到最新 git merge feature/login # 再把功能分支合进来merge之后会生成一个新的合并提交历史记录会呈现分叉再合并的形状。如果合并过程中出现冲突别慌git会在冲突文件里用、、标出两个版本的不同内容手动改成你想要的样子然后git add那个文件再git commit完成合并。4. git commit --amend 的正确使用姿势4.1 amend到底能干什么以及什么时候该用git commit --amend是git里一个很常用但也容易被误解的命令。它的字面意思是“修改最后一次提交”。很多初学者以为它只是改提交说明实际上它做的事情更多它会用当前暂存区的状态替换掉上一次提交的内容并且生成一个新的提交对象。这么说有点抽象我给你拆开说。假设你刚提交了一个commit但马上发现某个文件里有个小拼写错误。你有两个选择再提交一次说“fix typo”或者修改这个文件、git add然后执行git commit --amend这样上次那个commit就变了里面包含了拼写修正提交说明也没变。你的历史变得干净没有那种“改一下”“又改一下”的垃圾提交。这在实际开发里非常实用。查看提交历史git log --oneline--oneline让每条提交只显示一行的摘要信息。你执行amend之后git log里可以看到上次提交的哈希值变了这也是判断amend是否生效的方法。除了改提交内容amend最常见的用途就是改提交信息。比如你上次提交的说明写错了字或者表达不清楚git commit --amend -m 正确的提交说明用-m直接指定新的提交信息git会替你替换掉旧的。适合那种刚刚提交、还没推送、然后发现“哎呀信息写错了”的时刻。还有一种用法是补漏提交。比如你已经提交了一个改动但发现忘了把某个新文件加进来git add 忘记了文件.txt git commit --amend --no-edit--no-edit的意思是“保持原有的提交信息不变”只需要把新文件并进上一次提交即可。这是我个人用得最多的场景省得为了一个遗漏的文件多制造一条无意义的提交记录。4.2 amend的风险边界什么情况下绝对不能用必须强调一个红线如果上一次提交已经push到远程了就不要用amend去改它。为什么因为amend不是修改而是替换它会生成一个新的commit而旧的commit还在历史里。你本地的历史和远程就对不上了。一旦你执行git pushgit会拒绝推送说远程有你已经不包含的提交。你被迫要git push --force去覆盖远程历史这在团队协作里是灾难级的操作——别人的本地历史基于的是那个旧的commit你这么一覆盖所有同事都会遇到莫名其妙的冲突。强制推送这个操作我在实际工作中见过太多次因此搞坏团队仓库的案例。总结成一句话就是amend只用来收拾还没出门的烂摊子。提交之后没推送随便改推送之后老老实实新建一个commit把它修掉。另一个容易被忽略的点是amend会把之前的提交“吞掉”。如果你在amend之前做了reset或者checkout可能会丢失一些东西。但在最常见的使用场景——最近一次提交还没push你只是改了文件然后amend——是安全的不用担心找不回来。最后给大家一个检查锦囊。如果你不确定该不该amend就看一下这个分支的远程状态git status git log {u}..HEAD{u}是当前分支的远程追踪分支git log {u}..HEAD会列出所有“本地有但远程没有”的提交。如果这个输出里有内容说明你有些提交还没push这时候amend是安全的如果输出为空说明你的提交已经都推送走了这时候再想amend就得多个心眼了。5. 常用查询与diff命令把仓库“读”明白5.1 status和log的高级用法不只是看一眼git status基础用法我就不重复了说几个好用的参数。git status -s-s是short模式输出的信息非常紧凑每行一个文件用两个字母表示状态??表示未跟踪M表示已修改未暂存M表示已修改且已暂存。一眼扫过去就知道仓库干不干净。尤其是在多文件的项目里这个模式比默认的完整输出清爽太多。我几乎只用-s模式。git log的进阶用法也值得掌握。看最近几条提交加上改动内容git log -p -2这会显示最近两条提交的完整diff适合想看最近改了什么细节的场景。如果只想看某个文件的提交历史git log --oneline -- 文件名注意--后面的文件名这是git的标准写法用来分隔参数和路径能避免文件名和参数冲突。还有个实用的场景——某个文件是谁在什么时候改的git blame 文件名这个命令会在每一行前面标注出最后一次修改它的提交哈希、作者和日期。接手别人代码的时候看到一行奇怪的代码不知道是干嘛的git blame一眼定位到作者和当时的提交信息比挨个问人高效多了。5.2 diff的常用参数以及那个神秘的mnemonicprefixdiff用来查看具体改动内容是code review和排查问题时的必备工具。查看还没暂存的改动git diff查看已经暂存、还没提交的改动git diff --staged有没有发现默认git diff是不管暂存区的这个区分很关键。全部改动里有些你add了有些没add默认diff只看没add的那些。如果你刚git add完想看看到底暂存了什么再提交必须用--staged。比较两个分支或两个提交之间的差异git diff main..feature/login git diff HEAD~2 HEADHEAD~2表示当前提交往上数两个版本。这种写法在你临时想看某个历史版本和现在的差别时特别好用。diff还有一个实用参数是--stat只显示统计信息不显示具体内容git diff --stat输出类似“3 files changed, 15 insertions(), 2 deletions(-)”文件级别掌握改动规模不用看具体代码。热搜词里有个很典型的命令值得专门解释一下git -c diff.mnemonicprefixfalse -c core.quotepathfalse --no-optional-locks这条命令看起来长其实就是几种参数叠加在TortoiseGit这类GUI工具的日志里经常出现。-c的意思是“临时修改一项配置”后面跟的键值对只在这次命令中生效。diff.mnemonicprefixfalse控制diff输出时文件名前后的标记false时用我们常见的a/文件、b/文件格式core.quotepathfalse是让中文文件名正常显示而不是转义成八进制编码这个在中文项目里非常实用--no-optional-locks是告诉git别对仓库加可选锁防止并行操作时出现无谓的等待。整体上就是GUI工具为了更稳定地运行而拼出来的一串参数你不需要记住它但看到时能看懂它在干嘛就不会一头雾水了。6. 常见问题与排查技巧实录6.1 我踩过的几个坑以及当时的排查过程这么多年用git遇到过的坑数不胜数说三个最有代表性的。第一个坑是中文文件名乱码。项目中有中文名文件执行git status时看到的不是文件名本身而是一串类似\346\265\213\350\257\225.txt的转义序列。第一次碰到这情况我还以为是仓库坏了后来查了才知道是git默认对非ASCII字符做转义显示。解决办法就是把core.quotepath设为falsegit config --global core.quotepath false配置完之后再跑git status中文名就正常显示了。这个配置强烈建议所有用中文文件名的项目都配上。第二个坑是误提交了大文件。有次写了个demo项目不小心把一个几百MB的视频文件加进仓库并提交了。当时觉得没什么直到同事clone下来拉了半天才发现问题。处理的办法是如果只是最近一次提交误加了大文件可以用amend把它从暂存区拿掉git rm --cached 大文件.bin git commit --amend --no-edit--cached的意思是只从git索引里移除保留磁盘上的文件。但你注意这只能阻止它继续被跟踪旧的提交记录里那个大文件还在仓库的历史体积并没有真正变小。要彻底清掉历史里的脏东西得用git filter-branch或者BFG Repo-Cleaner这类工具操作比较复杂我建议最好的防御是提交之前扫一眼git status看到不该出现的文件及时加进.gitignore防患于未然。第三个坑是团队协作时的提交信息混乱。项目里有同事提交信息写得天马行空“aaa”“fix”“update”满天飞三个月后回看历史完全不知道每笔提交干了什么。后来我们约定功能提交用feat: xxx修bug用fix: xxx文档用docs: xxx重构用refactor: xxx。这个约定并不复杂但带来的收益很大——版本回退、代码审查、新人上手都顺了。所以我才在3.1里反复强调提交说明的重要性这不是形式主义是生产力的基础。6.2 快速排查速查表遇到问题先对号入座问题现象常见原因解决办法commit时报错要求配置user.name/email当前仓库没有局部配置全局也没配按1.2节补配全局配置或在该仓库单独配push时报“Permission denied (publickey)”公钥未配、私钥路径不对、复制不全检查~/.ssh/下密钥文件确认公钥完整粘贴到平台push被拒提示“non-fast-forward”远程有新提交本地没有merge先git pull再push或者先fetch看差异再merge误提交了不需要的文件忘了配.gitignore或直接add了git rm --cached加进.gitignore再amend发现上一次提交信息写错了提交后未推送git commit --amend -m 正确信息提交记录里中文名乱码core.quotepath默认转义git config --global core.quotepath falsegit log看不到预期提交HEAD不在那个分支上git log --all --oneline看所有分支的提交merge出现冲突不知道怎么处理两个分支改了同一处代码打开冲突文件手动保留正确内容add后commitclone很慢仓库历史里可能有超大文件检查仓库体积必要时使用浅克隆git clone --depth 1这张表整理了最常见的十个场景遇到问题别慌先对照现象找原因。绝大多数git问题的共同点是git本身不会帮你“修复”什么你需要的只是搞清楚当前仓库的真实状态而搞清楚状态的命令就是git status、git log、git diff这三个反复用问题基本都能定位。我个人在实际操作中的体会有几条最后分享给大家。第一git命令不复杂复杂的是你脑子里要有“仓库状态”这个模型随时知道文件在哪、提交在哪、分支指向哪。记住git status是你最好的朋友多跑它。第二不要留恋那些酷炫的“高级操作”多数项目中90%的场景就是add、commit、push、pull、branch、merge这几个基础命令把这些做到熟练比会一百个花哨命令有用得多。第三提交信息是你的脸面也是团队协作的信用基础认真写清楚每一笔提交干了什么三个月后你会感谢自己。这个内容往后的扩展方向也很多比如git的rebase到底该不该用、git flow和trunk-based怎么选、子模块和子树怎么维护还有钩子脚本做自动化校验之类的都是在一个熟练基础上自然而然的进阶方向。先把这篇的所有命令练熟后面这些内容我以后再继续整理。