Git - git stash 语法演进与实战指南

标签：Git · 版本控制 · 开发工具

一、git stash 基础回顾

git stash 用于临时存储工作区和暂存区的未提交修改，让工作区恢复干净状态，适合切换分支、拉取代码等场景。

git stash                    # 暂存当前修改（基本用法）
git stash list               # 查看所有暂存记录
git stash pop                # 恢复最近一次暂存并删除记录
git stash apply              # 恢复但不删除记录
git stash drop stash@{0}     # 删除指定暂存
git stash clear              # 清除所有暂存

二、语法演进时间线

版本	新增语法	说明
Git 2.13+	git stash push	替代已弃用的 git stash save，支持 pathspec
Git 2.13+	git stash push -m "消息"	带消息暂存，替代 save "消息"
Git 2.13+	git stash push -- <file>	只暂存指定文件
Git 2.23+	git switch / git restore	常配合 stash 使用，语义更清晰
Git 2.35+	git stash push -S / --staged	只暂存已 staged 的变更
Git 2.35+	git stash push --pathspec-from-file=<file>	从文件读取 pathspec
Git 2.35+	git stash show --include-untracked	查看含未跟踪文件的 diff
Git 2.35+	git stash show --only-untracked	只查看未跟踪文件 diff
Git 2.51+	git stash export	导出 stash 为可移植格式
Git 2.51+	git stash import	导入他人导出的 stash
Git 2.51+	pull.autostash 配置	git pull 自动 stash

三、各版本新语法详解

3.1 Git 2.13+：push 替代 save

旧写法（已弃用）：

git stash save "修复键盘遮挡问题"

新写法（推荐）：

git stash push -m "修复键盘遮挡问题"

对比项	save	push
消息参数	直接跟字符串	用 -m 指定
pathspec	不支持	支持 -- <file>
状态	已弃用	推荐使用

3.2 Git 2.13+：指定文件暂存

# 只暂存特定文件，其他文件修改保持不变
git stash push -m "键盘遮挡输入框滚动" -- src/views/trade/extract/ExtractCheck.vue

# 暂存多个文件
git stash push -m "修复多个文件" -- file1.vue file2.vue

3.3 Git 2.23+：配合 switch 切换分支

# 旧（所有版本兼容）
git checkout bugfix-branch

# 新（Git 2.23+，语义更清晰）
git switch bugfix-branch

3.4 Git 2.35+：只暂存 staged 变更

git stash push --staged -m "只暂存已暂存的变更"

场景： 工作区有两组修改，一组已 git add 准备提交，另一组还在改。用 --staged 只暂存已 staged 的部分。

3.5 Git 2.35+：从文件读取 pathspec

git stash push --pathspec-from-file=file-list.txt

3.6 Git 2.35+：查看含未跟踪文件的 diff

git stash show --include-untracked     # 包含未跟踪文件
git stash show --only-untracked        # 只看未跟踪文件
git stash show -p --include-untracked stash@{0}  # patch 格式

3.7 Git 2.51+：stash 导出/导入

# 导出
git stash export --file my-stash.bundle

# 导入
git stash import --file my-stash.bundle

场景： 跨机器、跨仓库共享未完成的修改。

3.8 Git 2.51+：pull 自动 stash

git config --global pull.autostash true
# 之后 git pull 自动 stash → 拉取 → 恢复

优先级： pull.autostash > rebase.autostash > merge.autostash

四、常用参数速查

参数	全称	说明
-m	--message	暂存消息
-u	--include-untracked	包含未跟踪文件
-a	--all	包含所有文件（含 .gitignore）
-k	--keep-index	暂存后保留 index 状态
-p	--patch	交互式选择暂存内容
-S	--staged	只暂存 staged 变更（2.35+）
-q	--quiet	静默模式

五、完整工作流示例

场景一：开发中紧急切分支修 bug

# 1. 只暂存当前修改的文件
git stash push -m "键盘遮挡修复（android）" -- src/views/trade/extract/ExtractCheck.vue

# 2. 切到 bug 分支
git switch bugfix-branch

# 3. 修 bug 并提交
git add .
git commit -m "fix: 修复xxx"
git push

# 4. 切回原分支
git switch feature/keyboard-scroll

# 5. 恢复暂存
git stash pop

场景二：跨机器共享未完成的修改

# A 机器：暂存多个文件并导出
git stash push -m "WIP: 表单验证重构" \
    -- src/views/trade/extract/ExtractCheck.vue \
       src/views/trade/deposit/SubmitCertificate.vue \
       src/utils/commonUtils.js

git stash export --file /tmp/my-work.bundle

# B 机器：导入并恢复
git stash import --file /tmp/my-work.bundle
git stash pop

场景三：从文件列表批量暂存

# file-list.txt 内容：
# src/views/trade/extract/ExtractCheck.vue
# src/views/trade/deposit/SubmitCertificate.vue
# src/utils/commonUtils.js

git stash push -m "WIP: 表单验证重构" --pathspec-from-file=file-list.txt
git stash export --file /tmp/my-work.bundle

六、版本要求速查

功能	最低版本	检查命令
push + pathspec	Git 2.13+	git --version
--staged	Git 2.35+	git --version
--pathspec-from-file	Git 2.35+	git --version
show --include-untracked	Git 2.35+	git --version
export / import	Git 2.51+	git --version
pull.autostash	Git 2.51+	git --version

七、常见问题

1. save 和 push 用哪个？

用 push。save 已弃用，push 功能更全（支持 pathspec）。

2. 怎么只暂存一个文件？

git stash push -m "消息" -- path/to/file.vue

3. 怎么只暂存已 add 的部分？

git stash push --staged

4. 恢复暂存后冲突怎么办？

git stash pop 冲突时不会删除暂存记录，需手动解决冲突后 git stash drop。

5. 暂存丢了怎么找回？

git fsck --unreachable | grep commit
git stash apply <commit-hash>

总结

场景	推荐命令
基本暂存	git stash push -m "消息"
指定文件暂存	git stash push -m "消息" -- <file>
只暂存 staged	git stash push --staged
包含未跟踪文件	git stash push -u
跨机器共享	git stash export/import
pull 自动暂存	git config pull.autostash true

核心要点：用 push 不用 save，指定文件用 --，只暂存已暂存用 --staged，跨机器用 export/import。