5.2 分散Git - プロジェクトへの貢献

具体的なユースケースを見る前に、コミットメッセージに関する簡単な注意点です。コミットを作成するための適切なガイドラインを持ち、それを守ることで、Git を使用した作業や他の人との共同作業が非常に楽になります。Git プロジェクトでは、パッチを提出するためのコミットを作成するためのいくつかの良いヒントをまとめたドキュメントを提供しています。これは、Git のソースコードの Documentation/SubmittingPatches ファイルで読むことができます。

まず、提出物には空白のエラーが含まれていてはなりません。Git にはこれをチェックする簡単な方法があります。コミットする前に git diff --check を実行すると、空白エラーの可能性が識別され、一覧表示されます。

コミット前にそのコマンドを実行すれば、他の開発者を不快にさせる可能性のある空白の問題をコミットしようとしているかどうかを確認できます。

次に、各コミットを論理的に分離された変更セットにすることを試みてください。可能であれば、変更を理解しやすいものにすることを心がけてください。週末に 5 つの異なる問題に対してコードを書き続け、それらをすべて月曜日に 1 つの巨大なコミットとして送信しないでください。たとえ週末にコミットしなくても、月曜日にステージングエリアを使用して、1 つの問題につき少なくとも 1 つのコミットに作業を分割し、コミットごとに役立つメッセージを付けます。一部の変更が同じファイルを変更する場合は、git add --patch を使用してファイルを部分的にステージングすることを試みてください（詳しくはインタラクティブなステージングで説明します）。ブランチの先端にあるプロジェクトのスナップショットは、すべての変更がどこかの時点で追加される限り、1 つのコミットでも 5 つのコミットでも同じです。したがって、他の開発者が変更をレビューする必要がある場合に、彼らの作業を楽にするように努めてください。

このアプローチにより、後で必要になった場合に、変更セットの 1 つを簡単に取り出したり、元に戻したりすることもできます。履歴の書き換えでは、履歴を書き換えたり、ファイルをインタラクティブにステージングしたりするための便利な Git のトリックが数多く紹介されています。これらのツールを使用して、他の人に作業を送る前に、クリーンで理解しやすい履歴を作成してください。

最後に注意すべき点は、コミットメッセージです。質の高いコミットメッセージを作成する習慣を身につけることで、Git を使用したり、他の人と共同作業したりするのが非常に楽になります。一般的なルールとして、メッセージは、変更セットを簡潔に説明する約 50 文字以内の単一行で始まり、その後に空白行、さらに詳細な説明が続きます。Git プロジェクトでは、詳細な説明に、変更の動機と、以前の動作との実装の対比を含めることを要求しています。これは従うべき良いガイドラインです。コミットメッセージは命令形で記述してください。「バグを修正する」のように書き、「バグを修正した」または「バグを修正します」のように書かないでください。以下は、もともと Tim Pope が書いたものを少し修正したテンプレートです。

すべてのコミットメッセージがこのモデルに従っていれば、あなたと共同作業を行う開発者にとって、物事がはるかに簡単になります。Git プロジェクトには、適切にフォーマットされたコミットメッセージがあります。git log --no-merges を実行して、適切にフォーマットされたプロジェクトコミット履歴がどのように見えるかを確認してみてください。

遭遇する可能性のある最もシンプルなセットアップは、1 人または 2 人の開発者が参加するプライベートプロジェクトです。この文脈での「プライベート」とは、クローズドソース、つまり外部の世界からアクセスできないことを意味します。あなたと他の開発者は全員、リポジトリへのプッシュアクセス権を持っています。

この環境では、Subversion や他の集中型システムを使用する場合と似たワークフローに従うことができます。オフラインコミットや、非常に単純なブランチングとマージなどの利点は依然として得られますが、ワークフローは非常に似たものになります。主な違いは、マージがコミット時にサーバー側ではなくクライアント側で行われることです。共有リポジトリを使用して 2 人の開発者が共同作業を開始するとどうなるかを見てみましょう。最初の開発者であるジョンがリポジトリをクローンし、変更を加えてローカルにコミットします。これらの例では、プロトコルメッセージは少し短くするために …​ に置き換えられています。

2 番目の開発者であるジェシカも同様に、リポジトリをクローンして変更をコミットします。

これで、ジェシカは自分の作業をサーバーにプッシュします。これは問題なく機能します。

上記出力の最後の行は、プッシュ操作からの便利なリターンメッセージを示しています。基本的な形式は <oldref>..<newref> fromref → toref で、oldref は古い参照を、newref は新しい参照を、fromref はプッシュされているローカル参照の名前を、toref は更新されるリモート参照の名前を意味します。以下の説明でも同様の出力が表示されるので、意味の基本的な考えを理解すると、リポジトリのさまざまな状態を理解するのに役立ちます。詳細については、git-push のドキュメントを参照してください。

