【GitHub 备份操作手册】备份不再出错-Seo优化-塔城地区网站建设公司

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 配置 .gitignore
  - 1.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 archive）
- 7. 一页命令速查表
- 8. 版权与声明

0. 前置准备

0.1 Git 安装与首次配置

# Ubuntu / Debian (含 WSL)sudoaptupdate&&sudoaptinstall-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 用密码登录，需要生成 Token：

GitHub 网页 → 头像 →Settings→Developer settings→Personal access tokens→Tokens (classic)→Generate new token
勾选repo（完整读写仓库权限），生成后立即复制保存（只显示一次）
推送时用户名填 GitHub 用户名，密码框粘贴 Token

gitclone https://github.com/<你的GitHub用户名>/<你的仓库名>.git# 推送时提示输入密码 → 粘贴 Token 即可

方式二：SSH 密钥（推荐）

# 1. 生成密钥（一路回车即可，邮箱换成自己的）ssh-keygen-ted25519-C"<你的邮箱>"# 2. 查看公钥并复制cat~/.ssh/id_ed25519.pub

GitHub 网页 →Settings→SSH and GPG keys→New SSH key→ 粘贴公钥
测试连接：

ssh-Tgit@github.com# 看到 "Hi <你的GitHub用户名>! You've successfully authenticated..." 即成功

仓库地址用 SSH 格式（注意不是 https）：

gitremoteaddorigin git@github.com:<你的GitHub用户名>/<你的仓库名>.git

检测：git remote -v如果显示https://github.com/...就是 HTTPS 认证，显示git@github.com:...就是 SSH 认证。两种混用会反复要密码。

0.3 环境说明

WSL（Ubuntu）：默认用户是 root 时，家目录是/root，~等价于/root。
普通 Linux：家目录是/home/<用户名>，~等价于/home/<用户名>。
教程中命令不依赖具体路径，在项目目录内执行即可。

1. 首次上传（初始化）

如果项目从未备份过，请按顺序执行以下步骤。

1.1 初始化仓库

cd<你的项目目录>gitinit

1.2 配置 .gitignore

创建忽略文件，防止编译产物等垃圾文件被上传：

cd<你的项目目录>touch.gitignoreecho"build/">>.gitignoreecho"devel/">>.gitignoreecho"install/">>.gitignoreecho"log/">>.gitignoreecho".vscode/">>.gitignoreecho"*.swp">>.gitignore

ROS2 / 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-m"Initial backup"

1.4 关联远程并推送

gitbranch-Mmaingitremoteaddorigin https://github.com/<你的GitHub用户名>/<你的仓库名>.git# 注意：首次使用 --force 覆盖远程仓库的默认文件（如 README）gitpush-uorigin main--force

若使用 SSH 认证，将 remote 换成：git@github.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# 查看当前分支gitbranch

4. 分支管理

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 -a

4.2 合并分支

把dev分支的改动合入main：

# 1. 先切到要接收改动的分支（main）gitswitch main# 2. 合并 dev 进来gitmerge dev# 3. 推送到远程gitpush

合并时可能提示 “CONFLICT”（冲突），说明两个分支改了同一处代码，需要手动解决：

打开冲突文件，会看到<<<<<<<=======>>>>>>>标记的两段内容
手动保留正确内容，删掉标记行
保存后执行：

gitadd<冲突文件>gitcommit-m"解决合并冲突"gitpush

4.3 删除分支

# 删除本地分支（已合并的分支用 -d 安全删除）gitbranch-ddev# 分支未合并但确定不要了，用 -D 强制删除gitbranch-Ddev# 删除远程分支gitpush origin--deletedev

4.4 查看分支

gitbranch# 本地分支gitbranch-a# 本地 + 远程全部分支gitbranch-vv# 分支与远程的关联关系

5. 版本查看与恢复

5.1 只看不恢复

# 看某个 commit 改了什么gitshow<commit-hash># 看某个文件的历史版本（只列出该文件相关的提交）gitlog--oneline<file-path># 查看某个文件在某个 commit 里的内容（不会改本地文件）gitshow<commit-hash>--<file-path>

获取 commit-hash：git log --oneline每行开头的黄色字符串就是。

5.2 恢复单个文件

# 把某个文件恢复成特定版本（会覆盖本地文件，谨慎）gitrestore--source<commit-hash><file-path># 或者用老命令gitcheckout<commit-hash>--<file-path>

5.3 整体回退到特定版本

命令	效果	远端影响
`git reset --soft <hash>`	commit 撤销，本地修改保留，文件不改	需 --force 推送
`git reset --mixed <hash>`	commit 撤销，暂存区清空，文件不改（默认）	需 --force 推送
`git reset --hard <hash>`	commit 撤销，文件也变回那个版本（慎用）	需 --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 git@github.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-Tgit@github.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--hard<hash># 回到 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（垃圾回收）# 如果仓库超过 1GB，GitHub 会发邮件警告但不会删你的仓库

方案 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--expire=now--allgitgc--prune=now--aggressivegitpush

方案四：用 Git LFS 管理大文件（必须保留大文件时）

sudoaptinstallgit-lfsgitlfsinstallgitlfs track"*.avi"gitlfs track"*.bag"gitadd.gitattributesgitcommit-m"启用 LFS 管理大文件"gitpush

LFS 会把大文件存在 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

第二步：检查有没有大文件已经进了暂存区

# 查看本次所有变更文件（已暂存 + 未暂存 + 新文件，遵守 .gitignore）gitdiff--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

第四步：确认无误后再 push

gitadd.gitcommit-m"你的备注"gitpush

6.7 README / 首次推送冲突

症状：首次git push报failed to push some refs。

原因：GitHub 网页建仓库时自动生成了 README/LICENSE，与本地历史"分叉"。

修复：首次上传本来就要覆盖远程，直接强制推送：

gitpush-uorigin main--force

6.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|gzip>backup_20260824.tar.gz

git 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`
撤销 add	`git 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-only`+`git ls-files --others --exclude-standard`查变更，逐个检查大小
压缩仓库备份	`git archive -o backup.zip HEAD`（不含 .git 历史，纯代码快照）

8. 版权与声明

本手册供个人学习使用，如有问题欢迎交流。