说实话Git和Gitee对我来说早就不只是工具而是日常工作流的一部分。Git管版本、Gitee管托管和协作两个配合起来无论是个人项目还是团队开发效率都能提上去不少。这篇东西说白了就是我长期使用中整理出的一份速查手册不整虚的理论直接聚焦日常开发里最高频的Git命令、Gitee操作以及那些不看文档就一定会踩的坑。适合刚入门的新手照着一步步操作也适合有经验的开发者随手翻一翻当备忘录。1. 先把环境弄干净Git安装与全局配置1.1 跨平台安装的三种方式Git的安装在不同系统上差别挺大我逐个说下实测过的方案。Windows上最省事的是去Git官网下载安装包一路Next就行。但有几个选项要特别注意建议在安装向导的“Adjusting your PATH”一步选择“Git from the command line and also from 3rd-party software”这样以后在命令行里直接敲git就能用很多开发工具也能自动识别到git。默认选项虽然也能用但有些第三方软件找不到git很容易出各种奇怪问题。还有换行符那一项先别急着选后面单独说。macOS上如果装了Homebrew一条命令搞定brew install git。没装Homebrew的话去官网下载dmg安装包也可以。Linux发行版更简单Ubuntu/Debian用sudo apt install gitCentOS/RHEL用sudo yum install git也是几秒钟的事。装完先确认版本终端里执行git --version能正常输出版本号就说明安装成功。我习惯提示一下版本别太老Git 2.23之后才有git switch和git restore这两个命令很多老博客写的命令在新版本里行为都不一样版本对不上你照着敲可能就报错。装完第一步别急着clone代码先确认git版本再配置用户信息。老项目的脚本里对git版本有要求的情况不少版本太老有些命令行为会不一样。1.2 全局配置和换行符陷阱装完git第一件事就是配置用户名和邮箱这个不配commit的时候要么报错要么提交记录里显示一堆问号推送上去也没法关联到你的Gitee账号。git config --global user.name 你的名字 git config --global user.email 你的邮箱这里有个细节容易被忽略Gitee读取的是提交记录里的邮箱用它来关联账号。所以最好填你注册Gitee时用的邮箱否则push上去了Gitee那边不会正确挂到你的用户名下。然后是换行符这个老坑。Windows的换行符是CRLF回车换行Linux和macOS是LF只有换行。如果不做处理同一份代码在Windows和Linux之间来回切换时git会认为整个文件都变了diff里全是莫名其妙的内容。我的做法是Windows上设置core.autocrlf truemacOS/Linux上设置core.autocrlf input。这样git在提交时自动把CRLF转成LF检出时再按平台转回来能省掉一大堆无关痛痒的变更。# Windows git config --global core.autocrlf true # macOS / Linux git config --global core.autocrlf input再建议一条预设默认分支名。早期git默认分支是master现在新建仓库很多人习惯用main。与其每次init之后手动改名不如直接全局配置git config --global init.defaultBranch main这样以后git init出来的仓库默认就是main分支省一步操作。1.3 初始化一个本地仓库新项目想纳入git管理在项目根目录执行git init目录里就会生成一个隐藏的.git文件夹里面存着所有版本历史信息。之后正常add、commit就行。不过更常见的情况是从Gitee上clone一个已存在的仓库到本地那就不需要git init了。clone命令后面专门讲这里先记住流程新项目用init已有远程项目用clone两个操作二选一别重复。还有个高频场景项目已经写了一段时间代码量不小了现在才想起来用git。这时候先别急着init先想清楚哪些文件不该提交比如bin目录、编译产物、本地配置、IDE的workspace文件。把.gitignore先写好再初始化能避免很多麻烦。.gitignore的内容我在后面第2节单独展开。2. 日常用得最多的本地操作命令2.1 提交前的三件套status、add、commitgit status是使用频率最高的命令没有之一。任何时候不确定当前仓库是什么状态先敲git status。它会告诉你哪些文件改了、哪些文件还没被git跟踪、当前在哪个分支、和远端比是领先还是落后。信息全且直观。我习惯每次提交前都敲一遍确认要提交的东西符合预期再动手。然后就是git add。add的作用是把文件从工作区放进暂存区相当于告诉git“这些文件这次要提交”。几个常用形式git add . # 把当前目录所有改动加入暂存 git add 文件名 # 只添加指定文件 git add -p # 交互式逐块确认适合一个大文件里混了多个改动提交用git commit -m 提交说明。提交说明的写法我强烈建议带上类型前缀比如feat:表示新功能fix:表示修bugdocs:表示文档变更refactor:表示重构。这个习惯一旦养成看git log的时候一目了然团队协作时别人也能快速理解每个提交的意图。git commit -m feat: 新增用户登录接口 git commit -m fix: 修复订单列表分页错乱问题2.2 查看历史与对比差异git log是查看提交历史的命令。默认输出比较朴素我推荐记这个组合git log --oneline --graph --decorate --all--oneline把每个提交压缩成一行--graph用字符画显示分支分叉--decorate显示分支和标签指向--all显示所有分支。这条命令基本满足日常查看历史的所有需求。想看某个文件具体改了什么用git diff。三个形式的区别经常有人搞混git diff # 工作区和暂存区的差异也就是还没add的内容 git diff --cached # 暂存区和上次提交的差异也就是已经add的内容 git diff HEAD # 工作区和最新提交的差异也就是所有未提交的改动我的口诀是不带参数看“还没add的”带--cached看“已经add了的”带HEAD看“相对于上次提交的全部改动”。排查“这行代码是谁改的”“当时为什么这么写”时git log -p直接看每次提交的具体改动非常有用。只想看某个文件的提交历史用git log -- 文件路径。2.3 .gitignore该写什么.gitignore专门声明哪些文件不被git跟踪。很多新手漏掉它结果把node_modules、target、.idea这种目录全推上去了仓库变得又大又乱别人clone下来还容易出问题。常见忽略项包括编译输出目录target、dist、build、out依赖目录node_modules、vendorIDE配置.idea、.vscode注意.vscode有些团队会保留公共配置本地环境文件.env.local、application-local.yml日志和临时文件.log、.tmp操作系统文件.DS_Store、Thumbs.db写.gitignore有一个关键顺序问题已经被git跟踪过的文件即使写了ignore规则也不会被忽略。必须先执行git rm -r --cached 文件路径把文件从git索引里移除再写进.gitignore然后提交一次。顺序反了文件会一直赖在仓库里。这个坑我见人踩过无数次。3. 连接Gitee从注册到SSH密钥3.1 创建Gitee仓库的细节先在Gitee注册并登录右上角“”号里选“新建仓库”。几个字段要仔细看仓库名称、是否私有、是否初始化仓库自动生成README、.gitignore、开源许可证。Gitee免费账号就可以创建私有仓库对个人项目和非公开代码来说很友好不一定非要开源才能用。选择“公开”时建议初始化时选一个开源许可证否则别人看到你的代码也不知道能不能用。私有仓库的许可证可以先不选等以后打算开源了再补。许可证具体怎么选我在第6节专门讲。创建完仓库Gitee会展示一个页面上面有HTTPS和SSH两种远程地址还有几行提示命令。先别急着照抄操作先把SSH密钥配好不然每次push都要输账号密码很烦。3.2 SSH密钥配置与认证原理SSH密钥可以理解成一对锁和钥匙公钥放在Gitee服务器上私钥留在本地。push的时候git用私钥签名服务器用公钥验证验证通过就允许操作。这样既不用每次输密码也比密码认证更安全。生成密钥的命令ssh-keygen -t ed25519 -C 你的邮箱推荐ed25519而不是传统的RSA 2048因为ed25519密钥更短、生成更快、安全性也不差。如果你的git版本太老不支持ed25519再用ssh-keygen -t rsa -b 4096 -C 你的邮箱。生成过程中会提示保存路径直接回车用默认位置就行。还会让你输入passphrase这是给私钥加的一层密码保护。不输入的话连接更方便但私钥泄露了风险更大输入的话每次连接都要输一遍稍微麻烦。我个人的选择是本机不设passphrase前提是电脑有全盘加密如果你没有加密习惯建议还是设上。生成的公钥在~/.ssh/id_ed25519.pub文件里用cat命令打开复制全部内容。然后到Gitee右上角头像里的“设置”-“安全设置”-“SSH公钥”粘贴保存。验证是否配置成功ssh -T gitgitee.com第一次连接会提示确认主机指纹输入yes回车。配置没问题的话会输出“Hi 用户名Youve successfully authenticated”之类的成功提示。SSH认证失败是极高概率出现的问题。最常见的两个原因一是公钥没粘贴完整尤其是末尾部分二是公钥添加到了别的平台而不是Gitee。排查顺序先ssh -T gitgitee.com看输出再检查本机~/.ssh下的文件名和权限最后回Gitee页面核对公钥内容。3.3 添加远端并完成首次推送密钥配好之后回到仓库页面复制SSH地址。本地已有仓库的情况git remote add origin gitgitee.com:你的用户名/仓库名.git git branch -M main git push -u origin main解释一下这三条remote add把远程仓库地址绑定到本地origin这个名字branch -M main把当前分支改名为main如果你初始化时已经设置默认分支为main这步可跳过push -u origin main把本地main分支推送到远程-u参数记住关联关系以后直接git push就行。从Gitee拉新项目到本地用clonegit clone gitgitee.com:你的用户名/仓库名.gitclone完会自动带上远程仓库配置不需要再手动add remote。这里有个必踩的坑创建仓库时如果勾选了“初始化仓库”自动生成README本地和远程就各有了一次不相关的首次提交直接push会报错“failed to push some refs”。解决办法是先git pull --rebase origin main把远程的README合进本地再push。我第一次用Gitee时就卡在这里半小时当时还不知道rebase是什么现在回过头看其实就是一次同步操作。4. 分支管理实战4.1 分支的创建、切换与合并分支是git最核心、最能体现价值的功能。简单理解分支就是一条独立的开发线你可以在分支上随便改代码不影响主分支和其他人的工作。常用命令记这几个就够git branch # 查看本地分支列表当前分支前面有星号 git branch 分支名 # 创建新分支 git checkout 分支名 # 切换分支 git switch 分支名 # 切换分支新版更推荐 git checkout -b 分支名 # 创建并切换最常用 git branch -d 分支名 # 删除分支注意从git 2.23开始官方推荐用git switch切分支、用git restore恢复文件来替代checkout的一部分职责。但实际工作中老命令checkout还是无处不在两种都要认得。合并分支的命令是git merge。在feature分支上开发完新功能想合回main先切回main再执行git merge feature。git会把两个分支的历史合并到一起产生一个合并提交。4.2 合并冲突的解决流程两个分支改动了同一个文件的同一行git就不知道谁对谁错会产生冲突。冲突发生后git status会告诉你哪些文件冲突了打开文件会看到类似这样的标记 HEAD 这里是当前分支的内容 这里是合并进来的分支的内容 feature解决冲突就是手动把这段内容改成你想要的样子删掉那些标记行然后git add这个文件再git commit。注意git不会替你判断谁的改动是对的这个决策必须人来做。我踩过的坑是合并不一定只在merge时发生git pull的时候也可能触发冲突因为pull本质上是fetch加merge。遇到pull冲突别慌解决流程和merge冲突完全一样。有一个缓解技巧git pull --rebase比git pull产生冲突的概率低一些因为rebase会把本地提交一个个应用到远端最新代码上而不是一次性做一个合并。4.3 rebase与merge该选谁这是个能引发争论的话题我从实用角度说我的选择。merge保留完整的合并历史git log --graph里能看到清晰的“分叉再合并”结构。好处是保留了真实的时间线坏处是历史里会出现很多“Merge branch ...”这样的提交时间长了有点乱。rebase做的事情是把当前分支的提交“重新移植”到目标分支的顶端效果是提交历史变成一条直线非常干净。我的习惯是个人开发的分支、还没推送过的提交用rebase整理历史团队共享的分支、已经推送过的提交用merge。原因是rebase会改写提交的哈希值如果你rebase了一个别人也在用的分支会引发一连串冲突和混乱。所以有个原则不要把rebase用在共享分支上。实际场景举例feature分支是从main分出来的开发期间main来了几个新提交想把main的新改动同步到feature执行git rebase main。成功后feature看起来像是从最新main上长出来的逻辑很干净。前提是feature只有你在用。5. 回滚与撤销救命的命令5.1 三个撤销场景开发中总会遇到改错了想撤销的情况按场景拆开讲。场景一文件还在工作区没add。改了半天的东西全不想要了执行git restore .当前目录所有未暂存的改动全被丢弃。只想撤销单个文件就git restore 文件名。这个操作不可逆执行前先用git diff看一眼到底改了啥。场景二已经add了但还没commit。撤销暂存用git restore --staged 文件名文件回到未暂存状态但改动内容还在。场景三已经commit了但还没推送到远程。这种最幸福用git reset可以随心回退git reset --soft HEAD~1 # 撤销最近一次提交改动保留在暂存区 git reset --hard HEAD~1 # 撤销提交并且丢弃改动回到上次提交的状态--hard慎用它会连工作区一起重置丢了的代码找不回来。如果你不确定改动还有没有用先git stash或复制一份备份再操作。5.2 commit --amend怎么用commit --amend的作用是修改最近一次提交。最常见场景是提交信息写错了或者漏了一个文件。改提交信息git commit --amend -m 新的提交说明补漏文件git add 漏掉的文件 git commit --amend --no-edit--no-edit的意思是不重新编辑提交说明沿用之前的信息。有一个关键禁忌amend本质是把原提交替换成新提交会改写提交哈希。如果上一次提交已经推送到远程并且分支是多人协作的amend之后强推会导致别人本地的历史对不上。我的规则是只有还没推送的提交才用amend已经推送了就老老实实再提一个新提交。5.3 用reflog找回丢失的提交手滑执行了git reset --hard提交丢了怎么办别慌git有一个“后悔药”reflog。git reflog会显示本机所有HEAD移动过的记录包括每一次reset、checkout、commit。每条记录前面有哈希值你误删的那次提交就藏在里面。找回方法git reflog git checkout 哈希值或者直接重置git reset --hard 哈希值这个命令能恢复绝大部分误操作但有两个前提一是reflog记录还在二是被找回的提交对象还没被git的垃圾回收机制清理。发现误删后越早恢复成功率越高。我实测过几乎所有的git“误删除”都能靠reflog找回来只要你在本地仓库里操作过。唯一救不了的是那些从未commit过的工作区改动所以重要改动尽量早提交这个习惯值得养成。6. Gitee特有的几个实用功能6.1 Gitee Pages部署静态站点Gitee Pages可以把仓库里的静态页面发布成一个能通过网址访问的站点。对个人博客、项目文档、前端Demo来说很实用。部署流程仓库里放一个包含index.html的静态页面目录到仓库页面的“服务”菜单里找到“Gitee Pages”选择要发布的分支和目录点击启动。部署完成后Gitee会给一个默认的gitee.io后缀域名也可以绑定自己的域名。需要注意几点Gitee Pages要求账号完成实名认证启动部署后要等平台审核审核通过后才能正常访问。内容必须符合平台规定这没什么好讨价还价的。我的使用场景是把技术文档仓库部署成在线手册再绑一个自定义域名团队内部访问起来比翻本地文件方便很多。6.2 大文件上传与Git LFSGitee仓库有单文件大小限制普通方式上传超过一定大小的大文件会被拒绝。这种情况需要Git LFSLarge File Storage。LFS的思路是仓库里只存一个文本指针真正的二进制大文件放在LFS存储服务器上。clone仓库时git按需拉取LFS文件不会让仓库体积爆炸。使用步骤git lfs install # 安装LFS只需要执行一次 git lfs track *.zip # 声明要跟踪的文件类型 git add .gitattributes # track后生成的.gitattributes要提交 git add 大文件 git commit -m 添加大文件 git push注意LFS不是完全免费的Gitee对LFS的存储空间和流量有配额限制免费用户额度很小。偶尔传一两个大文件够用如果是音视频素材这类重度场景还是建议换对象存储服务。如果大文件只是自己用不一定要进仓库。放到网盘或内网共享盘在README里写个下载说明这招治标不治本但对个人项目来说最省事。6.3 开源许可证怎么选创建公开仓库时Gitee会让你选许可证。很多人纠结其实选错比不选要好。公开仓库没有许可证意味着“保留所有权利”别人虽然能看到你的代码但法律上不允许使用。几个常见许可证的区别MIT非常宽松别人想怎么用都行只要保留版权声明。适合个人项目、工具类、库类。Apache-2.0比MIT多一些条款比如专利授权适合希望更正式一点的项目。GPL-3.0要求任何修改和分发代码的人也必须以GPL协议开源。适合希望代码永远保持开源的项目但对商业使用不友好。我的建议个人工具、博客主题选MIT公司项目要和法务确认如果你希望别人改进后的代码也必须开源才考虑GPL。还有一个实用小知识改许可证方案没问题但旧版本还是按旧许可证执行所以越早定越好。6.4 Gitee仓库能包含子项目吗这个问题其实就是问monorepo和submodule。Gitee本身没有“子项目”这种特殊概念一个仓库就是一个仓库但有两种变通方案。第一种是monorepo一个仓库里放多个独立项目用目录区分。比如一个前端仓库底下有admin、mobile、docs三个子目录各自有独立的package.json。这种方式管理简单、体积可控、权限统一是大多数团队实际采用的。缺点是多个项目共用一条提交历史版本发布规则要自己约定好。第二种是Git Submodule在一个仓库里引用另一个Git仓库。当你要把公共组件仓库直接嵌入项目时可以git submodule add gitgitee.com:用户名/公共组件仓库.git别人获取代码时用git clone --recursive子模块会一并拉取。submodule的坑在于子模块指针容易失联团队成员忘了拉子模块导致编译报错的情况很常见维护成本不低。小型团队我更推荐monorepo。7. IDE集成IDEA和VS Code配合Gitee7.1 IDEA拉取与推送项目IDEA内置了完整的Git支持不需要额外装插件。第一步是把本机git路径配好File - Settings - Version Control - GitPath to Git executable指向git安装路径。用SSH方式操作Gitee时IDEA里不需要登录Gitee账号只要本机SSH密钥配好了IDEA直接复用即可。从Gitee拉取项目到IDEA的流程File - New - Project from Version Control粘贴仓库SSH地址选择本地目录点Clone。IDEA会自动识别Maven、Gradle或前端项目非常顺滑。日常提交推送修改文件后文件会变色新增蓝色、修改红色在Commit窗口勾选要提交的文件写提交信息点Commit或Commit and Push。IDEA的Changes面板比命令行直观得多适合不熟悉命令行的新人。不过IDEA里的分支操作也比较全右键分支名可以checkout、merge、compare我经常在IDEA里完成大部分git操作。7.2 VS Code的Git面板VS Code左侧活动栏的源代码管理图标就是Git面板。它有几点做得很好文件内直接显示改动行提交信息输入框集成在面板上push、pull都有对应按钮。CtrlShiftP输入Git: Clone输入仓库地址就能可视化clone。我特别推荐新人用VS Code的源代码管理面板入门Git因为每一步都有可视化反馈。但有几个操作还是得回终端git rebase、git stash、git reset --hard集成面板要么不支持要么提示不够直观。所以别指望IDE完全替代命令行两条腿走路效率最高。7.3 多远端协作的技巧一个仓库绑定多个远端地址在和多个平台协作时会用到。默认远端叫origin可以再添加一个git remote add backup gitgitee.com:用户名/仓库名.git git remote -v # 查看所有远端 git push origin main # 推送到默认远端 git push backup main # 推送到备份远端 git fetch backup # 拉取备份远端的提交但不自动合并 git merge backup/main # 手动合并多远端在参与开源项目时很常见主仓库在Gitee上额外挂一个远端做备份或者同时参与其他项目。注意一点git push不带参数默认推送到origin别养成不带参数的习惯免得推错地方。8. 高频问题排查实录8.1 SSH认证失败排查SSH认证失败几乎是每个git新手都会遇到的。典型报错是“gitgitee.com: Permission denied (publickey)”。按我的排查顺序来ssh -T gitgitee.com # 第一步测试连接看报错信息 ls ~/.ssh # 第二步检查密钥是否存在 cat ~/.ssh/id_ed25519.pub # 第三步查看公钥内容 git remote -v # 第四步确认用的是SSH地址 eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519 # 第五步可能是ssh-agent没启动还有一个容易被忽略的企业电脑的防火墙或安全策略可能拦截SSH端口导致连接超时。这种情况可以改用HTTPS地址配合访问令牌的方式拉取推送。Gitee支持生成访问令牌HTTPS方式下输入用户名和令牌就能认证虽然每次要输但至少能用。8.2 推送被拒绝推送被拒绝的典型场景是本地和远端的历史不一致报错一般是“Updates were rejected because the remote contains work that you do not have locally.”解决办法有两种。远端确实有新提交并且你想保留执行git pull --rebase origin 分支名把远端提交合到本地再推送。确定本地提交是完整的、远端的改动都不要再考虑git push --force或git push --force-with-lease。但强制推送会覆盖远端历史多人协作的分支千万不要force一旦误伤队友的提交那场面很难收拾。--force-with-lease比--force安全它只有在远端分支没有你预期之外的提交时才允许推送相当于加了一道保险。8.3 大小写问题引发的bug文件大小写问题在Windows和macOS上坑过不少人。默认文件系统大小写不敏感你在一个环境创建了Utils.java另一个环境改成util.javagit可能不识别这是重命名还是新文件尤其跨平台协作时会导致编译找不到类。缓解方法git config core.ignorecase false但这个配置只影响后续操作已提交过的历史问题还是要手动处理。最稳妥的做法是先把这个文件改成一个临时名字比如util.bak提交一次再改回正确的大小写再提交一次。让git真正记录一次删除和一次新增这样不同平台都能强制同步。8.4 其他高频小坑速查整理了一张问题速查表遇到问题先对着查问题现象高频原因解决命令/方法Permission denied (publickey)SSH公钥未配置或配置错误ssh -T gitgitee.com排查检查~/.ssh文件推送被拒绝本地分支落后于远端git pull --rebase origin 分支名.gitignore不生效文件已被git跟踪git rm -r --cached 文件路径提交信息写错提交前没检查git commit --amend -m 新信息文件名显示成八进制乱码编码配置问题git config --global core.quotepath false提示no tracking information本地分支未关联远端git branch --set-upstream-toorigin/分支名 分支名误删提交手滑reset --hardgit reflog找回历史哈希还有一个我提了很多次但值得再强调的.gitignore不生效本质原因是文件已经被git跟踪了。git的ignore规则只对未跟踪文件生效想让它停用跟踪必须先git rm --cached再提交。最后再分享一个小技巧遇到拿不准的命令先git status看状态再git log看历史最后才决定用什么命令操作。这个顺序看起来简单但能避免绝大多数误操作。我现在遇到再复杂的git问题也还是靠这招稳住局面。多折腾几次这些命令自然就长在肌肉记忆里了。