山海尽明意刚接触 GitHub 的时候，很多人会陷入一个怪圈：命令记了一堆，真正要用的时候却不知道先敲哪个。尤其是从 Gitee、GitLab 或者 SVN 切过来的人，思维还停留在“中心化版本库”那一套，拿到 GitHub 仓库地址就开始乱试命令，结果要么推到别人的仓库，要么冲突冲突再冲突。这篇文章我把自己这些年整理出来的 GitHub 仓库常用命令按真实使用场景重新过了一遍，从首次初始化、日常推拉、分支协作到出了问题怎么抢救，全部用实际能跑通的命令来讲，不搞那些花里胡哨的排序，只讲能解决实际问题的。
1. 先搞清楚本地仓库和远程仓库的关系
1.1 初始化与首次连接的核心命令
我第一次用 GitHub 的时候，犯过一个特别蠢的错误：直接在网页端新建了一个仓库，然后本地 git init 之后，又用 git remote add origin 仓库地址 把它连起来，最后 push 的时候被拒绝，因为两边都没有共同的历史记录。所以第一步，先把下面这几条命令刻在脑子里：
bash复制# 场景一：本地从零开始，想推到 GitHub 新建的空仓库
git init
git add .
git commit -m "first commit"
git branch -M main
git remote add origin https://github.com/用户名/仓库名.git
git push -u origin main
# 场景二：GitHub 上已经有项目，想拉下来继续开发
git clone https://github.com/用户名/仓库名.git
git init 是在当前目录生成一个隐藏的 .git 文件夹，这个文件夹就是整个仓库的灵魂，里面存了所有提交记录、分支指针、配置信息。一旦删除了 .git，这个目录就只是个普通文件夹了，Git 不认它。所以很多人在重装系统或者迁移项目的时候，如果把 .git 连带着拷走了，本地提交记录还在，重新 git remote add 一下就能恢复推送关系。
git clone 就不一样了，它会自动把远程仓库完整复制下来，包括所有分支、所有历史提交，还会默认把 origin 这个远程名字设置好。很多人以为 clone 只拉默认分支，其实是错的，git clone 会把整个仓库的对象数据都拉到本地，只是 git branch -a 能看到所有远程分支，切换的时候直接 git checkout -b 本地分支名 origin/远程分支名 就行。
1.2 为什么要分清 clone 和 init
说白了，clone 是从别人手里接过来一个现成的项目，init 是自己从零打地基。这俩命令的使用场景完全不同，选错了方向后面就难受了。
举个例子，你在 GitHub 上看到一个开源项目，想改改代码自己用，正确姿势是 fork 到自己账号下再 clone 下来，而不是把别人的仓库地址直接 clone 到本地就改——因为 push 权限不在你手里，改完推不上去。反过来，如果你本地已经写好了项目，想公开到 GitHub，那就只要在网页端创建一个空仓库，然后走 init + remote add + push 这条流程。
还有人分不清 origin 到底是什么。origin 其实就是一个远程仓库的别名，默认从 clone 出来的仓库会自动命名为 origin。你可以通过 git remote -v 查看当前仓库关联了哪些远程地址，也可以添加多个：
bash复制git remote add upstream https://github.com/原作者/项目.git
git remote -v
加两个远程地址是参与开源项目的常规操作：origin 指向你 fork 出来的仓库，upstream 指向原作者仓库。这样你既能往自己的远程仓库推送，又能从上游拉最新代码。很多新手只看文档不操作，remote 这个概念死活理解不了，我这里用大白话解释一下：本地仓库是你家，origin 是你家在公司登记的对外地址，upstream 是总公司地址，你每天上班在本地写代码，下班了把成果推回自己公司，同时偶尔去总公司看看有没有新文件要同步回来。
2. 日常推拉代码：最常用的几个命令
2.1 提交前的代码暂存与提交组合
日常开发中，git add 和 git commit 绝对是最高频的命令。但这两个命令有个非常常见的使用误区，我见过太多人习惯性 git add . 一把梭，所有改动全部塞进一次提交，提交信息还写得模棱两可，比如 update、fix，过了俩月自己回头翻日志都不知道当时改了啥。
正常情况下，一次提交应该只包含一个逻辑变更。如果改动了多个文件，尽量把它们分成多个提交，用 git add 具体文件 或者 git add -p 交互式暂存。git add -p 可以在命令行里逐个文件地选择暂存哪些改动块，这个命令对新手来说一开始有点绕，但它能让你养成提交信息清晰的好习惯。
常见的暂存命令组合：
bash复制git add index.html # 暂存单个文件
git add src/ && git add test/ # 暂存多个目录
git add -p # 交互式选择代码块暂存
git commit -m "feat: 新增用户登录接口" # 带说明的提交
git commit -a -m "fix: 修复空指针异常" # 跳过暂存区，直接提交所有已跟踪文件
git commit -a 这个方法虽然能省一步，但只对已经被 Git 跟踪的文件生效，新建的文件还是需要先 git add。而且它会把所有修改过的文件全部提交，如果你在同一次改动里改了三个模块，用了 -a 就很难做精细化控制了，所以我还是建议养成 add 和 commit 分开的习惯。
2.2 pull 与 push 的注意事项
git pull 是 git fetch + git merge 的组合命令。很多人以为 pull 就是把远端代码拉下来，其实它会自动做一次合并。如果两个分支在同一个文件的同一行都有改动，就会产生合并冲突。解决冲突的过程不可怕，可怕的是新手看到 CONFLICT 几个大红字就慌了，直接把人家的代码删了。
我常用的一个规避冲突的方法是先 fetch 再看差异，再手动决定怎么合并：
bash复制git fetch origin
git diff main origin/main
git merge origin/main
先用 git fetch 把远端更新拉到本地，但暂时不合并，这会儿你可以用 git diff 仔细看两边改了什么，确认没有改了同样的地方再 merge。如果在多人协作的团队里，我更推荐用 git pull --rebase，它能把本地提交“搬到”远程提交的顶端，保持提交历史的线性，不像 merge 那样动不动就出现一条 Merge branch 'main' of github.com:xxx/xxx 的记录。
push 的时候也有一点要提醒：在别人比你多提交了几次的情况下，直接 push 会被拒绝。这时候别硬推，先拉再推：
bash复制git pull --rebase origin main
git push origin main
注意：对于团队正在多人协作的仓库，pull 时优先使用 --rebase 而不是直接 pull。rebase 能把提交历史整理成一条直线，避免在仓库里留下大量无意义的 merge 提交。
当然，关于 rebase 有一个流传很广的告诫：不要对公共分支上已经被别人拉取的提交做 rebase。因为 rebase 会改写提交的 hash，导致同事们本地记录和远端不一致。我的处理原则是：自己本地还没推送的分支随便 rebase，只要推送到公共分支了，后续就只合并，不改写。
3. 分支操作：版本管理的核心
3.1 新建、切换、合并分支
分支是 Git 相对 SVN 最让我觉得爽的地方。在 SVN 时代打个分支要等很久，在 Git 里分支不过是一个指针，新建成本几乎为零。所以日常开发我习惯给每个功能拆一个分支，开发完毕再合并回主分支，这样即使功能写崩了，主分支永远是稳定可用的。
基础的分支命令：
bash复制git branch feature-login # 新建分支
git checkout feature-login # 切换分支
git checkout -b feature-login # 新建并切换，最常用
git switch feature-login # Git 2.23+ 推荐用 switch
git switch -c feature-login # 新建并切换，等价于 checkout -b
我个人的习惯是用 git switch 来切分支、用 git checkout 去还原文件，这样语义更清晰，不容易混淆。不过团队里老同事可能还是用 checkout 多，这都无所谓，关键是别脏着工作区就切分支。
切分支之前一定要保证工作区是干净的，或者至少所有改动都 stash 过。如果你改了代码没提交，直接切另一个分支，那个分支上也会带着你未提交的改动，容易把功能分支的代码污染到其他分支上去。这里我提供一个安全的切分支流程：
bash复制git status # 确认当前改动
git stash # 暂存改动，保持工作区干净
git switch feature-login # 切换到目标分支
# 处理完再切回来
git switch -
git stash pop # 恢复暂存的改动
合并分支的命令也有讲究：
bash复制git switch main
git merge feature-login
合并时尽量用 --no-ff 保留合并记录：
bash复制git merge --no-ff feature-login
--no-ff 的意思是即使可以快进合并，也要生成一条 merge 提交，这样做的好处是以后看历史能清楚看到“某个时间点把一个功能合进来了”，对于团队协作来说，可视化程度更高。如果你喜欢线性的历史，也可以用 rebase 后再 merge，各人偏好不同，但团队内最好统一。
3.2 删除分支与同步远程分支
开发完一个功能分支后，清理掉它能让仓库列表清爽很多。删除分支分本地和远程两步：
bash复制git branch -d feature-login # 删除本地分支，-d 会在未合并时给出警告
git push origin --delete feature-login # 删除远程分支
如果分支里有未合并的修改，-d 会拒绝删除，这时候如果你确定这些修改不要了，可以用 -D 强制删除。我踩过一次坑：以为自己改动已经合并了，实际合并到的是另外一个分支，直接 -D 删掉，把写了两天的代码全弄没了。所以强制删除之前一定要用 git branch --contains 分支名 检查一下改动到底有没有被其他分支包含。
还有一种情况是远程分支被别人删了，但本地还存着远端跟踪分支记录，这时候需要清理：
bash复制git fetch --prune
加了 --prune 参数，fetch 的时候会顺便把本地已经不存在对应远程分支的跟踪信息删掉。团队合作中这种幽灵分支很容易堆积，我建议每个星期跑一次清理。
4. 远程仓库维护：从 clone 到 LFS 大文件管理
4.1 GitHub 仓库的常见操作顺序
GitHub 仓库除了日常提交代码之外，还有不少周边操作容易被忽略。比如有人问我在 GitHub 上怎么给仓库打版本号，其实方法很简单，用 tag：
bash复制git tag v1.0.0
git push origin v1.0.0
git tag -d v1.0.0 # 删除本地标签
git push origin :refs/tags/v1.0.0 # 删除远程标签
打标签是发布版本的好习惯，尤其是做开源项目或者给团队提供 SDK，每次发布都打一个 v1.0.0 这种语义化版本号的标签，别人在 GitHub 页面上能看到清晰的发布历史。
另一个很多人踩坑的场景是把大文件推到 GitHub。GitHub 对单个文件大小有 100MB 的限制，即使没超过这个限制，仓库太大的话 clone 起来也特别慢。正确的做法是使用 Git LFS（Large File Storage）:
bash复制brew install git-lfs # macOS 安装
apt install git-lfs # Ubuntu/Debian 安装
git lfs install # 初始化 LFS
git lfs track "*.psd" # 跟踪 PSD 文件
git add .gitattributes
git commit -m "add LFS config"
记住 git lfs track 生成的规则记录在 .gitattributes 文件里，这个文件一定要提交到仓库，不然其他人 clone 的时候不会自动启用相同的 LFS 规则。另外，在安装 LFS 之前，仓库里已经存在的大文件不会被自动转换，你需要用 git lfs migrate 来改写历史，但这个操作会改变提交 hash，如果别人已经基于这个仓库开发了，慎重使用。
4.2 子模块与多个远程仓库并存
有的项目需要依赖另一个仓库里的公共代码，Git 给的做法是子模块 submodule。常用命令如下：
bash复制git submodule add https://github.com/用户名/公共库.git libs/common
git submodule update --init --recursive # 拉取子模块
子模块用起来有个麻烦点：clone 主仓库后不会自动拉子模块的代码，得手动初始化。所以我合作的项目里，如果依赖不复杂，我更喜欢用包管理工具（npm、Maven 等）来管理依赖，只有依赖方和被依赖方需要同步修改的场景才用 submodule。
多远程仓库并存的场景，我前面提到过 upstream 和 origin，还有更常见的场景是把一个仓库同时推到 GitHub 和 Gitee 等平台的多个地址，旧版本的做法是添加多个 remote，然后逐个 push：
bash复制git remote add gitee https://gitee.com/用户名/仓库名.git
git push gitee main
如果你经常需要两个平台同步，可以在 push 的时候一次性推送多个远程地址。Git 有一个技巧是在 .git/config 里配置 push 的多个 URL，不过对于大多数开发者来说，手动 git push origin main && git push gitee main 就够了，别为了省几条命令引入复杂的配置。
5. 常见问题与排查技巧实录
5.1 认证失败与 SSH 配置
GitHub 在 2022 年之后就不支持用账号密码直接推代码了，只能用个人访问令牌或者 SSH 密钥。很多新人在 push 的时候一直提示密码错误，就是这个原因。
我用的是 SSH 方式，配置一次一劳永逸：
bash复制ssh-keygen -t ed25519 -C "你的邮箱@example.com"
# 一路回车，生成在 ~/.ssh/id_ed25519.pub
cat ~/.ssh/id_ed25519.pub
然后把输出的内容复制到 GitHub 的 Settings -> SSH and GPG keys 里添加。添加完用下面命令验证：
bash复制ssh -T git@github.com
如果看到 Hi 用户名! You've successfully authenticated，就说明认证没问题了。这里提一个非常常见的坑：Windows 用户如果之前把公钥内容复制漏了末尾换行符，或者本地 ~/.ssh 目录权限不对，会遇到权限拒绝的报错。Windows 上可以用管理员 PowerShell 执行 icacls 给当前用户单独授权，不过现在新版本的 Git for Windows 对这块处理已经好很多了。
如果是 HTTPS 方式，配置好令牌之后，建议把令牌存进凭证管理器，以后就不用反复输入了：
bash复制git config --global credential.helper store
store 会把凭证明文写在 ~/.git-credentials 里，自己个人电脑能用，但公司共享电脑千万别这样配，用 GitHub CLI 或者系统的凭证管理器更安全。
5.2 合并冲突的经典处理流程
合并冲突是每个用 Git 的人早晚要面对的。我第一次处理冲突的时候手忙脚乱，把整个文件删了重写，后来总结出的一套流程稳定可靠：
bash复制git merge 目标分支
# 出现冲突后：
git status # 查看哪些文件冲突了
Git 会在冲突文件里用 <<<<<<< HEAD、=======、>>>>>>> 标出两边的不同内容。手动编辑文件，保留你想要的内容，删掉那些标记符号，然后：
bash复制git add 冲突文件
git commit
这里有个小技巧：如果你用的是 VS Code，冲突文件右上角会出现“采用当前更改”“采用传入更改”这些按钮，可视化处理比命令行舒服多了。但不管用什么工具，核心原则只有一个——保留双方都必要的修改，不要因为冲突麻烦就整段覆盖掉对方的逻辑。
5.3 误操作回滚与找回“被删”的代码
Git 最让我有安全感的地方是，基本没有真正的“删除”，大多数误操作都能找回。我自己最常用的是这几个：
bash复制git reflog
git reflog 是 Git 的后悔药，它会记录 HEAD 指针的每一次移动。哪怕你 reset、rebase 之后发现不对，用 git reflog 找到操作之前的提交 hash，再 git reset --hard hash 就能回到过去。这里我强烈建议每个刚接触 Git 的人先记住一点：reset 是移动分支指针，revert 是生成一个反向提交。两者的区别在于已推送到远端的代码，不要用 reset，因为这会改写公共历史，应该用 revert：
bash复制git revert HEAD # 撤销最新一次提交
git revert 3a8f2bc # 撤销指定提交
对于已经 commit 但还没 push 的提交，用 reset 就可以了：
bash复制git reset --soft HEAD~1 # 撤销 commit，保留改动
git reset --hard HEAD~1 # 撤销 commit 且丢弃改动
--soft 和 --hard 的区别非常关键。--soft 只会取消提交记录，改动还留在暂存区，你可以重新分类提交；--hard 会把改动全部丢掉。不开玩笑地说，git reset --hard 是我见过最容易造成事故的命令，没有之一。如果你不确定要不要保留改动，宁可先用 git stash 或者 git branch 备份分支，把当前状态先存一份再操作。
5.4 网络连接与 GitHub 访问异常的处理思路
很多国内开发者会遇到 GitHub 能打开网页但 clone 很慢、push 经常断连的问题。这个话题其实不涉及任何特殊内容，就是正常的网络配置优化。遇到这种情况，我的排查顺序是：
bash复制ping github.com
curl -I https://github.com
先确认基础网络通不通，再确认端口是否被限制。如果是公司内网，可能需要用代理，那就给 Git 配一下代理设置即可：
bash复制git config --global http.proxy http://127.0.0.1:端口号
git config --global https.proxy http://127.0.0.1:端口号
# 取消代理
git config --global --unset http.proxy
git config --global --unset https.proxy
如果不想碰代理配置，还有一个思路是修改 DNS 或者使用 GitHub 官方推荐的 SSH over HTTPS 端口 443：
bash复制ssh -T -p 443 git@ssh.github.com
不过这属于网络层面的调优，不同网络环境差异很大。总体来说，我建议优先用 SSH 方式连接 GitHub，相比 HTTPS 方式在同等网络条件下传输更稳定，避免了每次 push 时额外握手带来的连接中断概率。
还有一个值得注意的细节：有些项目仓库体积本身很大，比如带了很多历史版本的静态资源，一上来就 git clone 整个仓库当然慢。这时候你可以用浅克隆，只拉取最新提交而不拉历史记录：
bash复制git clone --depth 1 https://github.com/用户名/仓库名.git
如果你在 CI 环境里只是要构建部署，浅克隆能大幅缩短时间。但要注意，浅克隆的仓库是没有完整历史记录的，不能正常做分支合并回退操作。需要完整历史时再执行 git fetch --unshallow 补全。
6. 命令之外：几个值得坚持的仓库管理习惯
6.1 用 .gitignore 提前规避垃圾文件
我见过太多仓库里混进去 node_modules、__pycache__、.DS_Store、编译产出的 target/ 目录这类文件。一旦这些文件被提交过一次，后续处理起来就特别麻烦，因为 Git 已经跟踪它们了，即使加了 .gitignore 也不会自动移除，需要手动 git rm --cached 移除跟踪状态。
所以配置 .gitignore 应该是在项目初始化那一刻就做的事情，而不是出了问题再补救。常用规则示例：
gitignore复制# 依赖目录
node_modules/
vendor/
# 编译输出
dist/
build/
*.class
# 编辑器与系统文件
.vscode/
.idea/
.DS_Store
# 日志
*.log
如果是已经提交过的垃圾文件，用下面的命令取消跟踪但保留本地文件：
bash复制git rm -r --cached node_modules
git commit -m "chore: 移除 node_modules 跟踪"
这样本地文件不会真的被删掉，只是 Git 不再跟踪它了。
6.2 提交信息规范与单次提交的粒度
前面多次提到提交信息的清晰度问题，这里我进一步展开。规范化的提交信息是团队协作的基础设施，建议采用目前业界认可度较高的约定式提交规范：
bash复制git commit -m "feat: 新增用户注册功能"
git commit -m "fix: 修复登录时 token 过期未跳转的问题"
git commit -m "docs: 更新接口文档"
git commit -m "refactor: 重构订单查询逻辑"
git commit -m "test: 添加用户模块单元测试"
如果项目用上了这套规范，后面生成 changelog、自动触发 CI、定位 bug 引入的提交都会容易很多。反过来，如果所有人提交信息都是 update、fix bug，别说同事看了头大，你自己三个月后回来看也完全想不起当时的上下文。
每个提交的内容越单一越好，不要把“修 bug”和“加功能”混在一个提交里。我见过一个提交同时改了接口、前端页面、数据库脚本和文档的，后面发现这个提交有问题，根本没办法精准回滚某一部分。宁可提交次数多一点，也不要贪图省事把一堆改动塞一个提交里。
6.3 仓库体积控制与定期维护
Git 仓库是会“发胖”的。哪怕改了删了文件，历史提交里还是保留着旧版内容，所以仓库体积只会单向增长。如果仓库里有大文件或者敏感信息（比如密钥、数据库密码）被推上过 GitHub，光删除文件是不够的，历史里还是能翻出来。
处理历史敏感信息的手段是用 git filter-repo 这类工具重写历史：
bash复制pip install git-filter-repo
git filter-repo --invert-paths --path 要删除的文件路径
重写历史是最后手段，因为它会改变所有提交的 hash，会让团队里所有基于旧历史的人冲突爆炸。所以真正要记牢的是：密钥、证书、数据库连接串这些内容，绝对不要提交进 Git 仓库，尤其是公开仓库。现在 GitHub 会自动扫描公开仓库里的常见密钥格式，一旦发现还会邮件通知你，但尽量别让事情走到那一步。
7. 末尾分享一点个人使用心得
我大概给你们总结一个每天高频使用的最短命令链：开发后 git status 看改动、git diff 确认细节、git add 暂存、git commit 提交、git pull --rebase 同步、git push 推送。这一条链走下来，覆盖了日常个人开发的百分之八十场景。团队协作再叠加上分支管理、合并、rebase、stash 这些，就足够应付绝大多数工作了。
有不少人问我 Git 到底要不要把命令全背下来，我的答案是从不需要。命令行帮助、图形工具、VS Code 的 Git 插件都能帮你解决查命令的问题，真正让你成长的，是理解了 Git 的数据模型——每次提交都是一次快照，分支只是一个指针，远程和本地之间只是搬运对象。把这些概念真正搞懂了，你就不会再被各种莫名其妙的报错吓到了。
最后分享一个我坚持了很多年的习惯：新建任何 Git 仓库的第一步，永远是先编辑 .gitignore 和 README，再写第一行代码。先定规则再开始，后面整个项目的管理都会顺畅很多。