1. 项目概述：为什么我们需要一份自己的Git命令备忘录？

干了这么多年开发，我电脑里一直存着一个叫“git_cheatsheet.md”的文件。它不是什么高深的秘籍，就是我自己整理的一份Git常用命令和踩坑记录。每次换新电脑、带新人，或者隔了几个月没碰某个复杂流程，我都会把它翻出来看看。我发现，无论你是刚入行的新手，还是像我这样摸爬滚打多年的老鸟，手边有这么一份“接地气”的、带注释和解决方案的清单，效率提升不是一点半点。

网上Git教程浩如烟海，但真到了关键时刻——比如合并冲突时手忙脚乱，或者想撤销一个已经推到远程的提交时——你往往没时间去从头翻看教程。你需要的是能直接“抄作业”的命令，以及这个命令背后“为什么”这么用，还有“用了会怎样”的实操心安。这份记录，就是要把那些高频、关键且容易出错的Git操作，从“知道”变成“熟练”，再从“熟练”升华到“理解”。它不追求大而全，只聚焦于那些在真实项目协作中，能真正帮你省时间、避大坑的场景。

2. 核心思路：如何构建一份高效的Git操作指南

我的这份记录，核心思路就三点：场景驱动、命令解释、问题前置。它不是按字母顺序罗列命令，而是围绕一个开发者日常的工作流来组织。

2.1 场景驱动：从“做什么”倒推“用什么”

我不会一上来就讲git init。而是假设你此刻要开始一个新功能开发，你会经历：克隆项目 -> 创建分支 -> 写代码 -> 暂存提交 -> 推送 -> 发起合并请求。我的命令清单就跟着这个流程走。这样，当你处于“我要开始写新功能了”这个场景时，你能立刻找到对应区块的命令，连贯地执行下去，而不是东找西找。

2.2 命令解释：知其然，更知其所以然

对于每个命令，我不仅记录语法，更会备注上我自己的理解。比如git commit -m “msg”和git commit -v有什么区别？为什么有时候推荐用-v？我会写上：“-v参数会在编辑器里显示本次提交的具体变更，方便你最后确认，避免提交了不该提交的调试代码。在提交重要改动时强烈建议使用。” 这样，这条命令就从冷冰冰的代码，变成了有温度的建议。

2.3 问题前置：把坑填平，把路铺好

这是这份记录价值最高的部分。我会把那些让我栽过跟头、或队友常问的问题，直接附在相关命令后面。比如，在git push命令旁，我会记录：“问题：推送被拒绝，提示‘非快进式更新’。解决：先执行git pull --rebase整合远程变更，再推送。注意：rebase会重写历史，在公共分支上谨慎使用。” 这就把解决方案和风险提示一次性给到位了。

3. 日常开发流核心命令详解

这是使用频率最高的部分，覆盖了从获取代码到提交推送的完整闭环。

3.1 仓库初始化与代码获取

一切始于获取代码。除了最基础的git clone <url>，有几个参数很实用。

• git clone --depth 1 <url>：浅克隆，只拉取最近一次提交的历史。对于历史庞大、你只需要最新代码的仓库，这能极大节省时间和磁盘空间。想获取完整历史后再执行git fetch --unshallow即可。
• git clone -b <branch_name> <url>：直接克隆指定分支，而不是默认的main或master。

注意：新项目初始化时，如果你是在已有代码目录执行git init，记得第一时间添加.gitignore文件，否则很容易把编译产物、IDE配置、本地环境文件等无关内容误提交上去。我习惯从 gitignore.io 根据项目类型（如Java、Node、Python）生成模板。

3.2 分支操作：高效协作的基石

分支是Git的灵魂，相关命令必须熟练。

• git branch：查看本地分支。-v参数可以查看每个分支最后一次提交信息，-a查看所有（本地+远程）分支。
• git checkout -b feature/xxx：创建并切换到新分支。这是功能开发的起手式。在Git 2.23版本后，更推荐使用git switch -c feature/xxx，语义更清晰（switch切换，create创建）。
• git branch -d <branch_name>：删除已合并的分支。这里有个大坑：如果分支未合并，此命令会失败。有时你想强制删除未合并的分支（比如实验性分支作废了），必须使用-D（大写）参数：git branch -D <branch_name>。执行前务必确认分支内容真的不需要了。
• git push origin --delete <branch_name>：删除远程分支。本地分支删除后，远程分支并不会自动删除，需要显式执行此命令。

