GitHub Pages用gh-pagesブランチとmasterブランチの自動同期
Gitフックを用いてGitHub Pages用のgh-pages
ブランチとmaster
ブランチを自動同期させる。
結論としては,リポジトリーに以下の内容の.git/hooks/post-commit
を格納して,コミットの度に,GitHubのリモートリポジトリーのgh-pages
ブランチに,直接master
ブランチを上書きで反映させることで実現できた。
git push -f origin master:gh-pages
導入
GitHubの公開リポジトリーは,ソースコードの閲覧が基本機能であり,HTMLの描画はできない。そのため,HTMLを閲覧する場合,HTMLコードをそのまま読むしかなかった。
GitHub Pagesという静的Webページを生成する機能を使うことで,HTMLの描画ページを閲覧可能となる。
GitHub Pagesにより静的Webページの作成方法には以下の3通りがある。
- ユーザーサイト:
ユーザー名.github.io
リポジトリーを公開 - プロジェクトサイト: リポジトリーの
gh-pages
ブランチを公開 - docsディレクトリー: リポジトリーの
docs
ディレクトリー配下を公開
これらの方法にはそれぞれ利点と欠点がある。自分が思う利点と欠点を以下の表にまとめた。
方法 | 利点 | 欠点 |
---|---|---|
ユーザーサイト |
|
|
プロジェクトサイト |
|
|
docs ディレクトリー |
|
|
ユーザーサイトは公開に当たっての制限が少なく一番自由度は高い。ただし,1個しか持てないことから,ユーザー名.github.io
リポジトリー配下にGitのsubmodule
で登録するなどして,自分で公開したいリポジトリーを登録する必要がある。
docs
ディレクトリーは,リポジトリーのmaster
ブランチにdocsディレクトリーを用意して公開物を配下に格納するだけで済むので,一番気軽だろう。ただし,GitHubの独自仕様のためにプロジェクトのディレクトリー構成を強制されるのが少々気になる。
個人的にはリポジトリー単位で公開の可否が可能で,ファイル配置の自由度が高いことから,gh-pages
ブランチを使ったプロジェクトサイトが一番だと考えている。
ただし,こちらはmaster
ブランチの内容のgh-pages
ブランチへの反映・同期が必要である。手作業で行う場合,以下のコマンドを実行することになる。
git checkout master
# git commit # masterでコミット
git rebase master gh-pages # gh-pagesブランチにmasterの内容を反映
git push origin gh-pages # GitHub Pagesに反映
git checkout master
master
ブランチでのコミットの度に上記コマンドを手打ちするのは手間だ。シェルスクリプトにすれば1回のスクリプト実行で済むとはいえ,スクリプトの実行が手間となり実行忘れにもつながる。
そこで,このmaster
ブランチとgh-pages
ブランチの同期を自動化する。
Gitフック
自動化にはGitフックを利用する。Gitには特定のアクションが発生した際にカスタムスクリプトを実行する方法があり,この機能をGitフックと呼ぶようだ。
このフックはクライアントとサーバーの2のグループに分類される。
- クライアントサイドフック: コミットやマージなどのクライアント操作で実行
- サーバーサイドフック: コミットの受取などのネットワーク操作で実行
今回はGitフックのクライアントサイドフックを使う。何らかのコミット後に先程のコマンドを実行することで自動同期する。
コミット後の任意のコマンドの実行には,.git/hooks/post-commit
にコマンドを記述し,実行権限を付与すればよい。
同期手順
以下のコマンドをリポジトリーの直下で実行して,post-commit
ファイルを作成することでmaster
ブランチとgh-pages
ブランチを自動同期するフックを作成できる。
mkdir -p .git/hooks
cat <<-EOT >.git/hooks/post-commit
git push -f origin master:gh-pages
EOT
chmod +x .git/hooks/post-commit
なお,master
ブランチとgh-pages
ブランチとの同期方法を手作業の手順から変更したことに注意してほしい。
当初は,以下のコマンドでgh-pages
ブランチをmaster
ブランチに付け替えることで,内容を反映させていた。
git rebase master gh-pages
git push -f origin gh-pages
git checkout master
しかし,この方法ではmaster
ブランチでgit commit --amend
やgit rebase -i
で履歴を変更してしまうと,git rebase
コマンドで競合が発生してしまった。
作業中にコミット忘れやコメントミスなどでgit commit --amend
することはよくある。そのため,git rebase
での反映には問題があった。
対策を検討していると「実践GitHub Pages運用のユースケースとワークフローの詳細 | ゆっくりと…」を見つけた。こちらの「2.3 gh-pages専用のリポジトリを作って運用する」で解説されている通り,いってしまえば,今回はGitHub Pagesでmaster
ブランチの内容を描画したいだけだ。
そのため,コミットの度にmaster
ブランチを直接リモートのgh-pages
ブランチにpush -f
で強制上書きすることにした。これにより,master
ブランチをgh-pages
ブランチと自動同期でき,GitHub Pagesを最新に保てる。
ローカルのgh-pages
ブランチは使わないため,以下のコマンドで削除しておく。
git branch -D gh-pages
後で参照しやすいように,GItHubのリポジトリーにも同じコードを格納した。
結論
master
ブランチの内容を自動的にgh-pages
ブランチに反映させ,GitHub Pagesを常に最新に保つ方法を解説した。
GitHub Pagesを使えば,公開用のドキュメントやプロジェクトのWebサイトを同時に作成できて,効率がいい。
今回の仕組みで自動的にWebサイトに反映できるようになるので,積極的にプロジェクトの情報を公開していきたい。
“GitHub Pages用gh-pagesブランチとmasterブランチの自動同期” に対して1件のコメントがあります。