Quick ?s
Cheat Sheets
Man Pages
The Lynx
Software
PATCH(1)							      PATCH(1)



NAME
       patch - apply a diff file to an original

SYNOPSIS
       patch [options] [originalfile [patchfile]]

       but usually just

       patch -pnum  (1985-01).

NOTES FOR PATCH SENDERS
       There are several things you should bear in mind if you are going to be
       sending out patches.

       Create  your  patch  systematically.   A  good  method  is  the command
       diff -Naur old new where old and new identify the old and new  directo
       ries.   The names old and new should not contain any slashes.  The diff
       commands headers should have dates and times in Universal  Time	using
       traditional  Unix  format,  so  that patch recipients can use the -Z or
       --set-utc option.  Here is an example command, using Bourne shell  syn
       tax:

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

       Tell  your  recipients  how  to	apply  the patch by telling them which
       directory to cd to, and which patch options to use.  The option	string
       -Np1 is recommended.  Test your procedure by pretending to be a recipi
       ent and applying your patch to a copy of the original files.

       You can save people a lot of grief by keeping a patchlevel.h file which
       is  patched to increment the patch level as the first diff in the patch
       file you send out.  If you put a Prereq: line in  with  the  patch,  it
       wont let them apply patches out of order without some warning.

       You  can create a file by sending out a diff that compares /dev/null or
       an empty file dated the Epoch (1970-01-01 00:00:00 UTC) to the file you
       want to create.	This only works if the file you want to create doesnt
       exist already in the target directory.  Conversely, you	can  remove  a
       file by sending out a context diff that compares the file to be deleted
       with an empty file dated the Epoch.  The file will  be  removed	unless
       patch  is conforming to POSIX and the -E or --remove-empty-files option
       is not given.  An easy way to generate patches that create  and	remove
       files is to use GNU diffs -N or --new-file option.

       If  the recipient is supposed to use the -pN option, do not send output
       that looks like this:

	  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

       because the two file names have different numbers of slashes, and  dif
       ferent  versions  of  patch  interpret  the file names differently.  To
       avoid confusion, send output that looks like this instead:

	  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


       Avoid sending patches that compare backup file names like  README.orig,
       since  this  might confuse patch into patching a backup file instead of
       the real file.  Instead, send patches that compare the same  base  file
       names in different directories, e.g. old/README and new/README.

       Take  care not to send out reversed patches, since it makes people won
       der whether they already applied the patch.

       Try not to have your patch modify derived files (e.g. the file  config
       ure  where  there  is a line configure: configure.in in your makefile),
       since the recipient should be able to regenerate the derived files any
       way.  If you must send diffs of derived files, generate the diffs using
       UTC, have the recipients apply the  patch  with	the  -Z  or  --set-utc
       option, and have them remove any unpatched files that depend on patched
       files (e.g. with make clean).

       While you may be able to get away with putting 582 diff	listings  into
       one  file, it may be wiser to group related patches into separate files
       in case something goes haywire.

DIAGNOSTICS
       Diagnostics generally indicate that patch  couldnt  parse  your	patch
       file.

       If  the	--verbose  option  is given, the message Hmm... indicates that
       there is unprocessed text in the patch file and that patch is  attempt
       ing  to	intuit	whether there is a patch in that text and, if so, what
       kind of patch it is.

       patchs exit status is 0 if all hunks are applied  successfully,	1  if
       some  hunks  cannot be applied, and 2 if there is more serious trouble.
       When applying a set of patches in a loop it behooves you to check  this
       exit  status  so  you  dont apply a later patch to a partially patched
       file.

CAVEATS
       Context diffs cannot reliably represent the  creation  or  deletion  of
       empty  files,  empty  directories,  or  special	files such as symbolic
       links.  Nor can they represent changes to file metadata like ownership,
       permissions, or whether one file is a hard link to another.  If changes
       like these are also  required,  separate  instructions  (e.g.  a  shell
       script) to accomplish them should accompany the patch.

       patch  cannot tell if the line numbers are off in an ed script, and can
       detect bad line numbers in a normal diff only when it finds a change or
       deletion.   A  context diff using fuzz factor 3 may have the same prob
       lem.  Until a suitable interactive interface is added, you should prob
       ably do a context diff in these cases to see if the changes made sense.
       Of course, compiling without errors is a pretty	good  indication  that
       the patch worked, but not always.

       patch  usually  produces  the correct results, even when it has to do a
       lot of guessing.  However, the results are  guaranteed  to  be  correct
       only  when the patch is applied to exactly the same version of the file
       that the patch was generated from.