3.3 状态查看与差异比较

搞清楚当前状态和改了什么是避免混乱的前提。

• git status：最常用的命令，务必养成频繁查看的习惯。它会告诉你哪些文件被修改、哪些已暂存、哪些未被跟踪。
• git diff：查看工作区与暂存区的差异。git diff --staged（或--cached）查看暂存区与上一次提交的差异。git diff HEAD查看工作区与最新提交的差异。
• git log：查看提交历史。光秃秃的git log信息很快会刷屏，我常用几个组合：
  • git log --oneline --graph --all：以单行、图形化方式展示所有分支历史，一目了然。
  • git log -p <file_path>：查看某个文件的详细修改历史。
  • git log --since=”2 weeks ago”：查看最近两周的提交。

3.4 暂存与提交：保存你的工作进度

提交不是简单打几个字，好的提交习惯能让历史清晰易懂。

• git add .：暂存所有变更。这是把双刃剑，方便但危险，容易把调试语句、临时文件一起加进去。更安全的做法是使用git add -p（交互式暂存），它会逐个片段（hunk）询问你是否要暂存，给你一次审查的机会。
• git commit -m “message”：提交。提交信息怎么写？我遵循一个简单模板：“<类型>: <简短摘要>”。例如：“feat: 添加用户登录验证功能”、“fix: 修复首页图片在移动端显示错位的问题”、“docs: 更新API接口文档”。类型如feat、fix、docs、style、refactor等，能让历史非常规整。
• git commit --amend：修改上一次提交。如果你刚提交完发现漏了文件，或者提交信息写错了，可以用这个命令。它会将暂存区的修改合并到上一次提交中，并允许你修改提交信息。警告：如果上一次提交已经推送到远程，不要轻易使用--amend，除非你确定团队协作模式允许（通常不允许），因为这改写了历史。

4. 代码同步与整合：处理远程协作

多人协作时，与远程仓库的同步是核心，也是最容易出问题的地方。

4.1 拉取与推送

• git pull：拉取远程更新并合并到当前分支。它相当于git fetch（获取远程更新） +git merge（合并到本地）。这里有个关键选择：git pull默认是merge方式，会产生一个合并提交。我更倾向于使用git pull --rebase，它会将你的本地提交“变基”到远程更新之后，使得历史线保持一条直线，更整洁。
• git push：推送本地提交到远程。常用形式是git push origin <branch_name>。如果远程分支不存在，可以用git push -u origin <branch_name>，-u参数会建立本地分支与远程分支的追踪关系，之后直接git push即可。

4.2 处理推送冲突：非快进式更新

这是新手最常遇到的错误之一。当你执行git push时，提示“! [rejected] main -> main (non-fast-forward)”。这意味着远程分支已经有了你本地没有的新提交，Git拒绝直接覆盖。

解决方案：

1. 首选方案（推荐）：git pull --rebase，然后解决可能出现的冲突，再git push。rebase会把你的提交“接”在别人提交的后面。
2. 备选方案：git pull（默认merge），然后解决冲突，再git push。这会产生一个额外的合并提交。

实操心得：在团队开发中，尤其是功能分支，我强烈建议养成先git pull --rebase再git push的习惯。这能保持提交历史的线性，在代码审查时更容易追踪。但在长期存在的公共分支（如main）上，有时使用merge保留合并记录更能反映真实的协作过程。

4.3 远程仓库管理

• git remote -v：查看已配置的远程仓库地址。
• git remote add upstream <url>：在为开源项目贡献时常用。将原始项目仓库添加为upstream（上游），你自己的Fork仓库作为origin。这样你可以随时从upstream同步最新代码到本地：git fetch upstream，然后合并到你的分支。

5. 撤销与回退：时光倒流的安全网

人总会犯错，Git的强大之处在于它提供了多级“撤销”机制，理解每一层的区别至关重要。

5.1 撤销工作区的修改（还没git add）

• git checkout -- <file>：丢弃指定文件在工作区的所有修改，恢复到最近一次git commit或git add时的状态。这是一个危险命令，因为它会永久丢弃你的修改，且无法通过Git找回。执行前请务必确认。
• git restore <file>：Git 2.23版本引入的新命令，作用同git checkout -- <file>，语义更清晰。

5.2 撤销暂存区的修改（已经git add了）

• git reset HEAD <file>：将指定文件从暂存区（Stage）移回工作区（Worktree），但保留文件内容的修改。这样你可以重新修改或审查。
• git restore --staged <file>：同上，是新命令。

