如何将仓库子目录拆分到独立分支且不干扰main分支历史

一、手动初始化分支（仅需执行一次） #

先把main分支里的dist内容迁移到新的dist分支，同时清理main分支的dist目录：

1. 创建并切换到空的dist分支（孤儿分支，无历史提交）

git checkout --orphan dist

2. 清空分支内所有文件（孤儿分支会默认携带main的文件，需要清除）

git rm -rf .

3. 从main分支拉取dist目录下的所有内容到当前分支根目录

git checkout main -- dist/.

4. 删除临时生成的dist目录（现在内容已经在根目录了）

rm -rf dist

5. 提交并推送到远程dist分支

git add .
git commit -m "初始化dist分支，同步main分支的dist内容"
git push origin dist

6. 切回main分支，清理dist目录并加入.gitignore

git checkout main
git rm -rf dist
echo "dist/" >> .gitignore
git add .gitignore
git commit -m "移除dist目录并加入忽略列表"
git push origin main

二、自动化流程（YAML配置） #

下面是通用的CI/CD配置（以GitHub Actions为例，其他平台可类比调整），实现每次main分支更新后自动同步dist内容到dist分支，同时确保main分支不会保留dist目录：

name: 同步dist目录到dist分支

on:
  # 当main分支推送代码时触发（可根据需要限制路径，比如只在src目录变化时触发）
  push:
    branches: [ main ]
  # 支持手动触发
  workflow_dispatch:

jobs:
  sync-dist-branch:
    runs-on: ubuntu-latest
    steps:
      - name: 拉取代码仓库
        uses: actions/checkout@v4
        with:
          fetch-depth: 0 # 需要拉取完整历史，避免分支切换出错

      - name: 配置Git身份
        run: |
          git config --global user.name "CI自动同步"
          git config --global user.email "ci-sync@example.com"

      # 如果dist是构建生成的，添加以下步骤生成dist目录（根据项目调整）
      - name: 安装依赖
        run: npm ci # 换成你的项目依赖安装命令，比如pip install、yarn install等

      - name: 构建生成dist目录
        run: npm run build # 换成你的构建命令，比如make build等

      - name: 同步dist内容到dist分支
        run: |
          # 切换到dist分支，不存在则创建孤儿分支
          git checkout dist || git checkout --orphan dist
          # 清空当前分支所有内容，确保只保留最新的dist文件
          git rm -rf .
          # 从当前工作区拉取dist目录下的内容到分支根目录
          cp -r dist/. .
          # 删除临时dist目录
          rm -rf dist
          # 检查是否有内容变化，无变化则跳过提交
          if git diff --quiet; then
            echo "dist目录无更新，跳过提交"
            exit 0
          fi
          # 提交并推送
          git add .
          git commit -m "自动同步main分支的最新dist内容"
          git push origin dist

      - name: 确保main分支没有dist目录
        run: |
          git checkout main
          # 如果dist目录存在则删除
          if [ -d "dist" ]; then
            git rm -rf dist
            # 确保.gitignore包含dist/，防止误提交
            grep -qxF 'dist/' .gitignore || echo 'dist/' >> .gitignore
            git add .gitignore
            # 检查是否有提交内容，无变化则跳过
            if git diff --quiet; then
              echo "main分支无需更新"
              exit 0
            fi
            git commit -m "自动清理main分支的dist目录"
            git push origin main
          fi

三、解决你遇到的问题 #

1. 克隆到独立目录上下文错误：你之前克隆后没有切换到dist分支，导致操作还是在main分支的上下文里。上面的流程通过git checkout dist明确切换分支，避免这个问题。
2. git subtree报错"fatal: no new revisions were found"：这个错误通常是因为subtree没有检测到新的提交变化，或者subtree的路径配置有误。用孤儿分支的方式更直接，因为我们需要dist分支完全独立，根目录就是原dist的内容，不需要和main分支共享历史。

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