すたらブログ

文系Webプログラマの備忘録

GitHubプロジェクトのディレクトリ構成を自分なりに整理

GitHub

目次

前提: デモはGitHubPagesで公開

GitHubでは、主に自作のjQueryプラグインを公開しています。
以前から、デモの公開場所にはusamimi.infoというホスティングサービスを利用しています。
無料かつ広告無しなのにPHPを使えるので、かれこれ7年以上愛用しています。
( http://www.usamimi.info/~sutara/ )
ただ、デモ一覧をPHP+SQLiteで管理しているのですがそのコードが古く、デモのソースを更新する場合はデータベースの値も変更したうえでFTP送信しなければならないなど、今の感覚では管理が面倒くさくなりました。
ここらで大掛かりな整理をしなければなりません。

手始めに、PHPを使わないデモはGitHubPagesで公開することにします。
PHPを使うデモだけをusamimiに残して、それらの管理と表示方法は後日じっくり考えます。

今後のディレクトリ構成

GitHubで管理しているプロジェクトをGitHubPagesでも公開する場合、「gh-pages」ブランチを作ってその中に必ずindex.htmlを入れなくてはいけません。
このindex.htmlの内容をどうするか悩みました。
プロジェクトの説明をあまり詳しく記述すればREADME.mdと被ってしまいますし。
プロジェクト内の特定のフォルダだけを「gh-pages」ブランチとすることもできるようですが、複雑にはしたくないので下記のような構成でいこうと決めました。

  • dist/
    プラグインの本体。
    jquery.hoge-fuga.js、min.js、その他CSSや画像など。
  • demo/
    デモ。
  • README.md
    プロジェクトの顔。
    丁寧に解説。
    デモへのリンクも設けるが、あくまで解説の添え物。
  • index.html
    デモの目次。
    無味乾燥だが、完全な一覧。

(追記: 2017-04-27)
以下の「実例」と「コマンドひとつで」の内容は古くなっています。
現在では、masterブランチの./index.html、または./docs/index.htmlを用意して、リポジトリの「Settings」で選択するだけでGitHub Pagesを公開できます。

実例

プロジェクト用ページの作成方法は色々あるようです。

しかし、「master」の内容を丸ごと流用するなら、git push origin master:gh-pagesというコマンドだけでOKです。
自動でリモートのみに「gh-pages」ブランチを作ってくれて、デモのページもすぐに表示可能になります。
今回は、「jquery.csv-calc」というプラグインのプロジェクトを前述の方針で整理しました。

(参考: 今さら聞けないgit pushコマンド - Shoichi Matsuda’s diary)

コマンドひとつで

今後はソースコードを変更したら、その都度「master」と「gh-pages」の両方へpushします。

# masterブランチへ
git push origin master

# その後、gh-pagesへ
# デモも更新される
git push origin master:gh-pages

なお、あらかじめプロジェクト内の.git/configを編集しておけば、コマンドひとつで両方へpushできるのでお手軽です。
例として、「jquery.csv-calc」の.git/configは下記のようになっています。

[core]
    repositoryformatversion = 0
    filemode = false
    bare = false
    logallrefupdates = true
    symlinks = false
    ignorecase = true
    hideDotFiles = dotGitOnly
[remote "origin"]
    url = git@github.com:sutara79/jquery.csv-calc.git
    fetch = +refs/heads/*:refs/remotes/origin/*
[branch "master"]
    remote = origin
    merge = refs/heads/master

下記のように[remote "origin"]の欄に追記します。

[remote "origin"]
    url = git@github.com:sutara79/jquery.csv-calc.git
    fetch = +refs/heads/*:refs/remotes/origin/*
    push = +refs/heads/master:refs/heads/gh-pages
    push = +refs/heads/master:refs/heads/master

これでgit push origin masterだけで、事前に-uや--set-upstreamを行っていればgit pushだけで、両方へpushしてくれます。
下記は実際の実行結果です。

$ git push
Counting objects: 3, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (3/3), done.
Writing objects: 100% (3/3), 520 bytes | 0 bytes/s, done.
Total 3 (delta 1), reused 0 (delta 0)
To git@github.com:sutara79/jquery.csv-calc.git
   fa42708..17f78c4  master -> gh-pages
   fa42708..17f78c4  master -> master