PATCH(1)

名前
patch - オリジナルファイルに差分ファイルを適用する

書式
patch [options] [originalfile [patchfile]]

通常はもっと簡単に

patch -pnum <patchfile

説明
patch は、プログラム diff で生成された差分リストを含むパッチファイル patchfile を引数に取り、 1 個または複数のオリジナルファイルにこれらの差分を適用し、 パッチの当たったバージョンを生成する。 通常、オリジナルファイルは パッチの当たったバージョンと置き換わる。 バックアップを作成することもできる ( -b または --backup オプションを参照 ) 。 通常、パッチを当てるファイルの名前はパッチファイルから得られる。 ただし、パッチの当たるファイルが 1 個だけの場合、 orginalfile としてコマンドラインで指定することができる。

実行すると、 patch は差分 (diff) リストの形式を判別する。 ただし、 -c (--context), -e (--ed), -n (--normal), -u (--unified) オプションのどれかが指定された場合、自動判別は行なわれない。 コンテキスト diff (old-style, new-style, unified) および ノーマル diff は patch プログラム自身がパッチを適用する。 いっぽう、 ed diff はパイプを通じて ed(1) エディタに流し込まれるだけである。

patch は差分の前にあるゴミを読み飛ばし、差分を適用し、 そして後ろにあるゴミを読み飛ばそうとする。 そのため、差分リストを含む記事やメッセージを patch に流し込むことができ、それで動作するはずである。 diff 全体が一定量インデントされている場合や、 コンテキスト diff が CRLF で終わる行を含んでいる場合、 インターネット RFC 934 で規定されるように "-" で始まる行の先頭に 1個または複数個の "- " が付いている場合には、 これらは考慮される。

コンテキスト diff や ノーマル diff ( ノーマル diff の場合の適用範囲はやや狭い ) の場合、 patch はパッチ中の行番号の誤りを検出することができ、 パッチのそれぞれの塊 (hunk) について、正しい位置を見つけようとする。 最初は、hunk に書かれた行番号に 直前の hunk を適用した際のオフセットを加減した位置ではないかと推測する。 もしそれが正しい位置ではない場合、 patch は hunk 中のコンテキストに一致する行が前後にないかを探す。 まず、 patch はコンテキストのすべての行が一致する位置を探す。 そのような位置が見つからない場合で、かつコンテキスト diff であり、 かつ fuzz factor (曖昧度合い) の最大値が 1 以上の場合、 コンテキストの最初と最後の行を無視してもう一度探す。 それも失敗し、 fuzz factor の最大値が 2 以上の場合、 コンテキストの最初と最後の 2 行ずつを無視してもう一度探す。 ( デフォルトの fuzz factor の最大値は 2 である。 ) patch は、パッチのその hunk を適用する位置を見つけられない場合、 その hunk を reject (却下) ファイルに書き出す。 通常、 reject ファイルの名前は出力ファイルの後ろに .rej を付けたものか、 .rej を付けるとファイル名が長くなりすぎる場合には # を付けたものとなる ( もし # 1 文字を付けても長くなりすぎる場合には、 ファイル名の最後の文字を # に置き換える ) 。 ( reject (却下) された hunk は入力されたパッチの形式にかかわらず、 通常のコンテキスト diff の形式で出力される。 入力がノーマル diff の場合、コンテキストの多くは単純に空になる。 ) reject ファイル中の hunk に付けられた行番号はパッチファイルのものとは 異なるかもしれない。 reject ファイル中の行番号は、古いファイルにおける位置ではなく、 patch が新しいファイルの中で hunk が当たると思うおおよその位置になっている。

それぞれの hunk の処理が終わると、 hunk が失敗したかどうかや、 もし失敗した場合、 patch が ( 新しいファイルの ) どの行に その hunk が当たると思ったかが通知される。 hunk が diff に示された行番号と異なる位置に適用された場合は、 そのオフセットが通知される。 大きなオフセットが 1 個だけ通知された場合、 ある hunk が間違った位置に適用された かもしれない。 一致する位置を探すために fuzz factor が使われたかどうかも通知されるが、 その場合には少々不審に思ったほうがよい。 --verbose オプションを指定すると、 hunk がぴったり一致した場合にも通知される。

