GitHub入門ガイド

2024年11月06日 11:06

この文書は、Gitが持つ複雑な機能をすべて教えようとすることなく、「Gitって一体何なんだろう」という状態から「僕の真新しいキャラクター・シートをみんなに使ってもらおう！」という状態まで、できるだけ早く到達するためのシンプルで骨太なガイドだ。 Gitはバージョン管理ソフトウェアですが、このガイドでは、変更を追跡するためにGitをどのように使うかは全く無視し、更新をRoll20のマスター・リポジトリに移動することだけに焦点を当てます。 More Info "セクションには、Git/GitHubの仕組みに関する一般的なガイドへのリンクがあります。

Git/GitHubとは？

Gitは、あなたのコンピューターにローカルにインストールするソフトウェアで、あなたのためにバージョン管理を行なう。 GitHubは Gitリポジトリのホスティングサービスです。 Gitはツールで、GitHubは Gitを使うプロジェクトのためのサービスだ。簡単な比較。

Gitの使い方にはいくつか種類がある。 Gitはとてもパワフルですが、それを最大限に活用するためには、コマンドシェルの使い方を学ぶ必要があります (xkcd コミック). 下部の "More Info "セクションには、コマンドシェルに関する追加情報が掲載されている。しかし、この文書で説明することはすべて、GitHub Desktop GUI (コンピュータのハードディスクとリポジトリを同期させるのにとても便利です - 以下の「リポジトリのクローン」を参照) と GitHub ウェブツールだけを使って行うことができます。

GitHubのセットアップ

アカウントの作成

GitHubを使うには、彼らのウェブサイトにアカウントを持つ必要がある。有料アカウントを作成することも、無料アカウントを作成することもできます。世界中に公開したくないプロジェクトを大量に作成する予定がない限り、有料アカウントを作成する理由はありません。さまざまな価格レベルの違いは、所有できるプライベート・リポジトリの数だけです。無料アカウントも含め、誰もが無制限にパブリック・リポジトリを持つことができる。

Roll20-character-sheetsやroll20-api-scriptsのマスターRoll20リポジトリは公開されています。また、これらのリポジトリのフォークを作成することになり、それも公開されるかもしれないので、Roll20の使用には無料のアカウントだけで十分だ。

Roll20公式リポジトリのFORK

フォークとは、リポジトリのコピーです。リポジトリをフォークすることで、元のプロジェクトに影響を与えることなく、自由に変更を試すことができます。

roll20-character-sheets "はキャラクターシートのリポジトリです。 MOD（API）スクリプトについては、"roll20-api-scripts "をフォークしてください。

フォークはGitHubのウェブツールを使って簡単にできる。以下にある公式リポジトリのForkボタンをクリックする。 https://github.com/Roll20/roll20-character-sheetsまたは https://github.com/Roll20/roll20-api-scriptsをクリックしてください。これで、あなたのアカウントにそのリポジトリのコピーが作成され、好きなように変更する権限が与えられます。リポジトリは何度でもフォークできるが、フォークする必要があるのは1度だけだ。この新しいリポジトリは元のリポジトリと同じアドレスになりますが、ルートが「Roll20」ではなく、あなたのroll20アカウント名になります。

同じシートやスクリプトで他のユーザーと作業している場合、新しいリポジトリの設定に入り、そのユーザーを共同作業者として追加するとよいでしょう。共同作業者を追加したり、共同作業者と一緒に作業したりする方法の詳細は、このチュートリアルの範囲外です。

Gitのバージョン管理システムに慣れていれば、キャラクターシートの提出に他の情報は必要ないはずです。それ以外の皆さんは、続きをお読みください！

リポジトリをクローンする

リポジトリのクローンもコピーを作成しますが、クローンされたリポジトリは作業コピーとして使用され、通常のフォルダやファイルとしてローカルコンピュータのハードドライブに存在します。 Gitは、デフォルトでは "origin "という名前で、クローン元のリポジトリとフォルダの間のリンクを維持します。

リストには、アカウント上のすべてのリポジトリが含まれます。

Git の初心者の方には、次のいずれかをダウンロードしてインストールすることを強くお勧めします。 GitHub for Windowsあるいは GitHub for Macのどちらかをダウンロードしてインストールすることを強くお勧めします。以下、本書ではこれらを「GitHub Desktop」または「デスクトップアプリ」と呼びます。 GitHubデスクトップアプリケーションは、GitHubのバージョン管理をコンピューターにインストールしてセットアップする簡単な方法であるだけでなく、GitHubのユーザーアカウントにリンクするのも簡単です。コンピューター上のファイルとGitHub上のリポジトリが古くなったときに教えてくれ、簡単に2つを同期することができる。

GitHub アプリケーションを最初に実行すると、GitHub アカウントにログインするよう求められます。次に、左上の大きなプラス記号をクリックして、リポジトリをクローンします。リポジトリをクローンすると、ファイルを置く場所を選択するプロンプトが表示されます。簡単に見つけられる場所を選ぶようにしてください！新しいコンピューターを手に入れたら、GitHub デスクトップをインストールしてリポジトリをクローンするだけです。

