Git を使った Drupal パッチの作成日本語訳

2015.05.12

Studio Umi

今回は Drupal プロジェクトへの貢献に欠かせない「 Git × Drupal 」に関するドキュメントを翻訳してご紹介したいと思います。こちらは完全に開発者の方向け（中でも特に Drupal にコントリビュートしたい方向け）のドキュメントです。

元記事はこちら。

Making a Drupal patch with Git | Drupal.org

いまこの記事をお読みになっている方の中には Git についてあまりよくご存知でない方もいらっしゃるでしょうか？ Git についてなじみのない方のために「 Git 」についてまずはざっくりご説明してみたいと思います。

Git とは「 VCS: Version Control System 」と呼ばれるもののひとつで「プログラムコードを管理するためのツール」です。 10 年ほど前に登場した後急速に利用者数が拡大し、多くのオープンソース・プロジェクトの開発現場を支えています。もともとは Linux の生みの親であるリーナスさんが「既存のコード管理ツールは全然ダメだから新しく作るわ」ということで開発されたものだそうです。

Drupal プロジェクトは多くのオープンソース・ソフトウェアの例にもれず、 Git を使ってコード管理が行われています。 Drupal のコアだけでなく、コントリビュートモジュール、コントリビュートテーマなども含めてすべて Git を利用する形が標準となっています。細かくいうと、 Drupal のプロジェクトは「コードの管理はすべて Git 」、「イシューの管理はすべて Drupal.org 」という形でまとめられており、イシューの作成・確認、パッチの作成、テストなどの一連のタスクがすべて Drupal.org と Git を使う形で管理されています。

オープンソース・ソフトウェアのプロジェクトでは「コミュニティや仕組みが大事」ということがよく言われますが、 Drupal ではこのあたりのポイントがとてもしっかり押さえられているところがプロジェクトとしての大きな特徴だと思います。

余談ですが、私個人の個人的な好みとして、プログラミングの「言語」というレイヤーでは（ Drupal のベースとなっている） PHP よりも使いやすくていいなと思う言語はいくつかありますが、以下の理由から Drupal （とそのベースである PHP ）には開発者として大きな魅力があると感じています。

プロジェクトの体制や仕組みがしっかり整えられている
多くの世界的なサイトが Drupal ベースで開発されている
結果として Drupal プロジェクトが数年でダメになるという心配を抱えることなく腰を据えて長期的な視点で技術力を蓄積できる
フルスタックの CMS （プラットフォーム）でプロジェクトの規模も大きいため、必然的に多くのノウハウが学べる

それはさておきまして。

今回は「 Drupal プロジェクトのためのパッチを Git を使って作ろう 」という趣旨のドキュメントを日本語に翻訳してみました。

以前小さな Drupal Sprint を行った際に、日本の開発者が Drupal プロジェクトに貢献したいと思っても、日本語での情報が不足していておいそれとは貢献できないということを痛感しました。このあたりのドキュメントを整備していくことで私たちと思いを同じくする人たちの活動のサポートができればと思います。

実際の翻訳文に入る前に 2 点お断りがあります。これらのポイントを認識の上でご覧いただけますと幸いです。

日本語としての読みやすさ・わかりやすさを重視し、意訳と直訳を併用しています。正確なニュアンスが知りたい方はぜひ原文の方をご覧になってください。
今回の翻訳は最終更新日 2015 年 01 月 23 日版のものをもとにしています。その後に加えられた変更のために原文と食い違っている部分があるかもしれません。その場合にはもちろん原文の方が正しいのでそちらを正としてご参照ください（大きな食い違いを発見された場合は弊社 contact などからお知らせいただけますと幸いです）。

では以下が翻訳文となります。

Git を使った Drupal パッチの作成

このページには、 Drupal.org に置かれているプロジェクトに対する貢献についての現時点でのおすすめのベスト・プラクティスが書かれています。これはハイレベルな概説であり、 Git を使用したパッチファイル形式によるコントリビュートのお話となります。ここでいうプロジェクトには例えばモジュールやテーマ、 Drupal コアなどが含まれています。よりハイレベルな Git のワークフローに関しては Advanced patch contributor guide をご覧ください。 Drush issue queue commands を使うと、パッチの作成と利用がよりすばやくかんたんにできるようになります。

メモ 1: もし Drupal へのパッチ適用に馴染みがない場合はパッチについての Getting Involved セクションを読んでください。

メモ 2: git 以外のツールを使ってパッチを作成することにした場合は -p1 パッチを作成するように気をつけてください。古い -p0 フォーマットは 2011 年に廃止されました。

Git を使ったパッチの適用と作成に関する短い動画があります。動画ではこのドキュメントの大部分がカバーされています。