コマンドラインでオリジナルファイル origfile が指定されなかった場合、 patch は diff の前にあるゴミから次のような規則を使って 編集すべきファイルを判別しようとする。

まず、 patch は候補となるファイル名の順序付きリストを次のようにして作る:

•   ヘッダがコンテキスト diff のものである場合、 patch はヘッダにある新旧のファイル名を使う。 -pnum または --strip=num オプションに見合った数のスラッシュがないファイル名は無視される。 /dev/null というファイル名も無視される。

•   diff の前のゴミの中に Index: があり、新旧両方のファイル名がないか patch が POSIX に準拠している場合、 patch は Index: の行にあるファイル名を使う。

•   以下のルールを実現するために、 ヘッダに現れた順に関係なく、 候補となるファイル名は、旧、新、 index の順序で扱われる。

そして patch は候補リストから次のようにファイル名を選択する:

•   複数の名前のファイルが見つかった場合、 patch は POSIX 準拠ならば最初の名前を、 そうでなければ最適な (best) 名前を選択する。

•   patch が RCS, ClearCase, SCCS を無視しない場合 ( -g num または --get=num オプションを参照 ) で、かつ候補リストの名前のファイルはどれも存在しないが RCS, ClearCase, SCCS マスタが見つかった場合、 patch は RCS, ClearCase, SCCS マスタの存在する 候補リスト中の最初の名前のファイルを選択する。

•   候補リストの名前のファイルがどれも存在せず、 RCS, ClearCase, SCCS マスタも見つからず、 候補リストには複数の名前があり、 patch が POSIX 準拠ではなく、 そのパッチがファイルを作成しようとしているように見受けられる場合、 patch は作成するディレクトリが最も少なくて済む、最適な (best) 名前を選択する。

•   以上の規則でファイル名が決まらない場合、 patch はパッチを当てるファイルの名前を尋ね、その名前を使う。

空でないファイル名のリストから 最適な (best) ものを選ぶために、 patch はまずパス名の要素が最も少ないものを選び、 その中からベースネームの最も短いものを選び、 さらにその中から最も短いものを選び、 最後に、残った中で最初の名前を選ぶ。

さらに、前のゴミに Prereq: という行が含まれる場合、 patch はその必要条件の行から最初の単語 ( 通常はバージョン番号 ) を取り、 オリジナルファイルにその単語があるかどうかをチェックする。 もしない場合、 patch は処理する前に確認を求める。

すべての結論は、 ニュースリーダを使っているときには、 次のような感じにすればよいということである:

    | patch -d /usr/src/local/blurfl

こうすれば、ディレクトリ blurfl にあるファイルに、パッチを含む記事から直接パッチを当てることができる。

パッチファイルに複数のパッチが含まれている場合、 patch は、それぞれが別々のパッチファイルから入力されたかのように当てようとする。 このときは、とりわけ、 パッチを当てるファイルの名前はそれぞれの差分リストから決まらなければならず、 それぞれの差分リストの前のゴミにはファイル名やリビジョン番号といった 必要なことがらが含まれていることが求められる。

オプション

-b  または  --backup
    バックアップファイルを作成する。 つまり、ファイルにパッチを当てるとき、 元のファイルを削除せずに、リネームまたはコピーする。 存在しないファイルをバックアップするときは、 空の、読み出す内容のないバックアップファイルが作られ、 ファイルが存在しなかったことを表すものとなる。 バックアップファイルの名前がどのように決まるかについては -V または --version-control オプションを参照。

--backup-if-mismatch
    パッチがファイルにぴったり一致しなかった場合で、 かつ他の方法でバックアップを要求されていない場合に ファイルをバックアップする。 patch が POSIX 準拠でない場合はデフォルトである。

--no-backup-if-mismatch
    パッチがファイルにぴったり一致しなかった場合で、 かつ他の方法でバックアップを要求されていない場合には ファイルをバックアップしない。 patch が POSIX 準拠の場合はデフォルトである。

