---

深入理解 Git Stash：用法、场景与技巧

在使用 Git 进行版本控制时，我们经常需要在不同的分支之间切换，或者在当前工作尚未完成、无法提交的情况下，需要紧急处理其他任务（如修复线上 bug）。这时，如果工作区或暂存区存在未提交的修改，Git 通常会阻止我们进行分支切换等操作，提示我们需要先提交或丢弃这些修改。然而，很多时候这些修改只是阶段性的，并不适合立即提交。这时，Git 的 stash 命令就如同救星一般，它提供了一个非常便捷的方式来临时保存当前的工作进度，让工作区恢复到干净的状态，以便我们可以自由地切换分支、拉取更新或进行其他操作。

Git stash 的字面意思就是“藏匿”或“储藏”，它做的事情正是如此：将当前工作区和暂存区中未提交的修改“藏起来”，放到一个栈（stash stack）中，让你的工作目录回到上一次提交时的状态。当你完成其他任务后，可以再将之前储藏的修改“取出来”，继续之前的工作。

本文将带你深入理解 Git Stash 的方方面面，包括其核心用法、各种应用场景以及一些实用的技巧。

一、 Git Stash 的核心用法 (Core Usage)

Git Stash 的基本用法非常直观，主要围绕着“保存”、“查看”、“应用”和“清理”这几个动作展开。

1. 保存当前工作进度 (Stashing Changes)

这是 git stash 最常用的功能。它会将你所有未提交的、被 Git 跟踪的文件的修改（包括已暂存和未暂存的）都保存起来。

• 基本命令：
  bash
git stash
# 或者更明确的写为
git stash push
  执行这个命令后，Git 会将当前工作区和暂存区的修改（不包括未被跟踪的文件或被忽略的文件）保存到一个新的 stash 中，并清空工作区和暂存区，使其回滚到 HEAD 所指向的提交状态。

• 添加描述信息：
  为了方便日后识别不同的 stash，尤其是在有多个 stash 的情况下，强烈建议在保存时添加一个描述信息：
  bash
git stash save "WIP: Feature X implementation before fixing hotfix"
  这个命令与 git stash push 加上 -m 参数或直接跟字符串的效果类似，但 save 是更早的语法，现在推荐使用 push -m 或直接 push 后跟字符串。
  bash
git stash push -m "WIP: Feature X implementation before fixing hotfix"
# 或者
git stash "WIP: Feature X implementation before fixing hotfix"

执行保存命令后，Git 会输出类似这样的信息：
Saved working tree and index state WIP on main: abc1234 Initial commit
这里的 WIP on main 表示这个 stash 是在 main 分支上基于 abc1234 这个提交创建的。后面的 WIP 可能会被你提供的描述信息替换。

2. 查看已保存的 Stash 列表 (Listing Stashes)

你可以使用 git stash list 命令来查看当前仓库中所有已保存的 stash。

• 命令：
  bash
git stash list
• 输出示例：
  stash@{0}: WIP on main: 5678def Add feature Y
stash@{1}: WIP on develop: abc1234 Implement feature X
stash@{2}: On bugfix/urgent-bug: fedcba9 Fix minor issue
  输出格式为 stash@{index}: message。stash@{index} 表示 stash 在栈中的位置，stash@{0} 总是最近保存的 stash，stash@{1} 是倒数第二个，以此类推。message 是你保存时提供的描述信息，如果没提供，Git 会生成一个默认的，包含当前分支和 HEAD 提交信息。

3. 查看 Stash 的内容 (Showing Stash Differences)

在应用 stash 之前，你可能想看看它里面具体修改了哪些文件和内容，可以使用 git stash show 命令。

• 查看最近的 Stash：
  bash
git stash show
  这会显示 stash@{0} 的修改摘要，类似于 git status 的输出，列出被修改、添加、删除的文件。

• 查看特定 Stash 的摘要：
  bash
