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プロジェクトは、より詳細な説明に、変更の動機と、その実装が以前の振る舞いとどのように異なるかを記述することを要求しています — これは従うべき良いガイドラインです。コミットメッセージは命令形で書いてください：「バグを修正」のように「Fix bug」とし、「Fixed bug」や「Fixes bug」とはしないでください。これは、Tim Popeが元々書いたものを軽く修正した、あなたが従うことができるテンプレートです。

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

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

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

2人目の開発者であるJessicaも同じことをします — リポジトリをクローンし、変更をコミットします

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

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

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

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

最初のステップとして、JohnはJessicaの作業をフェッチします（これはJessicaのアップストリームの作業をフェッチするだけで、まだJohnの作業にマージするわけではありません）

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

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

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

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

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

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

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

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

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

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

上記の出力から、Johnが作成したコミットが1つあり、Jessicaがまだ自分のローカル作業にマージしていないことがわかります。彼女がorigin/masterをマージした場合、それが彼女のローカル作業を変更する唯一のコミットになります。

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

まず（issue54トピックブランチでのすべての作業をコミットした後）、Jessicaはこれらすべての作業を統合する準備として、自分のmasterブランチに切り替えます。

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

問題は発生しませんでした。ご覧のように、単純なfast-forwardマージでした。Jessicaは、origin/masterブランチにあるJohnの以前にフェッチされた作業をマージすることで、ローカルマージプロセスを完了します。

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

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

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

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

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

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

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

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

JessicaはJohnに、featureAという名前のブランチに作業をプッシュしたので、今すぐ見ることができるとメールで伝えます。Johnからのフィードバックを待つ間、JessicaはJosieとfeatureBの作業を開始することにしました。まず、彼女はサーバーのmasterブランチをベースとして新しい機能ブランチを開始します。

さて、JessicaはfeatureBブランチでいくつかのコミットを行います。

Jessicaのリポジトリは次のようになります

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

Jessicaがまだチェックアウト済みのfeatureBブランチにいると仮定すると、彼女はgit mergeを使ってJosieの作業をそのブランチにマージできるようになります。

この時点で、Jessicaはマージされた「featureB」の作業すべてをサーバーにプッシュしたいと考えていますが、単に自分のfeatureBブランチをプッシュするのではなく、JosieがすでにアップストリームのfeatureBeeブランチを開始しているため、Jessicaはそのブランチにプッシュしたいと考えています。彼女は次のようにしてそれを行います。

これはrefspecと呼ばれます。Refspecで、Gitのrefspecとその様々な使い方について詳しく説明しています。また、-uフラグにも注目してください。これは--set-upstreamの短縮形で、後のプッシュとプルを容易にするようにブランチを設定します。

突然、JessicaはJohnからメールを受け取ります。Johnは共同作業しているfeatureAブランチにいくつかの変更をプッシュしたと伝え、Jessicaにそれらを確認するよう依頼します。再び、Jessicaはシンプルなgit fetchを実行して、Johnの最新の作業を含む（もちろん）サーバーからのすべての新しいコンテンツをフェッチします。

Jessicaは、新しくフェッチしたfeatureAブランチの内容を自分のローカルコピーの同じブランチと比較することで、Johnの新しい作業のログを表示できます。

もしJessicaが気に入れば、彼女はJohnの新しい作業を自分のローカルfeatureAブランチに次のようにマージできます。

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

Jessicaのコミット履歴は次のようになります

ある時点で、Jessica、Josie、Johnは、サーバー上のfeatureAとfeatureBeeブランチがメインラインへの統合準備ができたことを統合担当者に伝えます。統合担当者がこれらのブランチをメインラインにマージした後、フェッチによって新しいマージコミットがダウンロードされ、履歴は次のようになります。

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

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

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

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

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

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

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

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

この出力はメンテナに送信できます — それは作業がどこからブランチされたか、コミットを要約し、新しい作業がどこからプルされるべきかを特定します。

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

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

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

これにより、あなたの履歴は今やfeatureA作業後のコミット履歴のようになります。

ブランチをリベースしたため、-fをプッシュコマンドに指定して、サーバー上のfeatureAブランチを、その子孫ではないコミットで置き換える必要があります。別の方法としては、この新しい作業をサーバー上の異なるブランチ（おそらく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行はおそらく不要であり、ホスト値はimaps://の代わりにimap://になります。それが設定されたら、git imap-sendを使用して、指定されたIMAPサーバーのドラフトフォルダにパッチシリーズを配置できます。

この時点で、ドラフトフォルダに行き、宛先フィールドをパッチを送信するメーリングリストに変更し、必要であればメンテナまたはそのセクションの担当者をCCに入れ、送信することができます。

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

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

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

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

次に、コインの裏側、つまりGitプロジェクトの管理方法を見ていきます。あなたは寛大な独裁者や統合マネージャーになる方法を学ぶでしょう。