Next.jsなどのビルド成果物（out ディレクトリなど）を、GitHub Pages用のブランチ（deploy ブランチなど）にプッシュしたいケースはよくあります。
今回は、「ビルド生成された out ディレクトリの中身を、デプロイ先ブランチでは dist というディレクトリ名で配置したい」かつ「ソースコードなど余計なファイルは一切含めたくない」という要件を gh-pages パッケージで実現しようとした際にハマった事象と解決策を共有します。
やりたいこと
- プロジェクト: Next.js (Static Exports)
- ビルド成果物:
outディレクトリに出力される - デプロイ先ブランチ:
deploy - ゴール:
deployブランチのルートではなく、distディレクトリの中に成果物を配置したい。かつ、それ以外のファイル（ソースコード等）はブランチに残したくない。
理想のディレクトリ構造（deployブランチ）:
(root)
└── dist/
├── index.html
└── ... (outの中身)使ったツールと前提
npmパッケージの gh-pages を使用します。通常、以下のようなオプションで動作を制御できます。
-d [dir]: アップロードするローカルのディレクトリを指定（今回はout）。通常はここ指定した中身がルートに展開されます。--dest [dir]: デプロイ先のブランチ内での配置ディレクトリを指定。今回はoutの中身をdistとして置きたいので指定します。
これらを踏まえ、以下のコマンドを実行しました。
# outディレクトリの中身を、deployブランチのdistディレクトリ配下にpushする
gh-pages -d out --dest dist -b deploy事象：余計なファイルが含まれてしまう
上記のコマンドを実行したところ、dist ディレクトリは作成されましたが、mainブランチにあるソースコード（package.jsonやsrcフォルダなど）も一緒にdeployブランチに含まれてしまいました。
(deployブランチの実態)
├── src/ <-- いらない
├── package.json <-- いらない
└── dist/ <-- これだけ欲しい原因
「プッシュ対象のブランチ（deploy）がリモートに存在しなかったため」 です。
gh-pages の仕様として、指定したブランチ（今回なら deploy）が存在しない場合、現在のブランチ（main など）をベースに新しいブランチを作成しようとします。そのため、main にあるソースコードがそのままコピーされた状態でブランチが作られ、そこに dist ディレクトリが追加される形になっていました。
-d オプションで指定したディレクトリ「だけ」になるのは、あくまで gh-pages がそのブランチをクリーンアップして上書きする場合の話であり、ブランチ作成時のベースファイルまでは消してくれないようです。
解決策：空のOrphanブランチをあらかじめ作っておく
この問題を解決するには、gh-pages が実行される前に、履歴を持たない空っぽのブランチ（Orphan branch） を作成し、リモートに置いておく必要があります。
以下の手順で、完全に空の deploy ブランチを作成します。
1. Orphanブランチの作成
現在の履歴を引き継がない孤立したブランチを作成します。
# --orphan オプションで履歴を持たないブランチを作成
git checkout --orphan deploy※ git checkout -b ではなく --orphan を単独で使います（Gitのバージョンによっては git switch --orphan deploy でも可）。
2. ファイルの全削除
作成直後は、ワークツリーに main ブランチのファイルが残っている状態（ステージングされている状態）なので、これらをすべて削除します。
# カレントディレクトリ以下の全ファイルを削除
git rm -rf .3. 空コミットとプッシュ
完全に空の状態になったので、この状態をコミットしてリモートにプッシュします。
# 空のコミットを作成
git commit --allow-empty -m "Initial commit for deployment"
# リモートへプッシュ
git push -u origin deploy結果
空のブランチを用意した状態で、再度ビルドとデプロイコマンドを実行します。
npm run build
npx gh-pages -d out --dest dist -b deployこれで、余計なソースコードが含まれず、dist ディレクトリだけが存在するクリーンな deploy ブランチを作成することができました。
まとめ
Next.jsなどのビルド成果物（out ディレクトリなど）を、GitHub Pages用のブランチ（deploy ブランチなど）にプッシュしたいケースはよくあります。
今回は、「ビルド生成された out ディレクトリの中身を、デプロイ先ブランチでは dist というディレクトリ名で配置したい」かつ「ソースコードなど余計なファイルは一切含めたくない」という要件を gh-pages パッケージで実現しようとした際にハマった事象と解決策を共有します。
やりたいこと
- プロジェクト: Next.js (Static Exports)
- ビルド成果物:
outディレクトリに出力される - デプロイ先ブランチ:
deploy - ゴール:
deployブランチのルートではなく、distディレクトリの中に成果物を配置したい。かつ、それ以外のファイル（ソースコード等）はブランチに残したくない。
理想のディレクトリ構造（deployブランチ）:
(root)
└── dist/
├── index.html
└── ... (outの中身)使ったツールと前提
npmパッケージの gh-pages を使用します。通常、以下のようなオプションで動作を制御できます。
-d [dir]: アップロードするローカルのディレクトリを指定（今回はout）。通常はここ指定した中身がルートに展開されます。--dest [dir]: デプロイ先のブランチ内での配置ディレクトリを指定。今回はoutの中身をdistとして置きたいので指定します。
これらを踏まえ、以下のコマンドを実行しました。
# outディレクトリの中身を、deployブランチのdistディレクトリ配下にpushする
gh-pages -d out --dest dist -b deploy事象：余計なファイルが含まれてしまう
上記のコマンドを実行したところ、dist ディレクトリは作成されましたが、mainブランチにあるソースコード（package.jsonやsrcフォルダなど）も一緒にdeployブランチに含まれてしまいました。
(deployブランチの実態)
├── src/ <-- いらない
├── package.json <-- いらない
└── dist/ <-- これだけ欲しい原因
「プッシュ対象のブランチ（deploy）がリモートに存在しなかったため」 です。
gh-pages の仕様として、指定したブランチ（今回なら deploy）が存在しない場合、現在のブランチ（main など）をベースに新しいブランチを作成しようとします。そのため、main にあるソースコードがそのままコピーされた状態でブランチが作られ、そこに dist ディレクトリが追加される形になっていました。
-d オプションで指定したディレクトリ「だけ」になるのは、あくまで gh-pages がそのブランチをクリーンアップして上書きする場合の話であり、ブランチ作成時のベースファイルまでは消してくれないようです。
解決策：空のOrphanブランチをあらかじめ作っておく
この問題を解決するには、gh-pages が実行される前に、履歴を持たない空っぽのブランチ（Orphan branch） を作成し、リモートに置いておく必要があります。
以下の手順で、完全に空の deploy ブランチを作成します。
1. Orphanブランチの作成
現在の履歴を引き継がない孤立したブランチを作成します。
# --orphan オプションで履歴を持たないブランチを作成
git checkout --orphan deploy※ git checkout -b ではなく --orphan を単独で使います（Gitのバージョンによっては git switch --orphan deploy でも可）。
2. ファイルの全削除
作成直後は、ワークツリーに main ブランチのファイルが残っている状態（ステージングされている状態）なので、これらをすべて削除します。
# カレントディレクトリ以下の全ファイルを削除
git rm -rf .3. 空コミットとプッシュ
完全に空の状態になったので、この状態をコミットしてリモートにプッシュします。
# 空のコミットを作成
git commit --allow-empty -m "Initial commit for deployment"
# リモートへプッシュ
git push -u origin deploy結果
空のブランチを用意した状態で、再度ビルドとデプロイコマンドを実行します。
npm run build
npx gh-pages -d out --dest dist -b deployこれで、余計なソースコードが含まれず、dist ディレクトリだけが存在するクリーンな deploy ブランチを作成することができました。
まとめ
gh-pages でデプロイ用ブランチを新規に利用する場合、自動作成に任せると元のブランチのファイルが混入することがあります。
特定のディレクトリ構成のみをきれいに保ちたい場合は、初回のみ手動で空のOrphanブランチを作成しておくのが確実です。
コメント