全般的なパッチガイドライン

整理された状態にしておく

レビュアーが変更範囲を理解しやすくするために、各変更のタイプを個別のパッチに分割しましょう。例えば、バグフィックス、パフォーマンス改善、コードスタイル修正、空白修正などは別のパッチに含めるべきです。分割された変更のタイプ（とパッチ）は Drupal.org のイシューキュー上で異なるイシューにひもづけるようにしましょう。

行末やディレクトリのセパレータ

Windows ユーザのためのメモ: 行末とディレクトリのセパレータには Unix スタイル（ LF と / ）を使いましょう。テキストエディタの多くは行末を変換することができますし、 doc2unix を使って diff 出力をパイプしてもよいでしょう。

クイック & シンプルパッチ

この節はパッチをはじめてコントリビュートする人のためのステップ・バイ・ステップのガイドです。

モジュールやテーマのページに行きます。例: http://drupal.org/project/colorbox/
タイトルの下の "Version Control" をクリックします。例: http://drupal.org/project/colorbox/git-instructions
パッチや更新を行いたい dev バージョンを選択します。これはたいてい現在の Drupal リリースとモジュールのバージョンに '-dev' を加えたものになります。例: 7.x-1.x-dev 。 -dev バージョンに対するパッチを作成してください。なぜならこれが最新のコードだからです。 git で -dev ブランチで作業するときはブランチ名に '-dev' を追加したりブランチ名に '-dev' が付いているのを見たりはしないでしょう。ブランチ名の末尾が '.x' （例: 7.x-1.x ）の場合それがデベロップメントブランチであることを意味します。最後のリリース（ 7.x-1.2 など）以降のすべての変更はすべて -de ブランチにあることになります。
show ボタンをクリックして "git clone" コマンドラインが正しいこと / 更新されていることを確認します。
"git clone --branch .. " コマンドをコピーしましょう。
git コマンドを実行してモジュールやテーマのリビジョン付きのコピーをダウンロードしましょう。コマンドを適切なフォルダで実行するようにしてください（例: sites/all/modules や sites/all/themes ）。これはモジュールやテーマをダウンロードして展開するのと同じことになります。ただし git リビジョンが付加されています。

git clone --branch 7.x-1.x http://git.drupal.org/project/colorbox.git 
cd colorbox

モジュールやテーマのディレクトリ内でダウンロードしたブランチのローカルバージョンを作成するよう git に伝えましょう。こうすることで、別のブランチを更新 / 変更して変更点をコミットすることができます。その後でもローカルブランチに対するパッチもかんたんに生成することができます。

git branch [issue-number]-[issue-description]
例: git branch 1234-fix-for-header

この操作がうまく行ったか確かめるには次のコマンドを使いましょう:

git branch
* 7.x-1.x
  1234-fix-for-header

'*' に注目してください。これは git がどのブランチを使っているのかを教えてくれます。新しいブランチを使うにはブランチ 1234-fix-for-header からファイルをチェックアウトするように git に伝えましょう。メモ: 'git checkout branchname' はディレクトリ内のすべてのリビジョンつきファイルをブランチのファイルに置き換えます。本質的にこれはひとつのバージョンから別のバージョンへの切り替えとなります。今回のケースでは、ファイルは同じなので目を見張るような変更はありません。（ブランチ名をすばやく入力するにはタイピングをしてから 'tab' を叩いてください。）

git checkout 1234-fix-for-header
git branch
  7.x-1.x
* 1234-fix-for-header

モジュールやテーマに加えたい変更点を加えましょう。 git を使って全体的な変更箇所や特定の変更点を確認し、作成したファイルを追加し、作業内容をコミットしましょう。

git status
git diff 
git add new_file.php
git commit -a

パッチを作成する準備ができたら。対象となるモジュールやテーマのフォルダに行きます。変更箇所をすべてコミットしましょう。つづいて 'git diff 7.x-1.x' を使いパッチに入る変更点をレビューしましょう。
準備ができたら次のコマンドでパッチを作成しましょう:

git diff 7.x-1.x > [project_name]-[short-description]-[issue-number]-[comment-number].patch

ここまで来たらパッチをアップロードしてしまいましょう！ Drupal をよくする手伝いができましたね。おめでとう！

メモ

