tech.guitarrapc.cóm

Technical updates

Github for Unity を導入してみる

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

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

github.com

目次

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

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

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

ここで立ちはだかるのがGithub.com のDisk Quota と称される単一ファイル、リポジトリへの制限です。*2

About large files on GitHub - GitHub Docs

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未満維持を推奨。超えた場合サポートからのサイズ縮小リクエストが来ます。)
  2. 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 を利用することを推奨しています。

Managing large files - GitHub Docs

git-lfs.github.com

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

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

おそらく初めに悩むのが、git LFS が利用している git の smudge filterclean filter 機能だった方は私だけではないのではないでしょうか?実際、このfilter でトラブルが起こったります。*4

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

qiita.com

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

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

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

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

unity3d.com

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

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

gist.github.com

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

gist.github.com

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

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

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

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

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

github.com

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

GithubForUnitySample/ArchesDiffuse.png at master · guitarrapc/GithubForUnitySample · GitHub

通常のファイルと 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 を使います。つまり、プロジェクトごとに利用を選択できます。

GitHub for Unity | Bring Git and GitHub into Unity

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

Releases · github-for-unity/Unity · GitHub

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

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

Unity/README.md at master · github-for-unity/Unity · GitHub

なお、現在 サポートしている 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 というケースが多いと思いますが違うので注意してください。

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

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

Github ウィンドウ

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

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

  • Changes
  • History
  • Branches
  • Settings
  • Account

History タブ

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

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

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

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

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

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

github.com

github.com

github.com

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 を見るとここで使っている 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がマージ済みです。

t.co

github.com

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

github.com

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 が消えないケースがあること

github.com

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

github.com

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

github.com

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

github.com

まとめ

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

ぜひ使ってみるといいと思います。

参考

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

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

*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:αってそういう意味だしそこを割り切ると楽しく使えます。