Life goes on

何かJavaScriptとかVimとかMacとかに関係してそうな深淵から覗かれる者

git subtreeで自動生成ドキュメントをGitHub Pagesに連携してみた

何か色々試してみた結果これが一番スマートかなーとやってみました。

やりたかったことは結構シンプルでして。masterブランチで更新されてる特定のディレクトリをそのままgh-pagesブランチと連動して更新していきたいというだけでした。 要はこんな感じ。

  1. masterブランチでstyledoccoとかjsdocコマンドで生成したドキュメントファイルをdocsというディレクトリに入れておく。
  2. 1で生成したdocsディレクトリだけを、gh-pagesブランチに持っていく。
  3. gh-pagesgit pushしてドキュメントが更新されるようにする。

この一連の流れをどうやって実行しようかなーと思ってて、git submoduleだと参照はしやすくても、更新しにくいしなあということで結果git subtree使っていこうかなという感じに。 もちろんmasterで作ったdocsをいったんローカルリポジトリの外にコピーしてgh-pagesにしてまた持ってくる…っていうのも出来るっちゃ出来ますけどスマートじゃないやという。

で、色々調べたんですが、このgit subtreeがクセモノで。git submoduleとかだと色々サンプルもあるんですが、git subtreeに関しては古い情報と新しい情報が入り混じっててカオス。 おまけに実例というかサンプル少ない。ので、記録として。

ちなみに簡単なディレクトリ構成としては

root/
root/src
root/docs

のような感じでrootGruntfile.jsなどがある感じ。root/src内のcssとかをstyledoccoなど使って、root/docsに生成してます。

下準備

まずは、同じリモートリポジトリ内で管理してたdocsディレクトリをリポジトリ外に移動して新しくドキュメント用のリモートリポジトリを作ります。

$ cd root
$ mv docs ../docs
$ cd ../docs
$ git init
$ git add .
$ git commit -m "initial commit"
$ git remote add document https://path/to/document
$ git push -u origin master

リモートの設定をしてgit subtree addでディレクトリ管理

次に元のリポジトリに戻ってから、ドキュメントのリモートリポジトリをgit remote addします。設定できたら、git subtree addコマンドでsubtreeとしてdocsディレクトリを登録。

$ cd root
$ git remote add -f document https://path/to/document # ついでにfetchしておく
$ git subtree add --prefix=docs document master --squash # git add --prefix=subtreeさせたいディレクトリ リモートリポジトリ リモートで更新するブランチ
$ git checkout gh-pages
$ git subtree add --prefix=docs document master --squash

git subtree addするときは--squashオプション付けておけば、documentリポジトリのコミットを1つにまとめてマージしてくれます。これで準備完了。

ドキュメント更新

普通に例えば、grunt叩いたりmake叩いたりしてドキュメント生成します。で、これを普通にコミットまでさせるんですが、この更新をpushするときは普通のpushの他にgit subtree pushも使います。 これによって、全然違うリモートリポジトリであるdocumentpushすることができるようになります。ここがgit submoduleと一番違う部分じゃないかと。

$ git checkout master
$ grunt cssdoc # まあこれでstyledoccoでドキュメント生成すると思いなせえ
$ cd docs
$ git add .
$ git commit -m "update docs"
$ cd ../
$ git subtree push --prefix=docs document https://path/to/document # git subtree addと同じ
$ git push origin master # `origin/master`に変更push

試しに、すでに外部のリポジトリになってるはずのdocsリポジトリに行ってみてgit pullしてみるとちゃんとコミットが取りこまれるのが分かります。ちなログは適当。

$ cd ../docs
$ git pull origin master
remote: Counting objects: 18, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 15 (delta 10), reused 10 (delta 5)
Unpacking objects: 100% (15/15), done.
From github.com:Layzie/document
 * branch            master     -> FETCH_HEAD
   480cedb..386ca75  master     -> origin/master
Updating 430cedb..3iaca75
Fast-forward
 index.html | 14 ++++++++++----
 btn.html |  2 +-
 2 files changed, 11 insertions(+), 5 deletions(-)

GitHub Pagesの更新

もともとのリポジトリに既にあるdocsディレクトリに関しては、git subtree pullで変更を取り込んでいきます。

$ git checkout gh-pages
$ git subtree pull --prefix=docs document https://path/to/document --squash# git subtree addと同じ
remote: Counting objects: 18, done.
remote: Compressing objects: 100% (10/10), done.
remote: Total 15 (delta 10), reused 10 (delta 5)
Unpacking objects: 100% (15/15), done.
From github.com:Layzie/document
 * branch            master     -> FETCH_HEAD
   480cedb..386ca75  master     -> origin/master
Updating 430cedb..3iaca75
Fast-forward
 index.html | 14 ++++++++++----
 btn.html |  2 +-
 2 files changed, 11 insertions(+), 5 deletions(-)
$ git push origin gh-pages

やっぱりこのとき--squashしておかないと変にコンフリクト起したりするんで忘れずに。あとやっぱりpullのログは適当。

ということでこれで晴れてGitHub Pagesが更新されました!

参考URL

結構いろいろやり方書いてあったんですが、その中でも下記の3つは役に立ちました。というかほぼまま記事にしてる気がしないでもない。

ありがたや。