1. 从一次紧急需求说起：为什么需要“干净”的分支
那天下午，我正在处理一个老项目的重构。这个项目的历史可以追溯到五年前，提交记录密密麻麻，光是feature/开头的分支就有上百个，合并记录更是错综复杂。产品经理突然跑过来，指着屏幕上那个运行了三年、积累了无数“技术债”的release/v2.0分支说：“我们需要基于这个版本的代码，快速启动一个全新的、给特定客户定制的项目。要求是：代码库要干净，不能有之前任何客户的定制代码，最重要的是，不能有这个分支庞杂的提交历史，新项目要从‘零’开始记录。”
这个需求听起来有点反直觉。Git 的核心不就是记录历史吗？我们通常git checkout -b new-branch创建新分支，历史自然就带过去了。但仔细一想，场景其实很常见：
- 项目剥离与重启：从一个成熟但历史复杂的主干中，剥离出一个干净的核心框架，用于启动一个全新的、方向不同的项目。
- 代码交付与审计：向客户或合作伙伴交付源代码时，出于知识产权或代码洁癖，希望只提供最终成品代码，而不包含内部迭代的开发历史。
- 大型重构的起点：当决定对某个模块进行彻底重写时，希望在一个“历史清白”的分支上开始，避免旧历史对
git blame等操作造成干扰。 - 创建模板项目：将某个项目的当前状态保存为一个“模板”或“种子项目”，后续新项目都基于此模板创建，而不需要模板自身的演化历史。
如果你直接用git branch或git checkout -b，新分支会指向原分支最新的那个提交对象，历史通过指针追溯，一分不少。这显然不符合我们的要求。我们需要的是类似“另存为”的效果：只保留当前工作目录下的文件快照，并以此作为第一个提交，开启一段全新的、独立的历史线。
网上常见的“孤儿分支”（git checkout --orphan）是一个思路，但它创建的是一个完全空的分支，我们还需要手动把文件添加进去，步骤稍显繁琐。而更直接、更符合“只保留文件”直觉的方法，是利用 Git 底层命令，进行一次“外科手术式”的操作。下面，我就把这次解决问题的完整链路，包括思考过程、具体命令、背后的原理以及我踩过的坑，详细分享给你。
2. 核心思路拆解：Git如何“忘记”历史
要理解怎么操作，首先得明白 Git 是怎么存储数据的。简单来说，Git 仓库里主要有四种对象：blob（存储文件内容）、tree（存储目录结构和对应的blob）、commit（提交对象，包含作者、时间、提交信息和一个指向顶层tree的指针，以及父提交指针）、tag（标签）。分支（branch）本质上只是一个指向某个commit对象的可移动指针。
所以，当我们说一个分支“包含”历史，其实是说这个分支指针指向的commit，通过它的父指针，可以一路回溯到初始提交，形成一条链。创建新分支并保留历史，就是新建一个指针，指向同一个commit。
那么，要“不保留历史”，我们就需要打破这个链条。具体来说，是创建一个新的commit对象，这个对象的父提交指针为空（即没有父提交），同时，这个新commit所指向的tree对象，应该和原分支最新提交的tree对象内容完全一致。这样，新提交就拥有了和原分支一模一样的文件树快照，但它的历史追溯就到此为止了，前面是一片空白。
听起来有点抽象？我们可以把它分解为几个关键步骤：
- 获取源状态：拿到原分支最新提交对应的文件树（tree）。
- 创建新起点：创建一个没有父提交的、全新的提交对象（root commit），并让它指向步骤1中的文件树。
- 切换并指向：创建一个新的分支，让它的指针指向这个全新的提交。
Git 提供了多种方式来实现这个目标，每种方式在操作细节和原理上略有不同。接下来，我们将深入两种最典型的方法：一种是利用git checkout --orphan的“官方”方法，另一种是更底层、更灵活的git commit-tree命令组合。我会详细解释每一步在做什么，以及为什么这么做。
3. 方法一：使用git checkout --orphan的标准化流程
这是 Git 官方提供的、用于创建无历史分支的命令。--orphan参数的名字很形象，它创建了一个“孤儿”分支，这个分支还没有任何提交（即没有父提交）。当你在这个分支上首次提交时，这个提交就会成为根提交（root commit）。
3.1 完整操作步骤与命令解析
假设我们当前在old-branch分支上，它的代码状态正是我们想要的。我们想创建一个名为new-clean-branch的新分支，只保留当前文件。
# 1. 确保你在源分支上，并且工作区是干净的 git checkout old-branch git status # 确认没有未提交的修改 # 2. 创建孤儿分支并切换到该分支 git checkout --orphan new-clean-branch执行完git checkout --orphan new-clean-branch后，你会立刻切换到new-clean-branch分支。但如果你立刻运行git status，可能会看到一个非常有趣的现象：所有之前被 Git 跟踪的文件，都会出现在“待提交的变更”区域，就好像你刚刚把它们全部git add了一样。
这是因为--orphan创建的新分支，其HEAD指向了一个不存在的提交（或者说一个空的提交）。Git 比较当前工作区（实际上还是old-branch的文件状态）和这个新分支的“当前提交”（空），发现所有文件都是“新文件”，所以将它们全部标记为已暂存（staged）。
注意：此时，这些文件在工作目录里，也在暂存区里，但它们还没有被提交。历史仍然是空的。
# 3. （可选但推荐）清理不必要的文件 # 虽然我们想保留代码，但有些文件可能不需要，比如原分支的 .gitignore、配置文件等。 # 你可以手动删除或修改它们。 # 例如，如果你想保留.gitignore，可以不动它。如果想清空，可以： # echo “” > .gitignore # 4. 提交，创建全新的根提交 git commit -m “Initial commit for new-clean-branch: fresh start from old-branch state”这个git commit命令是整个过程的关键。它创建了一个全新的提交对象，这个对象没有父提交。它把当前暂存区（也就是所有从old-branch带过来的文件快照）作为这次提交的内容。从此，new-clean-branch分支就有了第一个，也是唯一一个（到目前为止）的提交，它包含了我们需要的所有文件，但历史是全新的。
3.2 原理深入与潜在陷阱
原理：git checkout --orphan并没有复制任何提交历史。它只是创建了一个新的分支引用（refs/heads/new-clean-branch），并将HEAD指向它，同时将索引（暂存区）重置为与源分支工作区相同的状态。因为新分支还没有任何提交，所以索引与“空提交”比较的结果就是所有文件都是新增。
陷阱一：未跟踪文件。--orphan只会处理已被 Git 跟踪的文件。如果old-branch工作区存在未跟踪的文件（比如node_modules/,*.log等），它们不会自动出现在新分支的暂存区。如果你需要它们，必须手动添加。这其实是一个优点，因为它天然地过滤了构建产物、日志等垃圾文件。
陷阱二：提交信息。由于这是根提交，它的提交信息就是新项目的起点。建议写清楚，例如“项目初始化：基于[原项目名]的[原分支名]状态剥离”。
陷阱三：远程仓库。现在new-clean-branch只是一个本地分支。如果你需要推送到远程（例如 GitHub、GitLab），需要：
git push -u origin new-clean-branch由于这是一个与远程任何分支都没有历史关联的全新分支，首次推送必须使用-u(或--set-upstream) 来建立跟踪关系。
这个方法相对简单直观，是大多数情况下的首选。但它有一个“缺点”：它必须基于一个已存在的、干净的工作目录。如果你想基于某个特定的提交（而不是当前工作目录）来创建干净分支，或者想进行更精细的控制，就需要用到更底层的方法。
4. 方法二：底层命令git commit-tree的精细控制
git commit-tree是 Git 的管道命令（plumbing command），它允许我们直接使用一个tree对象的 SHA-1 哈希值来创建一个提交对象，并且可以指定其父提交。如果我们不指定父提交，创建的就是一个根提交。这给了我们最大的灵活性。
4.1 操作步骤详解
我们的目标是：基于old-branch分支最新的提交（假设其哈希为abc123），创建一个新的根提交，并以此创建新分支。
# 1. 获取源提交的树对象（tree）哈希 git checkout old-branch SOURCE_COMMIT_HASH=$(git rev-parse HEAD) # 获取当前提交的完整哈希，例如 abc123 SOURCE_TREE_HASH=$(git rev-parse $SOURCE_COMMIT_HASH^{tree}) # 获取该提交对应的树对象哈希 # 可以 echo $SOURCE_TREE_HASH 查看一下 # 2. 创建一个没有父提交的新的提交对象 # 我们需要提供一个提交信息。可以写在一个文件里，或者用 echo 管道传递。 echo “Initial commit: Fresh codebase from $SOURCE_COMMIT_HASH” > /tmp/commitmsg.txt NEW_COMMIT_HASH=$(git commit-tree $SOURCE_TREE_HASH < /tmp/commitmsg.txt) # 此时，NEW_COMMIT_HASH 就是新创建的根提交的哈希值 # 3. 基于这个新的提交对象创建分支 git branch new-clean-branch-advanced $NEW_COMMIT_HASH # 4. 切换到新分支 git checkout new-clean-branch-advanced现在，new-clean-branch-advanced分支就指向了我们刚刚创建的、孤立的根提交。用git log --oneline查看，你会发现只有一条提交记录，历史是干净的。
4.2 进阶技巧与场景应用
这种方法强大在哪里？
场景一：基于任意历史提交创建干净分支。你不需要切换工作目录到那个提交的状态。假设你想基于old-branch的某个历史提交def456创建干净分支：
TARGET_TREE_HASH=$(git rev-parse def456^{tree}) echo “Fresh start from historical commit def456” | git commit-tree $TARGET_TREE_HASH | xargs git branch new-branch-from-history场景二：在创建提交前修改树对象。你可以先通过git read-tree和git write-tree等命令，对获取到的SOURCE_TREE_HASH所代表的文件树进行修改（例如，删除某个目录，添加一个文件），生成一个新的tree对象，再用这个新的tree去创建提交。这实现了在“剥离历史”的同时进行“代码快照手术”。
场景三：编写自动化脚本。由于所有操作都基于明确的哈希值和命令，这种方法非常适合集成到 CI/CD 流水线或自动化脚本中，用于定期从主分支生成干净的“发布快照”分支。
重要提示：
git commit-tree创建提交时，默认使用当前 Git 配置的用户名和邮箱作为作者和提交者。如果你在脚本中运行，需要确保这些配置是正确的，或者通过-p参数指定父提交（这里我们不需要），以及通过环境变量GIT_AUTHOR_NAME,GIT_AUTHOR_EMAIL,GIT_COMMITTER_NAME,GIT_COMMITTER_EMAIL来覆盖。
5. 实战避坑：从操作到维护的全链路指南
无论用哪种方法，创建完“干净分支”只是第一步。在实际项目中，你可能会遇到一些意想不到的问题。
5.1 子模块的处理
如果你的原项目包含了 Git 子模块（Submodules），那么事情就变得复杂了。上述两种方法都不会自动处理子模块。
- 方法一(
--orphan)：执行后，子模块的目录会变成空文件夹（因为.gitmodules文件还在，但子模块本身未被初始化）。你需要手动运行git submodule init && git submodule update来重新拉取，但这会拉取原分支配置的子模块提交，可能不是你想要的。 - 方法二(
commit-tree)：情况类似，新分支包含的是子模块目录的tree引用，但子模块仓库本身的内容需要额外处理。
建议：如果项目有子模块，并且你希望在新分支中保留它们，最稳妥的方式是：
- 在原分支，确保子模块已更新到所需版本。
- 使用
git checkout --orphan方法。 - 提交前，删除
.gitmodules文件以及所有子模块目录（如rm -rf third_party/libfoo）。 - 将子模块的代码直接复制到项目目录中（作为普通代码管理），或者重新思考代码架构。对于想要“干净历史”的新项目，携带子模块往往不是个好主意。
5.2 大文件与仓库体积
你可能会担心：虽然历史没了，但原分支的所有文件内容（blob对象）是不是还留在仓库里，导致仓库体积没变小？ 答案是：是的，短期内它们还在。Git 的对象存储是内容寻址的。只要某个blob或tree对象被任何提交引用，它就不会被垃圾回收。我们创建的新提交，其tree指向的blob对象，和原分支最新提交指向的blob对象，很可能是同一个（因为文件内容没变）。所以，文件数据并没有重复存储，但也没有被删除。
如果你希望彻底清理原分支不再使用的历史对象，以减小仓库体积，需要在原分支上进行操作（例如git gc --aggressive --prune=now），但这会影响所有共享该仓库的人，且需要谨慎操作。对于“干净分支”本身，由于其历史短，后续的提交不会引用旧对象，随着时间推移和原分支历史的演进，那些独有的旧对象最终可能被 GC 清理。
5.3 与远程仓库的协作
当你把new-clean-branch推送到远程后，其他同事如何参与？
# 同事需要获取这个全新的分支 git fetch origin git checkout -b new-clean-branch origin/new-clean-branch对于他们来说，这就是一个普通的新分支，只是历史很短。所有常规的 Git 操作（pull,push,merge）都照常工作，没有任何特殊之处。这解决了“交付干净代码”场景下的协作问题。
5.4 IDE 与 GUI 客户端的兼容性
像 VS Code、IntelliJ IDEA、SourceTree 这样的工具，它们能正确识别这种“孤儿分支”或“根提交分支”吗？就我的经验而言，主流现代工具都没有问题。它们会正常显示分支、提交历史和文件变更。在 IDEA 中，你可能需要右键项目 -> Git -> Repository -> Fetch 来获取远程的这个新分支。在 SourceTree 中，拉取（Pull）后新分支会自动出现在侧边栏。唯一可能的小问题是，有些工具的图形化分支合并视图可能会因为缺少共同祖先而显示得有些奇怪，但这不影响实际功能。
6. 方法对比与选型建议
我们来系统对比一下两种核心方法：
| 特性 | git checkout --orphan | git commit-tree+git branch |
|---|---|---|
| 操作复杂度 | 低，一条命令进入状态，再提交即可。 | 中，需要多条命令组合，涉及哈希值获取。 |
| 灵活性 | 较低，只能基于当前工作目录状态。 | 极高，可以基于任意提交的树对象，可在提交前加工树对象。 |
| 直观性 | 高，符合“创建分支-提交”的常规工作流。 | 低，需要理解 Git 底层对象模型。 |
| 适用场景 | 绝大多数情况，基于当前最新代码创建干净分支。 | 自动化脚本、需要基于历史某一点创建、需要在创建时精确控制文件树。 |
| 对工作区影响 | 会改变当前工作目录和暂存区状态。 | 不改变当前工作目录和暂存区，纯粹在.git目录内操作。 |
| 子模块处理 | 需要额外手动处理，较麻烦。 | 同样需要额外手动处理。 |
选型建议：
- 新手或追求快捷：无脑选择
git checkout --orphan。它的流程最接近常规 Git 操作，不易出错。 - 需要自动化或精确控制：选择
git commit-tree。当你需要将这一过程写入脚本，或者要基于某个 Tag 版本创建干净分支时，它是唯一的选择。 - 不确定时：先用
git checkout --orphan手动操作一遍，理解整个流程和结果。当遇到其局限性时，再考虑使用底层命令。
我个人在大多数需要为演示、交付或启动新项目而创建干净代码库的场景下，都使用--orphan方法。它的步骤简单，结果可预测。只有在我编写内部工具，用于每周从开发主干自动生成一次“本周发布快照”分支时，才会用到commit-tree脚本。
7. 扩展思考：git archive的替代方案
除了在 Git 仓库内操作，还有一个更“物理”的思路：直接导出文件，然后初始化一个新仓库。这完全跳出了分支操作的范畴，但能达到同样的目的，并且是100%绝对干净，连一个多余的 Git 对象都不会留下。
# 1. 在原仓库中，导出所需分支的最新文件 git archive --format=tar --prefix=project-clean/ HEAD | (cd /path/to/new/location && tar xf -) # 这条命令将当前分支（HEAD）的所有文件，以tar格式导出到指定目录的 project-clean/ 文件夹下。 # 2. 进入新目录，初始化全新的 Git 仓库 cd /path/to/new/location/project-clean git init git add . git commit -m “Initial commit: fresh repository from exported code”这种方法的核心优劣分析：
优点：
- 绝对干净：新仓库与旧仓库在 Git 层面没有任何关联，对象数据库完全独立。
- 体积最小：新仓库只包含你提交的文件所对应的对象，没有任何历史包袱。
- 操作安全：对原仓库零风险，纯读操作。
缺点：
- 丢失 Git 元数据：
.gitignore,.gitattributes等文件会被保留（因为它们是普通文件），但原仓库的所有分支、标签、提交记录、注释等信息全部丢失。 - 无法追溯：新仓库的代码完全无法通过 Git 历史追溯到原仓库的任何一个提交。
- 步骤稍多：需要文件导出和重新初始化的步骤。
适用场景：
- 代码交付：当你需要将代码作为“最终产品”交给客户，且合同明确要求不包含任何开发历史时，这是最合规的方式。
- 创建开源项目模板：你想把自己的项目变成一个供他人使用的 starter template，通常希望提供一个最简化的初始状态。
- 彻底的项目分家：两个项目未来将走向完全不同的方向，且确定不再需要共享任何 Git 历史。
所以，如果你的需求不仅仅是“在同一个仓库里要一个干净的分支”，而是“我需要一个完全独立的、全新的代码仓库”，那么git archive是比创建孤儿分支更彻底、更合适的工具。它完成了物理层面的剥离，而不仅仅是逻辑层面的历史切割。
经过上面几种方法的折腾，最后再分享一个我总结的小 checklist，在创建“干净分支”前问自己几个问题，能帮你选对方法：
- 新分支是否还需要与原仓库共享未来的更新？如果否，考虑
git archive新建仓库。 - 是否需要基于某个特定的历史提交（而非最新提交）？如果是，选择
git commit-tree方法。 - 是否只是临时用于演示或测试，后续会合并回原分支？如果是，或许你需要的不是干净分支，而是
git worktree或者直接打 Tag。 - 项目是否有复杂的子模块或大型二进制文件？如果有，务必提前规划好处理方案，这往往是最大的麻烦来源。
归根结底，Git 的强大在于它提供了从高层到低层的一系列工具。理解“只保留文件不保留历史”这个需求背后的本质——创建无父提交的新提交——就能在众多工具中选择最顺手的那一把。下次当你面对一个历史厚重、需要轻装上阵的新起点时，希望这些方法能帮你干净利落地解决问题。
