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

具体的なユースケースを見る前に、コミットメッセージについて簡単に説明します。コミットを作成するための良いガイドラインを持ち、それに従うことで、Gitでの作業や他者との共同作業がはるかに容易になります。Gitプロジェクトは、パッチを提出するためのコミットを作成するための多くの良いヒントをまとめたドキュメントを提供しています。これはGitのソースコードのDocumentation/SubmittingPatchesファイルで読むことができます。

まず、提出するコードには空白エラーが含まれていてはなりません。Gitはこれを簡単にチェックする方法を提供しています。コミットする前にgit diff --checkを実行すると、潜在的な空白エラーを特定してリスト表示してくれます。

コミットする前にこのコマンドを実行すると、他の開発者を悩ませる可能性のある空白の問題をコミットしようとしているかどうかを判断できます。

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

このアプローチにより、後で変更セットのいずれかを抽出したり、元に戻したりするのが容易になります。履歴の書き換えでは、履歴を書き換えたり、ファイルを対話的にステージングしたりするための多くの有用なGitのトリックが説明されています。これらのツールを使用して、作業を他の誰かに送信する前に、クリーンで理解しやすい履歴を作成してください。

最後に覚えておくべきことはコミットメッセージです。高品質なコミットメッセージを作成する習慣をつけることで、Gitの使用と共同作業がはるかに容易になります。一般的に、メッセージは50文字以内の単一行で簡潔に変更セットを説明し、その後に空行、そしてより詳細な説明を続けるべきです。Gitプロジェクトでは、より詳細な説明に、変更の動機と、その実装が以前の動作とどのように異なるかを含めることを要求しています。これは従うべき良いガイドラインです。コミットメッセージは命令形で書いてください。例えば、「バグを修正」であり、「バグを修正した」や「バグを修正する」ではありません。これは、Tim Popeが元々書いたものを少し改変したテンプレートです。

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

おそらく遭遇する最も単純な設定は、他の1、2人の開発者と行うプライベートプロジェクトです。この文脈での「プライベート」とは、クローズドソース、つまり外部にアクセスできないことを意味します。あなたと他の開発者は皆、リポジトリへのプッシュアクセスを持っています。

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

2番目の開発者、ジェシカも同じことをします。リポジトリをクローンし、変更をコミットします。

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

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

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

この場合、ジョンがプッシュする作業は、ジェシカが以前プッシュした作業と競合するため失敗します。Subversion に慣れている人にとっては、2人の開発者が同じファイルを編集したわけではないことに気づくでしょうから、これは特に重要です。Subversion は異なるファイルが編集された場合でも、サーバー上で自動的にそのようなマージを行います。しかし、Git の場合、まずローカルでコミットをマージする必要があります。言い換えれば、ジョンはジェシカの上流の変更をまずフェッチし、それらをローカルリポジトリにマージしてからでなければ、プッシュすることはできません。

まず、ジョンはジェシカの作業をフェッチします（これはジェシカの上流の作業を _フェッチ_ するだけであり、まだジョンの作業にマージはしません）。

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

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

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

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

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

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

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

それはその間にジョンがプッシュした作業を引き出します。ジェシカの履歴は次のようになります。

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

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

上記の出力から、ジョンが作成したコミットのうち、ジェシカがまだ自分のローカル作業にマージしていないコミットが1つだけあることがわかります。彼女がorigin/masterをマージすると、その1つのコミットが彼女のローカル作業を変更することになります。

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

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

ジェシカは、origin/masterとissue54のどちらを先にマージしても構いません。両方とも上流なので、順序は関係ありません。どちらの順序を選択しても、最終的なスナップショットは同じになるはずです。履歴のみが異なります。彼女は最初にissue54ブランチをマージすることを選択します。

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

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

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

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

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

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

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

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

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

ジェシカはジョンにメールを送り、featureAというブランチに作業をプッシュしたことを伝え、今見てもらえると伝えます。ジョンからのフィードバックを待つ間、ジェシカはジョージーとfeatureBの作業を始めることにします。まず、サーバーのmasterブランチをベースにして新しい機能ブランチを開始します。

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

ジェシカのリポジトリは現在このようになっています。

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

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

この時点で、ジェシカはこれらマージされた「featureB」の作業をすべてサーバーに戻したいと思っていますが、自分のfeatureBブランチを単純にプッシュしたくありません。むしろ、ジョージーがすでに上流のfeatureBeeブランチを開始しているので、ジェシカは**その**ブランチにプッシュしたいと思っており、次のように行います。

これは*refspec*と呼ばれます。RefspecでGitのrefspecとその利用方法について詳しく説明しています。また、-uフラグにも注目してください。これは--set-upstreamの短縮形であり、後で簡単にプッシュおよびプルできるようにブランチを設定します。

突然、ジェシカはジョンからメールを受け取ります。ジョンは、彼らが共同作業しているfeatureAブランチにいくつかの変更をプッシュしたと彼女に伝え、ジェシカにそれらを見るように頼みます。再び、ジェシカは簡単なgit fetchを実行して、ジョンからの最新の作業を含む、サーバーからの*すべて*の新しいコンテンツをフェッチします。

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

ジェシカは気に入ったものを見つけた場合、ジョンの新しい作業を自分のローカルのfeatureAブランチにマージできます。

最後に、ジェシカはマージされたすべてのコンテンツにいくつかの軽微な変更を加えたいと思うかもしれません。そこで彼女は自由にそれらの変更を加え、ローカルのfeatureAブランチにコミットし、最終結果をサーバーにプッシュします。

ジェシカのコミット履歴は現在このようになっています。

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

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

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

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

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

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

いずれにせよ、作業を次のようにプッシュできます。

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

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

この出力はメンテナーに送信できます。作業がどこから分岐したか、コミットの概要、そして新しい作業をどこからプルするかを伝えます。

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

これで、各トピックはサイロ（パッチキューに似たもの）内に収められ、トピックが互いに干渉したり依存したりすることなく、次のように書き換え、リベース、変更できます。

プロジェクトのメンテナーが他のパッチをいくつか取り込み、あなたの最初のブランチを試しましたが、もはやきれいにマージされないとしましょう。この場合、そのブランチをorigin/masterの上にリベースし、メンテナーのために競合を解決し、それから変更を再提出しようとすることができます。

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

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

もう一つの可能なシナリオを見てみましょう。メンテナーがあなたの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行は必要ないかもしれません。ホストの値はimaps://ではなくimap://になります。設定が完了したら、git imap-sendを使用して、指定されたIMAPサーバーの「下書き」フォルダにパッチシリーズを配置できます。

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

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

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

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

このセクションでは、複数のワークフローについて取り上げ、クローズドソースプロジェクトでの小規模チームの一員としての作業と、大規模な公開プロジェクトへの貢献の違いについて話しました。コミットする前に空白エラーをチェックすること、そして素晴らしいコミットメッセージを書くことができるようになりました。パッチのフォーマット方法、および開発者メーリングリストへのメール送信方法を学びました。マージの扱いについても、さまざまなワークフローの文脈で説明しました。これで、あらゆるプロジェクトで共同作業を行う準備ができました。

次に、その逆の側面、つまりGitプロジェクトのメンテナンス方法を見ていきます。慈悲深い独裁者や統合マネージャーになる方法を学びます。