tech.guitarrapc.cóm

Technical updates

GitHub for Unityを導入してみる

Unityはいくつかの理由でGitHub.comを使うのが手間になることがあります。その中で最も障害となりえるのがlarge binary assets、つまり大きなサイズのバイナリファイルの扱いです。

今回は、先日発表されたGitHub for Unityを利用することで、このフローがどう改善するのか見てみましょう。

https://github.com/blog/2329-introducing-GitHub-for-unity

なぜGitHub.comでUnityを管理するのが手間なのか

さて、ゲーム開発は多くのスタッフが協力して成り立ちます。コードやアセットの管理にGitHubのような分散バージョン管理システム(DVCS) を用いるのは自然でしょう。

これはUnityのようなゲームエンジンでコンテンツを作るときも同じです。しかしUnityをはじめとしてゲーム開発ではアセットが大量に必要になります。特にTexture *1ファイルの数とサイズが大きくなりやすいことで苦しいことも多いのではないでしょうか。

ここで立ちはだかるのがGitHubのディスクQuotaと称される単一ファイル、リポジトリへの制限です。*2

https://help.github.com/articles/what-is-my-disk-quota/

2017/7/14時点で次の推奨 (事実上の制限) になっています。*3

1. We recommend repositories be kept under 1GB each. This limit is easy to stay within if large files are kept out of the repository. If your repository exceeds 1GB, you might receive a polite email from GitHub Support requesting that you reduce the size of the repository to bring it back down. (リポジトリサイズ : 1GB未満維持を推奨。超えた場合サポートからのサイズ縮小リクエストが来ます)
1. we place a strict limit of files exceeding 100 MB in size (単一ファイル当り 100MBの制約)

※ 他にもWebからのファイル追加では、25MBまでのファイルサイズ制限があったりしますが主眼ではないので割愛します。

このGitHub.comサイズ制約を意識していないと、大量の画像ファイルやメッシュデータなどをバージョン管理しようとしたときに容易に制限に引っかかってしまいます。私は当時、よくpushしようとしてFile limitでpushが失敗してしょんぼりしましたが皆さんはどうでしょうか?

大容量に成りうるファイルのバージョン管理にはgit lfsを利用する

GitHubは、そういった大容量のファイルを扱う際はgit lfsを利用することを推奨しています。

LFS対象のファイルは、GitHub上ではポインタファイルとして扱われるのでファイルの大きさによらず1KB未満で済みます。やったね。

version https://git-lfs.github.com/spec/v1
oid sha256:4665a5ea423c2713d436b5ee50593a9640e0018c1550b5a0002f74190d6caea8
size 36

私が初めに悩んだのが、LFSのsmudge filterclean filter機能でした。実際filterでトラブルが起こったります。*4

Git LFSに関しては素晴らしいQiitaエントリがあるので参考にどうぞ。smudge/clean filterについてもサクッと理解できます。

gitgit lfsは別のコマンドなので少し面倒な部分があります。またコマンドはなく何かしらのGitを扱えるツールを用いる場合、別途Git LFSをサポートしている必要があります。

GitHub for Unity を用いないこれまでの流れ

さて、GitHub + git lfsの例を見てみましょう。

今回はサバイバルシューターのチュートリアルでやってみます。

https://unity3d.com/jp/learn/tutorials/projects/survival-shooter-tutorial

ディレクトリを見るとTexturesにpngやtifがあるのでこれをgit lfs対象としてみます。

まず、.gitattributesはこのようにしてみました。

https://gist.github.com/guitarrapc/f0efdc8b4960e9346ddcad791e6340dd

私はUnityの場合、.gitignoreをこのようにしています。

https://gist.github.com/guitarrapc/1a6bdf76b4021e5ed3ba43268a3d869e

早速git addします。Source Treeでstagingにあげようとすると2MBを超えるファイルは警告がでますね。もちろんこの*.assetgit lfsの対象拡張子にしています。

さて、git addでstagingエリアに上がったファイルを見るとsmudgeフィルタを通ってポインタファイル化されています。例えば、ArchesDiffuse.pngという画像(バイナリ)ファイルがテキストで表現されています。

SourceTreeでpush状態を見るとGit LFSに対象ファイルがどんどんpushされているのが見えます。これはもちろんコマンドでも同様にわかります。

