Git を使った Drupal のパッチの作り方

2017/01/10Drupal 8

今回は Drupal へのコード周りのコントリビュートに欠かせない「パッチの作り方」に関する記事を翻訳してご紹介したいと思います。

このコントリビュートのお話と関連するところとして 2017/01/15 に DrupalCamp Japan 2017 が開催されます。興味のある方はぜひイベントページをご覧になってみてください。

DrupalCamp Japan 2017 in Tokyo （サイト削除済み）

さて、パッチの作り方の記事についてです。今回の翻訳元は drupal.org の次のページです。

Making a Drupal patch with Git

対象バージョンは本稿執筆時点の 2016 年 6 月 1 日更新版です。

日本語としての読みやすさを重視して意訳をかなり入れています。正確な原文のニュアンスは失われているので、原文の正確な中身を知りたい方は原文の方にあたってみてください。

翻訳ここから。

Git を使ったパッチの作り方

このページでは、 Drupal.org にホスティングされているプロジェクト（モジュールやテーマ、 Drupal コアなど）に対して Git を使用してコントリビュートを行うための現時点でのベストプラクティスの概要を説明しています。より高レベルな Git ワークフローについては Advanced patch contributor guide を参照してください。 Drush issue queue commands ではパッチの作成と利用をより速くかんたんにする方法が紹介されています。

メモ 1: Drupal にパッチをあてることについてあまり馴染みがない場合は the Getting Involved section on Patches をご覧ください。

メモ 2: Git 以外のツールでパッチを作成する場合は -p1 パッチを出力するようにしてください。旧式の -p0 形式は 2011 に廃止となりました。

Git でパッチを作成する方法、適用する方法についての短い動画があります。動画ではこの記事の多くの部分がカバーされています。

General patch guidelines - 一般的なパッチガイドライン

Keeping things organized - きれいにまとめる

レビュアーが変更の範囲を把握しやすくするために、異なるタイプの変更は別のパッチに分けましょう。例えば、バグフィックス、パフォーマンス改善、コードスタイル修正、空白の修正などは別々のパッチにするべきです。各変更（とそのパッチ）は Drupal.org の別々のイシューにくっつけましょう。

Line endings and directory separators - 行末とディレクトリセパレータ

Windows をお使いの方へ: Unix の行末（ LF ）とディレクトリセパレータ（ / ）を使いましょう。多くのテキストエディタでは行末を変換することができます。 doc2unix で diff の出力をパイプするという手もあります。

Quick and simple patch - クイック & シンプルパッチ

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

1. モジュールまたはテーマのページを開きます。例: https://drupal.org/project/colorbox/
1. タイトルの下の「 Version Control 」をクリックします。例: https://drupal.org/project/colorbox/git-instructions
1. パッチの作成対象となる dev 版を選択します。これは通常現在の Drupal リリースにモジュールのバージョンと「 -dev 」がついたものになります。例: 8.x-1.x-dev 。パッチは最新のコードである dev 版に対して作成してください。 Git の dev ブランチで作業をするとき実際には「 -dev 」をブランチ名にはつけません。ブランチ名の末尾が「 .x 」（例: 8.x.-1.x ）であれば、それは開発ブランチであることを意味します。

最後のリリース以降の変更はすべて開発ブランチに含まれています。

1. 「 Show 」ボタンをクリックして「 git clone 」コマンドを更新します。
1. 「 git clone --branch .. 」のコマンドをコピーします。
1. git コマンドを実行してモジュールやテーマの git 版をダウンロードします。

コマンドを適当なフォルダ（例: sites/all/modules や sites/all/themes ）で実行すれば、モジュールやテーマを通常ダウンロードする場合と同等の結果になります。

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

1. ダウンロードしたモジュールやテーマのディレクトリで、ローカルバージョンの「ブランチ」を作成します。こうすることで、独立したブランチを更新し、変更をコミットし、パッチを生成することがかんたんになります。

イシューのページ URL が https://drupal.org/node/123456 の場合、イシュー番号は 123456 です。

git branch [イシュー番号]-[イシューの説明]
# 例: git branch 1234-fix-for-header

# 確認
git branch
* 8.x-1.x
  1234-fix-for-header

1. 「 * 」に注目してください。

これは現在 git が使用するブランチを示しています。新しく作ったブランチ 1234-fix-for-header を使用するために、そのブランチのファイルをチェックアウトするように git に伝えましょう。注意: 「 git checkout ブランチ名 」は git 管理下のすべてのファイルをそのブランチのファイルで置き換えます。ここではファイルはすべて同じなので得に変更されるものはありません。ブランチ名をすばやく入力するには、数文字入力してタブキーを押してください。

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