この例を続けると、その後すぐに、ジョンはいくつかの変更を加え、ローカルリポジトリにコミットし、同じサーバーにプッシュしようとします。

この場合、ジョンのプッシュは、ジェシカが以前に自分の変更をプッシュしたために失敗します。Subversion に慣れている場合は、これは特に理解しておく必要があります。なぜなら、2 人の開発者が同じファイルを編集しなかったことに気付くでしょう。Subversion では、異なるファイルが編集された場合、サーバー上でこのようなマージが自動的に行われますが、Git では、最初にコミットをローカルにマージする必要があります。言い換えれば、ジョンはプッシュを許可される前に、まずジェシカのアップストリームの変更をフェッチし、それを自分のローカルリポジトリにマージする必要があります。

最初の手順として、ジョンはジェシカの作業をフェッチします（これはジェシカのアップストリームの作業をフェッチするだけであり、ジョンの作業にはまだマージしません）。

この時点で、ジョンのローカルリポジトリは次のようになります。

これで、ジョンはフェッチしたジェシカの作業を自分のローカル作業にマージできます。

ローカルマージがスムーズに進む限り、ジョンの更新された履歴は次のようになります。

この時点で、ジョンはこの新しいコードをテストして、ジェシカの作業が自分のコードに影響を与えないことを確認する必要があります。すべて問題ないようであれば、最後に新しいマージされた作業をサーバーにプッシュできます。

最終的に、ジョンのコミット履歴は次のようになります。

その間、ジェシカは issue54 という新しいトピックブランチを作成し、そのブランチに 3 つのコミットを行いました。彼女はまだジョンの変更をフェッチしていないため、彼女のコミット履歴は次のようになります。

突然、ジェシカはジョンがいくつかの新しい作業をサーバーにプッシュしたことを知り、それを見てみたいと思います。そこで、彼女はまだ持っていないサーバーからのすべての新しいコンテンツを次のコマンドでフェッチできます。

これにより、ジョンがその間にプッシュした作業がプルダウンされます。ジェシカの履歴は次のようになります。

ジェシカは自分のトピックブランチの準備ができたと考えていますが、プッシュできるように、フェッチしたジョンの作業のどの部分を自分の作業にマージする必要があるかを知りたいと考えています。彼女は git log を実行して調べます。

issue54..origin/master という構文はログフィルターで、後のブランチ（この場合は origin/master）に存在し、最初のブランチ（この場合は issue54）には存在しないコミットのみを表示するように Git に要求します。この構文については、コミット範囲で詳しく説明します。

上記出力から、ジェシカが自分のローカル作業にマージしていないジョンが行った単一のコミットがあることがわかります。origin/master をマージすると、ローカル作業が変更されるのはその単一のコミットになります。

これで、ジェシカは自分のトピック作業を自分の master ブランチにマージし、ジョンの作業（origin/master）を自分の master ブランチにマージしてから、再びサーバーにプッシュできます。

最初に（issue54 トピックブランチのすべての作業をコミットした後）、ジェシカはこのすべての作業を統合する準備として、自分の master ブランチに戻ります。

ジェシカは、origin/master または issue54 のいずれかを最初にマージできます。どちらもアップストリームであるため、順序は重要ではありません。どちらの順序を選択しても、最終的なスナップショットは同じになるはずです。異なるのは履歴だけです。彼女は最初に issue54 ブランチをマージすることを選択します。

問題は発生しません。ご覧のとおり、これは単純な早送りマージでした。ジェシカは、origin/master ブランチにある、以前フェッチしたジョンの作業をマージして、ローカルマージプロセスを完了します。

すべてがクリーンにマージされ、ジェシカの履歴は次のようになります。

これで、origin/master がジェシカの master ブランチから到達可能になったため、（ジョンがその間にさらに変更をプッシュしていなければ）プッシュを正常に行えるはずです。

各開発者は数回コミットし、お互いの作業を正常にマージしました。

これは最もシンプルなワークフローの 1 つです。しばらくの間（通常はトピックブランチで）作業を行い、統合の準備ができたら、その作業を自分の master ブランチにマージします。その作業を共有したい場合は、origin/master が変更されている場合は、master をフェッチして origin/master からマージし、最後にサーバーの master ブランチにプッシュします。一般的なシーケンスは次のようになります。