無事に普段と同じフローでlfs対象ファイルもpushされました。

ではGitHub.com上のファイルを見てみます。

https://github.com/guitarrapc/GitHubForUnitySample

先ほどのArchesDiffuse.pngは、中身がポインタファイルにも関わらず、GitHub.com上ではちゃんとpngとしてLFS先の実体画像が表示されています。LFS対象でない普通の画像ファイルと同じように扱えているのは素晴らしいですね。

image

通常のファイルとLFS管理ファイルの違いは、Stored with Git LFSという表記があることです。

では実際の中身を見るため、Rawファイルを見てみましょう。

https://raw.githubusercontent.com/guitarrapc/GitHubForUnitySample/master/Assets/Textures/ArchesDiffuse.png

先ほど同様ポインタファイルになっていることが分かります。

git lfsの場合のgit lfs clone/git lfs pullを試してみてください。

GitHub for Unity を用いてみる

さて通常のgit/git lfsを用いたGitHubでのUnityファイルのバージョン管理はわかりました。これがGitHub for Unityでどう変わるか見てみましょう。

ダウンロード

導入するためには、.unitypackageを使います。つまり、プロジェクトごとに利用を選択できます。

https://unity.github.com/

パッケージは、リリースタグから取得できます。今のところはAlphaなので動作が不安定なことは理解した上で使うといいでしょう。*5

https://github.com/github-for-unity/Unity/releases

今回は、 v0.15-alphaを用います。

事前準備とかは、READMEを見るといいです。ブログ見る必要なくなります。

https://github.com/github-for-unity/Unity/blob/master/README.md

なお、現在サポートしているUnityは5.4~5.6。LFSは2.xです。

  • Unity 5.4-5.6 (Unity Personal も可)
    • We've only tested the extension so far on Unity 5.4 to 5.6. There's currently an blocker issue opened for 5.3 support, so we know it doesn't run there. There are some issues for 2017.x, so it may or may not run well on that version. Personal edition is fine
  • Git and Git LFS 2.x

Unity へのパッケージ導入

ツールバーから行きます。 Assets > Import Package > Custom Package....からダウンロードしたgithub-for-unity-0.15.0.0-alpha.unitypackageを導入します。

いい感じに導入されました。

ツールバーにGitHubメニューが増えました。

GitHub ログイン

ツールバーのGitHub > AuthenticateからGitHubにログインできます。このアカウントは、GitHub WebにログインするときのUserName/Passwordを用います。

注意点として、内部実装として、Octokit.Netを用いてGitHub API v3を使っているため、2FAを使っていてもPasswordです。通常2段階認証の場合、Passwordの代わりにPersonal Access Tokenを使うため、違いに注意してください。

Stanley Goldman (@stan_programmer) July 12, 2017

2段階認証を使っている場合は、2FA PINコードが求められます。

上手く認証できましたか?

GitHub ウィンドウ

ツールバーからGitHub > Show WindowでGitHubのタブが開きます。

さて、5つのタブがあります。

  • Changes
  • History
  • Branches
  • Settings
  • Account

History タブ

ここにはコミットグラフが表示されます。

先ほどのinitial commitというコミットログがグラフに表示されています。

またここから、Getch / Pull / Push操作が可能です。

コミットログを選択すると対象のファイルがツリー表示されます。

残念なことにツリービューのみの提供に加えて、ここのウィンドウサイズは変更できないため非常に見にくいです。

なお現在は日本語が文字化けます。PRがきているようですが....サイドエフェクトがあるようなのでいつになるか待っている状況です。

https://github.com/github-for-unity/Unity/issues/124

https://github.com/github-for-unity/Unity/pull/136

https://github.com/github-for-unity/Unity/issues/35

Branches タブ

localとremoteのブランチ状況が表示されます。

もちろんここでリモートブランチに切り替えたり、新規でブランチを切ることもできます。

ブランチをダブルクリックしてcheckoutできます。

Branchesの上に現在のブランチが表示されています。ブランチ一覧でも微妙にboldになっています。

Settings タブ

Git設定状態やLockされたファイル一覧が見えます。

Lockedファイルは、噂の他の人との共同作業用の機能です。わくわく機能ですね。

