将指定 Git 提交提取到子文件夹（不保留历史）
本文记录一次实际操作：把仓库中的某次提交 1e3150e82aa5c15d17457fa7effe23e7e3bae023（缩写 1e3150e）以子目录形式导出到子文件夹 1e3150e/ 中，仅保留文件快照、不保留 git 历史，并最终提交到仓库。
适用场景：想把某次提交的完整文件内容单独隔离到一个子目录，且不关心其提交历史时。
一、背景与目标
- 仓库分支：
main（当时领先 origin/main 1 个提交，工作区干净）
- 目标提交：
1e3150e82aa5c15d17457fa7effe23e7e3bae023
- 目标子文件夹：
1e3150e/
- 方式：使用
git archive 导出文件快照，tar 解包到子目录，不保留 git 历史
该提交是一条 CI 配置相关的提交，原始文件树包含 5 个文件：
.woodpecker/go.yml
.woodpecker/test.yaml
README.md
main.go
test.sh
二、操作步骤
第 1 步：校验环境与目标提交
在动手前，先确认仓库状态正常、目标提交确实存在：
git status
git log --oneline -5
git branch -a
git rev-parse --short 1e3150e82aa5c15d17457fa7effe23e7e3bae023
关键输出：git rev-parse --short 返回 1e3150e，证明长哈希是有效的提交对象。
注意：本次导出后，工作区会出现同名文件夹 1e3150e。之后凡是用到该哈希的命令（如 git show 1e3150e），git 会把 1e3150e 误判为路径而产生「有歧义的参数」错误。解决办法是用 -- 分隔版本与路径，例如 git show --stat --oneline 1e3150e --。
第 2 步：查看提交包含的文件
git show --stat --oneline 1e3150e --
--stat 只显示本次提交相对父提交的变化（本次改动 3 个路径），不含 main.go、test.sh 这些未改动的文件。要看该提交当时的完整文件快照，用：
git ls-tree -r --name-only 1e3150e --
输出即我们要完整提取的 5 个文件。
第 3 步：导出提交文件到子文件夹
mkdir -p 1e3150e
git archive 1e3150e | tar -x -C 1e3150e
mkdir -p 1e3150e：创建目标子目录（首次遗漏此步导致 tar 报「无法 open」错误，补上后成功）。git archive 1e3150e：把该提交的文件树打包成 tar 流输出到 stdout，不含任何 git 历史。|：管道，把 git archive 的 stdout 直接作为 tar 的 stdin。tar -x -C 1e3150e：解包并先切换到 1e3150e 目录，于是归档内的相对路径被还原为 1e3150e/.woodpecker/go.yml 等，实现「放进子文件夹」。
第 4 步：校验导出结果
find 1e3150e -type f
确认 5 个文件均已正确落在子文件夹内：
1e3150e/.woodpecker/go.yml
1e3150e/.woodpecker/test.yaml
1e3150e/README.md
1e3150e/main.go
1e3150e/test.sh
第 5 步：提交到仓库
git add 1e3150e
git commit -m "chore: 提取提交 1e3150e 到子文件夹 1e3150e
将 1e3150e82aa5c15d17457fa7effe23e7e3bae023 的文件快照以子目录形式导出到 1e3150e/，不保留 git 历史。"
提交后生成新提交 eb15b92，5 个文件以普通文件形式进入仓库。
三、命令解析小结
| 步骤 | 命令 | 目的 |
|---|
| 校验 | git rev-parse / git log / git branch / git status | 确认目标提交存在、环境干净 |
| 勘察 | git show --stat / git ls-tree -r | 看清提交改动与当时完整文件 |
| 提取 | git archive <提交> \| tar -x -C <子目录> | 把快照无损导出到子文件夹，不带历史 |
| 校验 | find <子目录> -type f | 确认结果 |
| 提交 | git add / git commit | 纳入版本管理 |
为什么用 git archive 而不是 git checkout？
git archive 只产出文件内容，不动工作区、索引和分支，最适合「把某次提交拷贝成子目录普通文件」的场景，且天然过滤掉 .git 历史。git checkout <提交> -- <路径> 会把文件直接覆盖到工作区对应路径，难以重定向到自定义子文件夹，且容易与工作区现有文件冲突。
四、扩展：如果需要保留历史
如果希望子文件夹是一个可追溯的子项目（保留完整提交历史），可改用以下方案：
git subtree：git subtree add --prefix=1e3150e <仓库> <提交> 以子树方式挂载，保留历史。git read-tree：将某次提交的文件树读入指定前缀路径的索引中。
这两种方式会引入额外的提交历史与合并记录，按需选择。
五、常见问题
Q：命令报「有歧义的参数 '1e3150e'：可同时是版本和文件」？
导出后工作区出现了同名文件夹 1e3150e，git 把哈希误判为路径。在版本与路径间加 -- 分隔即可，例如 git show --stat --oneline 1e3150e --。
Q：tar 报「无法 open: 没有那个文件或目录」？
目标目录尚未创建。先 mkdir -p <子目录> 再执行 git archive ... | tar -x -C <子目录>。