macOS下Git合并时触发git-crypt报fatal: stash failed错误求助

问题场景 #

在macOS系统中，使用Git配合git-crypt工具时，从功能分支执行git merge master会触发fatal: stash failed错误，但单独运行git stash命令完全正常。以下是完整的Git追踪日志：

GIT_TRACE=2 GIT_TRACE_PACK_ACCESS=true GIT_TRACE_SETUP=true GIT_ASKPASS=true git merge master

11:00:47.179302 trace.c:310             setup: git_dir: .git
11:00:47.179619 trace.c:311             setup: git_common_dir: .git
11:00:47.179623 trace.c:312             setup: worktree: /Users/tdecaux/devops-docker
11:00:47.179626 trace.c:313             setup: cwd: /Users/tdecaux/devops-docker
11:00:47.179629 trace.c:314             setup: prefix: (null)
11:00:47.179681 chdir-notify.c:67       setup: chdir from '/Users/tdecaux/devops-docker' to '/Users/tdecaux/devops-docker'
11:00:47.179687 git.c:439               trace: built-in: git merge master
11:00:47.180899 packfile.c:1641         .git/objects/pack/pack-ecc09223a926974948b38ab4cf9d2c1458227b58.pack 12352217


11:00:47.195181 run-command.c:655       trace: run_command: '"git-crypt" clean'
11:00:47.209903 git.c:439               trace: built-in: git rev-parse --git-dir
11:00:47.213576 run-command.c:655       trace: run_command: git stash create
11:00:47.217756 trace.c:310             setup: git_dir: .git
11:00:47.218130 trace.c:311             setup: git_common_dir: .git
11:00:47.218136 trace.c:312             setup: worktree: /Users/tdecaux/devops-docker
11:00:47.218138 trace.c:313             setup: cwd: /Users/tdecaux/devops-docker
11:00:47.218139 trace.c:314             setup: prefix: (null)
11:00:47.218186 chdir-notify.c:67       setup: chdir from '/Users/tdecaux/devops-docker' to '/Users/tdecaux/devops-docker'
11:00:47.218198 git.c:439               trace: built-in: git stash create
11:00:47.225162 run-command.c:655       trace: run_command: '"git-crypt" clean'
11:00:47.237452 git.c:439               trace: built-in: git rev-parse --git-dir

fatal: stash failed

排查与调试步骤 #

1. 验证git-crypt钩子是否为冲突根源 #

Git在merge过程中会自动触发clean/smudge钩子，而merge上下文里的git stash create调用可能因git-crypt钩子的环境异常失败。可以临时禁用钩子测试：

git config --local filter.git-crypt.clean ""
git config --local filter.git-crypt.smudge ""

执行完后再次尝试git merge master，如果成功，说明钩子是问题所在。测试完成后恢复钩子配置：

git config --local filter.git-crypt.clean "git-crypt clean"
git config --local filter.git-crypt.smudge "git-crypt smudge"

2. 对比git stash create在不同上下文的执行差异 #

单独执行git stash create正常，但merge调用时可能处于特殊环境。手动模拟merge的追踪环境执行：

GIT_TRACE=2 git stash create

对比该命令的输出与merge日志中的git stash create环节，查看是否有钩子执行失败的细节差异。

3. 检查git-crypt状态与密钥可用性 #

• 确认git-crypt处于解锁状态：

  git-crypt status
  

  如果仓库处于锁定状态，merge时钩子无法处理加密文件，会导致stash失败。
• 检查密钥文件的权限，macOS下过严的文件权限可能导致git-crypt无法读取密钥，确保密钥文件（如.git-crypt/keys/default/0）的权限为当前用户可读。

4. 升级Git与git-crypt版本 #

部分旧版本Git在处理钩子与stash的交互时存在兼容性问题，通过Homebrew升级到最新稳定版：

brew upgrade git
brew upgrade git-crypt

升级后再次尝试merge操作。

5. 获取更详细的错误日志 #

增加stash专属的追踪参数，定位具体失败环节：

GIT_TRACE=2 GIT_TRACE_STASH=true GIT_TRACE_ERROR=true git merge master

该命令会输出stash操作的详细错误堆栈，帮助定位是钩子执行失败、文件权限问题还是其他底层错误。

6. 临时绕开自动stash完成merge #

如果需要紧急完成merge，可以手动替代Git的自动stash流程：

git stash
git merge master
git stash pop

该操作可以验证merge本身是否存在其他问题，同时作为临时解决方案。

内容的提问来源于stack exchange，提问作者Thomas Decaux