.\" patch man page
.de Id
.ds Dt \\$4
..
.Id $Id: patch.1,v 1.4 2005/08/08 15:02:43 jm Exp $
.ds = \-\^\-
.de Sp
.if t .sp .3
.if n .sp
..
.\"
.\" Japanese Version Copyright (C) 2005 Suzuki Takashi
.\"         all rights reserved.
.\" Translated Sat Jun 18 13:10:39 JST 2005
.\"         by Suzuki Takashi <JM@linux.or.jp>.
.\"
.\"WORD:        context diff    コンテキスト diff (context, unifiedの総称として)
.\"WORD:        normal diff     ノーマル diff
.\"WORD:        diff            差分, diff
.\"WORD:        diff list       差分リスト
.\"WORD:        diff listing    差分リスト
.\"WORD:        patched         パッチの当たった
.\"WORD:        hunk            塊, hunk
.\"WORD:        fuzz factor     曖昧度合い, fuzz factor
.\"WORD:        reject          却下, reject
.\"WORD:        simple backup   簡易バックアップ
.\"
.TH PATCH 1 \*(Dt GNU
.ta 3n
.SH "名前"
patch \- オリジナルファイルに差分ファイルを適用する
.SH "書式"
.B patch
.RI [ options ]
.RI [ originalfile
.RI [ patchfile ]]
.Sp
通常はもっと簡単に
.Sp
.BI "patch \-p" "num"
.BI < patchfile
.SH "説明"
.B patch
は、プログラム
.B diff
で生成された差分リストを含むパッチファイル
.I patchfile
を引数に取り、
1 個または複数のオリジナルファイルにこれらの差分を適用し、
パッチの当たったバージョンを生成する。
通常、オリジナルファイルは
パッチの当たったバージョンと置き換わる。
バックアップを作成することもできる (
.B \-b
または
.B \*=backup
オプションを参照 ) 。
通常、パッチを当てるファイルの名前はパッチファイルから得られる。
ただし、パッチの当たるファイルが 1 個だけの場合、
.I orginalfile
としてコマンドラインで指定することができる。
.PP
実行すると、 patch は差分 (diff) リストの形式を判別する。
ただし、
\fB\-c\fP (\fB\*=context\fP),
\fB\-e\fP (\fB\*=ed\fP),
\fB\-n\fP (\fB\*=normal\fP),
\fB\-u\fP (\fB\*=unified\fP)
オプションのどれかが指定された場合、自動判別は行なわれない。
コンテキスト diff (old-style, new-style, unified) および
ノーマル diff は
.B patch
プログラム自身がパッチを適用する。
いっぽう、
.B ed
diff はパイプを通じて
.BR ed (1)
エディタに流し込まれるだけである。
.PP
.B patch
は差分の前にあるゴミを読み飛ばし、差分を適用し、
そして後ろにあるゴミを読み飛ばそうとする。
そのため、差分リストを含む記事やメッセージを
.B patch
に流し込むことができ、それで動作するはずである。
diff 全体が一定量インデントされている場合や、
コンテキスト diff が \s-1CRLF\s0 で終わる行を含んでいる場合、
インターネット RFC 934 で規定されるように
"\fB\-\fP" で始まる行の先頭に
1個または複数個の "\fB\- \fP" が付いている場合には、
これらは考慮される。
.PP
コンテキスト diff や
ノーマル diff ( ノーマル diff の場合の適用範囲はやや狭い ) の場合、
.B patch
はパッチ中の行番号の誤りを検出することができ、
パッチのそれぞれの塊 (hunk) について、正しい位置を見つけようとする。
最初は、hunk に書かれた行番号に
直前の hunk を適用した際のオフセットを加減した位置ではないかと推測する。
もしそれが正しい位置ではない場合、
.B patch
は hunk 中のコンテキストに一致する行が前後にないかを探す。
まず、
.B patch
はコンテキストのすべての行が一致する位置を探す。
そのような位置が見つからない場合で、かつコンテキスト diff であり、
かつ fuzz factor (曖昧度合い) の最大値が 1 以上の場合、
コンテキストの最初と最後の行を無視してもう一度探す。
それも失敗し、 fuzz factor の最大値が 2 以上の場合、
コンテキストの最初と最後の 2 行ずつを無視してもう一度探す。
( デフォルトの fuzz factor の最大値は 2 である。 )
.B patch
は、パッチのその hunk を適用する位置を見つけられない場合、
その hunk を reject (却下) ファイルに書き出す。
通常、 reject ファイルの名前は出力ファイルの後ろに
.B \&.rej
を付けたものか、
.B \&.rej
を付けるとファイル名が長くなりすぎる場合には
.B #
を付けたものとなる
( もし
.B #
1 文字を付けても長くなりすぎる場合には、
ファイル名の最後の文字を
.B #
に置き換える ) 。
( reject (却下) された hunk は入力されたパッチの形式にかかわらず、
通常のコンテキスト diff の形式で出力される。
入力がノーマル diff の場合、コンテキストの多くは単純に空になる。 )
reject ファイル中の hunk に付けられた行番号はパッチファイルのものとは
異なるかもしれない。
reject ファイル中の行番号は、古いファイルにおける位置ではなく、
.B patch
が新しいファイルの中で hunk が当たると思うおおよその位置になっている。
.PP
それぞれの hunk の処理が終わると、
hunk が失敗したかどうかや、
もし失敗した場合、
.B patch
が ( 新しいファイルの ) どの行に
その hunk が当たると思ったかが通知される。
hunk が diff に示された行番号と異なる位置に適用された場合は、
そのオフセットが通知される。
大きなオフセットが 1 個だけ通知された場合、
ある hunk が間違った位置に適用された
.IR かもしれない 。
一致する位置を探すために fuzz factor が使われたかどうかも通知されるが、
その場合には少々不審に思ったほうがよい。
.B \*=verbose
オプションを指定すると、 hunk がぴったり一致した場合にも通知される。
.PP
コマンドラインでオリジナルファイル
.I origfile
が指定されなかった場合、
.B patch
は diff の前にあるゴミから次のような規則を使って
編集すべきファイルを判別しようとする。
.LP
まず、
.B patch
は候補となるファイル名の順序付きリストを次のようにして作る:
.TP 3
.B " \(bu"
ヘッダがコンテキスト diff のものである場合、
.B patch
はヘッダにある新旧のファイル名を使う。
.BI \-p num
または
.BI \*=strip= num
オプションに見合った数のスラッシュがないファイル名は無視される。
.B /dev/null
というファイル名も無視される。
.TP
.B " \(bu"
diff の前のゴミの中に
.B Index:\&
があり、新旧両方のファイル名がないか
.B patch
が \s-1POSIX\s0 に準拠している場合、
.B patch
は
.B Index:\&
の行にあるファイル名を使う。
.TP
.B " \(bu"
以下のルールを実現するために、
ヘッダに現れた順に関係なく、
候補となるファイル名は、旧、新、 index の順序で扱われる。
.LP
そして
.B patch
は候補リストから次のようにファイル名を選択する:
.TP 3
.B " \(bu"
複数の名前のファイルが見つかった場合、
.B patch
は \s-1POSIX\s0 準拠ならば最初の名前を、
そうでなければ最適な (best) 名前を選択する。
.TP
.B " \(bu"
.B patch
が \s-1RCS\s0, ClearCase, \s-1SCCS\s0 を無視しない場合 (
.BI "\-g\ " num
または
.BI \*=get= num
オプションを参照 ) で、かつ候補リストの名前のファイルはどれも存在しないが
\s-1RCS\s0, ClearCase, \s-1SCCS\s0 マスタが見つかった場合、
.B patch
は \s-1RCS\s0, ClearCase, \s-1SCCS\s0 マスタの存在する
候補リスト中の最初の名前のファイルを選択する。
.TP
.B " \(bu"
候補リストの名前のファイルがどれも存在せず、
\s-1RCS\s0, ClearCase, \s-1SCCS\s0 マスタも見つからず、
候補リストには複数の名前があり、
.B patch
が \s-1POSIX\s0 準拠ではなく、
そのパッチがファイルを作成しようとしているように見受けられる場合、
.B patch
は作成するディレクトリが最も少なくて済む、最適な (best) 名前を選択する。
.TP
.B " \(bu"
以上の規則でファイル名が決まらない場合、
.B patch
はパッチを当てるファイルの名前を尋ね、その名前を使う。
.LP
空でないファイル名のリストから
.I 最適な (best)
ものを選ぶために、
.B patch
はまずパス名の要素が最も少ないものを選び、
その中からベースネームの最も短いものを選び、
さらにその中から最も短いものを選び、
最後に、残った中で最初の名前を選ぶ。
.PP
さらに、前のゴミに
.B Prereq:\&
という行が含まれる場合、
.B patch
はその必要条件の行から最初の単語 ( 通常はバージョン番号 ) を取り、
オリジナルファイルにその単語があるかどうかをチェックする。
もしない場合、
.B patch
は処理する前に確認を求める。
.PP
すべての結論は、
ニュースリーダを使っているときには、
次のような感じにすればよいということである:
.Sp
	\fB| patch \-d /usr/src/local/blurfl\fP
.Sp
こうすれば、ディレクトリ
.B blurfl
にあるファイルに、パッチを含む記事から直接パッチを当てることができる。
.PP
パッチファイルに複数のパッチが含まれている場合、
.B patch
は、それぞれが別々のパッチファイルから入力されたかのように当てようとする。
このときは、とりわけ、
パッチを当てるファイルの名前はそれぞれの差分リストから決まらなければならず、
それぞれの差分リストの前のゴミにはファイル名やリビジョン番号といった
必要なことがらが含まれていることが求められる。
.SH "オプション"
.TP 3
\fB\-b\fP  または  \fB\*=backup\fP
バックアップファイルを作成する。
つまり、ファイルにパッチを当てるとき、
元のファイルを削除せずに、リネームまたはコピーする。
存在しないファイルをバックアップするときは、
空の、読み出す内容のないバックアップファイルが作られ、
ファイルが存在しなかったことを表すものとなる。
バックアップファイルの名前がどのように決まるかについては
.B \-V
または
.B \*=version\-control
オプションを参照。
.TP
.B \*=backup\-if\-mismatch
パッチがファイルにぴったり一致しなかった場合で、
かつ他の方法でバックアップを要求されていない場合に
ファイルをバックアップする。
.B patch
が \s-1POSIX\s0 準拠でない場合はデフォルトである。
.TP
.B \*=no\-backup\-if\-mismatch
パッチがファイルにぴったり一致しなかった場合で、
かつ他の方法でバックアップを要求されていない場合には
ファイルをバックアップしない。
.B patch
が \s-1POSIX\s0 準拠の場合はデフォルトである。
.TP
\fB\-B\fP \fIpref\fP  または  \fB\*=prefix=\fP\fIpref\fP
簡易バックアップファイルの名前を生成するとき、ファイル名に
.I pref
というプレフィクスをつける。
例えば、
.B "\-B\ /junk/"
とすると、
.B src/patch/util.c
というファイルに対する簡易バックアップファイルの名前は
.B /junk/src/patch/util.c
となる。
.TP
\fB\*=binary\fP
すべてのファイルをバイナリモードで読み書きする。
ただし、標準出力と
.B /dev/tty
を除く。
\s-1POSIX\s0 準拠のシステムではこのオプションは無効である。
このオプションで違いの出る \s-1DOS\s0 のようなシステムでは、
パッチを
.B "diff\ \-a\ \*=binary"
のようにして作らなければならない。
.TP
\fB\-c\fP  または  \fB\*=context\fP
パッチファイルを通常のコンテキスト diff として解釈する。
.TP
\fB\-d\fP \fIdir\fP  または  \fB\*=directory=\fP\fIdir\fP
何をするよりも前に、
ただちにディレクトリ
.I dir
に移動する。
.TP
\fB\-D\fP \fIdefine\fP  または  \fB\*=ifdef=\fP\fIdefine\fP
変更に印を付けるのに
.BR #ifdef " .\|.\|. " #endif
のような構造を使う。
このとき差分を示すシンボルに
.I define
を用いる。
.TP
.B "\*=dry\-run"
パッチを当てたときの結果を表示するが、
実際にはどのファイルも変更しない。
.TP
\fB\-e\fP  または  \fB\*=ed\fP
パッチファイルを
.B ed
スクリプトとして解釈する。
.TP
\fB\-E\fP  または  \fB\*=remove\-empty\-files\fP
パッチを当てたあと空になったファイルを削除する。
通常、このオプションは不要である。
なぜなら
.B patch
はヘッダのタイムスタンプを見て、パッチを当てたあとに
ファイルが存在するべきかどうかを判断することができるからである。
しかし、入力がコンテキスト diff でない場合や
.B patch
が \s-1POSIX\s0 準拠の場合、
.B patch
はこのオプションが与えられない限りパッチ後に空になったファイルを削除しない。
.B patch
がファイルを削除するときは、
空の上位ディレクトリも削除しようとする。
.TP
\fB\-f\fP  または  \fB\*=force\fP
ユーザが何をしようとしているかを完全に分かっているとみなし、
何も問い合わせをしない。
どのファイルにパッチを当てるべきかが
ヘッダに書かれていないパッチはスキップし、
ファイルのバージョンがパッチ中の
.B Prereq:\&
の行に書かれたバージョンと違っていてもパッチを当て、
パッチが反転しているように見えても反転していないとみなす。
このオプションはコメント出力を抑制しない。そうしたければ
.B \-s
を使うこと。
.TP
\fB\-F\fP \fInum\fP  または  \fB\*=fuzz=\fP\fInum\fP
fuzz factor の最大値を設定する。
このオプションはコンテキスト diff に対してのみ有効で、
.B patch
が hunk を適用する位置を探すときに無視する行数の最大値を指定する。
fuzz factor を大きくすると
パッチが間違って当たってしまう場合が多くなることに注意すること。
デフォルトの fuzz factor は 2 で、
コンテキスト diff のコンテキストの行数よりも大きく設定してはならない。
コンテキストの行数は通常 3 である。
.TP
\fB\-g\fP \fInum\fP  または  \fB\*=get=\fP\fInum\fP
このオプションは
ファイルが \s-1RCS\s0 または \s-1SCCS\s0 で管理されていて、
ファイルが存在しないか読み取り専用で
デフォルトバージョンに一致する場合、
またはファイルが ClearCase で管理されていてファイルが存在しない場合の
.B patch
の動作を変更する。
.I num
が正であれば、
.B patch
はリビジョン管理システムからファイルを取得 ( チェックアウト ) する。
0 であれば、
.B patch
は \s-1RCS\s0, ClearCase, \s-1SCCS\s0 を無視し、ファイルを取得しない。
負であれば、
.B patch
はファイルを取得するかどうかをユーザに尋ねる。
このオプションのデフォルトの値は、
環境変数
.B PATCH_GET
が設定されていればその値となる。
そうでない場合、デフォルトの値は
.B patch
が \s-1POSIX\s0 準拠であれば 0 、そうでなければ負となる。
.TP
.B "\*=help"
オプションの要約を表示し、終了する。
.TP
\fB\-i\fP \fIpatchfile\fP  または  \fB\*=input=\fP\fIpatchfile\fP
パッチを
.I patchfile
から読み込む。
.I patchfile
が
.B \-
の場合は標準入力から読み込み、これがデフォルトである。
.TP
\fB\-l\fP  または  \fB\*=ignore\-whitespace\fP
タブやスペースが変更されている場合のために、パターンの一致をゆるく見る。
パッチファイル中の 1 個または複数の空白の並びは
オリジナルファイルの空白のどの並びにも一致し、
行末の空白の並びは無視される。
通常文字は完全に一致していなければならない。
コンテキストの各行はオリジナルファイルの 1 行に一致していなければならない。
.TP
\fB\-n\fP  または  \fB\*=normal\fP
パッチファイルをノーマル diff として解釈する。
.TP
\fB\-N\fP  または  \fB\*=forward\fP
反転していると思われるパッチやすでに適用済みと思われるパッチを無視する。
.B \-R
も参照。
.TP
\fB\-o\fP \fIoutfile\fP  または  \fB\*=output=\fP\fIoutfile\fP
ファイルにパッチを当てて置き換えるのではなく、
出力を
.I outfile
に送る。
.TP
\fB\-p\fP\fInum\fP  または  \fB\*=strip\fP\fB=\fP\fInum\fP
パッチファイルで見つかったファイル名それぞれについて、
.I num
個のスラッシュを含む最小のプレフィクスを取り除く。
隣接した 1 個または複数のスラッシュの並びは 1 個のスラッシュとして
数えられる。
このオプションは
パッチを送った人と異なるディレクトリにファイルを格納している場合のために、
パッチファイル中のファイル名の扱いを変更する。
例えば、パッチファイル中のファイル名が
.Sp
	\fB/u/howard/src/blurfl/blurfl.c\fP
.Sp
であったとすると、
.B \-p0
とするとファイル名全体が変更されずに用いられ、
.B \-p1
とすると
.Sp
	\fBu/howard/src/blurfl/blurfl.c\fP
.Sp
のように先頭のスラッシュが取り除かれ、
.B \-p4
とすると
.Sp
	\fBblurfl/blurfl.c\fP
.Sp
のようになり、
.B \-p
を指定しなければ \fBblurfl.c\fP となる。
最終的に参照されるディレクトリは
カレントディレクトリ、または
.B \-d
オプションで指定されたディレクトリである。
.TP
.B \*=posix
以下のようにより厳格に \s-1POSIX\s0 標準にしたがう。
.RS
.TP 3
.B " \(bu"
diff ヘッダから複数のファイル名が得られた場合、
リスト (old, new, index) のうち最初に存在したファイルを用いる。
.TP
.B " \(bu"
パッチを当てたあと空になったファイルを削除しない。
.TP
.B " \(bu"
\s-1RCS\s0, ClearCase, \s-1SCCS\s0 から
ファイルを取得するかどうかを尋ねない。
.TP
.B " \(bu"
コマンドラインではすべてのオプションがファイルの前になければならない。
.TP
.B " \(bu"
パッチが元のファイルにぴったり一致しない場合でも、
ファイルをバックアップしない。
.RE
.TP
.BI \*=quoting\-style= word
ファイル名を出力するのにスタイル
.I word
を使う。
.I word
は次のどれかでなければならない:
.RS
.TP
.B literal
ファイル名をそのまま出力する。
.TP
.B shell
ファイル名にシェルのメタキャラクタが含まれる場合や
曖昧な出力となってしまう場合、
ファイル名にシェル用の引用符を付ける。
.TP
.B shell-always
通常は引用符が必要でない場合にもシェル用の引用符を付ける。
.TP
.B c
C 言語文字列と同様にファイル名に引用符を付ける。
.TP
.B escape
.B c
と同じように引用符を付けるが、最初と最後のダブルクウォート文字を省略する。
.LP
.B \*=quoting\-style
オプションのデフォルト値は環境変数
.B QUOTING_STYLE
で指定することができる。
環境変数が設定されていない場合、デフォルト値は
.B shell
である。
.RE
.TP
\fB\-r\fP \fIrejectfile\fP  または  \fB\*=reject\-file=\fP\fIrejectfile\fP
reject ( 却下された hunk) を
デフォルトの
.B \&.rej
ファイルではなく
.I rejectfile
に出力する。
.TP
\fB\-R\fP  または  \fB\*=reverse\fP
このパッチは新旧のファイルが反転しているとみなす。
( まあ、ときどきある。人間のやることだから。 )
.B patch
はそれぞれの hunk を当てる前に反転させる。
reject ( 却下された hunk) も反転したあとの形式で出力される。
.B \-R
オプションは
.B ed
形式の diff スクリプトに対しては動作しない。
反対の操作をするには情報が少なすぎるからである。
.Sp
パッチの最初の hunk が失敗すると、
.B patch
は hunk を反転させて当たるかどうかをみる。
もし当たる場合、
.B \-R
オプションをセットするかどうかを尋ねる。
もし当たらない場合、通常の方法を継続する。
( 注意: この方法では、
ノーマル diff で最初のコマンドが追加の ( つまり、本来は削除であった ) 場合に
反転されたパッチを検出することができない。
それは、空のコンテキストはどこにでもマッチするために、
追加は常に成功するからである。
幸い、ほとんどのパッチは行を追加するか、変更するものであって、
削除するものは少ないため、
経験的にいって、反転したノーマル diff のほとんどは削除から始まっていて、
失敗してくれる。 )
.TP
\fB\-s\fP  または  \fB\*=silent\fP  または  \fB\*=quiet\fP
エラーが発生しない限り、静かに動作する。
.TP
\fB\-t\fP  または  \fB\*=batch\fP
.B \-f
と同様に質問を抑制する。
ただし、異なる仮定をする。
ヘッダにファイル名を含まないパッチはスキップし (\fB\-f\fP と同じ ) 、
ファイルのバージョンがパッチ中の
.B Prereq:\&
の行に書かれたバージョンと違うパッチはスキップし、
パッチが反転しているように見える場合は反転しているとみなす。
.TP
\fB\-T\fP  または  \fB\*=set\-time\fP
パッチを当てたあとのファイルの変更日時とアクセス日時を
コンテキスト diff ヘッダのタイムスタンプに設定する。
コンテキスト diff ヘッダはローカル時刻を使っているとみなす。
このオプションは推奨されない。
なぜならローカル時刻を使ったパッチは異なるタイムゾーンの人には
簡単に使えないから、
またローカルタイムスタンプは
サマータイムの調整で時刻が戻った場合に曖昧になるからである。
このオプションを使う代わりに、
\s-1UTC\s0 でパッチを生成し、
.B \-Z
または
.B \*=set\-utc
を使うこと。
.TP
\fB\-u\fP  または  \fB\*=unified\fP
パッチファイルを unified コンテキスト diff として解釈する。
.TP
\fB\-v\fP  または  \fB\*=version\fP
.B patch
のリビジョンヘッダとパッチレベルを出力し、終了する。
.TP
\fB\-V\fP \fImethod\fP  または  \fB\*=version\-control=\fP\fImethod\fP
バックアップファイルの名前を決定するのに
.I method
を使う。
method は
.B PATCH_VERSION_CONTROL
( または、それがない場合、
.BR VERSION_CONTROL )
環境変数で指定でき、このオプションで上書きされる。
method はバックアップファイルが作られるかどうかには影響せず、
作られるバックアップファイルの名前に影響するだけである。
.Sp
.I method
の値は \s-1GNU\s0 Emacs の `version-control' 変数と同様である。
.B patch
はもっと分かりやすい同義語も理解する。
.I method
の有効な値は次のとおりである
( 区別が付けば短縮形を用いてもよい ):
.RS
.TP 3
\fBexisting\fP  または  \fBnil\fP
番号付きのバックアップがある場合、バックアップに番号を付ける。
そうでない場合、簡易バックアップを作る。
これがデフォルトである。
.TP
\fBnumbered\fP  または  \fBt\fP
バックアップに番号を付ける。
.I F
というファイルに対する番号付きバックアップファイルの名前は
.IB F .~ N ~
のようになる。
.I N
はバージョン番号である。
.TP
\fBsimple\fP  または  \fBnever\fP
簡易バックアップを作る。
.B \-B
または
.BR \*=prefix 、
.B \-Y
または
.BR \*=basename\-prefix 、
.B \-z
または
.B \*=suffix
オプションで簡易バックアップファイルの名前が決まる。
これらのうちどのオプションも指定されない場合、
簡易バックアップサフィクスが使われる。
サフィクスは
.B SIMPLE_BACKUP_SUFFIX
環境変数が存在する場合はその値、そうでない場合は
.B \&.orig
である。
.PP
番号付きまたは簡易バックアップの場合、
バックアップファイルの名前が長すぎると、
代わりにバックアップサフィクス
.B ~
が使われる。
.B ~
を付加しても長すぎる場合、
ファイル名の最後の文字が
.B ~
に置き換えられる。
.RE
.TP
\fB\*=verbose\fP
処理が行なわれる様子について追加の情報を出力する。
.TP
\fB\-x\fP \fInum\fP  または  \fB\*=debug=\fP\fInum\fP
内部デバッグフラグを設定する。
.B patch
を変更する人にしか興味のないものである。
.TP
\fB\-Y\fP \fIpref\fP  または  \fB\*=basename\-prefix=\fP\fIpref\fP
簡易バックアップファイルの名前を生成するとき、
ファイル名のベースネームに
プレフィクス
.I pref
を付ける。
例えば、
.B "\-Y\ .del/"
とした場合、
.B src/patch/util.c
の簡易バックアップファイルの名前は
.B src/patch/.del/util.c
となる。
.TP
\fB\-z\fP \fIsuffix\fP  または  \fB\*=suffix=\fP\fIsuffix\fP
.I suffix
を簡易バックアップサフィクスとして使う。
例えば、
.B "\-z\ -"
とした場合、
.B src/patch/util.c
の簡易バックアップファイルの名前は
.B src/patch/util.c-
となる。
バックアップサフィクスは
.B SIMPLE_BACKUP_SUFFIX
環境変数で指定することができ、このオプションで上書きされる。
.TP
\fB\-Z\fP  または  \fB\*=set\-utc\fP
パッチを当てたあとのファイルの変更日時とアクセス日時を
コンテキスト diff ヘッダのタイムスタンプに設定する。
コンテキスト diff ヘッダは
世界協定時 (\s-1UTC\s0 、\s-1GMT\s0 としても知られる ) を
使っているとみなす。
.B \-T
または
.B \*=set\-time
オプションも参照すること。
.Sp
.B \-Z
または
.B \*=set\-utc
および
.B \-T
または
.B \*=set\-time
オプションは、通常はファイルのオリジナルの時刻が
パッチヘッダ中の時刻と一致しない場合や
内容がパッチとぴったり一致しない場合には、ファイルの時刻を設定しない。
しかし、
.B \-f
または
.B \*=force
オプションが指定された場合、ファイルの時刻は強制的に設定される。
.Sp
.B diff
の出力形式の制限のため、
これらのオプションでは
内容の変化しないファイルの時刻は更新されない。
また、これらのオプションを使った場合には、
パッチの当たったファイルに依存するファイルを削除して
( 例えば
.B "make\ clean"
で ) 、
あとで
.B make
を実行したときにパッチの当たったファイルの時刻で
混乱しないようにしなければならない。
.SH "環境変数"
.TP 3
.B PATCH_GET
.B patch
が存在しないファイルや読み取り専用のファイルをデフォルトで
\s-1RCS\s0, ClearCase, \s-1SCCS\s0 から取得するかどうかを指定する。
.B \-g
または
.B \*=get
オプションを参照。
.TP
.B POSIXLY_CORRECT
設定されている場合、
.B patch
はデフォルトで
\s-1POSIX\s0 標準により厳格に従う。
.B \*=posix
オプションを参照。
.TP
.B QUOTING_STYLE
.B \*=quoting\-style
オプションのデフォルトの値。
.TP
.B SIMPLE_BACKUP_SUFFIX
.B \&.orig
の代わりに簡易バックアップファイルの名前に使う拡張子。
.TP
\fBTMPDIR\fP, \fBTMP\fP, \fBTEMP\fP
一時ファイルを入れるディレクトリ
.B patch
はこのリストの中で最初に設定されている環境変数を使う。
どれも設定されていない場合、デフォルトはシステム依存である。
Unix ホストでは通常
.B /tmp
である。
.TP
\fBVERSION_CONTROL\fP または \fBPATCH_VERSION_CONTROL\fP
バージョンコントロールスタイルを選択する。
.B \-V
または
.B \*=version\-control
オプションを参照。
.SH "ファイル"
.TP 3
.IB $TMPDIR "/p\(**"
一時ファイル。
.TP
.B /dev/tty
制御端末。ユーザに尋ねた質問の答えを得るために使われる。
.SH "関連項目"
.BR diff (1),
.BR ed (1)
.Sp
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).
.SH "パッチを送る人への注意"
パッチを送ろうとする場合に心に留めておかなければならない点がいくつかある。
.PP
パッチを機械的に作ること。
よい方法は
.BI "diff\ \-Naur\ " "old\ new"
のようなコマンドを使うことである。
.I new
と
.I old
はそれぞれ新旧のディレクトリである。
.I old
と
.I new
には 1 個もスラッシュがあってはいけない。
.B diff
コマンドのヘッダに含まれる日時は伝統的な Unix 形式を使って
協定世界時で書かれていなければならない。
そうすれば
パッチを受け取った人が
.B \-Z
または
.B \*=set\-utc
オプションを使うことができる。
次のものは Bourne シェル形式を使ったコマンド例である:
.Sp
	\fBLC_ALL=C TZ=UTC0 diff \-Naur gcc\-2.7 gcc\-2.8\fP
.PP
受け取る人にはパッチの当て方を伝える。
つまり、どのディレクトリに
.B cd
すればよいかとどの
.B patch
オプションを使えばよいかを伝える。
オプション文字列は
.B "\-Np1"
が推奨される。
受け取った人になったつもりで手順を試し、
オリジナルファイルのコピーを取って、作ったパッチを当ててみる。
.PP
送り出すパッチファイルの最初の diff として、
パッチレベルをインクリメントしていく
.B patchlevel.h
ファイルを入れておくと、
多くの人の面倒を軽減できる。
パッチに
.B Prereq:\&
行を加えておけば、
順番を間違えて警告を食らうのを防ぐことができる。
.PP
.B /dev/null
や
日時が Epoch (1970-01-01 00:00:00 \s-1UTC\s0) の空のファイルと
作成したいファイルを比較した diff を送ることで、
ファイルを作成することができる。
この方法はターゲットのディレクトリに作成したいファイルが
まだ存在しない場合に限って動作する。
反対に、削除したいファイルと日時が Epoch の空のファイルを比較した
コンテキスト diff を送ることで、ファイルを削除することができる。
ファイルは
.B patch
が \s-1POSIX\s0 準拠でなく、
.B \-E
または
.B \*=remove\-empty\-files
オプションが指定されない場合に削除される。
ファイルを作成したり削除したりするパッチを生成する簡単な方法は、
\s-1GNU\s0
.B diff
の
.B \-N
または
.B \*=new\-file
オプションを使うことである。
.PP
受け取った人が
.BI \-p N
オプションを使うことが想定される場合、
次のようなパッチを送らないこと:
.Sp
.ft B
.ne 3
	diff \-Naur v2.0.29/prog/README prog/README
.br
	\-\^\-\^\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997
.br
	+\^+\^+ prog/README   Mon Mar 17 14:58:22 1997
.ft
.Sp
なぜなら二つのファイル名は異なる数のスラッシュを含んでおり、
.B patch
のバージョンによって
ファイル名を異なるように解釈するからである。
混乱を避けるために、代わりに次のようなパッチを送ること:
.Sp
.ft B
.ne 3
	diff \-Naur v2.0.29/prog/README v2.0.30/prog/README
.br
	\-\^\-\^\- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997
.br
	+\^+\^+ v2.0.30/prog/README   Mon Mar 17 14:58:22 1997
.ft
.Sp
.PP
バックアップファイルと名前が同じファイル、例えば
.B README.orig
と比較したパッチを送らないこと。
この方法では
.B patch
が混乱して、
正しいファイルではなく
バックアップファイルにパッチを当ててしまうかもしれないからである。
そうではなく、
ファイル名が同じで別のディレクトリにあるファイルどうし、例えば
.B old/README
と
.B new/README
を比較したパッチを送ること。
.PP
反転したパッチを送らないように注意すること。
もうパッチを当てたのかと思ってしまうからである。
.PP
自動生成されるファイル
( 例えば、 makefile に
.B "configure: configure.in"
という行がある場合の
.B configure
というファイル )
を変更するパッチを作らないようにすること。
受け取った人は自動生成されるファイルを再生成することができるからである。
自動生成されるファイルの diff を送らなければならない場合、
\s-1UTC\s0 を用いて diff を作り、
受け取った人に
.B \-Z
または
.B \*=set\-utc
オプションを使ってパッチを当ててもらい、
パッチの当たったファイルに依存する、
パッチの当たっていないファイルを削除してもらう
( 例えば
.B "make\ clean"
で ) 。
.PP
582 もの差分リストを 1 個のファイルに入れなくても済むのであれば、
ぐちゃぐちゃになってしまった場合に備えて
関連するパッチを別々のファイルにまとめておくのが賢明である。
.SH "エラーと終了ステータス"
エラーは一般に、
.B patch
がパッチファイルを解析できなかったことを示している。
.PP
.B \*=verbose
オプションを指定した場合、
.B Hmm.\|.\|.\&
はパッチファイルの中に処理されなかったテキストがあり、
.B patch
がテキストの中にパッチがあるかどうかを
必死に探そうとしていることを表している。
パッチが見つかると、そのパッチがどんな種類のものかを示す。
.PP
.B patch
の終了ステータスは、
すべての hunk の適用に成功した場合に 0 、
一部の hunk が適用できなかった場合に 1 、
もっと深刻な問題に見舞われた場合に 2 となる。
バッチ処理で複数のパッチを適用する場合、
終了ステータスをチェックして、
部分的にしかパッチの当たっていないファイルに
以降のパッチを当てないようにすることが必要である。
.SH "警告"
コンテキスト diff は空のファイルや空のディレクトリ、
シンボリックリンクなどのスペシャルファイルの作成や削除を
確実に表すことはできない。
所有者やアクセス権限、あるファイルが
別のファイルのハードリンクであることといった
ファイルメタデータの変更を表すこともできない。
もしそのような変更も必要であれば、
別に手順書 ( 例えば、シェルスクリプト ) を用意して、
パッチに添付しなければならない。
.PP
.B patch
は、
.B ed
スクリプト中の行番号がはみ出しているかどうかは分からないし、
ノーマル diff の行番号の間違いは
変更や削除を見つけた場合に限って検出できる。
fuzz factor が 3 のコンテキスト diff も同じ問題に遭遇するかもしれない。
適当な対話式のインタフェースが導入されるまでは、
このような場合はコンテキスト diff を作って
変更が妥当かどうかを確認しなければならない。
もちろん、エラーなくコンパイルできたことは
パッチがうまく当たったよい証拠になるが、必ずしもそうとはいえない。
.PP
.B patch
は多数の推測が必要な場合であっても、通常は正しい結果を出す。
しかし、結果が正しいことが保証されるのは、
そのパッチが生成されたファイルと全く同一のバージョンの
ファイルに適用された場合だけである。
.SH "互換性の問題"
\s-1POSIX\s0 標準は
.B patch
の古典的な振る舞いと異なる振る舞いを規定している。
.B patch
のバージョン 2.1 およびそれ以前 ( これらは \s-1POSIX\s0 に
準拠していない ) と
相互に運用しなければならない場合、これらの違いを知っておく必要がある。
.TP 3
.B " \(bu"
古典的な
.B patch
では、
.B \-p
オプションの引数は省略可能であり、単独の
.B \-p
は
.B \-p0
と同等であった。
今日の
.B patch
では
.B \-p
オプションに引数が必須で、
.B "\-p\ 0"
が
.B \-p0
と同等である。
互換性を最大限に保つために、
.B \-p0
や
.B \-p1
といったオプションを使う。
.Sp
また、古典的な
.B patch
はパスプレフィクスを取り除く際、スラッシュの数を単純に数えていた。
今日の
.B patch
はパス名の要素を数える。
つまり、 1 個または複数の隣接するスラッシュの列は
1 個のスラッシュとして数えられる。
互換性を最大限に保つために、
ファイル名に
.B //
を含むパッチは送らないようにすること。
.TP
.B " \(bu"
古典的な
.B patch
では、デフォルトでバックアップが有効であった。
今日の
.B patch
では
.B \-b
または
.B \*=backup
オプションで有効になる。
.Sp
反対に、 \s-1POSIX\s0
.B patch
では、不整合があってもバックアップは一切作られない。
\s-1GNU\s0
.B patch
では、この振る舞いは
.B \*=no\-backup\-if\-mismatch
オプションか、
.B \*=posix
オプションまたは
.B POSIXLY_CORRECT
環境変数で \s-1POSIX\s0 準拠にするかで有効になる。
.Sp
古典的な
.B patch
の
.BI \-b "\ suffix"
オプションは
\s-1GNU\s0
.B patch
の
.BI "\-b\ \-z" "\ suffix"
オプションと同等である。
.TP
.B " \(bu"
古典的な
.B patch
は、
パッチヘッダからパッチを当てるファイルの名前を決定するのに
複雑な ( しかも完全にはドキュメントになっていない ) 手法を用いていた。
この手法は \s-1POSIX\s0 に準拠しておらず、いくつか誤りもあった。
今日の
.B patch
は異なる、同じくらい複雑な (しかしドキュメントはましな) 手法を用いており、
オプションで \s-1POSIX\s0 に準拠することができる。
誤りが減っているとよいのだが。
2 つの手法は、
コンテキスト diff のヘッダのファイル名と
.B Index:\&
の行がプレフィクスを除いて全く同じである場合には互換性がある。
作ったパッチは、
それぞれのヘッダのファイル名がすべて同じ数のスラッシュを含んでいれば、
通常は互換性がある。
.TP
.B " \(bu"
古典的な
.B patch
がユーザに質問をするときは、
質問を標準エラーに出力し、
以下のリストのうちターミナルである最初のファイルから回答を求める:
標準エラー、標準出力、
.BR /dev/tty 、
標準入力。
今日の
.B patch
は質問は標準出力に出力し、
.B /dev/tty
から回答を得る。
回答のデフォルトのうちいくつかは変更されており、
デフォルトの回答を使っても
.B patch
が無限ループに陥らないようになっている。
.TP
.B " \(bu"
古典的な
.B patch
は、失敗した hunk の数をステータス値として終了し、
本当の問題に出くわした場合は 1 をステータス値としていた。
今日の
.B patch
は hunk が失敗すると 1 で終了し、問題がある場合は 2 で終了する。
.TP
.B " \(bu"
\s-1GNU\s0
.BR patch 、
古典的
.BR patch 、
\s-1POSIX\s0 準拠の
.B patch
のどれを使うか分からない人に宛てて手順を送る場合、
次のオプション以外は使わないこと。
以下のリストでは空白も意味を持ち、引数は必須である。
.Sp
.nf
.in +3
.ne 11
.B \-c
.BI \-d " dir"
.BI \-D " define"
.B \-e
.B \-l
.B \-n
.B \-N
.BI \-o " outfile"
.BI \-p num
.B \-R
.BI \-r " rejectfile"
.in
.fi
.SH "バグ"
バグは電子メールで
.B <bug-gnu-utils@gnu.org>
へ報告してください。
.PP
.B patch
は部分一致や大きく逸脱したオフセットやひっくり返ったコードに対して
もっと賢くすることもできるだろうが、その道は長いだろう。
.PP
コードが重複している場合 ( 例えば
\fB#ifdef OLDCODE\fP .\|.\|. \fB#else .\|.\|. #endif\fP
のように区切られている場合 ) 、
.B patch
は両方のバージョンにパッチを当てることはできない。
もしパッチが当たったとしたら、
間違ったほうにパッチが当たってしまっていることもよくあり、
それでも成功したから続きをやれというだろう。
.PP
すでに当たっているパッチを当てようとすると、
.B patch
はパッチが反転していると思い、パッチを戻すかを尋ねる。
これは機能のひとつとみなすことができよう。
.SH "著作権"
Copyright
.if t \(co
1984, 1985, 1986, 1988 Larry Wall.
.br
Copyright
.if t \(co
1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998
Free Software Foundation, Inc.
.PP
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.
.PP
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.
.PP
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.
.SH "著者"
オリジナルの
.B patch
は Larry Wall が書いた。
Paul Eggert は恣意的な制限を取り除き、
バイナリファイルへの対応や、ファイルの時刻設定、ファイルの削除を追加した。
また、より \s-1POSIX\s0 に準拠するようにした。
ほかには Wayne Davison が unidiff への対応を追加し、
David MacKenzie がコンフィグレーションとバックアップへの対応を追加した。