尧图网页设计 
跑了几年项目我见过太多“手工作坊”式的代码管理方式代码靠压缩包备份文件名永远带着日期后缀某天改崩了想回退只能凭记忆一条条改回来给同事传代码用聊天软件发压缩包传完再手动对比差别。后来我强迫自己把Git和Gitee这套组合真正用起来才发现代码管理从手工作坊升级到正规军效率差距真的不是一星半点。这篇文章就是一份从零到一的Gitee和Git超详细实战指南覆盖Git安装、SSH配置、创建仓库、上传拉取、分支合并、IDE集成到常见报错排查适合刚接触编程的学生、需要交代码的毕业生以及刚入职想把本地项目推到公司仓库的新人。全程没有艰深的术语轰炸都是我在实际开发里反复踩坑后验证过的路径照着走就能跑通。1. 为什么要告别“手工作坊”先弄清楚Git和Gitee帮你解决了什么1.1 “手工作坊”式代码管理的几种死法我见过三种最典型的翻车现场。第一种是“改崩了回不去”。前一天功能还正常今天连续调了十几处突然整个页面变成白屏。你想着“回到昨天下午那个能跑的状态”翻开文件夹最快只能找到前天中午的压缩包昨天下午的没有备份。于是只能对着代码一点点打补丁后悔自己为什么不多存几次。第二种是“多设备不同步”。办公室里改了登录模块回家想继续发现U盘里是三天前的版本。回头把两台机器的代码拷到一起同名文件互相覆盖哪个新哪个旧只能靠肉眼猜。很多个人开发者其实是被这个问题逼到用Git的——不是因为协作而是因为自己都要被自己搞疯了。第三种是“协作靠发压缩包”。带实习生或者结对开发的时候经常出现A把整个项目压缩包发给BB改完再打包发回来。一来二去五六个版本没人说得清哪个是最新的某个修复是不是已经被合进去了。这种模式就算项目只有两个人也容易乱更别提多人协作。这些场景的本质都一样缺少一套记录改动、随时回溯、多人同屏的版本管理机制。Git就是专门解决这个问题的而Gitee是让这个机制跑在云端的落脚点。1.2 Git是什么Gitee又是什么别再混为一谈新手最容易混淆的点是Git和Gitee到底谁是谁做个不太严谨但好懂的类比。Git是一个分布式版本控制系统装在你电脑上负责为你的代码每一次改动生成一条历史记录。它像一个自带翻页索引的账本谁改的、改了什么、什么时候改的、因为什么理由改全部写得清清楚楚。而Gitee是一个托管Git仓库的云端平台你把本地仓库推到Gitee等于把账本的副本放进了云端保险柜换电脑、换同事、想展示代码随时可以从保险柜里取出来。可以这样记Git是引擎Gitee是停车场。引擎没有停车场也能转但有了停车场车才能停稳、才能给别人看。为什么会选Gitee而不是GitHub原因也很实际国内访问速度对新手更友好全中文的交互界面个人仓库免费私有仓库创建门槛低。很多学校和企业内部项目也都用Gitee学会了基本操作以后换GitLab、GitCode底层都是同一套Git命令熟悉成本很低。1.3 先记住核心工作流本地仓库、远程仓库、克隆、推送、拉取网上教程一上来就铺开一堆概念很容易把人劝退。其实新手只需要理解一条链路本地仓库、远程仓库、克隆、推送、拉取。本地工作目录就是眼前的项目文件夹。执行git init后这个目录会多出一个隐藏的.git文件夹本地仓库就诞生了。之后每做一次修改通过git add把变更放进暂存区再通过git commit生成一个带说明的版本记录。commit就是账本里的一条记录记录了改动的完整快照和作者信息。远程仓库就是你在Gitee上创建的仓库。把本地commit通过git push推上去别人或另一台机器就能看到。反过来你需要在另一台电脑上继续工作时用git clone把远程仓库整个复制到本地之后用git pull把远程新增的提交拉下来。那一开始到底要背哪几个命令我建议先背这六个git init、git add、git commit、git push、git pull、git clone。它们之间的关系见下表命令作用一句话类比git init把目录变成仓库给项目开一个账本git add把文件变更加入暂存区挑出要记账的条目git commit生成一次版本记录正式记入账本git push把本地提交推到远程把账本放进云端保险柜git pull拉取远程的新提交把云端最新账本取回来git clone复制远程仓库到本地从云端复制一整套账本理解一遍这张表后面所有操作都围绕它展开。2. 从零装好环境Windows下Git安装与基础配置2.1 Git下载与安装三个关键选项别乱动在Windows上装Git我推荐直接用官网的安装包git-scm.com下载Windows版本然后一路Next。但我不会告诉你“闭着眼点就行”这种不负责任的话因为有几个选项有必要解释一下。第一个是安装路径。默认C盘完全没问题如果你喜欢改到D盘注意路径里不要出现中文和空格避免后面某些工具路径解析出问题。第二个是“Adjusting your PATH environment”选默认的“Git from the command line and also from 3rd-party software”即可这一项保证了Git在CMD和PowerShell里也能直接敲出来。第三个是“Checkout Windows-style, commit Unix-style line endings”默认就好。这个选项处理换行符问题Windows用CRLFLinux/Mac用LFGit会自动转换新手保持默认最省事。装完打开一个CMD或者PowerShell敲一下这个命令验证是否成功git --version能输出版本号比如git version 2.43.0.windows.1就说明安装成功。同时你也会发现开始菜单里多了Git Bash、Git GUI这几个程序其中Git Bash是我们接下来要用的主力终端。2.2 安装后的第一件事配置user.name与user.emailGit装好之后第一件事不是急着建仓库而是先告诉Git你是谁。git commit生成记录时需要作者信息不配置的话提交要么失败要么显示一串系统默认的“unknown”。打开Git Bash执行git config --global user.name 你的用户名 git config --global user.email 你注册Gitee用的邮箱--global的意思是全局配置对这台机器上的所有仓库生效。如果你在公司项目里想用另一个身份可以在项目目录里不带--global再设置一遍该仓库内的配置会覆盖全局配置。查一下配置是否写对了git config --list会列出user.name、user.email等一堆配置项。这里给个真诚的建议user.name最好跟你的Gitee账号用户名一致user.email用Gitee注册邮箱。这样将来提交记录能正确关联你的Gitee账号头像、提交数统计都能对上如果随便起个名字提交记录里就是一个陌生人以后想认领非常麻烦。2.3 Git Bash一个比CMD更顺手的新手终端装完Git你会看到安装包附带了一个叫Git Bash的终端。它的外观和Linux终端很像支持ls、cd、cat这些Unix命令在Windows里提供接近Linux命令行的体验。对于平时只用CMD的小伙伴来说Git Bash最大的优点是“跟网上的教程不容易产生歧义”因为大多数Git教程的命令都是基于Unix风格写的两边的回车键、引号、粘贴快捷键习惯都不一样混着用很容易踩坑。更好用的一个入口是右键菜单。在任意文件夹里点右键选择“Git Bash Here”终端打开后就直接定位到了当前目录省去一堆cd操作。我自己的习惯是项目文件夹右键打开Git Bash所有Git操作全在里面执行很少去开什么IDE内嵌终端。这里顺便分享一个小习惯粘贴命令到Git Bash用ShiftInsert或者直接点终端窗口的右键菜单选Paste不要用快捷键CtrlV后者在部分Windows终端里无效。很多人刚上手时命令老是“粘贴不进去”其实就是这个细节。3. 打通本地与GiteeSSH密钥配置与仓库创建3.1 为什么推荐SSH而不是HTTPSGitee上的仓库地址有两种协议HTTPS和SSH。HTTPS地址长这样https://gitee.com/用户名/仓库名.gitSSH地址长这样gitgitee.com:用户名/仓库名.git。新手阶段容易遇到一个问题用HTTPS clone很顺利但每次push都要输一次用户名密码输多了就很烦。SSH方式则不同配置一次密钥之后以后push、pull全程免密。所以我推荐长期做开发的人直接用SSH省下来的时间虽然看起来不多但一旦你每天高频推送体验差异会非常明显。SSH原理其实也不难理解你的电脑生成一对密钥一个私钥自己保存和一个公钥放到服务器公钥想成一扇门锁私钥想成一把钥匙。连接时服务器用公钥验证这把“钥匙”配对成功就放行。整个过程不需要输入密码。常见选择对比如下协议推代码是否免密适合场景HTTPS否临时clone、偶尔协作、不方便配置SSH环境SSH是日常开发、高频推送、更换设备同步篇幅有限这篇文章后面都以SSH为主讲。3.2 生成SSH密钥一条命令搞定在Git Bash里执行ssh-keygen -t ed25519 -C 你注册Gitee的邮箱如果环境比较老、不支持ed25519算法可以改用RSAssh-keygen -t rsa -b 4096 -C 你注册Gitee的邮箱执行后一路回车即可密钥文件会默认保存在用户主目录的.ssh目录下文件名是id_ed25519和id_ed25519.pub。中间如果问“Enter passphrase”可以留空直接回车配合免密操作更顺滑如果设置密码短语安全性会更高一点但没配好反而容易忘记。完成后查看公钥内容cat ~/.ssh/id_ed25519.pub屏幕上会出现一串以ssh-ed25519开头或ssh-rsa开头的长文本这就是要复制粘贴到Gitee上的内容。提示.pub文件是公钥可以给任何人看同目录下的id_ed25519没有后缀是私钥绝对不能发给别人。把这个私钥文件保管好就相当于保管好自己仓库的钥匙。3.3 在Gitee上添加公钥并验证连接接下来登录Gitee鼠标移到右上角头像进入“设置”左侧菜单找到“SSH公钥”把刚才cat出来的公钥内容复制粘贴进去。“标题”随便填比如“我的Windows电脑”方便以后识别是哪台设备的密钥。填完点确定。然后回到Git Bash验证是否打通ssh -T gitgitee.com第一次会弹出一句“Are you sure you want to continue connecting”输入yes回车。如果配置成功终端会显示类似“Hi 你的用户名! Youve successfully authenticated, but Gitee does not provide shell access.”的信息意思是认证通过。如果报Permission denied先回头检查公钥是不是复制完整了、有没有多余的空行再检查一下本机加载的私钥ssh-add -l如果列表里没有你的私钥执行eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519再重新ssh -T验证。这一步也是很多人忽略的坑公钥配在Gitee上了但Windows的SSH agent没加载私钥死活认证不过。3.4 创建Gitee仓库仓库名与开源许可证怎么选登录Gitee右上角“”号选“新建仓库”进入创建页。仓库名这一步我建议养成好习惯用全小写英文加短横线组合比如my-first-project。不要用中文虽然Gitee支持中文仓库名但在Git命令行里输入中文路径名很容易出幺蛾子连复制粘贴都容易带乱码。仓库“路径”会自动根据名称生成可以手动改。创建页面里有一组选项是否初始化仓库是否添加.gitignore是否加开源许可证。如果此时本地已经有写好的项目我推荐不勾选初始化等本地代码直接推上来如果本地是空目录可以勾选初始化顺手生成README仓库页面不至于一片空白。开源许可证怎么选如果仓库设置为公开而且你有意让别人使用、分发你的代码建议选一个。MIT协议最宽松使用者几乎可以做任何事只要保留版权声明最适合个人工具和学习项目。Apache License 2.0相对更规范额外包含了专利授权条款适合准备长期发展的小组项目。GPL系列带有“传染性”要求衍生项目也必须开源适合希望社区回馈的场景。如果只是私有仓库自用许可证可以先不选以后开源时再补。3.5 一个仓库能包含子项目吗这个我经常被问到答案是能但要看你说的“子项目”是什么含义。如果你的意思是一个Gitee仓库里放几个小工具模块每个模块有独立的目录那完全没问题。Git仓库本身就是按目录组织的你可以建一个仓库叫my-tools下面放tools-a、tools-b两个目录各自提交互不影响远程仓库里也都是整体展示。这其实是很多开源项目的做法叫单仓多包管理成本最低。如果你的意思是两个子项目要各自独立版本历史、独立issue和独立权限那就要考虑git submodule或者直接把仓库拆分成多个仓库。submodule是Git提供的一种引用方式让一个仓库里嵌入另一个仓库的特定版本适合像公共库、SDK这种跨项目复用的场景。但它的操作复杂度明显更高新手不建议一上来就用。我给的建议很明确能放一个仓库就放一个仓库。真到了性能瓶颈或协作边界清晰的那天再拆不迟。过早拆分只会让仓库管理和协作流程翻倍变复杂。4. 第一行代码上云把本地项目推到Gitee4.1 初始化本地仓库本地项目已经在电脑上了现在要把它变成Git仓库。找到项目文件夹右键点击“Git Bash Here”然后执行git init这条命令会在当前目录下创建一个隐藏的.git文件夹里面存放仓库全部版本记录。执行后一般会提示“Initialized empty Git repository in ...”项目就正式获得了Git身份。这里要提一个在第3.4节埋下的坑如果你在Gitee创建仓库时勾选了“初始化仓库”远程仓库就有了一个初始的README提交。本地仓库此时是从空开始init的两边每个commit的历史是完全独立的。本地第一次push时Git会拒绝推送因为远程有本地没有的提交。临时解决办法很简单——如果本地已经有内容创建Gitee仓库时就不要选初始化如果选了就用4.3节的方法合并。4.2 添加、提交、推送到远程第一次push全程在项目目录里把文件加入暂存区并生成第一次提交git add . git commit -m first commit第一句git add .会把当前目录所有未被忽略的文件放入暂存区。第二句commit则生成一条带说明的版本记录。接着关联远程仓库。回到Gitee仓库首页复制SSH地址然后执行git remote add origin gitgitee.com:你的用户名/仓库名.git把远程仓库命名为origin是Git约定俗成的名字也可以叫别的但新手照默认识别起来最方便。最后推送git push -u origin master-u参数第一次使用会把本地的master分支和远程的master分支绑定起来之后只需要敲git push就能推送。如果远程仓库默认分支是main先把本地分支改名再推送git branch -M main git push -u origin main看到进度条走完输出类似“master - master”的信息说明第一次推送成功。打开Gitee仓库页面代码已经躺在云端了。4.3 第一次推送时最常见的报错很多新手第一次push都会看到一个吓人的红色报错To gitee.com:用户名/仓库名.git ! [rejected] master - master (non-fast-forward) error: failed to push some refs to ... hint: Updates were rejected because the remote contains work that you do翻译成人话就是远程仓库里有你没有的提交拒绝合并。出现这个报错要么是创建远程仓库时勾选了初始化要么是别人或另一台机器已经往仓库推送过代码。解决办法是先把远程的最新提交拉下来让本地和远程历史重新对齐再推送git pull --rebase origin master git push -u origin mastergit pull的--rebase参数会把本地提交“接”到远程历史之后整体提交线更干净不会多出一条合并提交。新手直接采用这个姿势能少踩很多坑。4.4 从Gitee拉取项目到本地在另外一台电脑上或者想重新下载自己的项目最简单的方式是git clonegit clone gitgitee.com:你的用户名/仓库名.git执行后当前目录下会生成一个以仓库名命名的文件夹里面包含了完整的代码、.git仓库历史并且自动配置好了origin远程地址。clone完成直接就可以继续开发不需要再git remote add。这里插一句为什么不要用网页上的“下载ZIP”因为ZIP包是代码的静态快照没有任何Git历史不能pull不能push拿到手等于回到了手工作坊。git clone虽然第一次耗时多一点但换来的是完整的版本演进。如果clone一半断了多数情况是网络不稳定重新执行一次git clone即可。如果网络环境实在不好也可以改用HTTPS地址clone连上后把远程地址再换成SSH方法见5.4节。不要因为一次失败就放弃git clone多试几次或者换个时段成功率都会高很多。5. 日常开发核心操作提交、回滚、分支合并5.1 git add、commit、push的黄金节奏仓库跑通后日常开发就在几个命令里循环。我给新手一个每次改代码都适用的节奏git status先看当前状态了解哪些文件被改动过哪些是新增的。有选择地把本次涉及的文件加入暂存git add 具体文件。谨慎使用git add .尤其多人协作时容易把无关文件甚至敏感文件一次性带进去。git commit -m 清晰说明这次改动信息写清楚点别人看历史能直接知道这一条提交干了什么。push之前先git pull --rebase把远程的新提交拉下来对齐。git push推送到远程。为什么要小步提交因为commit是回溯的单位。假设你今天写了三个功能中途第二个写坏了如果三个功能是三个commit你可以只回退第二个如果全混进一个commit神仙也难精准恢复。给commit写信息时参考这种格式“feat: 增加登录页验证码”、“fix: 修复订单列表分页错乱”、“docs: 更新README部署步骤”一看就懂。补充一个新手必知的概念.gitignore。项目里那些不该进仓库的文件比如编译产物target/、依赖目录node_modules/、IDE配置.idea/、日志文件都可以写在.gitignore里。写好后Git会直接忽略这些路径add .也不会误加入。一个简单的Java项目示例target/ *.class .idea/ *.iml5.2 分支是什么怎么合并分支是Git里最强大的设计之一。你可以把它理解成平行世界主分支master/main放稳定代码开发分支随便折腾等新功能验证通过了再把开发分支合并回主分支。实际的场景是这样周一开工你准备做用户中心模块。先创建并切换分支git switch -c feature/user-center这条命令一步完成“创建切换”。以后你在feature/user-center分支上随便写代码、随便提交都不会影响master分支。等模块写完了先切回主分支git switch master然后把开发分支合并进来git merge feature/user-center合并完成后开发分支可以删除git branch -d feature/user-center合并冲突是最常见的新手焦虑来源。两个人或者其他分支改了同一文件的同一行merge时Git会停下在文件中插入类似这样的冲突标记 HEAD 你当前分支的内容 被合并分支的内容 feature/user-center处理冲突不是用命令而是手动编辑文件把中间内容改成最终想要的样子删掉、、这些标记再add、commit。冲突本身不可怕可怕的是没看清楚就乱提交。我的习惯是冲突文件全部打开逐段确认再统一提交。5.3 commit写错了怎么办git commit --amendcommit提交完了才发现信息写错、或者漏了一个小文件怎么办不用急commit还没推送的情况下有一个专用的补救命令git commit --amend。改提交信息git commit --amend -m 正确的提交信息想补一个漏掉的文件git add 漏掉的文件 git commit --amend --no-edit--no-edit的意思是保留原有提交信息只是把漏掉的文件吸进上一次提交里。原理上讲amend会创建一个新的提交对象替换掉原来那一次提交提交哈希会改变。所以它有两条使用规则要记住一是只在commit尚未推送时使用二是如果已经推送了又非改不可可以用git push --force-with-lease强制更新但该操作会改变共享历史只能在极短时间窗口内、确认没有别人拉取时才做。平时最好不要碰强推这也是团队协作的基本礼貌。5.4 免密推送的收尾把HTTPS仓库换成SSH很多新手第一反应是直接选HTTPS clone顺手嘛。结果推送几次后就被“每次输密码”折磨到不行。这时其实不需要重新clone只需要把远程地址从HTTPS换成SSH。查看当前远程地址git remote -v修改origin的地址git remote set-url origin gitgitee.com:你的用户名/仓库名.git改完再git remote -v确认一下下次push就能享受SSH免密了。另一个“免密”的实现方式是让Git记住HTTPS账号密码比如Windows Credential Manager。但我不推荐多人共用电脑时这么做凭据管理器里存的是固定账号密码串号排查起来很麻烦。相比之下SSH密钥的归属更清晰换设备、删权限都可控这也是我整篇文章始终推荐SSH的原因。6. IDE无缝衔接IDEA和VSCode里的Gitee6.1 IntelliJ IDEA连接Gitee远程仓库不少同学用IDEA写代码但只在命令行里push其实IDEA自带的Git集成已经做得很完整把Gitee接进来后commit、push、pull都可以点按钮完成。第一种方式从Gitee直接把项目克隆到IDEA。打开IDEA选择File - New - Project from Version Control在URL框粘贴Gitee仓库的SSH地址选择存放目录点CloneIDEA会自己识别出项目结构并打开。第二种方式本地项目要关联远程仓库。打开项目后在顶部菜单Git - Manage Remotes里添加origin把SSH地址填入然后在Git菜单里选择Commit勾选要提交的文件填好提交信息再点Push推送框中确认目标仓库和分支即可。有两点要提醒IDEA本身不内置Git需要系统里先装好GitIDEA默认使用SSH连接密钥配置请参考第3节。如果你发现IDEA里每次push都弹窗口要账号密码检查Settings - Version Control - Git把SSH executable改成Native一般就能识别到本地密钥了。6.2 VSCode使用Gitee可视化操作同样够用VSCode的Git集成也很方便左侧的“源代码管理”面板CtrlShiftG就是日常操作入口。要在VSCode里克隆Gitee仓库先打开命令面板CtrlShiftP输入Git: Clone回车后粘贴仓库地址选择本地目录VSCode会自动打开这个项目。日常提交只需要三步在源代码管理面板里点击文件右侧的“”号将文件暂存在上方输入框填写提交信息然后点击“提交”按钮提交完成后再点一下“同步更改”VSCode会执行pull然后push把本地提交推送到Gitee。如果想看某一行代码是谁写的、哪次提交改的推荐安装GitLens插件直接在编辑器里提供逐行归属信息非常实用。如果VSCode里push时一直弹出账号密码大概率又是仓库地址用了HTTPS改用SSH即可方法见5.4节。6.3 再说一句命令行值不值得学每当我推荐直接在IDE里操作Git时总担心新手会因此完全绕过命令行。我的看法是IDE可以成为你的主操作台但命令行绝对值得掌握基础的那十来条。原因很简单形态各异的报错、突如其来的冲突、需要精准回退的复杂操作最终都会回到命令行。你见过谁用可视化工具解一个rebase冲突比命令行快的可能也有但少数。而且学会命令行之后换任何一套IDE、换任何平台你都不会有迁移成本因为命令是到处通用的。心态上不妨放宽只要本地有push过的版本Git里干错事都能恢复。删了分支有reflog。commit不见了有reset。放心大胆地试错这才是学Git最快的路子。7. 疑难杂症与排查实录7.1 fatal: not a git repository (or any of the parent directories): .git这个报错我几乎每个月都会看到有人问。出现它的场景通常是打开某个文件夹执行git status或git log结果终端甩你一句fatal: not a git repository (or any of the parent directories): .git。意思就是当前目录不是Git仓库父目录也不是。原因通常是这个目录根本没执行过git init或者没在clone下来的项目根目录里。排查顺序很固定先pwd看当前路径。再ls -a看看有没有.git目录。如果确定在仓库里但没有.git八成是.git被误删那只能重新git init版本历史丢了没办法。如果还没进仓库cd到项目根目录再操作。新手容易犯的小错误在项目子目录里执行Git命令而Git是在项目根目录init的。子目录本身如果是仓库内的一部分Git向上查找.git是没问题的但如果这个子目录并不在任何仓库里自然就报错。7.2 SSH认证失败两个高频场景SSH配好后push/pull偶尔会冒出来两种“认证失败”但人话完全不同。第一种是Connection timed out。报错样式ssh: connect to host gitee.com port 22: Connection timed out。这是22端口连不上多半是当前网络环境限制或封锁了22端口常见于公司网络、校园网络。Gitee对此有官方解法用443端口访问SSH服务。先用以下命令验证ssh -T -p 443 gitssh.gitee.com能认证通过的话把远程地址改成ssh://gitssh.gitee.com:443/用户名/仓库.git或者在用户目录的~/.ssh/config里配置Host段把Hostname指定为ssh.gitee.com、Port指定为443。要是懒得折腾临时把远程地址切回HTTPS也完全合法。第二种是Permission denied (publickey)。意思是密钥认证没通过。排查时先确认公钥已经完整粘贴到Gitee再检查ssh-add -l看私钥有没有被agent加载按3.3节的方法加载后再试。别忽视最简单的一环是不是复制公钥时漏了开头或者结尾的字符。7.3 清除Git账号密码缓存不小心用错误账号推送过或者输入密码时被记住后面怎么都切不回来这种问题通常出在HTTPS的凭据缓存上。Windows下最直接的操作打开控制面板 - 用户账户 - 凭据管理器 - Windows凭据在列表里找到git:https://gitee.com这一类条目点删除。下次push时会重新弹出账号密码输入框。如果还不行可能Git配置里绑定了credential.helper执行git config --global --unset credential.helper把全局的凭据助手去掉。之后再pushGit就不会再去凭据管理器里找了。个人建议如果这台电脑会多人使用或者只是临时开发机别开HTTPS的凭据保存用SSH密钥能避免掉90%的账号串号问题。7.4 Git LFS上传大文件到Gitee的正确姿势Gitee仓库里上传普通代码没什么问题但一旦涉及几十MB甚至几百MB的数据集、安装包、视频资源普通Git仓库会非常吃力仓库体积滚雪球。Git LFS就是干这个的把大文件用指针替换实际内容存到LFS存储服务仓库里的.git负担大幅减小。使用前先安装git lfs install然后在仓库里声明要跟踪的文件类型git lfs track *.zip git lfs track *.mp4执行后仓库里会出现一个.gitattributes文件把它一起提交到仓库里git add .gitattributes git commit -m add git lfs track git push origin master之后凡是以.zip、.mp4结尾的文件都会被LFS存储。其他人clone时Git会通过LFS指针自动拉取大文件内容。Gitee对LFS有明确的仓库大小和流量限制具体数值以官方最新说明为准不过大多数个人项目的中型资源都够用。遇到git lfs clone卡住的情况不少人会愣住。我的建议不要死磕git lfs clone改用普通git clone进目录后再执行git lfs pull把大文件补齐。两个步骤分开走哪个出问题都好排查。另外有一个相关命令git config --global --unset lfs.fetchexclude。如果有人之前设置过LFS排除规则导致某个大文件类型在fetch时被跳过后续执行该命令取消排除再git lfs pull把缺失的大文件拉下来仓库内容才算完整。7.5 Gitee Pages把仓库变成在线网页最后聊一个有点甜头的功能Gitee Pages。它可以把仓库里的静态文件直接部署成一个可公开访问的网页特别适合个人主页、文档站、前端demo演示。使用前有两个前提要完成Gitee的实名认证仓库要设置为公开。操作路径不复杂进入仓库首页在顶部的“服务”菜单里找到“Gitee Pages”点击新建选择要部署的分支和目录再点击部署即可。部署成功后会得到一个格式类似xxx.gitee.io的访问地址。前端初学者可以把写好的HTML页面推到仓库然后用Pages快速生成一个能展示的作品链接。提示Pages服务面向的是公开访问仓库内容等于对所有人开放。部署个人主页或demo时不要把密钥、数据库配置、联系方式这些敏感信息放进仓库里这些内容一旦公开即使删除历史推送也无济于事因为别人可能已经下载过了。Pages的具体规则和配额以Gitee官方页面当前说明为准。有空翻一翻比网上搬运的各种攻略靠谱。结尾通篇看下来从为什么需要Git到环境搭建、SSH打通、仓库创建、第一次推送再到分支、IDE集成、疑难排查、大文件管理基本覆盖了新手从零到一的全过程。我个人在实际操作中最深的体会是Git和Gitee真正改变的不是工具而是习惯——每个改动都留一条说明每版代码都有一个可回退的锚点这种安全感是手工作坊式管理给不了的。最后再分享一个小技巧如果你刚开始别试图把文档读完了再动手。先建一个测试仓库随便写几句代码走一遍init、add、commit、push、pull的完整链路。出错了也不要紧对照第7节的排查实录逐个解决。代码管理这种事一旦踏出第一步后面的路就顺了。 Git与Gitee实战指南：从零搭建版本控制工作流
跑了几年项目我见过太多“手工作坊”式的代码管理方式代码靠压缩包备份文件名永远带着日期后缀某天改崩了想回退只能凭记忆一条条改回来给同事传代码用聊天软件发压缩包传完再手动对比差别。后来我强迫自己把Git和Gitee这套组合真正用起来才发现代码管理从手工作坊升级到正规军效率差距真的不是一星半点。这篇文章就是一份从零到一的Gitee和Git超详细实战指南覆盖Git安装、SSH配置、创建仓库、上传拉取、分支合并、IDE集成到常见报错排查适合刚接触编程的学生、需要交代码的毕业生以及刚入职想把本地项目推到公司仓库的新人。全程没有艰深的术语轰炸都是我在实际开发里反复踩坑后验证过的路径照着走就能跑通。1. 为什么要告别“手工作坊”先弄清楚Git和Gitee帮你解决了什么1.1 “手工作坊”式代码管理的几种死法我见过三种最典型的翻车现场。第一种是“改崩了回不去”。前一天功能还正常今天连续调了十几处突然整个页面变成白屏。你想着“回到昨天下午那个能跑的状态”翻开文件夹最快只能找到前天中午的压缩包昨天下午的没有备份。于是只能对着代码一点点打补丁后悔自己为什么不多存几次。第二种是“多设备不同步”。办公室里改了登录模块回家想继续发现U盘里是三天前的版本。回头把两台机器的代码拷到一起同名文件互相覆盖哪个新哪个旧只能靠肉眼猜。很多个人开发者其实是被这个问题逼到用Git的——不是因为协作而是因为自己都要被自己搞疯了。第三种是“协作靠发压缩包”。带实习生或者结对开发的时候经常出现A把整个项目压缩包发给BB改完再打包发回来。一来二去五六个版本没人说得清哪个是最新的某个修复是不是已经被合进去了。这种模式就算项目只有两个人也容易乱更别提多人协作。这些场景的本质都一样缺少一套记录改动、随时回溯、多人同屏的版本管理机制。Git就是专门解决这个问题的而Gitee是让这个机制跑在云端的落脚点。1.2 Git是什么Gitee又是什么别再混为一谈新手最容易混淆的点是Git和Gitee到底谁是谁做个不太严谨但好懂的类比。Git是一个分布式版本控制系统装在你电脑上负责为你的代码每一次改动生成一条历史记录。它像一个自带翻页索引的账本谁改的、改了什么、什么时候改的、因为什么理由改全部写得清清楚楚。而Gitee是一个托管Git仓库的云端平台你把本地仓库推到Gitee等于把账本的副本放进了云端保险柜换电脑、换同事、想展示代码随时可以从保险柜里取出来。可以这样记Git是引擎Gitee是停车场。引擎没有停车场也能转但有了停车场车才能停稳、才能给别人看。为什么会选Gitee而不是GitHub原因也很实际国内访问速度对新手更友好全中文的交互界面个人仓库免费私有仓库创建门槛低。很多学校和企业内部项目也都用Gitee学会了基本操作以后换GitLab、GitCode底层都是同一套Git命令熟悉成本很低。1.3 先记住核心工作流本地仓库、远程仓库、克隆、推送、拉取网上教程一上来就铺开一堆概念很容易把人劝退。其实新手只需要理解一条链路本地仓库、远程仓库、克隆、推送、拉取。本地工作目录就是眼前的项目文件夹。执行git init后这个目录会多出一个隐藏的.git文件夹本地仓库就诞生了。之后每做一次修改通过git add把变更放进暂存区再通过git commit生成一个带说明的版本记录。commit就是账本里的一条记录记录了改动的完整快照和作者信息。远程仓库就是你在Gitee上创建的仓库。把本地commit通过git push推上去别人或另一台机器就能看到。反过来你需要在另一台电脑上继续工作时用git clone把远程仓库整个复制到本地之后用git pull把远程新增的提交拉下来。那一开始到底要背哪几个命令我建议先背这六个git init、git add、git commit、git push、git pull、git clone。它们之间的关系见下表命令作用一句话类比git init把目录变成仓库给项目开一个账本git add把文件变更加入暂存区挑出要记账的条目git commit生成一次版本记录正式记入账本git push把本地提交推到远程把账本放进云端保险柜git pull拉取远程的新提交把云端最新账本取回来git clone复制远程仓库到本地从云端复制一整套账本理解一遍这张表后面所有操作都围绕它展开。2. 从零装好环境Windows下Git安装与基础配置2.1 Git下载与安装三个关键选项别乱动在Windows上装Git我推荐直接用官网的安装包git-scm.com下载Windows版本然后一路Next。但我不会告诉你“闭着眼点就行”这种不负责任的话因为有几个选项有必要解释一下。第一个是安装路径。默认C盘完全没问题如果你喜欢改到D盘注意路径里不要出现中文和空格避免后面某些工具路径解析出问题。第二个是“Adjusting your PATH environment”选默认的“Git from the command line and also from 3rd-party software”即可这一项保证了Git在CMD和PowerShell里也能直接敲出来。第三个是“Checkout Windows-style, commit Unix-style line endings”默认就好。这个选项处理换行符问题Windows用CRLFLinux/Mac用LFGit会自动转换新手保持默认最省事。装完打开一个CMD或者PowerShell敲一下这个命令验证是否成功git --version能输出版本号比如git version 2.43.0.windows.1就说明安装成功。同时你也会发现开始菜单里多了Git Bash、Git GUI这几个程序其中Git Bash是我们接下来要用的主力终端。2.2 安装后的第一件事配置user.name与user.emailGit装好之后第一件事不是急着建仓库而是先告诉Git你是谁。git commit生成记录时需要作者信息不配置的话提交要么失败要么显示一串系统默认的“unknown”。打开Git Bash执行git config --global user.name 你的用户名 git config --global user.email 你注册Gitee用的邮箱--global的意思是全局配置对这台机器上的所有仓库生效。如果你在公司项目里想用另一个身份可以在项目目录里不带--global再设置一遍该仓库内的配置会覆盖全局配置。查一下配置是否写对了git config --list会列出user.name、user.email等一堆配置项。这里给个真诚的建议user.name最好跟你的Gitee账号用户名一致user.email用Gitee注册邮箱。这样将来提交记录能正确关联你的Gitee账号头像、提交数统计都能对上如果随便起个名字提交记录里就是一个陌生人以后想认领非常麻烦。2.3 Git Bash一个比CMD更顺手的新手终端装完Git你会看到安装包附带了一个叫Git Bash的终端。它的外观和Linux终端很像支持ls、cd、cat这些Unix命令在Windows里提供接近Linux命令行的体验。对于平时只用CMD的小伙伴来说Git Bash最大的优点是“跟网上的教程不容易产生歧义”因为大多数Git教程的命令都是基于Unix风格写的两边的回车键、引号、粘贴快捷键习惯都不一样混着用很容易踩坑。更好用的一个入口是右键菜单。在任意文件夹里点右键选择“Git Bash Here”终端打开后就直接定位到了当前目录省去一堆cd操作。我自己的习惯是项目文件夹右键打开Git Bash所有Git操作全在里面执行很少去开什么IDE内嵌终端。这里顺便分享一个小习惯粘贴命令到Git Bash用ShiftInsert或者直接点终端窗口的右键菜单选Paste不要用快捷键CtrlV后者在部分Windows终端里无效。很多人刚上手时命令老是“粘贴不进去”其实就是这个细节。3. 打通本地与GiteeSSH密钥配置与仓库创建3.1 为什么推荐SSH而不是HTTPSGitee上的仓库地址有两种协议HTTPS和SSH。HTTPS地址长这样https://gitee.com/用户名/仓库名.gitSSH地址长这样gitgitee.com:用户名/仓库名.git。新手阶段容易遇到一个问题用HTTPS clone很顺利但每次push都要输一次用户名密码输多了就很烦。SSH方式则不同配置一次密钥之后以后push、pull全程免密。所以我推荐长期做开发的人直接用SSH省下来的时间虽然看起来不多但一旦你每天高频推送体验差异会非常明显。SSH原理其实也不难理解你的电脑生成一对密钥一个私钥自己保存和一个公钥放到服务器公钥想成一扇门锁私钥想成一把钥匙。连接时服务器用公钥验证这把“钥匙”配对成功就放行。整个过程不需要输入密码。常见选择对比如下协议推代码是否免密适合场景HTTPS否临时clone、偶尔协作、不方便配置SSH环境SSH是日常开发、高频推送、更换设备同步篇幅有限这篇文章后面都以SSH为主讲。3.2 生成SSH密钥一条命令搞定在Git Bash里执行ssh-keygen -t ed25519 -C 你注册Gitee的邮箱如果环境比较老、不支持ed25519算法可以改用RSAssh-keygen -t rsa -b 4096 -C 你注册Gitee的邮箱执行后一路回车即可密钥文件会默认保存在用户主目录的.ssh目录下文件名是id_ed25519和id_ed25519.pub。中间如果问“Enter passphrase”可以留空直接回车配合免密操作更顺滑如果设置密码短语安全性会更高一点但没配好反而容易忘记。完成后查看公钥内容cat ~/.ssh/id_ed25519.pub屏幕上会出现一串以ssh-ed25519开头或ssh-rsa开头的长文本这就是要复制粘贴到Gitee上的内容。提示.pub文件是公钥可以给任何人看同目录下的id_ed25519没有后缀是私钥绝对不能发给别人。把这个私钥文件保管好就相当于保管好自己仓库的钥匙。3.3 在Gitee上添加公钥并验证连接接下来登录Gitee鼠标移到右上角头像进入“设置”左侧菜单找到“SSH公钥”把刚才cat出来的公钥内容复制粘贴进去。“标题”随便填比如“我的Windows电脑”方便以后识别是哪台设备的密钥。填完点确定。然后回到Git Bash验证是否打通ssh -T gitgitee.com第一次会弹出一句“Are you sure you want to continue connecting”输入yes回车。如果配置成功终端会显示类似“Hi 你的用户名! Youve successfully authenticated, but Gitee does not provide shell access.”的信息意思是认证通过。如果报Permission denied先回头检查公钥是不是复制完整了、有没有多余的空行再检查一下本机加载的私钥ssh-add -l如果列表里没有你的私钥执行eval $(ssh-agent -s) ssh-add ~/.ssh/id_ed25519再重新ssh -T验证。这一步也是很多人忽略的坑公钥配在Gitee上了但Windows的SSH agent没加载私钥死活认证不过。3.4 创建Gitee仓库仓库名与开源许可证怎么选登录Gitee右上角“”号选“新建仓库”进入创建页。仓库名这一步我建议养成好习惯用全小写英文加短横线组合比如my-first-project。不要用中文虽然Gitee支持中文仓库名但在Git命令行里输入中文路径名很容易出幺蛾子连复制粘贴都容易带乱码。仓库“路径”会自动根据名称生成可以手动改。创建页面里有一组选项是否初始化仓库是否添加.gitignore是否加开源许可证。如果此时本地已经有写好的项目我推荐不勾选初始化等本地代码直接推上来如果本地是空目录可以勾选初始化顺手生成README仓库页面不至于一片空白。开源许可证怎么选如果仓库设置为公开而且你有意让别人使用、分发你的代码建议选一个。MIT协议最宽松使用者几乎可以做任何事只要保留版权声明最适合个人工具和学习项目。Apache License 2.0相对更规范额外包含了专利授权条款适合准备长期发展的小组项目。GPL系列带有“传染性”要求衍生项目也必须开源适合希望社区回馈的场景。如果只是私有仓库自用许可证可以先不选以后开源时再补。3.5 一个仓库能包含子项目吗这个我经常被问到答案是能但要看你说的“子项目”是什么含义。如果你的意思是一个Gitee仓库里放几个小工具模块每个模块有独立的目录那完全没问题。Git仓库本身就是按目录组织的你可以建一个仓库叫my-tools下面放tools-a、tools-b两个目录各自提交互不影响远程仓库里也都是整体展示。这其实是很多开源项目的做法叫单仓多包管理成本最低。如果你的意思是两个子项目要各自独立版本历史、独立issue和独立权限那就要考虑git submodule或者直接把仓库拆分成多个仓库。submodule是Git提供的一种引用方式让一个仓库里嵌入另一个仓库的特定版本适合像公共库、SDK这种跨项目复用的场景。但它的操作复杂度明显更高新手不建议一上来就用。我给的建议很明确能放一个仓库就放一个仓库。真到了性能瓶颈或协作边界清晰的那天再拆不迟。过早拆分只会让仓库管理和协作流程翻倍变复杂。4. 第一行代码上云把本地项目推到Gitee4.1 初始化本地仓库本地项目已经在电脑上了现在要把它变成Git仓库。找到项目文件夹右键点击“Git Bash Here”然后执行git init这条命令会在当前目录下创建一个隐藏的.git文件夹里面存放仓库全部版本记录。执行后一般会提示“Initialized empty Git repository in ...”项目就正式获得了Git身份。这里要提一个在第3.4节埋下的坑如果你在Gitee创建仓库时勾选了“初始化仓库”远程仓库就有了一个初始的README提交。本地仓库此时是从空开始init的两边每个commit的历史是完全独立的。本地第一次push时Git会拒绝推送因为远程有本地没有的提交。临时解决办法很简单——如果本地已经有内容创建Gitee仓库时就不要选初始化如果选了就用4.3节的方法合并。4.2 添加、提交、推送到远程第一次push全程在项目目录里把文件加入暂存区并生成第一次提交git add . git commit -m first commit第一句git add .会把当前目录所有未被忽略的文件放入暂存区。第二句commit则生成一条带说明的版本记录。接着关联远程仓库。回到Gitee仓库首页复制SSH地址然后执行git remote add origin gitgitee.com:你的用户名/仓库名.git把远程仓库命名为origin是Git约定俗成的名字也可以叫别的但新手照默认识别起来最方便。最后推送git push -u origin master-u参数第一次使用会把本地的master分支和远程的master分支绑定起来之后只需要敲git push就能推送。如果远程仓库默认分支是main先把本地分支改名再推送git branch -M main git push -u origin main看到进度条走完输出类似“master - master”的信息说明第一次推送成功。打开Gitee仓库页面代码已经躺在云端了。4.3 第一次推送时最常见的报错很多新手第一次push都会看到一个吓人的红色报错To gitee.com:用户名/仓库名.git ! [rejected] master - master (non-fast-forward) error: failed to push some refs to ... hint: Updates were rejected because the remote contains work that you do翻译成人话就是远程仓库里有你没有的提交拒绝合并。出现这个报错要么是创建远程仓库时勾选了初始化要么是别人或另一台机器已经往仓库推送过代码。解决办法是先把远程的最新提交拉下来让本地和远程历史重新对齐再推送git pull --rebase origin master git push -u origin mastergit pull的--rebase参数会把本地提交“接”到远程历史之后整体提交线更干净不会多出一条合并提交。新手直接采用这个姿势能少踩很多坑。4.4 从Gitee拉取项目到本地在另外一台电脑上或者想重新下载自己的项目最简单的方式是git clonegit clone gitgitee.com:你的用户名/仓库名.git执行后当前目录下会生成一个以仓库名命名的文件夹里面包含了完整的代码、.git仓库历史并且自动配置好了origin远程地址。clone完成直接就可以继续开发不需要再git remote add。这里插一句为什么不要用网页上的“下载ZIP”因为ZIP包是代码的静态快照没有任何Git历史不能pull不能push拿到手等于回到了手工作坊。git clone虽然第一次耗时多一点但换来的是完整的版本演进。如果clone一半断了多数情况是网络不稳定重新执行一次git clone即可。如果网络环境实在不好也可以改用HTTPS地址clone连上后把远程地址再换成SSH方法见5.4节。不要因为一次失败就放弃git clone多试几次或者换个时段成功率都会高很多。5. 日常开发核心操作提交、回滚、分支合并5.1 git add、commit、push的黄金节奏仓库跑通后日常开发就在几个命令里循环。我给新手一个每次改代码都适用的节奏git status先看当前状态了解哪些文件被改动过哪些是新增的。有选择地把本次涉及的文件加入暂存git add 具体文件。谨慎使用git add .尤其多人协作时容易把无关文件甚至敏感文件一次性带进去。git commit -m 清晰说明这次改动信息写清楚点别人看历史能直接知道这一条提交干了什么。push之前先git pull --rebase把远程的新提交拉下来对齐。git push推送到远程。为什么要小步提交因为commit是回溯的单位。假设你今天写了三个功能中途第二个写坏了如果三个功能是三个commit你可以只回退第二个如果全混进一个commit神仙也难精准恢复。给commit写信息时参考这种格式“feat: 增加登录页验证码”、“fix: 修复订单列表分页错乱”、“docs: 更新README部署步骤”一看就懂。补充一个新手必知的概念.gitignore。项目里那些不该进仓库的文件比如编译产物target/、依赖目录node_modules/、IDE配置.idea/、日志文件都可以写在.gitignore里。写好后Git会直接忽略这些路径add .也不会误加入。一个简单的Java项目示例target/ *.class .idea/ *.iml5.2 分支是什么怎么合并分支是Git里最强大的设计之一。你可以把它理解成平行世界主分支master/main放稳定代码开发分支随便折腾等新功能验证通过了再把开发分支合并回主分支。实际的场景是这样周一开工你准备做用户中心模块。先创建并切换分支git switch -c feature/user-center这条命令一步完成“创建切换”。以后你在feature/user-center分支上随便写代码、随便提交都不会影响master分支。等模块写完了先切回主分支git switch master然后把开发分支合并进来git merge feature/user-center合并完成后开发分支可以删除git branch -d feature/user-center合并冲突是最常见的新手焦虑来源。两个人或者其他分支改了同一文件的同一行merge时Git会停下在文件中插入类似这样的冲突标记 HEAD 你当前分支的内容 被合并分支的内容 feature/user-center处理冲突不是用命令而是手动编辑文件把中间内容改成最终想要的样子删掉、、这些标记再add、commit。冲突本身不可怕可怕的是没看清楚就乱提交。我的习惯是冲突文件全部打开逐段确认再统一提交。5.3 commit写错了怎么办git commit --amendcommit提交完了才发现信息写错、或者漏了一个小文件怎么办不用急commit还没推送的情况下有一个专用的补救命令git commit --amend。改提交信息git commit --amend -m 正确的提交信息想补一个漏掉的文件git add 漏掉的文件 git commit --amend --no-edit--no-edit的意思是保留原有提交信息只是把漏掉的文件吸进上一次提交里。原理上讲amend会创建一个新的提交对象替换掉原来那一次提交提交哈希会改变。所以它有两条使用规则要记住一是只在commit尚未推送时使用二是如果已经推送了又非改不可可以用git push --force-with-lease强制更新但该操作会改变共享历史只能在极短时间窗口内、确认没有别人拉取时才做。平时最好不要碰强推这也是团队协作的基本礼貌。5.4 免密推送的收尾把HTTPS仓库换成SSH很多新手第一反应是直接选HTTPS clone顺手嘛。结果推送几次后就被“每次输密码”折磨到不行。这时其实不需要重新clone只需要把远程地址从HTTPS换成SSH。查看当前远程地址git remote -v修改origin的地址git remote set-url origin gitgitee.com:你的用户名/仓库名.git改完再git remote -v确认一下下次push就能享受SSH免密了。另一个“免密”的实现方式是让Git记住HTTPS账号密码比如Windows Credential Manager。但我不推荐多人共用电脑时这么做凭据管理器里存的是固定账号密码串号排查起来很麻烦。相比之下SSH密钥的归属更清晰换设备、删权限都可控这也是我整篇文章始终推荐SSH的原因。6. IDE无缝衔接IDEA和VSCode里的Gitee6.1 IntelliJ IDEA连接Gitee远程仓库不少同学用IDEA写代码但只在命令行里push其实IDEA自带的Git集成已经做得很完整把Gitee接进来后commit、push、pull都可以点按钮完成。第一种方式从Gitee直接把项目克隆到IDEA。打开IDEA选择File - New - Project from Version Control在URL框粘贴Gitee仓库的SSH地址选择存放目录点CloneIDEA会自己识别出项目结构并打开。第二种方式本地项目要关联远程仓库。打开项目后在顶部菜单Git - Manage Remotes里添加origin把SSH地址填入然后在Git菜单里选择Commit勾选要提交的文件填好提交信息再点Push推送框中确认目标仓库和分支即可。有两点要提醒IDEA本身不内置Git需要系统里先装好GitIDEA默认使用SSH连接密钥配置请参考第3节。如果你发现IDEA里每次push都弹窗口要账号密码检查Settings - Version Control - Git把SSH executable改成Native一般就能识别到本地密钥了。6.2 VSCode使用Gitee可视化操作同样够用VSCode的Git集成也很方便左侧的“源代码管理”面板CtrlShiftG就是日常操作入口。要在VSCode里克隆Gitee仓库先打开命令面板CtrlShiftP输入Git: Clone回车后粘贴仓库地址选择本地目录VSCode会自动打开这个项目。日常提交只需要三步在源代码管理面板里点击文件右侧的“”号将文件暂存在上方输入框填写提交信息然后点击“提交”按钮提交完成后再点一下“同步更改”VSCode会执行pull然后push把本地提交推送到Gitee。如果想看某一行代码是谁写的、哪次提交改的推荐安装GitLens插件直接在编辑器里提供逐行归属信息非常实用。如果VSCode里push时一直弹出账号密码大概率又是仓库地址用了HTTPS改用SSH即可方法见5.4节。6.3 再说一句命令行值不值得学每当我推荐直接在IDE里操作Git时总担心新手会因此完全绕过命令行。我的看法是IDE可以成为你的主操作台但命令行绝对值得掌握基础的那十来条。原因很简单形态各异的报错、突如其来的冲突、需要精准回退的复杂操作最终都会回到命令行。你见过谁用可视化工具解一个rebase冲突比命令行快的可能也有但少数。而且学会命令行之后换任何一套IDE、换任何平台你都不会有迁移成本因为命令是到处通用的。心态上不妨放宽只要本地有push过的版本Git里干错事都能恢复。删了分支有reflog。commit不见了有reset。放心大胆地试错这才是学Git最快的路子。7. 疑难杂症与排查实录7.1 fatal: not a git repository (or any of the parent directories): .git这个报错我几乎每个月都会看到有人问。出现它的场景通常是打开某个文件夹执行git status或git log结果终端甩你一句fatal: not a git repository (or any of the parent directories): .git。意思就是当前目录不是Git仓库父目录也不是。原因通常是这个目录根本没执行过git init或者没在clone下来的项目根目录里。排查顺序很固定先pwd看当前路径。再ls -a看看有没有.git目录。如果确定在仓库里但没有.git八成是.git被误删那只能重新git init版本历史丢了没办法。如果还没进仓库cd到项目根目录再操作。新手容易犯的小错误在项目子目录里执行Git命令而Git是在项目根目录init的。子目录本身如果是仓库内的一部分Git向上查找.git是没问题的但如果这个子目录并不在任何仓库里自然就报错。7.2 SSH认证失败两个高频场景SSH配好后push/pull偶尔会冒出来两种“认证失败”但人话完全不同。第一种是Connection timed out。报错样式ssh: connect to host gitee.com port 22: Connection timed out。这是22端口连不上多半是当前网络环境限制或封锁了22端口常见于公司网络、校园网络。Gitee对此有官方解法用443端口访问SSH服务。先用以下命令验证ssh -T -p 443 gitssh.gitee.com能认证通过的话把远程地址改成ssh://gitssh.gitee.com:443/用户名/仓库.git或者在用户目录的~/.ssh/config里配置Host段把Hostname指定为ssh.gitee.com、Port指定为443。要是懒得折腾临时把远程地址切回HTTPS也完全合法。第二种是Permission denied (publickey)。意思是密钥认证没通过。排查时先确认公钥已经完整粘贴到Gitee再检查ssh-add -l看私钥有没有被agent加载按3.3节的方法加载后再试。别忽视最简单的一环是不是复制公钥时漏了开头或者结尾的字符。7.3 清除Git账号密码缓存不小心用错误账号推送过或者输入密码时被记住后面怎么都切不回来这种问题通常出在HTTPS的凭据缓存上。Windows下最直接的操作打开控制面板 - 用户账户 - 凭据管理器 - Windows凭据在列表里找到git:https://gitee.com这一类条目点删除。下次push时会重新弹出账号密码输入框。如果还不行可能Git配置里绑定了credential.helper执行git config --global --unset credential.helper把全局的凭据助手去掉。之后再pushGit就不会再去凭据管理器里找了。个人建议如果这台电脑会多人使用或者只是临时开发机别开HTTPS的凭据保存用SSH密钥能避免掉90%的账号串号问题。7.4 Git LFS上传大文件到Gitee的正确姿势Gitee仓库里上传普通代码没什么问题但一旦涉及几十MB甚至几百MB的数据集、安装包、视频资源普通Git仓库会非常吃力仓库体积滚雪球。Git LFS就是干这个的把大文件用指针替换实际内容存到LFS存储服务仓库里的.git负担大幅减小。使用前先安装git lfs install然后在仓库里声明要跟踪的文件类型git lfs track *.zip git lfs track *.mp4执行后仓库里会出现一个.gitattributes文件把它一起提交到仓库里git add .gitattributes git commit -m add git lfs track git push origin master之后凡是以.zip、.mp4结尾的文件都会被LFS存储。其他人clone时Git会通过LFS指针自动拉取大文件内容。Gitee对LFS有明确的仓库大小和流量限制具体数值以官方最新说明为准不过大多数个人项目的中型资源都够用。遇到git lfs clone卡住的情况不少人会愣住。我的建议不要死磕git lfs clone改用普通git clone进目录后再执行git lfs pull把大文件补齐。两个步骤分开走哪个出问题都好排查。另外有一个相关命令git config --global --unset lfs.fetchexclude。如果有人之前设置过LFS排除规则导致某个大文件类型在fetch时被跳过后续执行该命令取消排除再git lfs pull把缺失的大文件拉下来仓库内容才算完整。7.5 Gitee Pages把仓库变成在线网页最后聊一个有点甜头的功能Gitee Pages。它可以把仓库里的静态文件直接部署成一个可公开访问的网页特别适合个人主页、文档站、前端demo演示。使用前有两个前提要完成Gitee的实名认证仓库要设置为公开。操作路径不复杂进入仓库首页在顶部的“服务”菜单里找到“Gitee Pages”点击新建选择要部署的分支和目录再点击部署即可。部署成功后会得到一个格式类似xxx.gitee.io的访问地址。前端初学者可以把写好的HTML页面推到仓库然后用Pages快速生成一个能展示的作品链接。提示Pages服务面向的是公开访问仓库内容等于对所有人开放。部署个人主页或demo时不要把密钥、数据库配置、联系方式这些敏感信息放进仓库里这些内容一旦公开即使删除历史推送也无济于事因为别人可能已经下载过了。Pages的具体规则和配额以Gitee官方页面当前说明为准。有空翻一翻比网上搬运的各种攻略靠谱。结尾通篇看下来从为什么需要Git到环境搭建、SSH打通、仓库创建、第一次推送再到分支、IDE集成、疑难排查、大文件管理基本覆盖了新手从零到一的全过程。我个人在实际操作中最深的体会是Git和Gitee真正改变的不是工具而是习惯——每个改动都留一条说明每版代码都有一个可回退的锚点这种安全感是手工作坊式管理给不了的。最后再分享一个小技巧如果你刚开始别试图把文档读完了再动手。先建一个测试仓库随便写几句代码走一遍init、add、commit、push、pull的完整链路。出错了也不要紧对照第7节的排查实录逐个解决。代码管理这种事一旦踏出第一步后面的路就顺了。