次のシナリオでは、大規模なプライベートグループでの貢献者の役割を見ていきます。小グループが機能について共同作業を行い、その後、それらのチームベースの貢献が別の当事者によって統合される環境での作業方法を学びます。

ジョンとジェシカが 1 つの機能（これを「featureA」と呼びます）で共同作業しており、一方、ジェシカと 3 番目の開発者であるジョージーが 2 番目の機能（「featureB」としましょう）で作業しているとします。この場合、会社は統合マネージャーワークフローの一種を使用しており、個々のグループの作業は特定のエンジニアのみが統合し、メインリポジトリの master ブランチはそれらのエンジニアのみが更新できます。このシナリオでは、すべての作業はチームベースのブランチで行われ、後でインテグレーターによってまとめられます。

ジェシカが 2 つの機能に取り組むときのワークフローを、この環境で 2 人の異なる開発者と並行して共同作業を行いながら見ていきましょう。彼女はすでにリポジトリをクローンしていると仮定して、最初に featureA に取り組むことにしました。彼女は機能用の新しいブランチを作成し、そこでいくつかの作業を行います。

この時点で、彼女は自分の作業をジョンと共有する必要があるため、featureA ブランチのコミットをサーバーにプッシュします。ジェシカは master ブランチへのプッシュアクセス権を持っていません。統合担当者のみが持っています。そのため、ジョンと共同作業するために別のブランチにプッシュする必要があります。

ジェシカはジョンに、featureA という名前のブランチにいくつかの作業をプッシュしたことをメールで知らせ、彼は今それを見ることができます。ジョンからのフィードバックを待っている間、ジェシカはジョージーと一緒に featureB の作業を開始することにしました。開始するには、サーバーの master ブランチに基づいて新しい機能ブランチを開始します。

これで、ジェシカは featureB ブランチでいくつかのコミットを行います。

ジェシカのリポジトリは次のようになります。

彼女は作業をプッシュする準備ができていますが、ジョシーから「featureB」の初期作業を含むブランチがすでにfeatureBeeブランチとしてサーバーにプッシュされているというメールを受け取ります。ジェシカは、自分の作業をサーバーにプッシュする前に、これらの変更を自分の変更とマージする必要があります。ジェシカはまず、git fetchでジョシーの変更を取得します。

ジェシカがチェックアウト済みのfeatureBブランチにまだいると仮定すると、git mergeでジョシーの作業をそのブランチにマージできます。

この時点で、ジェシカはマージされた「featureB」の作業すべてをサーバーにプッシュバックしたいと考えていますが、単に自分のfeatureBブランチをプッシュしたいわけではありません。むしろ、ジョシーがすでに上流のfeatureBeeブランチを開始しているため、ジェシカはそのブランチにプッシュしたいと考えており、それを次のコマンドで行います。

これはrefspecと呼ばれます。Git refspecとそのさまざまな使い方についての詳細は、Refspecを参照してください。また、-uフラグにも注目してください。これは--set-upstreamの短縮形であり、後でプッシュやプルを簡単にするためにブランチを設定します。

突然、ジェシカはジョンからメールを受け取り、彼が共同作業しているfeatureAブランチに変更をプッシュしたことを伝え、ジェシカにそれらを確認するように依頼しました。ここでも、ジェシカは単純なgit fetchを実行して、サーバーからのすべての新しいコンテンツを取得します（もちろん、ジョンによる最新の作業も含みます）。

ジェシカは、新たに取得したfeatureAブランチの内容を、同じブランチのローカルコピーと比較することで、ジョンの新しい作業のログを表示できます。

ジェシカが内容を気に入れば、git mergeでジョンの新しい作業をローカルのfeatureAブランチにマージできます。

最後に、ジェシカはマージされたコンテンツすべてにいくつかの小さな変更を加えたい場合があるので、それらの変更を自由に行い、ローカルのfeatureAブランチにコミットし、最終結果をサーバーにプッシュバックできます。

ジェシカのコミット履歴は、次のようになります。

ある時点で、ジェシカ、ジョシー、ジョンは、サーバー上のfeatureAブランチとfeatureBeeブランチがメインラインへの統合準備ができていることをインテグレーターに通知します。インテグレーターがこれらのブランチをメインラインにマージした後、フェッチによって新しいマージコミットがダウンロードされ、履歴は次のようになります。

多くのグループが、プロセスの後半でさまざまな作業ラインをマージして、複数のチームが並行して作業できるこの機能のためにGitに切り替えます。チームの小さなサブグループが、チーム全体を巻き込んだり妨げたりすることなく、リモートブランチを介して共同作業できることは、Gitの大きなメリットです。ここで見たワークフローのシーケンスは次のようになります。