-B pref  または  --prefix=pref
    簡易バックアップファイルの名前を生成するとき、ファイル名に pref というプレフィクスをつける。 例えば、 -B /junk/ とすると、 src/patch/util.c というファイルに対する簡易バックアップファイルの名前は /junk/src/patch/util.c となる。

--binary
    すべてのファイルをバイナリモードで読み書きする。 ただし、標準出力と /dev/tty を除く。 POSIX 準拠のシステムではこのオプションは無効である。 このオプションで違いの出る DOS のようなシステムでは、 パッチを diff -a --binary のようにして作らなければならない。

-c  または  --context
    パッチファイルを通常のコンテキスト diff として解釈する。

-d dir  または  --directory=dir
    何をするよりも前に、 ただちにディレクトリ dir に移動する。

-D define  または  --ifdef=define
    変更に印を付けるのに #ifdef ... #endif のような構造を使う。 このとき差分を示すシンボルに define を用いる。

--dry-run
    パッチを当てたときの結果を表示するが、 実際にはどのファイルも変更しない。

-e  または  --ed
    パッチファイルを ed スクリプトとして解釈する。

-E  または  --remove-empty-files
    パッチを当てたあと空になったファイルを削除する。 通常、このオプションは不要である。 なぜなら patch はヘッダのタイムスタンプを見て、パッチを当てたあとに ファイルが存在するべきかどうかを判断することができるからである。 しかし、入力がコンテキスト diff でない場合や patch が POSIX 準拠の場合、 patch はこのオプションが与えられない限りパッチ後に空になったファイルを削除しない。 patch がファイルを削除するときは、 空の上位ディレクトリも削除しようとする。

-f  または  --force
    ユーザが何をしようとしているかを完全に分かっているとみなし、 何も問い合わせをしない。 どのファイルにパッチを当てるべきかが ヘッダに書かれていないパッチはスキップし、 ファイルのバージョンがパッチ中の Prereq: の行に書かれたバージョンと違っていてもパッチを当て、 パッチが反転しているように見えても反転していないとみなす。 このオプションはコメント出力を抑制しない。そうしたければ -s を使うこと。

-F num  または  --fuzz=num
    fuzz factor の最大値を設定する。 このオプションはコンテキスト diff に対してのみ有効で、 patch が hunk を適用する位置を探すときに無視する行数の最大値を指定する。 fuzz factor を大きくすると パッチが間違って当たってしまう場合が多くなることに注意すること。 デフォルトの fuzz factor は 2 で、 コンテキスト diff のコンテキストの行数よりも大きく設定してはならない。 コンテキストの行数は通常 3 である。

-g num  または  --get=num
    このオプションは ファイルが RCS または SCCS で管理されていて、 ファイルが存在しないか読み取り専用で デフォルトバージョンに一致する場合、 またはファイルが ClearCase で管理されていてファイルが存在しない場合の patch の動作を変更する。 num が正であれば、 patch はリビジョン管理システムからファイルを取得 ( チェックアウト ) する。 0 であれば、 patch は RCS, ClearCase, SCCS を無視し、ファイルを取得しない。 負であれば、 patch はファイルを取得するかどうかをユーザに尋ねる。 このオプションのデフォルトの値は、 環境変数 PATCH_GET が設定されていればその値となる。 そうでない場合、デフォルトの値は patch が POSIX 準拠であれば 0 、そうでなければ負となる。

--help
    オプションの要約を表示し、終了する。

-i patchfile  または  --input=patchfile
    パッチを patchfile から読み込む。 patchfile が - の場合は標準入力から読み込み、これがデフォルトである。

-l  または  --ignore-whitespace
    タブやスペースが変更されている場合のために、パターンの一致をゆるく見る。 パッチファイル中の 1 個または複数の空白の並びは オリジナルファイルの空白のどの並びにも一致し、 行末の空白の並びは無視される。 通常文字は完全に一致していなければならない。 コンテキストの各行はオリジナルファイルの 1 行に一致していなければならない。

