git subtreeで自動生成ドキュメントをGitHub Pagesに連携してみた
何か色々試してみた結果これが一番スマートかなーとやってみました。
やりたかったことは結構シンプルでして。masterブランチで更新されてる特定のディレクトリをそのままgh-pagesブランチと連動して更新していきたいというだけでした。
要はこんな感じ。
masterブランチでstyledoccoとかjsdocコマンドで生成したドキュメントファイルをdocsというディレクトリに入れておく。- 1で生成した
docsディレクトリだけを、gh-pagesブランチに持っていく。 gh-pagesにgit pushしてドキュメントが更新されるようにする。
この一連の流れをどうやって実行しようかなーと思ってて、git submoduleだと参照はしやすくても、更新しにくいしなあということで結果git subtree使っていこうかなという感じに。
もちろんmasterで作ったdocsをいったんローカルリポジトリの外にコピーしてgh-pagesにしてまた持ってくる…っていうのも出来るっちゃ出来ますけどスマートじゃないやという。
で、色々調べたんですが、このgit subtreeがクセモノで。git submoduleとかだと色々サンプルもあるんですが、git subtreeに関しては古い情報と新しい情報が入り混じっててカオス。
おまけに実例というかサンプル少ない。ので、記録として。
ちなみに簡単なディレクトリ構成としては
root/ root/src root/docs
のような感じでrootにGruntfile.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も使います。
これによって、全然違うリモートリポジトリであるdocumentにpushすることができるようになります。ここが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つは役に立ちました。というかほぼまま記事にしてる気がしないでもない。
- git - subtree コマンドで別のリポジトリを指定したフォルダに取り込んでpushとかpullをできるようにする - Qiita [キータ]
- git subtree tutorial - O, Hai Der!
- Alternatives To Git Submodule: Git Subtree - Atlassian Blogs
ありがたや。