公開プロジェクトへの貢献は少し異なります。プロジェクトのブランチを直接更新する権限がないため、他の方法でメンテナーに作業を渡す必要があります。この最初の例では、簡単なフォークをサポートするGitホストでのフォークを介した貢献について説明します。多くのホスティングサイト（GitHub、BitBucket、repo.or.czなどを含む）がこれをサポートしており、多くのプロジェクトメンテナーがこのスタイルの貢献を期待しています。次のセクションでは、メールを介して貢献されたパッチを受け入れることを好むプロジェクトについて説明します。

まず、メインリポジトリをクローンし、貢献しようとしているパッチまたはパッチシリーズのトピックブランチを作成し、そこで作業することをお勧めします。シーケンスは基本的に次のようになります。

ブランチ作業が完了し、メンテナーに貢献する準備ができたら、元のプロジェクトページに移動し、「フォーク」ボタンをクリックして、プロジェクトの書き込み可能なフォークを作成します。次に、このリポジトリURLをローカルリポジトリの新しいリモートとして追加する必要があります。この例では、myforkと呼びましょう。

次に、このリポジトリに新しい作業をプッシュする必要があります。作業をmasterブランチにマージしてプッシュするのではなく、作業中のトピックブランチをフォークされたリポジトリにプッシュするのが最も簡単です。その理由は、作業が受け入れられない場合やチェリーピックされた場合に、masterブランチを巻き戻す必要がないためです（Gitのcherry-pick操作については、リベースとチェリーピックのワークフローで詳しく説明します）。メンテナーが作業をmerge、rebase、またはcherry-pickする場合、いずれにしても、メンテナーのリポジトリからプルすることで最終的にそれを取り戻すことができます。

いずれにしても、次のコマンドで作業をプッシュできます。

作業をリポジトリのフォークにプッシュしたら、マージしてもらいたい作業があることを元のプロジェクトのメンテナーに通知する必要があります。これはプルリクエストと呼ばれることが多く、通常はWebサイトを介してそのようなリクエストを生成します。GitHubには独自の「プルリクエスト」メカニズムがあり、GitHubで説明します。または、git request-pullコマンドを実行して、後続の出力をプロジェクトメンテナーに手動でメールで送信することもできます。

git request-pullコマンドは、トピックブランチをプルしたいベースブランチと、プルしたいGitリポジトリのURLを受け取り、プルを要求するすべての変更の概要を生成します。たとえば、ジェシカがジョンにプルリクエストを送信したい場合、彼女はプッシュしたばかりのトピックブランチで2つのコミットを実行したとすると、次のコマンドを実行できます。

この出力はメンテナーに送信できます。作業が分岐された場所、コミットの概要、および新しい作業をプルする場所をメンテナーに伝えます。

メンテナーではないプロジェクトでは、masterのようなブランチが常にorigin/masterを追跡し、拒否された場合に簡単に破棄できるトピックブランチで作業を行う方が一般的に簡単です。作業テーマをトピックブランチに分離すると、メインリポジトリの先端がその間に移動し、コミットがクリーンに適用されなくなった場合に、作業をリベースすることも簡単になります。たとえば、プロジェクトに2番目の作業トピックを送信したい場合は、プッシュしたばかりのトピックブランチでの作業を続行しないでください。メインリポジトリのmasterブランチからやり直してください。

これで、各トピックがサイロに格納されました。これは、パッチキューに似ており、次のように、トピックが相互に干渉したり依存したりすることなく、書き換え、リベース、変更できます。

プロジェクトメンテナーが他のパッチをいくつかプルインし、最初のブランチを試したものの、クリーンにマージできなくなったとしましょう。この場合、そのブランチをorigin/masterの上にリベースし、メンテナーの競合を解決してから、変更を再送信できます。

これにより履歴が書き換えられ、featureAの作業後のコミット履歴のようになります。

ブランチをリベースしたため、サーバー上のfeatureAブランチを、その子孫ではないコミットに置き換えることができるように、プッシュコマンドに-fを指定する必要があります。別の方法としては、この新しい作業をサーバー上の別のブランチ（おそらくfeatureAv2と呼ばれる）にプッシュすることです。

もう1つの考えられるシナリオを見てみましょう。メンテナーは2番目のブランチでの作業を見てコンセプトは気に入ったものの、実装の詳細を変更したいと考えています。また、この機会に、作業をプロジェクトの現在のmasterブランチに基づいて移動します。現在のorigin/masterブランチに基づいて新しいブランチを開始し、featureBの変更をそこにまとめ、競合を解決し、実装を変更してから、それを新しいブランチとしてプッシュします。