git stash show stash@{1}
  将 stash@{1} 替换为你想要查看的 stash 索引。

• 查看 Stash 的详细修改 (Diff)：
  要看到具体的代码修改内容（类似于 git diff），需要加上 -p 或 --patch 参数：
  bash
git stash show -p
# 或者
git stash show stash@{1} -p

4. 应用 Stash 的修改 (Applying Stash)

将 stash 中保存的修改恢复到当前工作区。有 apply 和 pop 两种主要方式。

• git stash apply：
  这个命令会将 stash 中的修改应用到当前工作区，但 不会 从 stash 列表中删除这个 stash。这意味着同一个 stash 可以被多次应用到不同的分支或位置。
  “`bash
  git stash apply
  # 应用最近的 stash (stash@{0})

  git stash apply stash@{1}

  应用 stash@{1}

  “`
  应用 stash 后，你的工作区将恢复 stash 保存时的状态。但请注意，应用 stash 只会恢复工作区的修改，它不会自动将修改添加到暂存区。

• git stash pop：
  这个命令的功能与 apply 类似，但它在成功应用 stash 后，会自动将该 stash 从 stash 列表中删除。如果应用过程中发生冲突，pop 将不会删除 stash。
  “`bash
  git stash pop
  # 应用并删除最近的 stash (stash@{0})

  git stash pop stash@{1}

  应用并删除 stash@{1}

  ``pop` 更常用于当你确定应用这个 stash 后就不再需要它的时候，避免 stash 列表变得冗长。

5. 丢弃 Stash (Dropping Stash)

如果你确定某个 stash 不再需要了，可以直接将其从列表中移除。

• 丢弃最近的 Stash：
  bash
git stash drop
# 默认丢弃 stash@{0}

• 丢弃特定 Stash：
  bash
git stash drop stash@{2}
# 丢弃 stash@{2}

6. 清空所有 Stash (Clearing Stash List)

这个命令会删除当前仓库中的所有 stash。这是一个不可逆的操作，请谨慎使用！

• 命令：
  bash
git stash clear
  在执行之前，Git 会给你一个警告，要求你确认。

二、 Git Stash 的高级用法与变体 (Advanced Usage)

除了核心用法，git stash 还提供了一些更精细的控制选项。

1. 包含未跟踪文件 (Including Untracked Files)

默认情况下，git stash 不会保存工作区中未被 Git 跟踪的新文件。如果你希望将这些文件也一起保存，可以使用 -u 或 --include-untracked 参数。

“`bash
git stash -u

或者

git stash –include-untracked
“`

2. 包含所有文件 (包括未跟踪和忽略的文件) (Including All Files)

有时候你甚至想保存被 Git 忽略的文件（例如日志文件、编译生成的文件等），可以使用 -a 或 --all 参数。

“`bash
git stash -a

或者

git stash –all
“`
这会将工作区中 所有 文件（包括未跟踪和被忽略的）的修改和新增文件都保存起来。使用时需要特别小心，因为你可能不希望这些临时文件被错误地 stash 和恢复。

3. 创建分支从 Stash (Creating a Branch from a Stash)

如果你发现 stash 中的修改实际上是针对一个新的特性或者需要在一个独立的环境中继续，可以直接从这个 stash 创建一个新的分支。

bash
git stash branch <new-branch-name> [stash_id]
* <new-branch-name>: 你想要创建的新分支的名称。
* [stash_id]: 可选，指定从哪个 stash 创建分支，默认为最近的 stash@{0}。

执行这个命令后，Git 会做几件事：
1. 从 stash 创建时的提交 (stash 的 base commit) 创建并切换到一个新的分支。
2. 将 stash 中的修改应用到这个新分支的工作区。
3. 如果应用成功且没有冲突，会自动将该 stash 从 stash 列表中删除（类似于 pop 的行为）。