-n  または  --normal
    パッチファイルをノーマル diff として解釈する。

-N  または  --forward
    反転していると思われるパッチやすでに適用済みと思われるパッチを無視する。 -R も参照。

-o outfile  または  --output=outfile
    ファイルにパッチを当てて置き換えるのではなく、 出力を outfile に送る。

-pnum  または  --strip=num
    パッチファイルで見つかったファイル名それぞれについて、 num 個のスラッシュを含む最小のプレフィクスを取り除く。 隣接した 1 個または複数のスラッシュの並びは 1 個のスラッシュとして 数えられる。 このオプションは パッチを送った人と異なるディレクトリにファイルを格納している場合のために、 パッチファイル中のファイル名の扱いを変更する。 例えば、パッチファイル中のファイル名が

        /u/howard/src/blurfl/blurfl.c

    であったとすると、 -p0 とするとファイル名全体が変更されずに用いられ、 -p1 とすると

        u/howard/src/blurfl/blurfl.c

    のように先頭のスラッシュが取り除かれ、 -p4 とすると

        blurfl/blurfl.c

    のようになり、 -p を指定しなければ blurfl.c となる。 最終的に参照されるディレクトリは カレントディレクトリ、または -d オプションで指定されたディレクトリである。

--posix
    以下のようにより厳格に POSIX 標準にしたがう。

    •   diff ヘッダから複数のファイル名が得られた場合、 リスト (old, new, index) のうち最初に存在したファイルを用いる。

    •   パッチを当てたあと空になったファイルを削除しない。

    •   RCS, ClearCase, SCCS から ファイルを取得するかどうかを尋ねない。

    •   コマンドラインではすべてのオプションがファイルの前になければならない。

    •   パッチが元のファイルにぴったり一致しない場合でも、 ファイルをバックアップしない。

--quoting-style=word
    ファイル名を出力するのにスタイル word を使う。 word は次のどれかでなければならない:

    literal
        ファイル名をそのまま出力する。

    shell
        ファイル名にシェルのメタキャラクタが含まれる場合や 曖昧な出力となってしまう場合、 ファイル名にシェル用の引用符を付ける。

    shell-always
        通常は引用符が必要でない場合にもシェル用の引用符を付ける。

    c   C 言語文字列と同様にファイル名に引用符を付ける。

    escape
        c と同じように引用符を付けるが、最初と最後のダブルクウォート文字を省略する。

    --quoting-style オプションのデフォルト値は環境変数 QUOTING_STYLE で指定することができる。 環境変数が設定されていない場合、デフォルト値は shell である。

-r rejectfile  または  --reject-file=rejectfile
    reject ( 却下された hunk) を デフォルトの .rej ファイルではなく rejectfile に出力する。

-R  または  --reverse
    このパッチは新旧のファイルが反転しているとみなす。 ( まあ、ときどきある。人間のやることだから。 ) patch はそれぞれの hunk を当てる前に反転させる。 reject ( 却下された hunk) も反転したあとの形式で出力される。 -R オプションは ed 形式の diff スクリプトに対しては動作しない。 反対の操作をするには情報が少なすぎるからである。

    パッチの最初の hunk が失敗すると、 patch は hunk を反転させて当たるかどうかをみる。 もし当たる場合、 -R オプションをセットするかどうかを尋ねる。 もし当たらない場合、通常の方法を継続する。 ( 注意: この方法では、 ノーマル diff で最初のコマンドが追加の ( つまり、本来は削除であった ) 場合に 反転されたパッチを検出することができない。 それは、空のコンテキストはどこにでもマッチするために、 追加は常に成功するからである。 幸い、ほとんどのパッチは行を追加するか、変更するものであって、 削除するものは少ないため、 経験的にいって、反転したノーマル diff のほとんどは削除から始まっていて、 失敗してくれる。 )

-s  または  --silent  または  --quiet
    エラーが発生しない限り、静かに動作する。