COMPATIBILITY ISSUES
       The POSIX standard specifies behavior that differs from patchs  tradi
       tional  behavior.  You should be aware of these differences if you must
       interoperate with patch versions 2.1 and earlier, which do not  conform
       to POSIX.

	 In  traditional  patch,  the -p options operand was optional, and a
	  bare -p was equivalent to  -p0.   The  -p  option  now  requires  an
	  operand, and -p 0 is now equivalent to -p0.  For maximum compatibil
	  ity, use options like -p0 and -p1.

	  Also, traditional patch simply counted slashes when  stripping  path
	  prefixes; patch now counts pathname components.  That is, a sequence
	  of one or more adjacent slashes now counts as a single  slash.   For
	  maximum  portability,  avoid	sending  patches containing // in file
	  names.

	 In traditional patch, backups were enabled by default.  This  behav
	  ior is now enabled with the -b or --backup option.

	  Conversely,  in POSIX patch, backups are never made, even when there
	  is a mismatch.  In GNU patch, this  behavior	is  enabled  with  the
	  --no-backup-if-mismatch  option,  or by conforming to POSIX with the
	  --posix option or by setting the POSIXLY_CORRECT  environment  vari
	  able.

	  The  -b suffix  option  of  traditional  patch  is equivalent to the
	  -b -z suffix options of GNU patch.

	 Traditional patch used a complicated (and  incompletely  documented)
	  method  to  intuit the name of the file to be patched from the patch
	  header.  This method did  not  conform  to  POSIX,  and  had	a  few
	  gotchas.   Now patch uses a different, equally complicated (but bet
	  ter documented) method that is optionally POSIX-conforming; we  hope
	  it  has  fewer  gotchas.  The two methods are compatible if the file
	  names in the context diff header and the Index: line are all identi
	  cal  after  prefix-stripping.   Your patch is normally compatible if
	  each headers file names all contain the same number of slashes.

	 When traditional patch asked the user a question, it sent the	ques
	  tion	to standard error and looked for an answer from the first file
	  in the following list that was a terminal: standard error,  standard
	  output,  /dev/tty, and standard input.  Now patch sends questions to
	  standard output and gets answers from /dev/tty.  Defaults  for  some
	  answers  have been changed so that patch never goes into an infinite
	  loop when using default answers.

	 Traditional patch exited with a status value that counted the number
	  of bad hunks, or with status 1 if there was real trouble.  Now patch
	  exits with status 1 if some hunks failed, or with  2	if  there  was
	  real trouble.

	 Limit	yourself  to  the following options when sending instructions
	  meant to be executed by anyone running GNU patch, traditional patch,
	  or  a  patch	that conforms to POSIX.  Spaces are significant in the
	  following list, and operands are required.

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

BUGS
       Please report bugs via email to .

       patch could be smarter about partial matches, excessively deviant  off
       sets and swapped code, but that would take an extra pass.

       If code has been duplicated (for instance with #ifdef OLDCODE ... #else
       ... #endif), patch is incapable of patching both versions, and,	if  it
       works  at  all,	will  likely patch the wrong one, and tell you that it
       succeeded to boot.

       If you apply a patch youve already  applied,  patch  thinks  it	is  a
       reversed  patch,  and offers to un-apply the patch.  This could be con
       strued as a feature.

COPYING
       Copyright (C) 1984, 1985, 1986, 1988 Larry Wall.
       Copyright (C) 1989, 1990, 1991, 1992, 1993,  1994,  1995,  1996,  1997,
       1998, 1999, 2000, 2001, 2002 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 per
       mission notice identical to this one.

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

AUTHORS
       Larry Wall wrote the original version of patch.	 Paul  Eggert  removed
       patchs  arbitrary limits; added support for binary files, setting file
       times, and deleting files; and made it conform better to POSIX.	 Other
       contributors  include  Wayne  Davison,  who  added unidiff support, and
       David MacKenzie, who added configuration and backup support.



GNU				  2002/05/25			      PATCH(1)




Yals.net is © 1999-2009 Crescendo Communications
Sharing tech info on the web for more than a decade!
This page was generated Thu Apr 30 17:05:20 2009