这是一个非常方便的功能，当你临时保存了一些修改，后来决定这些修改应该属于一个新的特性分支而不是当前分支时。

4. 交互式 Stash (Patch Stash)

有时候你只想保存工作区中 部分 文件的修改，或者一个文件中 部分 代码块的修改，而不是全部。这时可以使用交互式 stash：

“`bash
git stash –patch

或者

git stash -p
``
执行这个命令后，Git 会遍历你所有修改过的文件和修改块（hunks），逐个询问你是否要 stash 这个修改块。你可以选择：
*y：是，stash 这个修改块。
*n：否，不 stash 这个修改块。
*q：退出，不 stash 剩余的修改块。
*a：是，stash 这个文件中的所有修改块。
*d：否，不 stash 这个文件中的所有修改块。
*e：手动编辑这个修改块（很少用）。
*?`：显示帮助信息。

这使得你可以非常精细地控制哪些修改被 stash，哪些保留在工作区。

三、 Git Stash 的常见应用场景 (Usage Scenarios)

理解了 git stash 的用法，更重要的是知道在何时何地使用它。以下是一些典型的应用场景：

1. 临时切换分支处理紧急任务 (The Classic Use Case):
   这是 git stash 最常见也最主要的应用场景。你正在一个分支上开发一个新功能，工作进行到一半，但这时线上环境出现了紧急 bug，需要你立即切换到 main 或 hotfix 分支进行修复。然而，你当前的工作区和暂存区都很“脏”，有大量未提交的修改。这时，你不能直接切换分支（Git 会阻止你）。最优的方案就是使用 git stash 将当前未提交的修改保存起来，让工作区恢复干净，然后切换到目标分支进行 bug 修复。修复完成后，切回原来的分支，pop 或 apply 之前保存的 stash，继续之前的功能开发。

   • 正在 feature/new-feature 分支工作…
   • 收到紧急 bug 报告。
   • git stash save "WIP on feature/new-feature before hotfix"
   • git checkout hotfix
   • 修复 bug，提交，部署。
   • git checkout feature/new-feature
   • git stash pop (或者 git stash apply followed by git stash drop)
   • 继续开发新功能。

2. 拉取上游最新代码 (Pulling Latest Changes):
   当你需要从远程仓库拉取最新的代码到当前分支时 (git pull 或 git fetch 后 git merge/rebase)，如果你的工作区或暂存区有未提交的修改，git pull 可能会因为担心覆盖你的本地修改而失败，或者如果配置了自动合入/变基，可能会导致复杂的合并冲突。在这种情况下，先 stash 你的本地修改，拉取完最新代码后，再 apply 或 pop 你的 stash，处理可能出现的冲突，会使得拉取过程更安全和可控。

   • 在 develop 分支工作…
   • 需要同步远程仓库的最新代码。
   • git stash save "Local changes before pulling"
   • git pull origin develop
   • git stash pop
   • 解决可能出现的冲突。

3. 进行实验性修改 (Experimenting):
   你想尝试一种新的实现方式或代码结构，但又不确定是否可行，也不想立即创建一个新分支或提交一个临时的 commit。你可以先将当前稳定的工作状态 stash 起来，然后放心地在工作区进行各种实验性的修改。如果实验成功，可以将 stash pop 出来，将实验性的修改与 stash 中的修改合并；如果实验失败，可以直接丢弃实验性的修改，然后 pop 出 stash，恢复到之前的状态，而无需担心污染提交历史。

   • git stash save "Stable state before experiment"
   • 进行一些大胆的实验性修改。
   • 实验失败，丢弃修改：git reset --hard (危险操作，确保知道自己在做什么) 或 git clean -fdx。
   • 恢复到实验前的状态：git stash pop。