-t  または  --batch
    -f と同様に質問を抑制する。 ただし、異なる仮定をする。 ヘッダにファイル名を含まないパッチはスキップし (-f と同じ ) 、 ファイルのバージョンがパッチ中の Prereq: の行に書かれたバージョンと違うパッチはスキップし、 パッチが反転しているように見える場合は反転しているとみなす。

-T  または  --set-time
    パッチを当てたあとのファイルの変更日時とアクセス日時を コンテキスト diff ヘッダのタイムスタンプに設定する。 コンテキスト diff ヘッダはローカル時刻を使っているとみなす。 このオプションは推奨されない。 なぜならローカル時刻を使ったパッチは異なるタイムゾーンの人には 簡単に使えないから、 またローカルタイムスタンプは サマータイムの調整で時刻が戻った場合に曖昧になるからである。 このオプションを使う代わりに、 UTC でパッチを生成し、 -Z または --set-utc を使うこと。

-u  または  --unified
    パッチファイルを unified コンテキスト diff として解釈する。

-v  または  --version
    patch のリビジョンヘッダとパッチレベルを出力し、終了する。

-V method  または  --version-control=method
    バックアップファイルの名前を決定するのに method を使う。 method は PATCH_VERSION_CONTROL ( または、それがない場合、 VERSION_CONTROL) 環境変数で指定でき、このオプションで上書きされる。 method はバックアップファイルが作られるかどうかには影響せず、 作られるバックアップファイルの名前に影響するだけである。

    method の値は GNU Emacs の `version-control' 変数と同様である。 patch はもっと分かりやすい同義語も理解する。 method の有効な値は次のとおりである ( 区別が付けば短縮形を用いてもよい ):

    existing  または  nil
        番号付きのバックアップがある場合、バックアップに番号を付ける。 そうでない場合、簡易バックアップを作る。 これがデフォルトである。

    numbered  または  t
        バックアップに番号を付ける。 F というファイルに対する番号付きバックアップファイルの名前は F.~N~ のようになる。 N はバージョン番号である。

    simple  または  never
        簡易バックアップを作る。 -B または --prefix、 -Y または --basename-prefix、 -z または --suffix オプションで簡易バックアップファイルの名前が決まる。 これらのうちどのオプションも指定されない場合、 簡易バックアップサフィクスが使われる。 サフィクスは SIMPLE_BACKUP_SUFFIX 環境変数が存在する場合はその値、そうでない場合は .orig である。

    番号付きまたは簡易バックアップの場合、 バックアップファイルの名前が長すぎると、 代わりにバックアップサフィクス ~ が使われる。 ~ を付加しても長すぎる場合、 ファイル名の最後の文字が ~ に置き換えられる。

--verbose
    処理が行なわれる様子について追加の情報を出力する。

-x num  または  --debug=num
    内部デバッグフラグを設定する。 patch を変更する人にしか興味のないものである。

-Y pref  または  --basename-prefix=pref
    簡易バックアップファイルの名前を生成するとき、 ファイル名のベースネームに プレフィクス pref を付ける。 例えば、 -Y .del/ とした場合、 src/patch/util.c の簡易バックアップファイルの名前は src/patch/.del/util.c となる。

-z suffix  または  --suffix=suffix
    suffix を簡易バックアップサフィクスとして使う。 例えば、 -z - とした場合、 src/patch/util.c の簡易バックアップファイルの名前は src/patch/util.c- となる。 バックアップサフィクスは SIMPLE_BACKUP_SUFFIX 環境変数で指定することができ、このオプションで上書きされる。

-Z  または  --set-utc
    パッチを当てたあとのファイルの変更日時とアクセス日時を コンテキスト diff ヘッダのタイムスタンプに設定する。 コンテキスト diff ヘッダは 世界協定時 (UTC 、GMT としても知られる ) を 使っているとみなす。 -T または --set-time オプションも参照すること。

    -Z または --set-utc および -T または --set-time オプションは、通常はファイルのオリジナルの時刻が パッチヘッダ中の時刻と一致しない場合や 内容がパッチとぴったり一致しない場合には、ファイルの時刻を設定しない。 しかし、 -f または --force オプションが指定された場合、ファイルの時刻は強制的に設定される。

    diff の出力形式の制限のため、 これらのオプションでは 内容の変化しないファイルの時刻は更新されない。 また、これらのオプションを使った場合には、 パッチの当たったファイルに依存するファイルを削除して ( 例えば make clean で ) 、 あとで make を実行したときにパッチの当たったファイルの時刻で 混乱しないようにしなければならない。

環境変数

PATCH_GET
    patch が存在しないファイルや読み取り専用のファイルをデフォルトで RCS, ClearCase, SCCS から取得するかどうかを指定する。 -g または --get オプションを参照。

POSIXLY_CORRECT
    設定されている場合、 patch はデフォルトで POSIX 標準により厳格に従う。 --posix オプションを参照。

QUOTING_STYLE
    --quoting-style オプションのデフォルトの値。

SIMPLE_BACKUP_SUFFIX
    .orig の代わりに簡易バックアップファイルの名前に使う拡張子。

TMPDIR, TMP, TEMP
    一時ファイルを入れるディレクトリ patch はこのリストの中で最初に設定されている環境変数を使う。 どれも設定されていない場合、デフォルトはシステム依存である。 Unix ホストでは通常 /tmp である。

VERSION_CONTROL または PATCH_VERSION_CONTROL
    バージョンコントロールスタイルを選択する。 -V または --version-control オプションを参照。

ファイル

$TMPDIR/p*
    一時ファイル。

/dev/tty
    制御端末。ユーザに尋ねた質問の答えを得るために使われる。

関連項目
diff(1), ed(1)

Marshall T. Rose and Einar A. Stefferud, Proposed Standard for Message Encapsulation, Internet RFC 934 <URL:ftp://ftp.isi.edu/in-notes/rfc934.txt> (1985-01).

パッチを送る人への注意
パッチを送ろうとする場合に心に留めておかなければならない点がいくつかある。

パッチを機械的に作ること。 よい方法は diff -Naur old new のようなコマンドを使うことである。 new と old はそれぞれ新旧のディレクトリである。 old と new には 1 個もスラッシュがあってはいけない。 diff コマンドのヘッダに含まれる日時は伝統的な Unix 形式を使って 協定世界時で書かれていなければならない。 そうすれば パッチを受け取った人が -Z または --set-utc オプションを使うことができる。 次のものは Bourne シェル形式を使ったコマンド例である:

    LC_ALL=C TZ=UTC0 diff -Naur gcc-2.7 gcc-2.8

受け取る人にはパッチの当て方を伝える。 つまり、どのディレクトリに cd すればよいかとどの patch オプションを使えばよいかを伝える。 オプション文字列は -Np1 が推奨される。 受け取った人になったつもりで手順を試し、 オリジナルファイルのコピーを取って、作ったパッチを当ててみる。

送り出すパッチファイルの最初の diff として、 パッチレベルをインクリメントしていく patchlevel.h ファイルを入れておくと、 多くの人の面倒を軽減できる。 パッチに Prereq: 行を加えておけば、 順番を間違えて警告を食らうのを防ぐことができる。

/dev/null や 日時が Epoch (1970-01-01 00:00:00 UTC) の空のファイルと 作成したいファイルを比較した diff を送ることで、 ファイルを作成することができる。 この方法はターゲットのディレクトリに作成したいファイルが まだ存在しない場合に限って動作する。 反対に、削除したいファイルと日時が Epoch の空のファイルを比較した コンテキスト diff を送ることで、ファイルを削除することができる。 ファイルは patch が POSIX 準拠でなく、 -E または --remove-empty-files オプションが指定されない場合に削除される。 ファイルを作成したり削除したりするパッチを生成する簡単な方法は、 GNU diff の -N または --new-file オプションを使うことである。

受け取った人が -pN オプションを使うことが想定される場合、 次のようなパッチを送らないこと:

    diff -Naur v2.0.29/prog/README prog/README
    --- v2.0.29/prog/README Mon Mar 10 15:13:12 1997
    +++ prog/README Mon Mar 17 14:58:22 1997

なぜなら二つのファイル名は異なる数のスラッシュを含んでおり、 patch のバージョンによって ファイル名を異なるように解釈するからである。 混乱を避けるために、代わりに次のようなパッチを送ること:

    diff -Naur v2.0.29/prog/README v2.0.30/prog/README
    --- v2.0.29/prog/README Mon Mar 10 15:13:12 1997
    +++ v2.0.30/prog/README Mon Mar 17 14:58:22 1997

バックアップファイルと名前が同じファイル、例えば README.orig と比較したパッチを送らないこと。 この方法では patch が混乱して、 正しいファイルではなく バックアップファイルにパッチを当ててしまうかもしれないからである。 そうではなく、 ファイル名が同じで別のディレクトリにあるファイルどうし、例えば old/README と new/README を比較したパッチを送ること。

反転したパッチを送らないように注意すること。 もうパッチを当てたのかと思ってしまうからである。

自動生成されるファイル ( 例えば、 makefile に configure: configure.in という行がある場合の configure というファイル ) を変更するパッチを作らないようにすること。 受け取った人は自動生成されるファイルを再生成することができるからである。 自動生成されるファイルの diff を送らなければならない場合、 UTC を用いて diff を作り、 受け取った人に -Z または --set-utc オプションを使ってパッチを当ててもらい、 パッチの当たったファイルに依存する、 パッチの当たっていないファイルを削除してもらう ( 例えば make clean で ) 。

582 もの差分リストを 1 個のファイルに入れなくても済むのであれば、 ぐちゃぐちゃになってしまった場合に備えて 関連するパッチを別々のファイルにまとめておくのが賢明である。

エラーと終了ステータス
エラーは一般に、 patch がパッチファイルを解析できなかったことを示している。

--verbose オプションを指定した場合、 Hmm... はパッチファイルの中に処理されなかったテキストがあり、 patch がテキストの中にパッチがあるかどうかを 必死に探そうとしていることを表している。 パッチが見つかると、そのパッチがどんな種類のものかを示す。

patch の終了ステータスは、 すべての hunk の適用に成功した場合に 0 、 一部の hunk が適用できなかった場合に 1 、 もっと深刻な問題に見舞われた場合に 2 となる。 バッチ処理で複数のパッチを適用する場合、 終了ステータスをチェックして、 部分的にしかパッチの当たっていないファイルに 以降のパッチを当てないようにすることが必要である。

警告
コンテキスト diff は空のファイルや空のディレクトリ、 シンボリックリンクなどのスペシャルファイルの作成や削除を 確実に表すことはできない。 所有者やアクセス権限、あるファイルが 別のファイルのハードリンクであることといった ファイルメタデータの変更を表すこともできない。 もしそのような変更も必要であれば、 別に手順書 ( 例えば、シェルスクリプト ) を用意して、 パッチに添付しなければならない。

patch は、 ed スクリプト中の行番号がはみ出しているかどうかは分からないし、 ノーマル diff の行番号の間違いは 変更や削除を見つけた場合に限って検出できる。 fuzz factor が 3 のコンテキスト diff も同じ問題に遭遇するかもしれない。 適当な対話式のインタフェースが導入されるまでは、 このような場合はコンテキスト diff を作って 変更が妥当かどうかを確認しなければならない。 もちろん、エラーなくコンパイルできたことは パッチがうまく当たったよい証拠になるが、必ずしもそうとはいえない。

patch は多数の推測が必要な場合であっても、通常は正しい結果を出す。 しかし、結果が正しいことが保証されるのは、 そのパッチが生成されたファイルと全く同一のバージョンの ファイルに適用された場合だけである。

互換性の問題
POSIX 標準は patch の古典的な振る舞いと異なる振る舞いを規定している。 patch のバージョン 2.1 およびそれ以前 ( これらは POSIX に 準拠していない ) と 相互に運用しなければならない場合、これらの違いを知っておく必要がある。

•   古典的な patch では、 -p オプションの引数は省略可能であり、単独の -p は -p0 と同等であった。 今日の patch では -p オプションに引数が必須で、 -p 0 が -p0 と同等である。 互換性を最大限に保つために、 -p0 や -p1 といったオプションを使う。

    また、古典的な patch はパスプレフィクスを取り除く際、スラッシュの数を単純に数えていた。 今日の patch はパス名の要素を数える。 つまり、 1 個または複数の隣接するスラッシュの列は 1 個のスラッシュとして数えられる。 互換性を最大限に保つために、 ファイル名に // を含むパッチは送らないようにすること。

•   古典的な patch では、デフォルトでバックアップが有効であった。 今日の patch では -b または --backup オプションで有効になる。

    反対に、 POSIX patch では、不整合があってもバックアップは一切作られない。 GNU patch では、この振る舞いは --no-backup-if-mismatch オプションか、 --posix オプションまたは POSIXLY_CORRECT 環境変数で POSIX 準拠にするかで有効になる。

    古典的な patch の -b suffix オプションは GNU patch の -b -z suffix オプションと同等である。

•   古典的な patch は、 パッチヘッダからパッチを当てるファイルの名前を決定するのに 複雑な ( しかも完全にはドキュメントになっていない ) 手法を用いていた。 この手法は POSIX に準拠しておらず、いくつか誤りもあった。 今日の patch は異なる、同じくらい複雑な (しかしドキュメントはましな) 手法を用いており、 オプションで POSIX に準拠することができる。 誤りが減っているとよいのだが。 2 つの手法は、 コンテキスト diff のヘッダのファイル名と Index: の行がプレフィクスを除いて全く同じである場合には互換性がある。 作ったパッチは、 それぞれのヘッダのファイル名がすべて同じ数のスラッシュを含んでいれば、 通常は互換性がある。

•   古典的な patch がユーザに質問をするときは、 質問を標準エラーに出力し、 以下のリストのうちターミナルである最初のファイルから回答を求める: 標準エラー、標準出力、 /dev/tty、 標準入力。 今日の patch は質問は標準出力に出力し、 /dev/tty から回答を得る。 回答のデフォルトのうちいくつかは変更されており、 デフォルトの回答を使っても patch が無限ループに陥らないようになっている。

•   古典的な patch は、失敗した hunk の数をステータス値として終了し、 本当の問題に出くわした場合は 1 をステータス値としていた。 今日の patch は hunk が失敗すると 1 で終了し、問題がある場合は 2 で終了する。

•   GNU patch、 古典的 patch、 POSIX 準拠の patch のどれを使うか分からない人に宛てて手順を送る場合、 次のオプション以外は使わないこと。 以下のリストでは空白も意味を持ち、引数は必須である。

    -c
    -d dir
    -D define
    -e
    -l
    -n
    -N
    -o outfile
    -pnum
    -R
    -r rejectfile

バグ
バグは電子メールで <bug-gnu-utils@gnu.org> へ報告してください。

patch は部分一致や大きく逸脱したオフセットやひっくり返ったコードに対して もっと賢くすることもできるだろうが、その道は長いだろう。

コードが重複している場合 ( 例えば #ifdef OLDCODE ... #else ... #endif のように区切られている場合 ) 、 patch は両方のバージョンにパッチを当てることはできない。 もしパッチが当たったとしたら、 間違ったほうにパッチが当たってしまっていることもよくあり、 それでも成功したから続きをやれというだろう。

すでに当たっているパッチを当てようとすると、 patch はパッチが反転していると思い、パッチを戻すかを尋ねる。 これは機能のひとつとみなすことができよう。

著作権
Copyright 1984, 1985, 1986, 1988 Larry Wall.
Copyright 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998 Free Software Foundation, Inc.

Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies.

Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one.

Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be included in translations approved by the copyright holders instead of in the original English.

著者
オリジナルの patch は Larry Wall が書いた。 Paul Eggert は恣意的な制限を取り除き、 バイナリファイルへの対応や、ファイルの時刻設定、ファイルの削除を追加した。 また、より POSIX に準拠するようにした。 ほかには Wayne Davison が unidiff への対応を追加し、 David MacKenzie がコンフィグレーションとバックアップへの対応を追加した。