また、デスクトップアプリは、ブランチを管理するための最も簡単なインターフェースを持っています。デスクトップアプリケーション内でブランチを切り替えると、切り替えたブランチの最後のコミットと一致するようにファイルを追加/削除/変更します。

GitHub アプリケーションを使用していない場合は、リポジトリのクローン URL をリポジトリのページで確認できます。 GitHubはSSHとHTTPSの両方のクローンURLを提供しており、SubversionのチェックアウトURLも提供しています。しかし、手動でリポジトリをクローンする詳細については、このガイドの範囲を超えている。

GitHub フォークのワークフロー

上記の設定は一度しか行わない。次のセクションでは、Roll20 にアップデートを送信するたびに実行することを推奨する手順について説明します。

Roll20でファイルを同期

数分前にリポジトリをフォークしてクローンしたばかりでも、まだ同期しています。しかし、何週間も何ヶ月も経ってからリポジトリに戻ってきた場合、キャラクターシートやMOD（API）スクリプトのいくつかは更新されているでしょう。あなたが修正したいものがその中にある可能性がある。その場合、修正するファイルの最新バージョンで作業していることを確認する必要がある。別のフォークを作成する必要も、リポジトリを再度クローンする必要もありません。フォークをマスターにアップデートする必要がある。同期の方法については、以下のリンク先のガイドをお読みください。

同期が必要かどうかよりも、まず、これから作業するプロジェクトを同期する必要があるかどうかを確認したほうがいいでしょう。簡単なチェック方法としては、Roll20リポジトリのファイルを見て、最終更新日を確認することです。もうひとつは、そこでファイルを開き、"diff "ユーティリティを実行することだ。「diff」ユーティリティを実行することだ。更新するファイルに対して保留中のPullリクエストがあるかどうかを確認します。変更する特定のファイルが前回の同期から変更されていない場合、すべてのファイルの完全な同期を実行することはオプションです。

Roll20のマスターリポジトリからすべてのアップデートを取得するという方法もあります。これは、あなたが最後に同期したとき以降に他の人がroll20リポジトリに行ったすべての更新を取得します(あなたが気にしないかもしれないキャラクターシートやMod (API)スクリプトの束を含みます)。このリンクにはとリポジトリを同期するためのガイドがあります。. これが終わったら、Roll20 のマスターリポジトリ、自分のリポジトリ、ハードドライブにあるファイルはすべて同じになっているはずです。 roll20のキャンペーンも更新してください。

ブランチを作る

個別のプロジェクト（キャラクターシートやMOD（API）スクリプト）や個別のアップデートごとに新しいブランチを作成することをお勧めします。例えば、2つの異なるMod（API）スクリプトを同時に更新する場合、それぞれのスクリプト用にブランチを作成します。数週間後、同じスクリプトにさらに変更を加えることになったら、新しい更新用の新しいブランチを作成します。経験則として、プルリクエストごとに新しいブランチを1つ作ってください。

また、デスクトップアプリは、ブランチを管理するための最も簡単なインターフェースを持っています。一番上のメニューで、"Branch / New branch "を選んでください。デスクトップアプリケーションの中でブランチを切り替えると（2行目で作業中のリポジトリを切り替え、現在のブランチを切り替えることができます）、ハードドライブ上のファイルを追加/削除/変更して、切り替えたブランチの最後のコミットと一致するようにします。

GitHub Compare.png

変更をコミットし、コミットをプッシュする

変更をコミットすると、あなたが変更したすべての記録と、あなたが行ったことの人間が読める記述が、あなたのローカルコンピュータに保存されます。
その後、コミットをリポジトリにプッシュする。

リポジトリの作業コピーをクローンしたら、それに変更を加えることができます。これには、キャラクターシートやMOD（API）スクリプト用に新しいフォルダを作成し、そこにソースコードを追加したり、すでにあるファイルに修正を加えたりすることが含まれます。

Roll20のスクリプトやキャラクターシートを開発するとき、多くの人は実際の編集をすべてテキストエディタ（たとえばnotepad++）で行います。ハードドライブ上のファイル（「クローン」ステップで作成されたもの）を任意のテキストエディタで開き、エディタで変更を加えるだけでよい。 Roll20でコードを実行したいときはいつでも、ctrl/aとctrl/cを押してすべてのテキストを選択し、クリップボードにコピーしてください。そしてそれを正しいRoll20のキャンペーンフィールドに貼り付けます。追加の変更が必要な場合（デバッグなど）、編集、コピー、ペースト、テストのサイクルを継続的に実行するのが最も簡単な場合が多い。

テキストエディタに変更を保存するように指示すると、最終的に編集していたファイルに変更が書き込まれ、GitHub Desktop は編集したファイルが変更されたことを検知して左ペインに変更されたファイル名を表示し、右ペインに現在の保存と最後に行ったコミットで何が変わったかを要約して表示します。しかし、これらの変更は検出されただけで、GitHub は実際にコミットするまでその変更を記録しません。 Gitの専門家は、頻繁にコミットすることを推奨しています。コミットすることで、作業のオフサイト・バックアップと各コミットの記録が得られるからです。

