做视觉SLAM和激光雷达定位的同行应该都有类似的经历在Ubuntu 20.04上折腾完Fast-LIO2的依赖、编译和跑包之后第一反应是“终于能用了”第二反应就是“代码这么珍贵可不能丢”。尤其当你改过参数、调过CMakeLists、写过自己的配置文件再不备份一次磁盘扩容或者误删就能让你回到解放前。我的做法是把本地Fast-LIO2工作区完整推到Gitee仓库既能备份也方便换机器时快速拉取还能把过程中的版本节点留痕。整个过程看着简单但实际操作中坑不少——SSH密钥配对失败、分支名对不上、远程仓库里多了初始化文件导致push被拒、Fast-LIO2自带的子模块没拉全、编译目录误传上去占用仓库容量……这些问题单独看都能解决串在一起就特别容易劝退新手。这篇东西就按我实际操作的顺序来写从环境检查到仓库创建从SSH配置到第一次push成功再到那些非常典型的报错和排查思路尽量一步不落。你在Ubuntu 20.04上部署过Fast-LIO2、想把它安全托管到Gitee的话照着走基本不会卡壳如果只是为了学习git和Gitee的配合同样可以拿来当一套完整案例。1. 上传前先想明白Fast-LIO2 推 Gitee难点到底在哪很多教程一上来就让人敲git add、git commit、git push感觉跟背单词一样。真要自己上手最先卡住的往往不是命令而是思路这段代码到底应该以什么形式出现在Gitee上本地文件和远程仓库之间是什么关系为什么明明推送了却提示失败。1.1 先确认你手上这份 Fast-LIO2 是什么状态Fast-LIO2 的源码主要来自开源社区的维护自己在Ubuntu 20.04上操作时通常会碰到几种不同状态从原始仓库直接克隆下来的干净源码基本没改过配置已经编译过并且修改过config/目录下的yaml参数或者替换过自己的点云驱动做了二次开发添加了新的回调函数、新的消息类型甚至把ROS1版本改成了自己项目专用的分支在原有仓库基础上加了不少.bag数据包、pcd地图、日志文件。不同状态对应不同的上传策略。比如第二种和第三种状态重点要保源码和配置第四种状态就必须警惕大文件Gitee虽然不像某些国外平台那样对单文件限制卡得死但动辄几百MB的bag文件推上去轻则仓库臃肿重则push超时。所以在动手之前先花五分钟看清楚自己手上这段代码的“底细”好过推到一半再回头清理。1.2 为什么是 Gitee而不是其他代码托管平台Fast-LIO2 的原始仓库主要在GitHub上但国内访问GitHub的clone速度经常不稳定加上很多Fast-LIO2使用者都在同一个局域网环境或内网环境开发Gitee在国内服务器拉取速度快、稳定、还不容易中断更适合作为日常备份和团队协作的中转点。另一个重要原因是Gitee的私有仓库和成员管理功能对个人开发者免费你把Fast-LIO2的定制代码设为私有仓库只给实验室同事开权限既不用担心代码外流又能避免开源协议层面的尴尬。当然还有一个现实因素如果之后要在不同电脑上部署同一套Fast-LIO2环境从Gitee拉代码比从U盘拷来拷去省事得多。仓库托管好之后新机器上只需要安装好依赖然后git clone下来直接编译环境一致性会好很多。1.3 整条链路的五个关键环节把Fast-LIO2推到Gitee本质上是一个“本地文件 - git版本管理 - 远程仓库”的过程。我把它拆成五个环节每一个环节都有一个最常见的坑环境准备Ubuntu 20.04上有没有gitgit版本是否过老认证配置用SSH公钥还是HTTPS密码密钥有没有配对正确仓库创建Gitee仓库里的初始化文件会不会和本地仓库冲突本地关联remote add加错地址、分支名不一致推送过程忽略文件没写好把build、devel等编译产物和bag文件一并推上去。后文基本就按这条链路展开你现在心里有个谱就行。2. Ubuntu 20.04 本地环境准备没有 git 和 SSH后续全白搭我第一次操作的时候以为Ubuntu 20.04装完系统就自带全套环境结果git --version一敲提示找不到命令。装好git之后又发现ssh-keygen也不在默认路径里折腾了一圈才把基础工具配齐。这里就不再让你走弯路。2.1 检查并安装 git、curl 和 openssh-clientUbuntu 20.04 的软件源里自带git版本通常在2.25左右对Gitee和Fast-LIO2这种体量的项目来说完全够用。打开终端依次执行git --version curl --version ssh -V如果你能看到对应版本号说明基础工具齐全。如果提示Command git not found就执行sudo apt update sudo apt install -y git curl openssh-client注意这里不要用sudo apt install git-core有些教程会这么写但 Ubuntu 的git-core包和真正的 git 并不是同一个东西装上之后命令可能还是用不了。apt源建议改成国内的镜像源后面安装其他依赖也会快很多。git 装好之后还要确认一下全局配置。很多第一次用git的人忽略这一步commit之后发现提交人信息是一串随机字符串推到Gitee上显示的名字和邮箱也是错的。执行以下两条命令改成你自己的信息git config --global user.name 你的名字 git config --global user.email 你的邮箱example.com这里有个细节user.email 最好和你Gitee账号的邮箱保持一致。否则你在本地commit的记录推到Gitee后不会自动关联到账号头像排查提交历史时也不方便。2.2 生成 SSH 密钥并加入 ssh-agentSSH密钥其实相当于一把“钥匙”公钥放在Gitee上私钥留在本地。之后每次push、pull都不需要输密码。生成密钥的命令ssh-keygen -t ed25519 -C 你的邮箱example.com一路回车即可默认密钥位置是~/.ssh/id_ed25519。如果你之前生成过其他密钥这里会让你确认是否覆盖我建议不要覆盖旧密钥而是指定一个新名字例如ssh-keygen -t ed25519 -C 你的邮箱example.com -f ~/.ssh/gitee_ed25519生成之后把私钥加入到ssh-agent中eval $(ssh-agent -s) ssh-add ~/.ssh/gitee_ed255192.3 查看公钥并配置到 Gitee需要复制到Gitee的是.pub后缀的公钥文件cat ~/.ssh/gitee_ed25519.pub把输出的内容全部复制注意不要多复制空格和换行。然后登录Gitee网页端进入“设置 - SSH公钥”把公钥粘贴到框中标题可以写“Ubuntu20.04-FastLIO2”。配置完成之后用下面这条命令验证是否打通ssh -T gitgitee.com如果看到类似Hi 你的用户名! Youve successfully authenticated, but GITEE.COM does not provide shell access.的提示说明SSH配置成功。如果你看到Permission denied (publickey)优先检查公钥有没有复制全、Gitee上的公钥和本地私钥是不是同一对。实测经验很多人配置完SSH之后直接去git clone结果还是要求输密码多半是因为clone的时候用了HTTPS地址而不是SSH地址。这里先记着后面说远程地址的时候会专门强调。3. Gitee 仓库创建参数别乱选特别是许可证仓库参数选错不会立刻报错但会影响后续使用。尤其Fast-LIO2这种带着开源协议的项目许可证选错对个人使用影响不大真要做商业落地或公开发布容易埋雷。3.1 仓库名称、路径和可见性登录Gitee之后点击右上角“”号选择“新建仓库”。会出现一组参数仓库名称建议用fast-lio2或fast_lio2少用空格和中文后续clone和脚本调用都省心路径自动根据仓库名称生成也可以自己改但保持和仓库名一致最保险仓库介绍随便填比如“Fast-LIO2 在 Ubuntu 20.04 下的定制源码与配置”是否开源个人备份选“私有”团队协作选“私有”后添加成员代码想公开分享再选“公开”。这里我强烈建议选私有仓库。Fast-LIO2本身是开源项目但你在上面加的配置、点云数据路径、标定参数很可能包含自己传感器的硬件信息没必要全公开。3.2 开源许可证怎么选Fast-LIO2 与 GPL-2.0 的连带影响Gitee创建仓库页面会有一个“选择开源许可证”的选项常见的有MIT、Apache-2.0、GPL-3.0、GPL-2.0等。很多教程会告诉你随便选一个但这里最好认真看一下Fast-LIO2的上游许可证。Fast-LIO2 原始仓库采用的是GPL-2.0协议。这意味着如果你基于它二次开发并且对外分发代码那么整个项目在原则上也需要以GPL-2.0或兼容协议发布。如果你只是把仓库设为私有自己用、实验室用这一条约束基本感受不到可一旦你打算把定制版Fast-LIO2开源出去却选了MIT协议这就有协议冲突风险。所以我的建议是私有仓库直接选“不使用许可证”确定要开源的就选GPL-2.0并保留原始作者的版权声明别把上游协议信息删了。万一后面真要做商业产品再去单独找专业意见这里不是网上查几条问答就能定论的。3.3 初始化仓库时README、.gitignore 别急着勾Gitee在创建仓库时会让你勾选“使用Readme文件初始化这个仓库”、“使用Gitee的.gitignore模板”、“使用Apache-2.0 License”等选项。如果你是第一次把一个已存在的本地项目推上去我建议这三个选项都先不勾直接创建空白仓库。原因很简单远程仓库一旦初始化了README本地代码提交后推送时就会和远程产生“两套不相干的提交”出现Non-fast-forward的冲突提示处理起来多一步。对不熟悉git的新手来说这是最常见的劝退点。你可能想问那README文件什么时候加等第一次推送成功之后直接在Gitee网页端在线编辑或者本地添加后重新推送都可以。这样远程仓库一开始就是干净的避免冲突。4. 本地代码与远程仓库建立连接一个地址错误能卡半小时Fast-LIO2的代码在~/catkin_ws/src/FAST_LIO这种目录下也可能在你自己的工作目录里。先把终端cd到项目根目录然后依次执行下面的操作。4.1 HTTPS 还是 SSH我为什么推荐 SSHGitee仓库创建完成后网页上会显示两种远程地址HTTPS方式https://gitee.com/你的用户名/fast-lio2.gitSSH方式gitgitee.com:你的用户名/fast-lio2.gitHTTPS方式的好处是配置简单第一次推送时输入用户名和密码即可。但这里有个坑Gitee在HTTPS方式下密码并不是你登录网页的密码而是需要先在设置里生成“私人令牌”来作为密码。很多人第一次用HTTPS推送怎么输密码都提示认证失败就是这个原因。SSH方式则没有这个问题只要之前配置好了密钥后续push、pull、clone都不需要再输入任何机密信息。所以我建议你直接使用SSH地址。注意如果本地已经配置了多个SSH密钥比如一个给GitHub用一个给Gitee用需要在~/.ssh/config文件里写好对应的Host配置否则ssh可能默认把Gitee的流量也交给GitHub那把私钥导致认证失败。具体配置可以这样Host gitee.com HostName gitee.com User git IdentityFile ~/.ssh/gitee_ed255194.2 初始化本地仓库并关联远程进入Fast-LIO2目录执行git init git remote add origin gitgitee.com:你的用户名/fast-lio2.git用git remote -v检查远程地址git remote -v正常会输出两行分别是fetch和push的地址。如果你发现地址填错了可以重新设置git remote set-url origin gitgitee.com:你的用户名/fast-lio2.git4.3 Fast-LIO2 目录下必须提前准备的 .gitignoreFast-LIO2 编译之后目录里会多出build、devel、install等文件夹如果你是用catkin工作空间编译的话里面全是编译中间文件和可执行文件动辄几个GB绝对不能进git仓库。还有常见的.bag数据文件、pcd点云文件、*.log日志文件都不该占仓库空间。在项目根目录创建.gitignore文件写清楚忽略规则# 编译与运行产物 build/ devel/ install/ logs/ # 点云与数据集 *.bag *.bag.active *.pcd *.ply # 日志和临时文件 *.log *.tmp *.swp .cache/ # IDE 配置 .vscode/ .idea/这里再强调一下.gitignore只对“还没有被git跟踪的文件”生效。如果你一开始就把build目录加进去了之后再在.gitignore里写build/已经跟踪的文件不会被自动忽略。需要手动移除git rm -r --cached build--cached参数的意思是只从git索引中移除不删除本地实际文件这个操作很安全。4.4 子模块问题Fast-LIO2 的依赖目录别遗漏Fast-LIO2 在部署时经常会用到其它功能包比如livox_ros_driver2、ikd-Tree等。如果原始仓库是通过git clone --recurse-submodules拉下来的那本地项目里会存在一些子模块目录子模块通常是一个独立的git仓库链接。推送到Gitee时如果子模块对应的远程地址没改别人clone你的仓库后就能正常拉取子模块但如果你命名的子模块地址指向GitHub而目标机器访问GitHub不方便clone依然会卡住。所以如果Fast-LIO2仓库里带有子模块建议把每个子模块也推到Gitee对应的仓库然后修改主仓库里的.gitmodules文件把子模块地址改成Gitee的地址。这样整个环境就能完全依赖Gitee完成拉取。子模块多的话这一步比较繁琐但对后续换机器部署会省很多事。5. 推送代码全流程从第一次 commit 到 push 成功现在环境和仓库都准备好了进入核心环节。Fast-LIO2目录里可能已经有修改过的文件也可能是一个完整的新项目整个提交流程是一样的。5.1 第一次提交的完整命令顺序# 1. 查看当前git状态确认哪些文件会被跟踪 git status # 2. 将所有改动加入暂存区 git add . # 3. 查看暂存区里有哪些文件再确认一遍有没有误加入的大文件 git status # 4. 提交并写好信息 git commit -m Init Fast-LIO2 customized config # 5. 推送到远程仓库并设置上游分支 git push -u origin master这里面最容易被忽视的是第3步。Fast-LIO2项目如果编译过git status里很容易出现build、devel这些目录。就算你在.gitignore里写了忽略规则第一次git add .之前仍然建议看一眼状态。如果你发现不想提交的文件已经在暂存区里了可以用git rm -r --cached build然后再重新git add .。5.2 分支名不一致master 还是 main很多人在push时会遇到一个奇怪的现象本地提示一切正常但Gitee仓库里看不到提交记录或者提示error: src refspec main does not match any。原因很简单Gitee新建仓库时默认分支名可能是master取决于你在Gitee设置里的偏好而有些教程的示例和本地git默认初始化分支名可能是master或main两边对不上。查看本地当前分支名git branch如果本地是master远程仓库也是master直接执行git push -u origin master。如果远程默认分支是main你可以把本地分支改名后推送git branch -m master main git push -u origin main更简单的方式是忽略名字直接用git push -u origin HEAD:master把当前HEAD分支推送到远程的master分支前提是远程仓库是空的或者允许覆盖。5.3 远程仓库已经有文件时先 pull 再 push如果你在创建Gitee仓库时勾选了初始化README或者后来通过网页端添加过文件本地提交后直接push会报hint: Updates were rejected because the remote contains work that you do not have locally。这个问题有两个处理思路方案一把远程文件拉下来合并再推送。git pull origin master --allow-unrelated-histories git push origin master--allow-unrelated-histories很重要。因为本地仓库和远程仓库是两套没有共同祖先的提交历史不加这个参数会直接拒绝合并。方案二如果远程文件不重要直接强制覆盖不推荐会丢文件。git push -f origin master我个人在第一次操作时踩过这个坑之后Gitee建仓库一律不初始化任何文件。等推送成功了再在Gitee网页端添加README和说明文档一步到位省得跟“拒绝推送”较劲。5.4 推送成功后的验证push完成后别急着关终端。先在Gitee网页上刷新仓库页面确认一下代码文件都进去了没有出现build目录和过大的数据文件提交人和提交时间正确。如果发现最后几个文件是乱码或者提交人不是自己多半是git config的user.name和user.email没配对可以改完全局配置后重新提交。还可以用命令验证远程分支git branch -a git log --oneline --graph看到远程分支有记录并且提交历史是清晰的一条链就说明成功了。6. 推送和后续使用中的常见坑按故障对照表处理这一部分我把自己实际遇到过和帮别人排查过的问题整理成一个速查表。每个问题都是我见过真实现象之后的总结不是随便从文档里抄的。6.1 高频报错速查报错信息或现象可能原因处理办法Permission denied (publickey)SSH公钥没配好或ssh用了错误的私钥检查~/.ssh下的密钥执行ssh -T gitgitee.com测试确认Gitee公钥已添加Updates were rejected本地和远程有互不相干的提交历史执行git pull origin master --allow-unrelated-histories再pushsrc refspec main does not match any本地分支名和远程分支名不一致查看git branch改名后git push -u origin 分支名remote: error: File ... is 100 MB有超过Gitee单文件限制的大文件被提交用git rm --cached移除大文件加入.gitignore提交历史如果已包含大文件参考6.2warning: LF will be replaced by CRLFWindows和Linux换行符不同如果你在Windows上编辑过一般不影响可在仓库根目录增加.gitattributes统一换行符fatal: refusing to merge unrelated histories本地和远程提交历史无关联在pull时显式加--allow-unrelated-historiesCould not resolve host: gitee.com网络问题或DNS解析异常先ping gitee.com再检查网络校园网等特殊环境可换HTTPS地址6.2 不小心把大文件推上去了怎么清理Fast-LIO2项目最常出现的大文件就是.bag数据包和编译出来的.so库。如果在第一次push时没写.gitignore很容易把这些文件推上去。这时光删本地文件再commit一次是不够的因为git提交历史里已经包含了这个大文件对象仓库体积依然很大。标准做法是使用git filter-branch或更推荐的git filter-repo来重写历史。以.bag文件为例# 安装 git-filter-repo pip3 install git-filter-repo # 从整个历史中移除所有 .bag 文件 git filter-repo --invert-paths --path-glob *.bag注意git filter-repo会重写提交历史所有提交的哈希值都会变化如果仓库已经有多人协作重写之前一定要和团队沟通避免其他人的本地分支彻底失联。个人项目就无所谓重写后重新push即可。如果你不想装额外工具也可以用下面这条比较粗暴但有效的命令git filter-branch --force --index-filter \ git rm -r --cached --ignore-unmatch *.bag \ --prune-empty --tag-name-filter cat -- --all执行完之后建议重新clone一次仓库确认体积已经降下来再继续使用。6.3 Gitee 网页端显示的中文文件名乱码或提交人信息不对Fast-LIO2目录下有的配置文件名可能是中文或者你新建的文件名里带中文。git本身支持UTF-8文件名Ubuntu 20.04默认终端编码一般也没问题。如果显示乱码可以设置git config --global core.quotepath false这个配置项控制git对非ASCII路径的转义设成false之后git status和日志里就能正常显示中文文件名。提交人信息不对的情况前面已经说过不再重复。唯一的补充是如果已经提交错误了但还没有推送可以执行git commit --amend --author你的名字 你的邮箱example.com来修正最近一次的提交者信息。如果已经推送了就需要重写历史了代价比较大所以最好第一次就把用户名邮箱配好。6.4 更新代码后发现Fast-LIO2依赖变了怎么用Gitee同步自己维护的Fast-LIO2仓库和上游仓库保持一致也是个常见需求。很多人在Gitee上clone一份上游代码后就不知道后续怎么拉取上游更新了。这里提供一个比较干净的工作流前提是你在Gitee上的仓库就是普通git仓库没有用Gitee的“强制同步”功能# 在本地项目里把上游仓库添加为第二个远程地址 git remote add upstream https://github.com/hku-mars/FAST_LIO.git # 拉取上游更新但先别合并 git fetch upstream # 切回自己的主分支 git checkout master # 合并上游的代码通常是合并到master并保留自己的修改 git merge upstream/master这一步如果冲突很多多半是上游对核心算法文件做了大改而你又改过相同位置。解决冲突的基本原则是非核心文件以上游为准自己的模块配置以自己为准。实在改不动的场景也可以选择直接在Gitee仓库里删掉重建然后把本地代码重新push但这样会丢掉提交历史不推荐。7. 换机器、加插件、日常维护最后再分享点实用技巧代码推到Gitee只是开始后续日常使用和维护同样有讲究。我把自己用了很长时间的几个习惯列出来供你参考。7.1 换一台Ubuntu机器快速部署Fast-LIO2Gitee仓库准备好之后新机器上只要装好系统的基础依赖然后sudo apt update sudo apt install -y git curl git clone gitgitee.com:你的用户名/fast-lio2.git如果仓库里有子模块记得加上git clone --recurse-submodules gitgitee.com:你的用户名/fast-lio2.git这样Fast-LIO2的代码部分就齐了剩下的ROS依赖、编译工具链再单独装。注意新机器上的SSH密钥要重新生成并添加到Gitee否则clone同样会提示权限拒绝。7.2 用 VS Code 的 Gitee 插件减少敲命令的频率如果你习惯在VS Code里写代码可以在扩展市场搜索“Gitee”安装官方插件。登录账号后VS Code侧边栏可以直接看到仓库、提issues、创建分支省去一部分网页端操作。git的日常命令在VS Code的源代码管理面板里也能可视化操作对新手友好很多。但这不意味着你可以完全脱离终端。像git rebase、git filter-repo这类更底层的操作VS Code的图形界面并不总是好用关键时刻依然要回到命令行。我自己的习惯是日常提交用VS Code遇到棘手问题用终端。7.3 仓库版本管理的一个小习惯打标签Fast-LIO2的代码一旦经历过不同传感器的适配很容易出现“改了A型号雷达的参数之后想切回B型号发现忘了当时改了什么”。建议在关键节点打上git标签例如git tag -a mid360_2024 -m 适配Mid360参数 git push origin mid360_2024之后想找某个状态的代码直接git checkout mid360_2024比翻commit记录高效得多。标签推送后Gitee网页端也能看到对应的Release标记管理和下载都很直观。7.4 记得定期拉取上游更新Fast-LIO2不断有bug修复和新功能如果仓库里的代码长期不更新很可能错过关键修复。但直接合并上游代码又可能破坏自己的配置。我现在的做法是专门建一个upstream分支只跟踪上游原始代码自己的修改永远放在master分支。需要看上游更新时git checkout upstream git pull upstream master git checkout master git merge upstream冲突不可怕怕的是不知道冲突在哪。先在上游分支里看一遍改动再决定自己的代码怎么并思路会清楚很多。最后提一句别把Gitee当作唯一的备份虽然这篇内容全程在讲怎么把Fast-LIO2推到Gitee但说句实在话代码备份这件事别押在一个篮子里。Gitee偶尔也会出现仓库访问异常、或者个人仓库容量达到上限的情况我在本地另外做了一套定时备份用rsync定期把整个工程目录同步到另一块硬盘上。代码量不大的时候成本很低但带来的安全感是实打实的。再补一个我自己折腾过程中的小经验Fast-LIO2 的yaml参数文件里面经常包含传感器外参、雷达安装角度这些设备相关的信息上传私有仓库问题不大但如果哪一天要把仓库转为公开记得先把这些参数替换成通用值再检查一遍有没有暴露IP、MAC地址之类的无用信息。开源代码本质上是一张名片干净整洁比炫技更重要。希望这篇东西能帮你把Fast-LIO2顺利推到Gitee并在以后的开发里少踩几个坑。