huguma’s blog (仮)

IT技術関連中心の備忘録

GitHub pages(リポジトリ別Webページ)の設定(基礎編)

GitHubでは自分が作成したリポジトリに対応したWebページ(GitHub pages)を作成して公開できます。はじめに基本事項を確認しておきます。

  • リポジトリに対してひとつ(一式)
  • スタティックページのみ
  • 取得できるURLはhttps://ユーザ名.github.io/リポジトリ名
  • サイズの上限は1GB(目安)
    • ただし実際の条件は何だか複雑です(詳しくはこの後の応用編で説明する予定)

この他にユーザ単位のページ作成機能もあります。詳しくはGitHub pagesホームをご覧下さい。

GitHub project pagesで実際に作った例を一つ紹介します(先日自作した暇つぶし)。

http://higuma.github.io/bouncing-balls/

作成方法は大きく分けて2種類あります。

  • Automatic page generatorを使う
  • 手動で作成する(今回説明するのはこちら)
    • スタティックHTMLページなら何でも自由に作ることができます

ただしGitHubなので昔のレンタルサーバみたいにFTPでアップロードすればOKという訳にはいかず、gitの基礎知識が必要になります。方法は次に書いてあります。

GitHug Help - Creating Project Pages manually

必要な説明は全てここに書いてあるのですが、手順の各ステップがどういう意味なのかちゃんと理解して作業しないと痛い目に会います(実際痛かったです...)。ここでは自分への備忘録を兼ねてできるだけ親切に説明します。

全体の仕組み

はじめにどういうメカニズムで機能しているかを簡単に説明しておきます。GitHub側の仕組みはいたってシンプルなものです。

  • リポジトリ(以下repo)にgh-pagesというブランチがあるかチェック
  • もしあればそのブランチ全体をGitHub pagesとして認識する
  • gh-pagesブランチのpushを検出しhttps://ユーザ.github.io/リポジトリにデプロイ

GitHubは内部処理を公開していないため以上はあくまで推測ですが、この程度の察しを付けておけばその後作業する時に戸惑うことはないと思います。

GitHubにgh-pagesブランチがpushされることによりこの作業が行われ、デプロイが完了するとページを閲覧できるようになります。

  • デプロイ作業のため少し時間がかかります(通常1-2分、最大15分)
  • もしデプロイに失敗するとエラーメッセージが書かれたメールが送られてきます

失敗することはほぼないと思います。しかし私は数日前に無茶なことをしてこの珍しいメールを受信しました(これも後で応用編で説明する予定です)。

作業前に確認

それでは実際の作業の説明に入りますが、作業を始める前にローカルrepoとGitHubのリモートrepoの同期が取れていることを確認しておきます。

以下初歩的な内容は(初心者の皆さんへ)と前置きしますが、「初心者」とはちょっと前の私自身そのものです。勉強し始めの頃自分がつまづいた点を少し紹介しておきたいと思います。

  • masterブランチがcommit完了した状態になっていること(重要)
  • それをgithubにpush済であること(これも重要)

(初心者の皆さんへ)これがなぜ重要かというと、後でファイルの全消去という(恐怖の?)作業があるからです。でもcommitさえしておけば後でいくらでもcheckoutで復元できます(何も怖くありません)。

なおGitHub helpではこれを確実に保証するため、はじめにgit cloneで作業用のコピーを作っておくようにと書いています。

$ git clone https://github.com/user/repository.git

しかしこれはおすすめしません(全てを理解した上でやるならいいですが...)。最初の頃私がはまった事例を紹介します。

  • 言われた通りcloneしたrepoでgh-pageブランチを作成
    • この先も書いてある通り操作してGitHub pagesサイトを構築(ここまではよい)
  • だがコピーにはローカルrepoで.gitignoreで除外したファイルは含まれていない
  • そこでついmaster用repoとcloneしたgh-pages用repoの2つで並行作業してしまう
    • これが致命的な誤り!
  • その後master側に変更が生じた時に問題が発生し始める
    • 最初の数回はまあ何とかなる
    • しかし何回も繰り返しているとだんだん収拾つかなくなる
  • 最後は制御不能に陥る(そもそも2つを別々に管理するのが間違い)

gh-pagesブランチの作成

それではgh-pagesブランチを作成しますが、ここでは--orphanという(普段は使わない)オプションがポイントです。

$ git checkout --orphan gh-pages

通常(git checkout -bで作成する場合)はmasterから派生した子の枝として作成しますが、orphanブランチは親のいない独立した枝になります。ここから先はmasterとgh-pagesは全く関係がなくなり、ブランチを切り替えて作業することになります。

GitHubページを作成する

次はgh-pagesの中身を設定してGitHubページを構築します。初期状態はmasterブランチと同じ内容が残っているがまだcommitしていないという状態です。分かりやすく(強制的に)全削除してから作業を開始する場合は次の通りです。

$ git rm -rf .

(初心者の皆さんへ)ここはgitに「ファイルが削除された」と認識させるため必ずgit rmを使って下さい(単にrmでは認識しません)。なおgh-pagesから消去したファイルはmaster側にちゃんと保存されています(後で復元方法も説明します)。

もしmasterブランチの中にgh-pagesで使用するファイルが含まれている場合は全消去はせず、git mvで適宜ファイルを移動した方が効率的です(例えばpublic/ディレクトリにスタティックHTML一式がある場合はgit mv public/* .)。

今回は機能確認用に簡単なテスト用メッセージ表示だけ作っておきます。

$ echo 'GitHub Pages test' > index.html

commit + push (+ deploy)

完成したらcommitし、最後にgh-pagesをpushすれば後はGitHub側がdeployしてくれます。なおgit pushのときに(masterではなく)gh-pagesを指定することに注意して下さい。

$ git add .
$ git commit -m 'first pages commit'
$ git push origin gh-pages

後は(念のため1-2分待ってから)ユーザ名.github.io/リポジトリ名にアクセスすればページが表示されます。

masterとgh-pagesの両ブランチには依存関係は全くありません(mergeとかをする意味はありません)。意味のある操作は片方からもう片方に切り替えることだけです。

$ git checkout master
$ git checkout gh-pages

(初心者の皆さんへ)書きかけ状態でこれをやろうとするとgitに怒られます。慌てずに作業用にいったんcommitしてから行えばgitは一瞬のうちに内容を入れ替えてくれます。