1. ここまで来たら、モジュールやテーマに変更を加えましょう。

git を使って、変更の概要と具体的な内容を確認することができます。ファイルを追加して、コミットを実行しましょう。

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

1. パッチ作成の準備ができたら、変更を加えたモジュールかテーマのフォルダに行きましょう。

すべての変更をコミットし、 git diff 8.x-1.x を使ってパッチに入ることになる変更内容を確認しましょう。

git diff 8.x-1.x

（ git diff から抜けるには q キーを押してください）

1. イシューページを開いてページのいちばん下にあるファイルセクションに移動します。

「 Patchname suggestion 」ボタンをクリックして、出てくるポップアップからファイル名をコピーしましょう。

1. 準備が整ったら、前のステップで取得したファイル名を [パッチ名.patch] のところに使用して次のコマンドでパッチを作成します。

git diff 8.x-1.x > [パッチ名.patch]

1. さぁパッチをアップロードしましょう！

これでよりよい Drupal を作る活動に参加できました。おめでとう！

Notes - メモ

より深い情報は Advanced patch contributor guide に載っています。
'git clone' コマンドはフォルダがまだ存在しない場合にのみ機能します。

このコマンドがエラーを出して失敗するときは、 git はすでに行われたあなたの成果を上書きしてしまうのを防いでくれています。すでにフォルダがある場合はそれを別の場所に移動するか、何も変更を加えていない場合は削除してください。

フォルダの名前を変更したり移動したりするときは Drupal ディレクトリの外に移動するようにしてください。

そうすることで Drupal が移動後のモジュールまたはテーマを認識して 2 度読み込んでしまうのを防ぐことができます。

こんなやり方もあります。

このコマンド（？？？）を Drupal ディレクトリの外で実行して、すでに編集したフォルダを新しいフォルダにコピーします。ただし、この方法には変更点をリアルタイムにチェックできないというデメリットがあります。

ブランチがうまく動かず、モジュールをオフィシャルの状態に戻したくなった場合は次のようにしましょう。

変更をコミットし、メインブランチをチェックアウトします。それから Drupal のキャッシュをクリアします。メモ: 加えた変更をまだコミットしていない状態でブランチを変更すべきではありません。

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

More git commands - その他の git コマンド

パッチを作りたい対象のブランチをチェックアウトしていることの確認には次のコマンドを使用します:

git branch

最新版であることの確認には次のコマンドを使用します:

git pull origin [ブランチ名]

必要な変更を加えて、イシューページの「 Patchname suggestion 」ボタンを使ってパッチ名を取得した後に、取得したファイル名でパッチを作成します:

git diff > [パッチ名.patch]

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

git add [新しいファイルへのパス]
git diff --staged > [パッチ名.patch]

両方を含むパッチを作るには次のようにします:

git add [path.to.new.file]
git diff HEAD > [patch-name.patch]

master 以外のブランチでコミットのパッチを作成します:

git format-patch master --stdout > [パッチ名.patch]

Create a New patch - 新しいパッチの作成

この説明は新しいパッチの作成のためのものです。まず特定のファイルにコードを書いて次のコマンドを使用します。

git diff > [パッチ名.patch]

例

git diff > migrate_d6_i18n_nodes-2225775-136.patch

アンダースコアは単語を区切るために使用されます。 migrate_d6_i18n_nodes はイシューの短い説明です。 2225775 はイシュー番号です。イシュー番号はイシューページ URL の最後の部分です。 136 はコメント番号です。

（訳注: このパッチファイルの説明は上の命名ルールと一致していません）

Applying a patch - パッチの適用

ワーキングディレクトリのルートにパッチをダウンロードしてください。次のコマンドでパッチを適用します。 -v フラグをつけると冗長な出力が出るので、パッチがうまく適用されたかどうかを確認することができます。

git apply -v [パッチ名.patch]

パッチファイルを将来のコミットに含めてしまう事故の防止のためパッチファイルを削除:

rm [patch-name.patch]

When you're done: Reverting uncommitted changes - 作業が終わったら・・・未コミットの変更を元に戻す

特定のファイルの変更を元に戻す:

git checkout [ファイル名]

ワーキングツリー全体の変更を戻す:

git reset --hard

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

注意: 細心の注意のもとに使いましょう！ -n でドライランができます

git clean -fd

翻訳ここまで。

以上です。

ふだん git をお使いの方であれば一度慣れてしまえばこの作業には特につまづくところはないかと思いますが、最初だけ慣れるのに少し時間がかかるので、何回か試してみて体で覚えるのがよいものと思います。

参考

Making a Drupal patch with Git