GitHub 备份操作手册从零到进阶适用于 ROS / ROS2 / 各类工程项目的代码备份。文中你的GitHub用户名、你的仓库名、你的项目目录均为占位符使用时替换成自己的信息。文章目录GitHub 备份操作手册从零到进阶0. 前置准备0.1 Git 安装与首次配置0.2 两种认证方式HTTPS Token 与 SSH 密钥方式一HTTPS Personal Access Token简单但烦方式二SSH 密钥推荐0.3 环境说明1. 首次上传初始化1.1 初始化仓库1.2 配置 .gitignore1.3 提交本地代码1.4 关联远程并推送2. 日常更新后续备份3. 常用命令速查4. 分支管理4.1 创建 / 切换 / 推送分支4.2 合并分支4.3 删除分支4.4 查看分支5. 版本查看与恢复5.1 只看不恢复5.2 恢复单个文件5.3 整体回退到特定版本6. 常见问题与修复git 坏了怎么办6.1 仓库被 build / install 产物污染6.2 指南与实际 remote 不符推送错仓库6.3 push 被拒绝远端有新提交6.4 认证失败 / 频繁要求输密码6.5 撤销与补救amend / reset 找回6.6 大文件推送失败100MB 限制与 LFS场景一大文件还没被 git add / commit预防场景二大文件已经被 commit 但还没 push补救场景三大文件已经 push 到远程历史污染方案四用 Git LFS 管理大文件必须保留大文件时防御push 前检查大文件6.7 README / 首次推送冲突6.8 压缩仓库备份git archive7. 一页命令速查表8. 版权与声明0. 前置准备0.1 Git 安装与首次配置# Ubuntu / Debian (含 WSL)sudoaptupdatesudoaptinstall-ygit# 配置用户名和邮箱GitHub 上显示的作者信息gitconfig--globaluser.name你的名字gitconfig--globaluser.email你的邮箱# 查看当前配置是否生效gitconfig--list邮箱建议用 GitHub 注册邮箱提交记录才能正确关联到你的账号。如果之前提交记录显示错误作者可以用git config --global --replace-all user.name 你的名字修正。0.2 两种认证方式HTTPS Token 与 SSH 密钥两种方式二选一即可。推荐SSH配置一次长期有效日常备份不用反复输密码。方式一HTTPS Personal Access Token简单但烦GitHub 已不再支持 HTTPS 用密码登录需要生成 TokenGitHub 网页 → 头像 →Settings→Developer settings→Personal access tokens→Tokens (classic)→Generate new token勾选repo完整读写仓库权限生成后立即复制保存只显示一次推送时用户名填 GitHub 用户名密码框粘贴 Tokengitclone https://github.com/你的GitHub用户名/你的仓库名.git# 推送时提示输入密码 → 粘贴 Token 即可方式二SSH 密钥推荐# 1. 生成密钥一路回车即可邮箱换成自己的ssh-keygen-ted25519-C你的邮箱# 2. 查看公钥并复制cat~/.ssh/id_ed25519.pubGitHub 网页 →Settings→SSH and GPG keys→New SSH key→ 粘贴公钥测试连接ssh-Tgitgithub.com# 看到 Hi 你的GitHub用户名! Youve successfully authenticated... 即成功仓库地址用 SSH 格式注意不是 httpsgitremoteaddorigin gitgithub.com:你的GitHub用户名/你的仓库名.git检测git remote -v如果显示https://github.com/...就是 HTTPS 认证显示gitgithub.com:...就是 SSH 认证。两种混用会反复要密码。0.3 环境说明WSLUbuntu默认用户是 root 时家目录是/root~等价于/root。普通 Linux家目录是/home/用户名~等价于/home/用户名。教程中命令不依赖具体路径在项目目录内执行即可。1. 首次上传初始化如果项目从未备份过请按顺序执行以下步骤。1.1 初始化仓库cd你的项目目录gitinit1.2 配置 .gitignore创建忽略文件防止编译产物等垃圾文件被上传cd你的项目目录touch.gitignoreechobuild/.gitignoreechodevel/.gitignoreechoinstall/.gitignoreecholog/.gitignoreecho.vscode/.gitignoreecho*.swp.gitignoreROS2 / Catkin 工作空间常见忽略项按需增删# 编译产物 build/ devel/ install/ log/ # 编辑器与系统文件 .vscode/ *.swp *.swo .DS_Store # 隐私与密钥千万别传 *.key *.pem .env # 大型数据/缓存 *.bag *.db3 __pycache__/ # 视频文件GitHub 单文件上限 100MB.avi 经常几百MB起步 *.avi *.mp4 *.mkv *.mov *.wmv *.flv验证忽略是否生效git status里不应再出现build/等目录。1.3 提交本地代码gitadd.gitcommit-mInitial backup1.4 关联远程并推送gitbranch-Mmaingitremoteaddorigin https://github.com/你的GitHub用户名/你的仓库名.git# 注意首次使用 --force 覆盖远程仓库的默认文件如 READMEgitpush-uorigin main--force若使用 SSH 认证将 remote 换成gitgithub.com:你的GitHub用户名/你的仓库名.git–force 的代价会直接覆盖远程已有内容。只用于第一次推送或确定要覆盖远程日常更新不要加 --force。2. 日常更新后续备份以后每次修改完代码只需三步# 1. 添加所有修改gitadd.# 2. 提交并写备注描述这次改了什么方便以后查找gitcommit-m更新内容描述# 3. 推送到云端gitpush提交备注建议写清楚如git commit -m 修复导航参数错误而不是git commit -m update。3. 常用命令速查# 查看状态哪些文件被修改/新增/删除gitstatus# 查看提交历史带 -oneline 只看一行摘要gitloggitlog--oneline# 撤销上次 add手滑加错了文件暂存区退回工作区gitreset# 查看远程地址确认推送到哪gitremote-v# 查看当前分支gitbranch4. 分支管理GitHub 网页上的绿色 “Compare pull request” 按钮不要乱点点了会创建 Pull Request可能把分支代码合并到主分支。备份用途不需要它。4.1 创建 / 切换 / 推送分支# 基于当前代码创建新分支并切换过去gitswitch-cdev# 或者用老命令: git checkout -b dev# 推送到远程 GitHub并建立关联-u 只推一次即可gitpush-uorigin dev# 切换到指定分支gitswitch maingitswitch dev# 老命令: git checkout main# 查看所有分支带 * 的是当前所在分支gitbranch# 查看包含远程的分支: git branch -a4.2 合并分支把dev分支的改动合入main# 1. 先切到要接收改动的分支maingitswitch main# 2. 合并 dev 进来gitmerge dev# 3. 推送到远程gitpush合并时可能提示 “CONFLICT”冲突说明两个分支改了同一处代码需要手动解决打开冲突文件会看到标记的两段内容手动保留正确内容删掉标记行保存后执行gitadd冲突文件gitcommit-m解决合并冲突gitpush4.3 删除分支# 删除本地分支已合并的分支用 -d 安全删除gitbranch-ddev# 分支未合并但确定不要了用 -D 强制删除gitbranch-Ddev# 删除远程分支gitpush origin--deletedev4.4 查看分支gitbranch# 本地分支gitbranch-a# 本地 远程全部分支gitbranch-vv# 分支与远程的关联关系5. 版本查看与恢复5.1 只看不恢复# 看某个 commit 改了什么gitshowcommit-hash# 看某个文件的历史版本只列出该文件相关的提交gitlog--onelinefile-path# 查看某个文件在某个 commit 里的内容不会改本地文件gitshowcommit-hash--file-path获取 commit-hashgit log --oneline每行开头的黄色字符串就是。5.2 恢复单个文件# 把某个文件恢复成特定版本会覆盖本地文件谨慎gitrestore--sourcecommit-hashfile-path# 或者用老命令gitcheckoutcommit-hash--file-path5.3 整体回退到特定版本命令效果远端影响git reset --soft hashcommit 撤销本地修改保留文件不改需 --force 推送git reset --mixed hashcommit 撤销暂存区清空文件不改默认需 --force 推送git reset --hard hashcommit 撤销文件也变回那个版本慎用需 --force 推送例回退到 3 个 commit 前本地文件也变回去gitreset--hardHEAD~3gitpush--force# 覆盖远端警告reset --hard会丢弃未提交的修改无法找回。不确定时先用git stash或复制备份或者改用git revert生成一个新的反向提交不用 --force更安全。6. 常见问题与修复git 坏了怎么办大多数git 坏了并不是 git 本身损坏或 SSH 失效而是仓库内容被污染或配置指向错误。下面是对症修复。6.1 仓库被 build / install 产物污染症状git status里出现大量build/、install/、log/文件仓库体积暴涨push 变慢甚至失败。原因编译产物进了版本控制可能当初没有 .gitignore或 .gitignore 建在错误的目录。修复# 1. 先补好 .gitignore见 1.2确保以后不再跟踪# 2. 把已跟踪的产物目录从 git 中移除--cached 只删跟踪记录不删本地文件gitrm-r--cachedbuild/gitrm-r--cacheddevel/gitrm-r--cachedinstall/gitrm-r--cachedlog/# 3. 提交并推送gitadd.gitcommit-m移除编译产物恢复干净的仓库gitpush远程仓库的脏文件需要再跑一次git push --force才能彻底清掉如果之前已推送过但先确认没有其他人协作再用 --force。6.2 指南与实际 remote 不符推送错仓库症状教程/笔记写的地址和实际推送地址不一样push 提示认证失败、或代码推到了别的仓库、或remote origin already exists。原因remote 配置指向错误或重复添加了 origin。排查与修复# 1. 查看实际配置真相在这里别信笔记gitremote-v# 2. 修正 origin 地址换成你真正要推送的仓库gitremote set-url origin https://github.com/你的GitHub用户名/你的仓库名.git# SSH 形式: git remote set-url origin gitgithub.com:你的GitHub用户名/你的仓库名.git# 3. 如果提示 already exists先删掉再重新添加gitremote remove origingitremoteaddorigin https://github.com/你的GitHub用户名/你的仓库名.git# 4. 验证gitremote-vgitpush推送前养成习惯git remote -v确认地址再 push。这是备份到错误地方最常见的坑。6.3 push 被拒绝远端有新提交症状! [rejected] ... (fetch first)/non-fast-forward。原因远程仓库有你本地没有的提交比如在 GitHub 网页上改过 README或另一台电脑推过。修复保守推荐gitpull--rebaseorigin main# 把远端新提交合并到本地gitpush修复激进覆盖远端gitpush--force# 直接覆盖远端慎用6.4 认证失败 / 频繁要求输密码症状Permission denied (publickey)或每次 push 都要输密码。排查# SSH 方式测试密钥是否有效ssh-Tgitgithub.com# 查看当前 remote 用的是 https 还是 sshgitremote-v修复SSH 失败 → 检查公钥是否已添加到 GitHub见 0.2或重新生成密钥HTTPS 频繁要密码 → 缓存凭证gitconfig--globalcredential.helper store首次输入后会明文保存在~/.git-credentials个人电脑可用共享电脑不要用。6.5 撤销与补救amend / reset 找回# 修改上一次提交的备注还没推送时gitcommit--amend-m新的备注# 想找回误删/误 reset 的内容gitreflog# 查看所有历史操作记录gitreset--hardhash# 回到 reflog 里看到的任意版本reflog是后悔药只要操作发生在这台机器上即使reset --hard误删也能用它找回。6.6 大文件推送失败100MB 限制与 LFS症状push 报large files detected/File is over 100MB。原因GitHub 单文件上限 100MB网页上传 25MB仓库超过 1GB 会警告。常见罪魁祸首.avi视频几百 MB 起步、.bag数据包、.pkl模型权重。场景一大文件还没被 git add / commit预防先加 .gitignore 再 add大文件根本不会进暂存区# 把视频格式加入 .gitignoreecho*.avi.gitignoreecho*.mp4.gitignoreecho*.mkv.gitignoreecho*.bag.gitignoreecho*.db3.gitignore# 确认 git status 里不再出现大文件gitstatus# 正常提交gitadd.gitcommit-m添加 .gitignore 排除大文件gitpush场景二大文件已经被 commit 但还没 push补救.avi文件进了暂存区甚至 commit 了但还没 push——此时文件在本地 git 历史里git push会因超限报错。# 1. 先补好 .gitignore防止以后再犯echo*.avi.gitignoreecho*.mp4.gitignoreecho*.bag.gitignore# 2. 从 git 跟踪中移除--cached 只删跟踪记录不删本地文件gitrm-r--cached*.avigitrm-r--cached*.mp4# 或者按具体路径删git rm -r --cached src/data/recording.avi# 3. 确认移除干净gitstatus# 应该看到一堆 deleted: xxx.avi只是从暂存区删了本地文件还在# 4. 提交并推送gitadd.gitcommit-m移除误提交的大文件视频/数据集gitpush场景三大文件已经 push 到远程历史污染视频已经被推到 GitHub 上了仓库体积暴涨。即使现在删了文件git 历史里还保留着大文件的 blob仓库体积不会变小。方案 A忽略历史只确保以后不再犯推荐简单# 加 .gitignore git rm --cached正常提交推送即可# 仓库历史里的旧 blob 还在但 GitHub 会自动 GC垃圾回收# 如果仓库超过 1GBGitHub 会发邮件警告但不会删你的仓库方案 B用 BFG 清理历史仓库体积必须瘦身时# 安装 BFG需要 Java 环境# 下载https://rtyley.github.io/bfg-corpus-clean/# 1. 克隆裸仓库gitclone--mirrorhttps://github.com/用户名/仓库名.git# 2. 用 BFG 删除历史中的大文件java-jarbfg.jar --strip-blobs-bigger-than 100M仓库名.git# 3. 清理 推送cd仓库名.gitgitreflog expire--expirenow--allgitgc--prunenow--aggressivegitpush方案四用 Git LFS 管理大文件必须保留大文件时sudoaptinstallgit-lfsgitlfsinstallgitlfs track*.avigitlfs track*.baggitadd.gitattributesgitcommit-m启用 LFS 管理大文件gitpushLFS 会把大文件存在 GitHub 的单独存储免费额度 1GB 仓库 1GB 带宽/月超出要付费。视频/数据集建议另存网盘不走 LFS。防御push 前检查大文件手动git add .容易手滑把.avi等大文件加进去。push 之前建议按顺序检查第一步确认 .gitignore 已排除大文件# 确认 .gitignore 里有视频格式cat.gitignore|grep-E\.(avi|mp4|bag)# 如果没有补上echo*.avi.gitignoreecho*.mp4.gitignoreecho*.bag.gitignore第二步检查有没有大文件已经进了暂存区# 查看本次所有变更文件已暂存 未暂存 新文件遵守 .gitignoregitdiff--name-onlygitdiff--cached--name-onlygitls-files--others--exclude-standard逐个检查这些文件的大小。如果发现 100MB 的文件# 先从暂存区移除--cached 只删跟踪记录不删本地文件gitrm-r--cached大文件路径# 确认 .gitignore 里有对应格式防止以后再犯echo*.avi.gitignore# 重新提交gitadd.gitcommit-m移除误提交的大文件第三步检查远程是否有更新避免 push 冲突# 同步远程信息但不修改本地gitfetch--quiet# 查看本地领先/落后多少gitrev-list --left-right--countHEAD...{u}# 输出两个数字左边本地领先右边本地落后# 如果右边 0说明远程有更新建议先 pull第四步确认无误后再 pushgitadd.gitcommit-m你的备注gitpush6.7 README / 首次推送冲突症状首次git push报failed to push some refs。原因GitHub 网页建仓库时自动生成了 README/LICENSE与本地历史分叉。修复首次上传本来就要覆盖远程直接强制推送gitpush-uorigin main--force6.8 压缩仓库备份git archive不想每次 push 都要网络或者想把某个版本打个压缩包存本地/U盘/网盘# 把当前代码打包成 zip不含 .git 历史干净的代码快照gitarchive-obackup_20260824.zip HEAD# 打包指定分支gitarchive-obackup_dev.zip dev# 打包指定 commitgitarchive-obackup_v1.0.zip v1.0# 打成 tar.gz比 zip 更小gitarchive HEAD|gzipbackup_20260824.tar.gzgit archive只导出代码文件不包含.git目录提交历史、分支信息等。适合代码快照式备份不适合需要版本历史的场景。7. 一页命令速查表场景命令首次上传git init→ 配 .gitignore →git add .→git commit -m Initial backup→git branch -M main→git remote add origin 地址→git push -u origin main --force日常备份git add .→git commit -m 描述→git push查看状态git status查看历史git log --oneline撤销 addgit reset查看远程git remote -v修正远程git remote set-url origin 正确地址新建分支git switch -c dev推送新分支git push -u origin dev合并分支git switch main→git merge dev→git push删除分支git branch -d dev/git push origin --delete dev恢复文件git restore --source hash file回退版本git reset --hard hash→git push --force后悔药git reflog清掉编译产物git rm -r --cached build/→ commit → push排除视频大文件echo *.avi .gitignore→git rm -r --cached *.avi→ commit → push检测超大文件git diff --name-onlygit ls-files --others --exclude-standard查变更逐个检查大小压缩仓库备份git archive -o backup.zip HEAD不含 .git 历史纯代码快照8. 版权与声明本手册供个人学习使用如有问题欢迎交流。