--squashオプションは、マージされたブランチのすべての作業を取り込み、それを1つの変更セットにまとめることで、実際のマージが発生した場合と同じようにリポジトリの状態を生成しますが、実際にはマージコミットを作成しません。これは、将来のコミットが1つの親のみを持つことを意味し、別のブランチからのすべての変更を導入し、新しいコミットを記録する前に追加の変更を加えることができます。また、デフォルトのマージプロセスの場合は、--no-commitオプションもマージコミットを遅延させるのに役立ちます。

この時点で、メンテナーにリクエストされた変更を加えたことと、それらの変更がfeatureBv2ブランチにあることを通知できます。

多くのプロジェクトでは、パッチを受け入れるための手順が確立されています。プロジェクトごとにルールが異なるため、各プロジェクトの特定のルールを確認する必要があります。開発者のメーリングリストを介してパッチを受け入れる、より古い、大規模なプロジェクトがいくつかあるため、ここでその例について説明します。

ワークフローは前のユースケースと似ており、作業するパッチシリーズごとにトピックブランチを作成します。違いは、それらをプロジェクトに送信する方法です。プロジェクトをフォークして独自の書き込み可能バージョンにプッシュするのではなく、各コミットシリーズのメールバージョンを生成して、それらを開発者のメーリングリストにメールで送信します。

これで、メーリングリストに送信したい2つのコミットができました。git format-patchを使用して、リストにメールで送信できるmbox形式のファイルを生成します。これにより、各コミットがメールメッセージに変換され、コミットメッセージの最初の行が件名になり、メッセージの残りの部分に、コミットが導入するパッチが本文として含まれます。これの優れた点は、format-patchで生成されたメールからのパッチを適用すると、すべてのコミット情報が適切に保持されることです。

format-patchコマンドは、作成したパッチファイルの名前を出力します。-Mスイッチは、Gitに名前の変更を探すように指示します。ファイルは次のようになります。

また、これらのパッチファイルを編集して、コミットメッセージに表示したくない情報をメールリストに追加することもできます。---行とパッチの先頭（diff --git行）の間に追加したテキストは、開発者が読めますが、そのコンテンツはパッチ処理では無視されます。

これをメーリングリストにメールで送信するには、ファイルをメールプログラムに貼り付けるか、コマンドラインプログラムを介して送信できます。テキストを貼り付けると、特に改行やその他の空白を適切に保持しない「スマート」クライアントでは、多くの場合、書式設定の問題が発生します。幸いなことに、Gitには、IMAPを介して適切に書式設定されたパッチを送信するのに役立つツールがあります。これは、あなたにとってより簡単な場合があります。Gmailを介してパッチを送信する方法を示します。これは、私たちが最もよく知っているメールエージェントです。Gitソースコードの前述のDocumentation/SubmittingPatchesファイルでは、多くのメールプログラムの詳細な手順を読むことができます。

最初に、~/.gitconfigファイルでimapセクションを設定する必要があります。一連のgit configコマンドで各値を個別に設定するか、手動で追加できますが、最終的には構成ファイルは次のようになります。

IMAPサーバーがSSLを使用していない場合、最後の2行はおそらく必要なく、hostの値はimaps://ではなくimap://になります。これが設定されると、git imap-sendを使用して、指定されたIMAPサーバーの[下書き]フォルダーにパッチシリーズを配置できます。

この時点で、下書きフォルダーに移動し、「宛先」フィールドをパッチを送信するメーリングリストに変更し、必要に応じてそのセクションのメンテナーまたは担当者をCCに追加して、送信できるはずです。

SMTPサーバー経由でパッチを送信することもできます。以前と同様に、一連のgit configコマンドで各値を個別に設定するか、~/.gitconfigファイルのsendemailセクションに手動で追加できます。

これが完了したら、git send-emailを使用してパッチを送信できます。

すると、Gitは送信する各パッチについて、次のような大量のログ情報を出力します。

このセクションでは、複数のワークフローについて説明し、クローズドソースプロジェクトで小規模チームの一員として作業する場合と、大規模な公開プロジェクトに貢献する場合の違いについて説明しました。コミット前に空白エラーを確認すること、素晴らしいコミットメッセージを作成できることを知っています。パッチをフォーマットし、開発者のメーリングリストにメールで送信する方法を学びました。マージの処理についても、さまざまなワークフローの観点から説明しました。これで、あらゆるプロジェクトで共同作業を行うための準備が整いました。

次に、コインの反対側であるGitプロジェクトの保守方法を説明します。あなたは、慈悲深い独裁者または統合マネージャーになる方法を学びます。