パッチファイル名の [comment-number] はコメント番号を指し示します。コメント ID ではありません。予測するよい方法はイシューの最後のコメントに 1 を足すことです。より多くの情報は Advanced patch contributor guide にあります。
'git clone' コマンドはフォルダが 存在しない 場合にのみ動作します。フォルダが存在する場合はエラーが出ます。このおかげで、すでに行った変更を上書きしてしまうことを防いでくれます。フォルダがすでに存在する場合は移動させ、何も変更を加えていない場合は削除しましょう。
- フォルダをリネーム / 移動させる場合、そのフォルダは Drupal ディレクトリの外に出すようにしましょう。そうすることで Drupal はそれをモジュールやテーマと認識しませんし、重複して読み込もうとしません。
あるいはこのコマンドを Drupal ディレクトリ以外で実行しましょう。そして、すでに編集を加えたファイルを新しフォルダにコピーします。このやり方には変更点の実際の動作確認ができないというデメリットがあります。
あなたのブランチがまだうまく動かず、モジュールを動作版/公式版に戻したい場合は、変更点をコミットしてメインブランチをチェックアウトし、 Drupal キャッシュをクリアしてください。メモ: 変更点をコミットしていなければ git はブランチの変更を許可しません。

git commit -a
git branch
  7.x-1.x-dev
* 1234-fix-for-header
git checkout 7.x-1.x-dev
git branch
* 7.x-1.x-dev
  1234-fix-for-header

その他の git コマンド

パッチを適用したいブランチがチェックアウトできていることを確認します。次のコマンドを使いましょう。

git branch

次のコマンドで最新のものにしてください:

git pull origin [branchname]

変更を加えましょう。そしてもしイシューが Drupal.org の http://drupal.org/node/707484 にあるのならイシュー番号 707484 を使います:

git diff > [project_name]-[short-description]-[issue-number]-[comment-number].patch

[project_name] はプロジェクト名を指し示します。これはプロジェクト URL http://drupal.org/project/[project_name] に現れるもの、または git リモートリポジトリの場所 http://git.drupal.org/project/[project_name].git です。

もしパッチによって新しいファイルを追加する場合は次のようにします:

git add [path.to.new.file]
git diff --staged > [project_name]-[short-description]-[issue-number]-[comment-number].patch

両方を同時に行うには次のようにします:

git add [path.to.new.file]
git diff HEAD > [project_name]-[short-description]-[issue-number]-[comment-number].patch

master ではないカレントブランチ上のコミットに対するパッチを作成する場合は次のようにします:

git format-patch master --stdout > [project_name]-[short-description]-[issue-number]-[comment-number].patch

新しいパッチを作る

新しいパッチの作成をサポートするインストラクションは次のとおりです。

まず特定のファイルの中でコードを書きます
次のコマンドを使います

git diff  > [project_name]-[short-description]-[issue-number]-[comment].patch

例:

git diff > abc-make-table-4568951-5.patch

この例を見てください。

アンダースコアは単語を分けるのに使います。
abc はプロジェクト名。
make_table はイシューの簡易説明。
4568951 はイシュー番号です。
もしイシューが https://www.drupal.org/node/1245218 なら最後の 7 桁の数字を取ってこのイシューの最後のコメントをピックアップします。
5 はコメント番号です。

パッチを適用する

ワーキングツリーのルートにパッチをダウンロードしましょう。次のコマンドでパッチを適用します。 -v フラグを使えば出力が詳しくなり、パッチがちゃんと適用されたかどうかを確かめることができます。

git apply -v [patch-name.patch]

事故的に未来のコミットのパッチファイルを含めてしまうのを防ぐためにはそのファイルを削除しておきましょう:

rm [patch-name.patch]

作業終了後: 未コミットの変更を元に戻す

特定のファイルの変更をリバートする（元に戻す）:

git checkout [filename]

すべてのワーキングツリーの変更をリバートする（元に戻す）: Revert changes to the whole working tree:

git reset --hard

ワーキングツリーの外で追加されたファイルを削除する:

メモ: 注意して使ってください！ドライランのためには -n を追加します。

git clean -fd

翻訳文は以上です。いかがだったでしょうか？

一部少しわからない部分があり、そのあたりの翻訳に迷いがある感じになってしまいました。改善点などお気づきの点がございましたら contact などでお知らせいただけますと幸いです。

ふだん Git を日常的に使っていて Git にも Drupal にも慣れ親しんでいる開発者の方であれば、押さえるべきポイントは以下の 2 点のみかと思います。

プロジェクトファイルではなくそのリポジトリをダウンロードしよう。
パッチ名は [project_name]-[short-description]-[issue-number]-[comment-number].patch で。

日々の Drupal 開発や活用に役立つコンテンツとあわせて、引き続き今回のようなコントリビュート活動に役立つコンテンツもお出ししていきたいと思います。「こういう Drupal 記事を書いてほしい！」というようなご要望などございましたらご意見お寄せください（必ずお応えできるともかぎりませんが検討させていただきます！）。

Git を使った Drupal パッチの作成 日本語訳