Summaryなしでは変更をコミットできませんが、Descriptionは任意です。

コミットするのはとてもシンプルだ。デスクトップアプリは、コミットする必要があるものを特定するすべての作業をすでに終えている。変更のタイトルを入力し、オプションでより長い説明を入力し、"commit to (branch)" ボタンを押して変更をコミットします。 masterブランチではなく、必ず作業ブランチにコミットしてください。頻繁にコミットすることで、変更の詳細な履歴を残すことができる。サマリーには長さの制限がある。ただし、制限を超えると、メッセージは自動的に長い説明文にオーバーフローします。サマリー・フィールドのテキストが灰色になると、この現象がわかる。

コミットするとすぐに、GitHub のデスクトップに「No Local Changes (ローカルに変更はありません)」と大きく表示されるはずです。また、コミットをオリジンにプッシュすることも提案されるはずだ。あるいは、"Publish Branch "を提案されるかもしれない。変更をコミットしても、あなたのコンピューターに保存されるだけだ。 GitHubに変更を反映させるには、オリジンにプッシュする必要がある。 Push Origin」または「Publish Branch」ボタンを押すだけです。あるいは、オリジンやクローンが古くなった場合はいつでも、右上に数字と矢印が書かれた非常に貧弱なラベルのボタンがあるはずだ。そうすれば、リポジトリとクローンの間ですべてが同期されるので、代わりにそれをプッシュすることができる。デスクトップ・ツールの一番上にあるドロップダウンメニューの「リポジトリ - プッシュ」でも作業ができる。

変更が完了するまで編集とコミットを続け、テストとデバッグが完了したコードを提出し、roll20の他のメンバーが楽しめるようにします。これで、roll20 のサイト管理者に、あなたの変更を roll20 の公式マスターリポジトリに "pull" するよう依頼する準備ができました。

PULLリクエストの作成

その名の通り、プルはプッシュの反対である。コピーされたリポジトリが元のリポジトリにコミットを送信する代わりに、元のリポジトリはコピーからのコミットを要求します。

リポジトリのウェブページには、カーソルを合わせると「比較、レビュー、プルリクエストの作成」と書かれた緑色のボタンがあります。このボタンをクリックすると、プルリクエストを作成できるページに移動します。あなたのリポジトリ（"head"）と Roll20 のリポジトリ（"base"）の間に違いがあれば、ここに表示されます。 (近くの「編集」ボタンをクリックすれば、ヘッドとベースの両方に使用するものを変更できることに注意) あなたの変更はすべて master ブランチではなく working ブランチにあるので、プルリクエストは working ブランチから行うことになります。

Roll20 のリポジトリには共同作業者権限がないため、自分でプルアクションを実行することはできません。プルリクエストを作成 "と書かれた大きな緑色のボタンを押すと、ベースリポジトリにプルリクエストが作成されます。プルリクエストを作成する権限を持つ人（つまりRoll20の開発者）は、プルリクエストと提案された変更の内容を確認し、公式リポジトリにマージすることができます。

わかりやすくするために、プルリクエストには変更を加えたシートの名前を入れてください。 "【ダンジョンダイバーズ第3版】壊れたマイトロールを修正".

キャラクターシートの提出には、sheet.jsonとプレビュー画像を忘れずに添付してください。 Readmeを確認してください。 MOD(API)スクリプトを投稿する場合は、script.jsonを含めることを忘れないでください。 readmeを確認してください。すべてが正しいと仮定すると、あなたのシートやスクリプトはapproved.yamlファイルに追加され、すべてのユーザーが利用できるようになるはずです！

週に一度、Roll20は利用可能なすべてのシートリクエストを処理します。そうすると、GitHubからメールが届きます。このメールでは、あなたのリクエストに対して、あなたの投稿で発見された問題に関するコメントが残されたこと、または、あなたのシートが期待通りにマージされ、リクエストがクローズされたこと（正常に完了したため）をお知らせします。

PULLリクエストの変更

プルリクエストを作成し、プルリクエストがマージされる前に & をコミットしてリポジトリ/ブランチに追加変更をプッシュした場合、それらの新しい変更は自動的に元のプルリクエストに更新/インクルードされます。

プルリクエストボタン.png

クリーンアップ

そのブランチからのプルリクエストがすべて完了し、クローズされるまで、どのブランチも削除しないでください。実際、ブランチの削除を急ぐ必要はまったくない。それぞれの枝を一度だけ使うことを忘れない限り、何も傷つけることはない。

GitHub ソフトウェアは、ブランチを master にマージすることを推奨します。これは他のワークフローでは必要なステップだが、今回使用するフォークワークフローでは必要ない。その代わりに、次のアップデートの準備の第一歩として、フォークをroll20オリジナルと同期させることをお勧めします。これにより、あなたが行ったアップデートが（他の誰かが行った変更と同様に）あなたのフォークに反映される。

したがって、後始末は必要ない。