4. 清理工作目录 (Cleaning Working Directory):
   有时候工作目录中充斥着编译产生的临时文件、日志文件、调试输出等，非常混乱。在进行代码评审或者展示工作成果之前，你可能希望工作目录是干净的。git stash -a 或 git stash -u 可以将这些未跟踪或被忽略的文件也一起 stash 掉，让工作目录变得整洁。展示完毕后，再 pop 回来。

   • 工作目录有很多临时文件。
   • git stash -a "Clean up working directory"
   • 工作目录变得干净，进行展示或评审。
   • git stash pop

5. 处理中断的工作并稍后继续 (Picking Up Later):
   你正在处理一个复杂的任务，但不得不中断（例如，下班回家，或者去开会）。你当前的工作还没到一个可以提交的状态。这时，git stash 是保存进度的完美工具。你可以 stash 起来，在其他电脑上 clone 仓库，拉取最新代码（如果 stash 是在远程仓库上，这需要一些高级技巧或辅助工具，通常 stash 是本地的），或者稍后回到当前电脑时，直接 pop 之前的 stash 继续工作。

四、 Git Stash 的实用技巧 (Useful Techniques/Tips)

掌握一些使用 git stash 的技巧，可以让你更高效地利用它。

1. 始终使用有意义的消息 (git stash save "...")： 当你的 stash 列表变长时，没有描述信息的 stash@{0}: WIP on branch: commit_hash 会变得难以区分。为每个 stash 添加清晰的描述信息，能让你一目了然地知道每个 stash 保存了什么内容，方便日后查找和管理。

2. 理解 apply 和 pop 的区别： 选择 apply 还是 pop 取决于你是否可能需要多次应用同一个 stash。如果只是临时保存，用完就丢，那么 pop 更方便，它会自动清理 stash 列表。如果 stash 中的修改可能会被应用到多个地方（虽然这种情况较少），或者你对冲突处理没有信心，担心 pop 失败导致 stash 不被删除，那么先 apply，确认无误后再手动 drop 也是一种选择。

3. 谨慎使用 git stash clear： 这个命令会清除 所有 stash，且不可恢复。除非你非常确定不再需要任何一个 stash，否则应避免使用它。如果只想删除某个特定的 stash，使用 git stash drop <stash_id>。

4. 在应用/弹出前先查看 (git stash show -p)： 在 apply 或 pop 一个 stash 之前，先用 git stash show -p <stash_id> 查看其中的具体修改内容，可以帮助你确认这是你想要的 stash，并对可能出现的冲突有所准备。

5. 处理冲突： 当你 apply 或 pop 一个 stash 时，如果 stash 中的修改与当前工作区或 HEAD 提交的代码发生冲突，Git 会在冲突文件中留下标准的冲突标记 (<<<<<<<, =======, >>>>>>>)。你需要手动编辑这些文件，解决冲突，然后使用 git add 标记冲突已解决。解决完所有冲突后，需要进行一次新的提交来记录解决冲突后的状态（git commit）。注意，stash 的应用不会自动创建提交，即使没有冲突，你也需要手动 git add 和 git commit 来正式记录这些恢复的修改。

6. 恢复暂存区状态： 默认的 git stash 命令只会保存工作区（ unstaged changes）和暂存区（staged changes）的修改到 stash 中。当你 apply 或 pop 这个 stash 时，所有的修改都会被恢复到工作区，不会自动恢复到暂存区。如果你想恢复时也能区分哪些之前是暂存的，哪些不是，可以在 apply 或 pop 后，使用 git stash apply --index（或 pop --index）。这个选项会尽量恢复 stash 保存时的暂存区状态。但需要注意的是，--index 在复杂情况下（如文件被删除或重命名）可能无法完美恢复。

7. 仅 Stash 部分修改 (git stash --patch)： 前面已经介绍过，这是处理复杂情况下的利器，允许你选择性地保存修改。例如，你在一个文件里做了两个不相关的修改，只想 stash 其中一个，就可以使用 --patch。

8. Stash 已忽略的文件 (git stash --all)： 当你需要一个绝对干净的工作目录时（比如运行自动化脚本或构建），这个选项非常有用，即使是 .gitignore 中指定的文件也会被 stash 掉。

