1PATCH(1)                    General Commands Manual                   PATCH(1)
2
3
4

NAME

6       patch - apply a diff file to an original
7

SYNOPSIS

9       patch [options] [originalfile [patchfile]]
10
11       but usually just
12
13       patch -pnum <patchfile
14

DESCRIPTION

16       patch takes a patch file patchfile containing a difference listing pro‐
17       duced by the diff program and applies those differences to one or  more
18       original  files, producing patched versions.  Normally the patched ver‐
19       sions are put in place of the originals.  Backups can be made; see  the
20       -b  or  --backup option.  The names of the files to be patched are usu‐
21       ally taken from the patch file, but if there's  just  one  file  to  be
22       patched it can be specified on the command line as originalfile.
23
24       Upon startup, patch attempts to determine the type of the diff listing,
25       unless overruled by a -c (--context), -e (--ed), -n (--normal),  or  -u
26       (--unified)  option.  Context diffs (old-style, new-style, and unified)
27       and normal diffs are applied by the  patch  program  itself,  while  ed
28       diffs are simply fed to the ed(1) editor via a pipe.
29
30       patch  tries to skip any leading garbage, apply the diff, and then skip
31       any trailing garbage.  Thus you could feed an article or  message  con‐
32       taining  a  diff  listing  to patch, and it should work.  If the entire
33       diff is indented by a consistent amount, if lines end in CRLF, or if  a
34       diff  is  encapsulated  one  or  more times by prepending "- " to lines
35       starting with "-" as specified by Internet RFC 934, this is taken  into
36       account.   After  removing  indenting or encapsulation, lines beginning
37       with # are ignored, as they are considered to be comments.
38
39       With context diffs, and to a lesser extent with normal diffs, patch can
40       detect  when the line numbers mentioned in the patch are incorrect, and
41       attempts to find the correct place to apply each hunk of the patch.  As
42       a first guess, it takes the line number mentioned for the hunk, plus or
43       minus any offset used in applying the previous hunk.  If  that  is  not
44       the correct place, patch scans both forwards and backwards for a set of
45       lines matching the context given in the hunk.  First patch looks for  a
46       place where all lines of the context match.  If no such place is found,
47       and it's a context diff, and the maximum fuzz factor is  set  to  1  or
48       more, then another scan takes place ignoring the first and last line of
49       context.  If that fails, and the maximum fuzz factor is  set  to  2  or
50       more,  the  first  two  and  last two lines of context are ignored, and
51       another scan is made.  (The default maximum fuzz factor is 2.)
52
53       Hunks with less prefix context  than  suffix  context  (after  applying
54       fuzz)  must  apply  at the start of the file if their first line number
55       is 1.  Hunks with more prefix context than suffix context (after apply‐
56       ing fuzz) must apply at the end of the file.
57
58       If patch cannot find a place to install that hunk of the patch, it puts
59       the hunk out to a reject file, which normally is the name of the output
60       file  plus  a .rej suffix, or # if .rej would generate a file name that
61       is too long (if even appending the single character #  makes  the  file
62       name too long, then # replaces the file name's last character).
63
64       The  rejected hunk comes out in unified or context diff format.  If the
65       input was a normal diff, many of the contexts  are  simply  null.   The
66       line  numbers  on the hunks in the reject file may be different than in
67       the patch file: they reflect the approximate location patch thinks  the
68       failed hunks belong in the new file rather than the old one.
69
70       As  each  hunk is completed, you are told if the hunk failed, and if so
71       which line (in the new file) patch thought the hunk should go  on.   If
72       the  hunk  is installed at a different line from the line number speci‐
73       fied in the diff, you are told the offset.  A single large  offset  may
74       indicate  that  a  hunk was installed in the wrong place.  You are also
75       told if a fuzz factor was used to make the match,  in  which  case  you
76       should  also be slightly suspicious.  If the --verbose option is given,
77       you are also told about hunks that match exactly.
78
79       If no original file origfile is specified on the  command  line,  patch
80       tries  to figure out from the leading garbage what the name of the file
81       to edit is, using the following rules.
82
83       First, patch takes an ordered list of candidate file names as follows:
84
85        · If the header is that of a context diff, patch takes the old and new
86          file  names  in  the  header.  A name is ignored if it does not have
87          enough slashes to satisfy the -pnum or --strip=num option.  The name
88          /dev/null is also ignored.
89
90        · If  there is an Index: line in the leading garbage and if either the
91          old and new names are both absent  or  if  patch  is  conforming  to
92          POSIX, patch takes the name in the Index: line.
93
94        · For the purpose of the following rules, the candidate file names are
95          considered to be in the order (old, new, index), regardless  of  the
96          order that they appear in the header.
97
98       Then patch selects a file name from the candidate list as follows:
99
100        · If  some  of  the named files exist, patch selects the first name if
101          conforming to POSIX, and the best name otherwise.
102
103        · If patch is not ignoring RCS, ClearCase, Perforce, and SCCS (see the
104          -g num  or  --get=num  option), and no named files exist but an RCS,
105          ClearCase, Perforce, or SCCS master  is  found,  patch  selects  the
106          first named file with an RCS, ClearCase, Perforce, or SCCS master.
107
108        · If no named files exist, no RCS, ClearCase, Perforce, or SCCS master
109          was found, some names are given, patch is not conforming  to  POSIX,
110          and  the patch appears to create a file, patch selects the best name
111          requiring the creation of the fewest directories.
112
113        · If no file name results from the above heuristics, you are asked for
114          the name of the file to patch, and patch selects that name.
115
116       To  determine  the  best  of a nonempty list of file names, patch first
117       takes all the names with the fewest path name components; of those,  it
118       then  takes all the names with the shortest basename; of those, it then
119       takes all the shortest names; finally, it  takes  the  first  remaining
120       name.
121
122       Additionally,  if  the  leading  garbage contains a Prereq: line, patch
123       takes the first word from the prerequisites line  (normally  a  version
124       number)  and checks the original file to see if that word can be found.
125       If not, patch asks for confirmation before proceeding.
126
127       The upshot of all this is that you should be able to say,  while  in  a
128       news interface, something like the following:
129
130          | patch -d /usr/src/local/blurfl
131
132       and patch a file in the blurfl directory directly from the article con‐
133       taining the patch.
134
135       If the patch file contains more than one patch, patch  tries  to  apply
136       each  of  them  as if they came from separate patch files.  This means,
137       among other things, that it is assumed that the name  of  the  file  to
138       patch  must  be  determined for each diff listing, and that the garbage
139       before each diff listing contains interesting things such as file names
140       and revision level, as mentioned previously.
141

OPTIONS

143       -b  or  --backup
144          Make  backup  files.   That is, when patching a file, rename or copy
145          the original instead of removing it.  When backing up  a  file  that
146          does  not  exist,  an  empty, unreadable backup file is created as a
147          placeholder to represent the nonexistent file.  See the -V or --ver‐
148          sion-control  option  for  details  about  how backup file names are
149          determined.
150
151       --backup-if-mismatch
152          Back up a file if the patch does not match the file exactly  and  if
153          backups  are  not  otherwise  requested.  This is the default unless
154          patch is conforming to POSIX.
155
156       --no-backup-if-mismatch
157          Do not back up a file if the patch does not match the  file  exactly
158          and  if backups are not otherwise requested.  This is the default if
159          patch is conforming to POSIX.
160
161       -B pref  or  --prefix=pref
162          Use the simple method to determine backup file  names  (see  the  -V
163          method  or  --version-control  method  option), and append pref to a
164          file name when generating its backup file name.  For  example,  with
165          -B /junk/  the  simple  backup  file  name  for  src/patch/util.c is
166          /junk/src/patch/util.c.
167
168       --binary
169          Write all files in binary  mode,  except  for  standard  output  and
170          /dev/tty.  When reading, disable the heuristic for transforming CRLF
171          line endings into LF line endings.  This option is needed  on  POSIX
172          systems when applying patches generated on non-POSIX systems to non-
173          POSIX files.  (On POSIX systems, file reads and writes never  trans‐
174          form  line  endings.  On Windows, reads and writes do transform line
175          endings by default, and patches should be generated by diff --binary
176          when line endings are significant.)
177
178       -c  or  --context
179          Interpret the patch file as a ordinary context diff.
180
181       -d dir  or  --directory=dir
182          Change to the directory dir immediately, before doing anything else.
183
184       -D define  or  --ifdef=define
185          Use  the #ifdef ... #endif construct to mark changes, with define as
186          the differentiating symbol.
187
188       --dry-run
189          Print the results of applying the patches without actually  changing
190          any files.
191
192       -e  or  --ed
193          Interpret the patch file as an ed script.
194
195       -E  or  --remove-empty-files
196          Remove  output  files  that  are  empty  after the patches have been
197          applied.  Normally this option is unnecessary, since patch can exam‐
198          ine the time stamps on the header to determine whether a file should
199          exist after patching.  However, if the input is not a  context  diff
200          or  if  patch  is  conforming  to POSIX, patch does not remove empty
201          patched files unless this option is given.   When  patch  removes  a
202          file, it also attempts to remove any empty ancestor directories.
203
204       -f  or  --force
205          Assume  that  the user knows exactly what he or she is doing, and do
206          not ask any questions.  Skip patches whose headers do not say  which
207          file  is  to be patched; patch files even though they have the wrong
208          version for the Prereq: line in the patch; and assume  that  patches
209          are  not reversed even if they look like they are.  This option does
210          not suppress commentary; use -s for that.
211
212       -F num  or  --fuzz=num
213          Set the maximum fuzz factor.  This option only applies to diffs that
214          have  context,  and  causes patch to ignore up to that many lines of
215          context in looking for places to install a hunk.  Note that a larger
216          fuzz  factor increases the odds of a faulty patch.  The default fuzz
217          factor is 2.  A fuzz factor greater than or equal to the  number  of
218          lines of context in the context diff, ordinarily 3, ignores all con‐
219          text.
220
221       -g num  or  --get=num
222          This option controls patch's actions when a file  is  under  RCS  or
223          SCCS  control,  and  does  not exist or is read-only and matches the
224          default version, or when a file is under ClearCase or Perforce  con‐
225          trol  and does not exist.  If num is positive, patch gets (or checks
226          out) the file from the  revision  control  system;  if  zero,  patch
227          ignores  RCS,  ClearCase,  Perforce,  and  SCCS and does not get the
228          file; and if negative, patch asks the user whether to get the  file.
229          The  default  value  of  this  option  is  given by the value of the
230          PATCH_GET environment variable if it is set;  if  not,  the  default
231          value is zero.
232
233       --help
234          Print a summary of options and exit.
235
236       -i patchfile  or  --input=patchfile
237          Read  the  patch from patchfile.  If patchfile is -, read from stan‐
238          dard input, the default.
239
240       -l  or  --ignore-whitespace
241          Match patterns loosely, in case tabs or spaces have been  munged  in
242          your  files.   Any  sequence of one or more blanks in the patch file
243          matches any sequence in the original file, and sequences  of  blanks
244          at  the  ends  of  lines  are ignored.  Normal characters must still
245          match exactly.  Each line of the context must still match a line  in
246          the original file.
247
248       --merge or --merge=merge or --merge=diff3
249          Merge  a  patch  file into the original files similar to diff3(1) or
250          merge(1).  If a conflict is  found,  patch  outputs  a  warning  and
251          brackets  the  conflict  with  <<<<<<< and >>>>>>> lines.  A typical
252          conflict will look like this:
253
254              <<<<<<<
255              lines from the original file
256              |||||||
257              original lines from the patch
258              =======
259              new lines from the patch
260              >>>>>>>
261
262          The optional argument of --merge determines the  output  format  for
263          conflicts: the diff3 format shows the ||||||| section with the orig‐
264          inal lines from the patch; in the  merge  format,  this  section  is
265          missing.  The merge format is the default.
266
267          This  option  implies  --forward  and  does  not take the --fuzz=num
268          option into account.
269
270       -n  or  --normal
271          Interpret the patch file as a normal diff.
272
273       -N  or  --forward
274          Ignore patches that seem to be reversed or already  applied.  It  is
275          only checked if the first hunk of a patch can be reversed.  See also
276          -R.
277
278       -o outfile  or  --output=outfile
279          Send output to outfile instead of patching files in place.   Do  not
280          use  this option if outfile is one of the files to be patched.  When
281          outfile is -, send output to standard output, and send any  messages
282          that would usually go to standard output to standard error.
283
284       -pnum  or  --strip=num
285          Strip  the  smallest prefix containing num leading slashes from each
286          file name found in the patch file.  A sequence of one or more  adja‐
287          cent  slashes  is counted as a single slash.  This controls how file
288          names found in the patch file are treated, in  case  you  keep  your
289          files  in  a  different  directory  than the person who sent out the
290          patch.  For example, supposing the file name in the patch file was
291
292             /u/howard/src/blurfl/blurfl.c
293
294          setting -p0 gives the entire file name unmodified, -p1 gives
295
296             u/howard/src/blurfl/blurfl.c
297
298          without the leading slash, -p4 gives
299
300             blurfl/blurfl.c
301
302          and not specifying -p at all just gives you blurfl.c.  Whatever  you
303          end  up  with  is looked for either in the current directory, or the
304          directory specified by the -d option.
305
306       --posix
307          Conform more strictly to the POSIX standard, as follows.
308
309           · Take the first existing file from the list (old, new, index) when
310             intuiting file names from diff headers.
311
312           · Do not remove files that are empty after patching.
313
314           · Do not ask whether to get files from RCS, ClearCase, Perforce, or
315             SCCS.
316
317           · Require that all options precede the files in the command line.
318
319           · Do not backup files when there is a mismatch.
320
321       --quoting-style=word
322          Use style word to quote output names.  The word should be one of the
323          following:
324
325          literal
326                 Output names as-is.
327
328          shell  Quote  names  for the shell if they contain shell metacharac‐
329                 ters or would cause ambiguous output.
330
331          shell-always
332                 Quote names for the shell, even if they  would  normally  not
333                 require quoting.
334
335          c      Quote names as for a C language string.
336
337          escape Quote  as  with  c  except  omit the surrounding double-quote
338                 characters.
339
340          You can specify the default value of the --quoting-style option with
341          the  environment  variable QUOTING_STYLE.  If that environment vari‐
342          able is not set, the default value is shell.
343
344       -r rejectfile  or  --reject-file=rejectfile
345          Put rejects into rejectfile instead of the default .rej file.   When
346          rejectfile is -, discard rejects.
347
348       -R  or  --reverse
349          Assume  that  this  patch  was  created  with  the old and new files
350          swapped.  (Yes, I'm afraid  that  does  happen  occasionally,  human
351          nature  being  what it is.)  patch attempts to swap each hunk around
352          before applying it.  Rejects come out in the swapped format.  The -R
353          option  does not work with ed diff scripts because there is too lit‐
354          tle information to reconstruct the reverse operation.
355
356          If the first hunk of a patch fails, patch reverses the hunk  to  see
357          if it can be applied that way.  If it can, you are asked if you want
358          to have the -R option set.  If it can't, the patch continues  to  be
359          applied normally.  (Note: this method cannot detect a reversed patch
360          if it is a normal diff and if the first command is an  append  (i.e.
361          it  should  have been a delete) since appends always succeed, due to
362          the fact that  a  null  context  matches  anywhere.   Luckily,  most
363          patches  add  or  change  lines  rather  than  delete  them, so most
364          reversed normal diffs begin with a delete, which  fails,  triggering
365          the heuristic.)
366
367       --read-only=behavior
368          Behave  as  requested when trying to modify a read-only file: ignore
369          the potential problem, warn about it (the default), or fail.
370
371       --reject-format=format
372          Produce reject files in the specified format (either context or uni‐
373          fied).  Without this option, rejected hunks come out in unified diff
374          format if the input patch was of that format, otherwise in  ordinary
375          context diff form.
376
377       -s  or  --silent  or  --quiet
378          Work silently, unless an error occurs.
379
380       --follow-symlinks
381          When  looking  for input files, follow symbolic links.  Replaces the
382          symbolic links, instead of modifying the files  the  symbolic  links
383          point to.  Git-style patches to symbolic links will no longer apply.
384          This option exists for backwards compatibility  with  previous  ver‐
385          sions of patch; its use is discouraged.
386
387       -t  or  --batch
388          Suppress  questions  like  -f,  but make some different assumptions:
389          skip patches whose headers do not contain file names  (the  same  as
390          -f);  skip  patches for which the file has the wrong version for the
391          Prereq: line in the patch; and assume that patches are  reversed  if
392          they look like they are.
393
394       -T  or  --set-time
395          Set  the  modification  and  access times of patched files from time
396          stamps given in context diff headers.  Unless specified in the  time
397          stamps, assume that the context diff headers use local time.
398
399          Use  of  this option with time stamps that do not include time zones
400          is not recommended, because patches using local time  cannot  easily
401          be used by people in other time zones, and because local time stamps
402          are ambiguous when local clocks move backwards during  daylight-sav‐
403          ing  time  adjustments.   Make  sure  that  time stamps include time
404          zones, or generate patches with UTC and  use  the  -Z  or  --set-utc
405          option instead.
406
407       -u  or  --unified
408          Interpret the patch file as a unified context diff.
409
410       -v  or  --version
411          Print out patch's revision header and patch level, and exit.
412
413       -V method  or  --version-control=method
414          Use  method  to determine backup file names.  The method can also be
415          given by the PATCH_VERSION_CONTROL (or, if that's not set, the  VER‐
416          SION_CONTROL)  environment  variable,  which  is  overridden by this
417          option.  The method does not affect whether backup files  are  made;
418          it affects only the names of any backup files that are made.
419
420          The  value  of  method is like the GNU Emacs `version-control' vari‐
421          able; patch also recognizes synonyms that are more descriptive.  The
422          valid values for method are (unique abbreviations are accepted):
423
424          existing  or  nil
425             Make  numbered backups of files that already have them, otherwise
426             simple backups.  This is the default.
427
428          numbered  or  t
429             Make numbered backups.  The numbered backup file name  for  F  is
430             F.~N~ where N is the version number.
431
432          simple  or  never
433             Make  simple  backups.  The -B or --prefix, -Y or --basename-pre‐
434             fix, and -z or --suffix options specify the  simple  backup  file
435             name.   If  none of these options are given, then a simple backup
436             suffix is used; it is the value of the SIMPLE_BACKUP_SUFFIX envi‐
437             ronment variable if set, and is .orig otherwise.
438
439          With  numbered  or  simple  backups,  if the backup file name is too
440          long, the backup suffix ~ is used instead; if even appending ~ would
441          make  the  name  too long, then ~ replaces the last character of the
442          file name.
443
444       --verbose
445          Output extra information about the work being done.
446
447       -x num  or  --debug=num
448          Set internal debugging flags of interest only to patch patchers.
449
450       -Y pref  or  --basename-prefix=pref
451          Use the simple method to determine backup file  names  (see  the  -V
452          method  or  --version-control method option), and prefix pref to the
453          basename of a file name when generating its backup file  name.   For
454          example,   with   -Y .del/   the   simple   backup   file  name  for
455          src/patch/util.c is src/patch/.del/util.c.
456
457       -z suffix  or  --suffix=suffix
458          Use the simple method to determine backup file  names  (see  the  -V
459          method  or  --version-control  method option), and use suffix as the
460          suffix.   For  example,  with  -z -  the  backup   file   name   for
461          src/patch/util.c is src/patch/util.c-.
462
463       -Z  or  --set-utc
464          Set  the  modification  and  access times of patched files from time
465          stamps given in context diff headers. Unless specified in  the  time
466          stamps, assume that the context diff headers use Coordinated Univer‐
467          sal Time (UTC, often known as GMT).  Also see the -T  or  --set-time
468          option.
469
470          The  -Z  or  --set-utc and -T or --set-time options normally refrain
471          from setting a file's time if the  file's  original  time  does  not
472          match  the time given in the patch header, or if its contents do not
473          match the patch exactly.  However, if the -f or  --force  option  is
474          given, the file time is set regardless.
475
476          Due  to  the limitations of diff output format, these options cannot
477          update the times of files whose contents have not changed.  Also, if
478          you  use these options, you should remove (e.g. with make clean) all
479          files that depend on the patched files, so that later invocations of
480          make do not get confused by the patched files' times.
481

ENVIRONMENT

483       PATCH_GET
484          This  specifies  whether  patch gets missing or read-only files from
485          RCS, ClearCase, Perforce, or SCCS by default; see the  -g  or  --get
486          option.
487
488       POSIXLY_CORRECT
489          If  set,  patch  conforms  more  strictly  to  the POSIX standard by
490          default: see the --posix option.
491
492       QUOTING_STYLE
493          Default value of the --quoting-style option.
494
495       SIMPLE_BACKUP_SUFFIX
496          Extension to use for simple backup file names instead of .orig.
497
498       TMPDIR, TMP, TEMP
499          Directory to put temporary files in; patch uses the  first  environ‐
500          ment  variable  in  this  list  that  is  set.  If none are set, the
501          default is system-dependent; it is normally /tmp on Unix hosts.
502
503       VERSION_CONTROL or PATCH_VERSION_CONTROL
504          Selects version control  style;  see  the  -v  or  --version-control
505          option.
506

FILES

508       $TMPDIR/p*
509          temporary files
510
511       /dev/tty
512          controlling  terminal; used to get answers to questions asked of the
513          user
514

SEE ALSO

516       diff(1), ed(1), merge(1).
517
518       Marshall T. Rose and Einar A. Stefferud, Proposed Standard for  Message
519       Encapsulation,     Internet    RFC    934    <URL:ftp://ftp.isi.edu/in-
520       notes/rfc934.txt> (1985-01).
521

NOTES FOR PATCH SENDERS

523       There are several things you should bear in mind if you are going to be
524       sending out patches.
525
526       Create  your  patch  systematically.   A  good  method  is  the command
527       diff -Naur old new where old and new identify the old and new  directo‐
528       ries.   The names old and new should not contain any slashes.  The diff
529       command's headers should have dates and times in Universal  Time  using
530       traditional  Unix  format,  so  that patch recipients can use the -Z or
531       --set-utc option.  Here is an example command, using Bourne shell  syn‐
532       tax:
533
534          LC_ALL=C TZ=UTC0 diff -Naur gcc-2.7 gcc-2.8
535
536       Tell  your  recipients  how  to  apply  the patch by telling them which
537       directory to cd to, and which patch options to use.  The option  string
538       -Np1 is recommended.  Test your procedure by pretending to be a recipi‐
539       ent and applying your patch to a copy of the original files.
540
541       You can save people a lot of grief by keeping a patchlevel.h file which
542       is  patched to increment the patch level as the first diff in the patch
543       file you send out.  If you put a Prereq: line in  with  the  patch,  it
544       won't let them apply patches out of order without some warning.
545
546       You  can create a file by sending out a diff that compares /dev/null or
547       an empty file dated the Epoch (1970-01-01 00:00:00 UTC) to the file you
548       want to create.  This only works if the file you want to create doesn't
549       exist already in the target directory.  Conversely, you  can  remove  a
550       file by sending out a context diff that compares the file to be deleted
551       with an empty file dated the Epoch.  The file will  be  removed  unless
552       patch  is conforming to POSIX and the -E or --remove-empty-files option
553       is not given.  An easy way to generate patches that create  and  remove
554       files is to use GNU diff's -N or --new-file option.
555
556       If  the recipient is supposed to use the -pN option, do not send output
557       that looks like this:
558
559          diff -Naur v2.0.29/prog/README prog/README
560          --- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997
561          +++ prog/README   Mon Mar 17 14:58:22 1997
562
563       because the two file names have different numbers of slashes, and  dif‐
564       ferent  versions  of  patch  interpret  the file names differently.  To
565       avoid confusion, send output that looks like this instead:
566
567          diff -Naur v2.0.29/prog/README v2.0.30/prog/README
568          --- v2.0.29/prog/README   Mon Mar 10 15:13:12 1997
569          +++ v2.0.30/prog/README   Mon Mar 17 14:58:22 1997
570
571
572       Avoid sending patches that compare backup file names like  README.orig,
573       since  this  might confuse patch into patching a backup file instead of
574       the real file.  Instead, send patches that compare the same  base  file
575       names in different directories, e.g. old/README and new/README.
576
577       Take  care not to send out reversed patches, since it makes people won‐
578       der whether they already applied the patch.
579
580       Try not to have your patch modify derived files (e.g. the file  config‐
581       ure  where  there  is a line configure: configure.in in your makefile),
582       since the recipient should be able to regenerate the derived files any‐
583       way.  If you must send diffs of derived files, generate the diffs using
584       UTC, have the recipients apply the  patch  with  the  -Z  or  --set-utc
585       option, and have them remove any unpatched files that depend on patched
586       files (e.g. with make clean).
587
588       While you may be able to get away with putting 582 diff  listings  into
589       one  file, it may be wiser to group related patches into separate files
590       in case something goes haywire.
591

DIAGNOSTICS

593       Diagnostics generally indicate that patch  couldn't  parse  your  patch
594       file.
595
596       If  the  --verbose  option  is given, the message Hmm... indicates that
597       there is unprocessed text in the patch file and that patch is  attempt‐
598       ing  to  intuit  whether there is a patch in that text and, if so, what
599       kind of patch it is.
600
601       patch's exit status is 0 if all hunks are applied  successfully,  1  if
602       some  hunks  cannot  be applied or there were merge conflicts, and 2 if
603       there is more serious trouble.  When applying a set  of  patches  in  a
604       loop  it  behooves  you  to check this exit status so you don't apply a
605       later patch to a partially patched file.
606

CAVEATS

608       Context diffs cannot reliably represent the  creation  or  deletion  of
609       empty  files,  empty  directories,  or  special  files such as symbolic
610       links.  Nor can they represent changes to file metadata like ownership,
611       permissions, or whether one file is a hard link to another.  If changes
612       like these are also  required,  separate  instructions  (e.g.  a  shell
613       script) to accomplish them should accompany the patch.
614
615       patch  cannot tell if the line numbers are off in an ed script, and can
616       detect bad line numbers in a normal diff only when it finds a change or
617       deletion.   A  context diff using fuzz factor 3 may have the same prob‐
618       lem.  You should probably do a context diff in these cases  to  see  if
619       the  changes  made  sense.   Of  course,  compiling without errors is a
620       pretty good indication that the patch worked, but not always.
621
622       patch usually produces the correct results, even when it has  to  do  a
623       lot  of  guessing.   However,  the results are guaranteed to be correct
624       only when the patch is applied to exactly the same version of the  file
625       that the patch was generated from.
626

COMPATIBILITY ISSUES

628       The  POSIX standard specifies behavior that differs from patch's tradi‐
629       tional behavior.  You should be aware of these differences if you  must
630       interoperate  with patch versions 2.1 and earlier, which do not conform
631       to POSIX.
632
633        · In traditional patch, the -p option's operand was  optional,  and  a
634          bare  -p was equivalent to -p0.  The -p option now requires an oper‐
635          and, and -p 0 is now equivalent to -p0.  For maximum  compatibility,
636          use options like -p0 and -p1.
637
638          Also,  traditional  patch simply counted slashes when stripping path
639          prefixes; patch now counts pathname components.  That is, a sequence
640          of  one  or more adjacent slashes now counts as a single slash.  For
641          maximum portability, avoid sending patches  containing  //  in  file
642          names.
643
644        · In  traditional patch, backups were enabled by default.  This behav‐
645          ior is now enabled with the -b or --backup option.
646
647          Conversely, in POSIX patch, backups are never made, even when  there
648          is  a  mismatch.   In  GNU  patch, this behavior is enabled with the
649          --no-backup-if-mismatch option, or by conforming to POSIX  with  the
650          --posix  option  or by setting the POSIXLY_CORRECT environment vari‐
651          able.
652
653          The -b suffix option of  traditional  patch  is  equivalent  to  the
654          -b -z suffix options of GNU patch.
655
656        · Traditional  patch  used a complicated (and incompletely documented)
657          method to intuit the name of the file to be patched from  the  patch
658          header.   This  method  did  not  conform  to  POSIX,  and had a few
659          gotchas.  Now patch uses a different, equally complicated (but  bet‐
660          ter  documented) method that is optionally POSIX-conforming; we hope
661          it has fewer gotchas.  The two methods are compatible  if  the  file
662          names in the context diff header and the Index: line are all identi‐
663          cal after prefix-stripping.  Your patch is  normally  compatible  if
664          each header's file names all contain the same number of slashes.
665
666        · When  traditional patch asked the user a question, it sent the ques‐
667          tion to standard error and looked for an answer from the first  file
668          in  the following list that was a terminal: standard error, standard
669          output, /dev/tty, and standard input.  Now patch sends questions  to
670          standard  output  and gets answers from /dev/tty.  Defaults for some
671          answers have been changed so that patch never goes into an  infinite
672          loop when using default answers.
673
674        · Traditional patch exited with a status value that counted the number
675          of bad hunks, or with status 1 if there was real trouble.  Now patch
676          exits  with  status  1  if some hunks failed, or with 2 if there was
677          real trouble.
678
679        · Limit yourself to the following options  when  sending  instructions
680          meant to be executed by anyone running GNU patch, traditional patch,
681          or a patch that conforms to POSIX.  Spaces are  significant  in  the
682          following list, and operands are required.
683
684             -c
685             -d dir
686             -D define
687             -e
688             -l
689             -n
690             -N
691             -o outfile
692             -pnum
693             -R
694             -r rejectfile
695

BUGS

697       Please report bugs via email to <bug-patch@gnu.org>.
698
699       If code has been duplicated (for instance with #ifdef OLDCODE ... #else
700       ... #endif), patch is incapable of patching both versions, and,  if  it
701       works  at  all,  will  likely patch the wrong one, and tell you that it
702       succeeded to boot.
703
704       If you apply a patch you've already  applied,  patch  thinks  it  is  a
705       reversed  patch,  and offers to un-apply the patch.  This could be con‐
706       strued as a feature.
707
708       Computing how to merge a hunk is significantly harder  than  using  the
709       standard  fuzzy algorithm.  Bigger hunks, more context, a bigger offset
710       from the original location, and a worse match all  slow  the  algorithm
711       down.
712

COPYING

714       Copyright (C) 1984, 1985, 1986, 1988 Larry Wall.
715       Copyright  (C)  1989,  1990,  1991, 1992, 1993, 1994, 1995, 1996, 1997,
716       1998, 1999, 2000, 2001, 2002, 2009 Free Software Foundation, Inc.
717
718       Permission is granted to make and distribute verbatim  copies  of  this
719       manual  provided  the  copyright  notice and this permission notice are
720       preserved on all copies.
721
722       Permission is granted to copy and distribute modified versions of  this
723       manual  under  the  conditions  for verbatim copying, provided that the
724       entire resulting derived work is distributed under the terms of a  per‐
725       mission notice identical to this one.
726
727       Permission  is granted to copy and distribute translations of this man‐
728       ual into another language, under the above conditions for modified ver‐
729       sions,  except  that this permission notice may be included in transla‐
730       tions approved by the copyright holders instead of in the original Eng‐
731       lish.
732

AUTHORS

734       Larry  Wall  wrote  the original version of patch.  Paul Eggert removed
735       patch's arbitrary limits; added support for binary files, setting  file
736       times,  and deleting files; and made it conform better to POSIX.  Other
737       contributors include Wayne Davison,  who  added  unidiff  support,  and
738       David  MacKenzie,  who added configuration and backup support.  Andreas
739       Grünbacher added support for merging.
740
741
742
743                                      GNU                             PATCH(1)
Impressum