5.3 撤销提交

这是更复杂的操作，分几种情况：

• 情况一：撤销上一次提交，但保留修改内容在工作区。使用git reset --soft HEAD~1。这就像“撤回”了提交动作，代码改动还保留着，你可以重新修改、暂存、提交。HEAD~1表示上一个提交。
• 情况二：撤销上一次提交，并且丢弃修改内容。使用git reset --hard HEAD~1。这个命令极其危险！它会同时撤销提交和丢弃所有工作区修改，数据不可恢复。除非你100%确定这些改动都不要了，否则慎用。
• 情况三：撤销某次特定的历史提交，但保留后续提交。使用git revert <commit_hash>。这个命令会创建一个新的提交，其内容正好是撤销指定提交的修改。这是最安全的方式，因为它不会改写历史，适合已经推送到远程的提交。

5.4 找回丢失的提交

如果你误操作git reset --hard删除了还没推送的提交，别慌，只要操作记录还在，大概率能找回来。使用git reflog命令。它会记录HEAD和分支引用所有的变化历史。找到你误操作前的那个提交哈希值，然后执行git reset --hard <hash>就能恢复。

避坑指南：reset --hard和checkout -- <file>是Git里的“核武器”，威力巨大且不可逆（除非用reflog抢救）。我的原则是：在按下回车前，再执行一次git status和git diff，确认自己要丢弃的到底是什么。对于重要的、未提交的修改，养成先git stash（储藏）起来的习惯，给自己留条后路。

6. 高级场景与问题排查实录

这部分是我在复杂协作和问题排查中积累的“硬核”经验。

6.1 储藏（Stash）的灵活运用

git stash临时储藏工作区的改动，让你可以切换分支或进行其他操作，事后再恢复。

• git stash或git stash push -m “message”：储藏当前修改。加个信息是个好习惯。
• git stash list：查看所有储藏。
• git stash apply stash@{n}：应用某个储藏，但不从储藏列表中删除它。
• git stash pop stash@{n}：应用并删除某个储藏。
• git stash drop stash@{n}：删除某个储藏。
• git stash clear：清空所有储藏。

场景：你正在feature/A分支开发到一半，突然需要紧急修复main分支的一个Bug。你可以：1)git stash储藏feature/A的改动；2)git checkout main切换分支并修复；3) 修复完提交后，切回feature/A，执行git stash pop恢复现场。

6.2 合并冲突的解决流程

冲突不可避免，冷静处理是关键。

1. 触发冲突：在执行git merge或git pull时，如果Git无法自动合并，会提示CONFLICT。
2. 查看状态：立即执行git status，它会明确列出“Unmerged paths”（冲突文件）。
3. 手动解决：用编辑器打开冲突文件。Git会用<<<<<<<，=======，>>>>>>>标记出冲突区域。你需要判断保留哪边的代码，或者进行整合，然后删除这些标记。
4. 标记已解决：每个冲突文件解决后，执行git add <file>将其标记为已解决。
5. 完成合并：所有冲突解决并add后，执行git commit来完成这次合并提交。Git会为你生成一个默认的合并信息。

6.3 变基（Rebase）的利与弊

git rebase用于重新整理提交历史，使其更清晰。

• git rebase -i HEAD~n：交互式变基最近n次提交。你可以重新排序提交、合并（squash）多个小提交为一个、修改提交信息等。这是一个非常强大的历史整理工具。
• git rebase <base_branch>：将当前分支的提交“移植”到目标分支的最新提交之后。

优点：历史线干净、线性，便于阅读和二分查找Bug。缺点：改写了提交历史。黄金法则：只对你本地、尚未推送到公共仓库的提交进行变基。永远不要对已经推送到远程、可能被其他人基于其工作的提交进行变基。

6.4 常见问题速查表

这份记录不是一成不变的，它随着我遇到的每一个新问题、学到的每一个新技巧而不断生长。Git是一个工具，熟练使用它的命令只是第一步，理解其背后的设计哲学（快照、分支、分布式），才能在复杂的协作中游刃有余。最实在的建议是：在个人项目或实验分支上大胆尝试这些命令，特别是reset、rebase这些“危险”操作，亲眼看看git status和git log的变化，这比读十篇教程都管用。当你对时间线有了清晰的画面感，Git就不再是令人头疼的魔法，而成了你手中精准的雕刻刀。