9. Stash 列表的持久性： Git stash 是本地仓库的一部分， stash 列表保存在 .git/refs/stash 文件中。stash 是与当前仓库绑定的，不会自动随着分支切换而改变（即在任何分支上都能看到同一个 stash 列表），也不会被 git clone 复制。如果你需要将 stash 的修改转移到另一个仓库或另一台电脑，你需要先将其 apply 或 pop 出来，然后提交，再将提交推送到远程仓库，在另一端拉取。或者使用 git stash branch 创建一个临时分支，然后 push 该分支。

五、 Stash 与其他方法的对比

在需要临时保存工作进度时，除了 git stash，还有其他一些方法：

• 创建临时提交 (Temporary Commit): 可以将当前的修改 add 并 commit 一个临时的提交，消息可以写 “WIP” (Work In Progress)。完成其他任务后，可以 git reset HEAD~1 回退到这个临时提交之前，同时保留修改在工作区，然后继续工作。

  • 优点： 修改作为正常的 commit 保存在版本历史中（虽然是临时的），更不容易丢失。
  • 缺点： 污染了提交历史，需要后续进行 reset 操作来移除临时提交，如果期间进行了其他提交，reset 的操作会更复杂。

• 使用 git worktree: git worktree 允许你同时在同一个仓库的不同分支上工作，通过创建多个工作目录。你可以保留当前工作目录在原分支，然后创建一个新的 worktree 来切换到其他分支处理紧急任务。

  • 优点： 提供了完全隔离的工作环境，无需保存和恢复修改，非常适合需要长时间在多个分支间来回切换或同时处理多个任务的场景。
  • 缺点： 设置和管理比 stash 稍复杂，会创建额外的目录，不适合只想临时保存几分钟修改的简单场景。

总结： git stash 最适合用于需要快速、临时保存当前工作进度，以便进行短暂的中断（如切换分支、拉取代码、紧急修复）的场景。它简单易用，不会污染提交历史。对于更长期、更复杂的并行工作，或者需要保留历史记录的临时修改，可以考虑临时提交或 git worktree。

六、 潜在的陷阱 (Potential Pitfalls)

• Stash 丢失： 虽然 stash 列表是本地仓库的一部分，但如果不小心删除了仓库目录，或者使用了 git clean -fdx（不小心清理了 .git 目录下的文件，虽然不太常见），stash 可能会丢失。而且 stash 不会自动备份或同步到远程。
• Stash 冲突： 应用 stash 时可能会发生冲突，需要手动解决，这可能需要一些时间和精力。特别是当 stash 创建后，当前分支有了大量的更新，冲突的概率会增加。
• 多个 Stash 的管理： 如果频繁使用 git stash 但不及时清理，stash 列表会变得很长，管理起来会比较麻烦，需要依赖描述信息和 git stash show 来区分。
• --index 的局限性： git stash apply --index 试图恢复暂存区状态，但在某些情况下（如文件被删除或重命名），可能无法完美恢复到 stash 时的状态。

七、 总结

Git stash 是 Git 中一个极其强大和实用的工具，它是处理开发过程中临时中断和需要切换上下文的利器。它提供了一种简单、快速的方式来保存未提交的工作，让你的工作目录保持干净，从而能够顺利进行分支切换、代码同步或其他操作。

通过掌握 git stash 的核心用法（push/save, list, show, apply, pop, drop, clear）以及高级选项（-u, -a, –patch, branch），结合理解其适用的各种场景和一些实用技巧，你可以更有效地管理你的工作流程，减少因上下文切换带来的麻烦，提高开发效率。

记住，git stash 的本质是临时存储，不应被视为永久备份或版本历史的一部分。合理地使用 git stash，并及时清理不再需要的 stash，将使你的 Git 工作流更加顺畅。

---