You can see who has locked a file and release file locks after you've pushed your work. https://github.com/github-for-unity/Unity#settings-tab

さてPath to gitを見るとここで使っているPortabl Gitと分かります。

C:\Users\<UserName>\AppData\Local\GitHubUnity\PortableGit_f02737a78695063deace08e96d5042710d3e32db\cmd\git.exe

Account タブ

Go to Profieで、GitHub.com上のプロファイルページに移動します。

Changes タブ

ここに、Git上の変更が表示されます。ファイルの変更は色で表現されています。

  • 追加 : 緑
  • 削除 : 赤
  • 変更 : 黒
  • ファイルの移動 : 削除と追加として表示される

残念ながらこの画面で可能なのは、Commitのみです。

よくあるあるな、Discard/Remove/Reset/Ignoreなどの操作をしようにも右クリックが出ないためGit操作の完結をするには機能不足です。

残念ながらFile Diffもサポートしていませんが、Issueに上がって修正PRがマージ済みです。

https://t.co/Fdp8CHAVFc

https://github.com/github-for-unity/Unity/issues/55

またStaging Areaもありませんが、これはIssueが上がっています。

https://github.com/github-for-unity/Unity/issues/52

Commit 操作

ChangesタブからGitHub for Unityを取り込んだコミットをしてみます。チェックをつけてCommitメッセージを書きます。

これでCommitしてみましょう。

上手くいきました。

これをpushします。ここが少し時間かかります。が、問題なくリモートブランチを作ってプッシュされるのでちょっと待ってみてください。

pushしたら、GitHub.com上でLFS対象ファイルがどうなったか見てみましょう。うまく扱えているでしょうか?

https://github.com/guitarrapc/GitHubForUnitySample/blob/master/Assets/Editor/GitHub/GitHub.Api.dll

問題なくpushされたようです。

マージしてみましょう。残念ながらGitHub for UnityからPRを直接作成できないのでGitHub.com上からPRを作ります。

PRをマージします。

GitHub for UnityでBranchesタブからmasterをcheckoutします。で、当然GitHub for Unityが入る前になるのでタブ消えます。(あっ)

ちなみにSource Tree上ではこのように表示されるのでorigin/masterをPullしておきます。

さてHistoryを見ると、微妙にツリーっぽい表示になっています。

SourceTreeなどは見やすいツリー表示なので、ちょっとこれだけで把握は難しいですね。

これで一通りの動きが見えました。

コントリビュート

さて、GitHub for UnityはGitHub上で公開されています。Issueを積極的に受け入れる姿勢を見せており、Twitterでつぶやくと補足されます。うれしいです。

ということで、改善点があればIssueで積極的に共有するといいでしょう。コードはC# で書かれており、PRも積極的に受け付けているので、ぜひみなさんもどうでしょうか。

私からは4つIssueをあげてあります。

  • Index.lockが消えないケースもある

https://github.com/github-for-unity/Unity/issues/125

  • Tree Viewだけでなく、Flat List Viewを用意することの提案

https://github.com/github-for-unity/Unity/issues/126

  • ChangesタブでのRemove/Discard/Reset/IgnoreなどのGitのフル操作の提供提案

https://github.com/github-for-unity/Unity/issues/127

  • GitHub for Unityから直接PRをする提案

https://github.com/github-for-unity/Unity/issues/135

まとめ

GitHub for Unity、まだUnityのみですべてのGit操作が完結するというには早いです。しかしアルファのわりに動作は比較的安定しており、ある程度の層がここからできます。

ぜひ使ってみましょう。

参考

GitHub for Unityの基本的な使い方は他の方もまとめておいでです。

http://stepup-next.halfmoon.jp/blog/2017/06/30/unity-for-GitHub/

*1:tgaやpngなどの画像ファイル

*2:GitHub Enterpriseのようなホスティングは別とします。またほかのGitを使ったサービスも記事の対象外です。

*3:このサイズ制限がなければ、大規模なUnity開発でも懸念をいただくことなくGitHub.com利用できるですが仕方ありません。

*4:ちなみにlfsの対象指定はsmudge/clean filterの指定 = .gitattributesで行います。https://Git-scm.com/book/en/v2/Customizing-Git-Git-Attributes

*5:αってそういう意味だしそこを割り切ると楽しく使えます。