patch man page on Archlinux

Man page or keyword search:  
man Server   11224 pages
apropos Keyword Search (all sections)
Output format
Archlinux logo
[printable version]

PATCH(1P)		   POSIX Programmer's Manual		     PATCH(1P)

PROLOG
       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
       implementation of this interface may differ (consult the	 corresponding
       Linux  manual page for details of Linux behavior), or the interface may
       not be implemented on Linux.

NAME
       patch — apply changes to files

SYNOPSIS
       patch [−blNR] [−c|−e|−n|−u] [−d dir] [−D define] [−i patchfile]
	   [−o outfile] [−p num] [−r rejectfile] [file]

DESCRIPTION
       The patch utility shall read a source (patch) file  containing  any  of
       four  forms  of difference (diff) listings produced by the diff utility
       (normal, copied context, unified context, or in the style  of  ed)  and
       apply  those  differences  to a file. By default, patch shall read from
       the standard input.

       The patch utility shall attempt to determine the type of the diff list‐
       ing, unless overruled by a −c, −e, −n, or −u option.

       If  the patch file contains more than one patch, patch shall attempt to
       apply each of them as if they came from separate patch files. (In  this
       case,  the  application shall ensure that the name of the patch file is
       determinable for each diff listing.)

OPTIONS
       The patch utility shall conform	to  the	 Base  Definitions  volume  of
       POSIX.1‐2008, Section 12.2, Utility Syntax Guidelines.

       The following options shall be supported:

       −b	 Save  a  copy of the original contents of each modified file,
		 before the differences are applied, in a  file	 of  the  same
		 name  with  the  suffix  .orig	 appended  to  it. If the file
		 already exists, it shall be overwritten; if multiple  patches
		 are applied to the same file, the .orig file shall be written
		 only for the first patch. When the −o outfile option is  also
		 specified,  file.orig	shall  not  be created but, if outfile
		 already exists, outfile.orig shall be created.

       −c	 Interpret the patch file as a copied context difference  (the
		 output	 of  the  utility  diff	 when the −c or −C options are
		 specified).

       −d dir	 Change the current directory  to  dir	before	processing  as
		 described in the EXTENDED DESCRIPTION section.

       −D define Mark  changes	with  one of the following C preprocessor con‐
		 structs:

		     #ifdef define
		     ...
		     #endif

		     #ifndef define
		     ...
		     #endif

		 optionally combined with the C preprocessor construct	#else.
		 If  the  patched  file	 is processed with the C preprocessor,
		 where the macro define is defined, the output	shall  contain
		 the  changes from the patch file; otherwise, the output shall
		 not contain the patches specified in the patch file.

       −e	 Interpret the patch file as an ed script, rather than a  diff
		 script.

       −i patchfile
		 Read  the  patch information from the file named by the path‐
		 name patchfile, rather than the standard input.

       −l	 (The letter ell.) Cause any sequence of <blank> characters in
		 the  difference script to match any sequence of <blank> char‐
		 acters in the input file. Other characters shall  be  matched
		 exactly.

       −n	 Interpret the script as a normal difference.

       −N	 Ignore	 patches  where	 the  differences  have	 already  been
		 applied to the	 file;	by  default,  already-applied  patches
		 shall be rejected.

       −o outfile
		 Instead of modifying the files (specified by the file operand
		 or the difference listings) directly, write  a	 copy  of  the
		 file  referenced  by each patch, with the appropriate differ‐
		 ences applied, to outfile.  Multiple  patches	for  a	single
		 file  shall  be  applied  to the intermediate versions of the
		 file created by any previous patches,	and  shall  result  in
		 multiple,  concatenated versions of the file being written to
		 outfile.

       −p num	 For all pathnames in the patch file that indicate  the	 names
		 of  files  to be patched, delete num pathname components from
		 the beginning of each pathname. If the pathname in the	 patch
		 file  is  absolute,  any  leading <slash> characters shall be
		 considered the first component (that is,  −p 1	 shall	remove
		 the  leading <slash> characters). Specifying −p 0 shall cause
		 the full pathname to be used. If −p is	 not  specified,  only
		 the basename (the final pathname component) shall be used.

       −R	 Reverse  the  sense of the patch script; that is, assume that
		 the difference script was created from the new version to the
		 old  version.	 The −R option cannot be used with ed scripts.
		 The patch utility shall attempt to reverse  each  portion  of
		 the  script before applying it. Rejected differences shall be
		 saved in swapped format. If this option is not specified, and
		 until	a  portion  of the patch file is successfully applied,
		 patch attempts to apply each portion in its reversed sense as
		 well  as  in  its normal sense. If the attempt is successful,
		 the user shall be prompted to determine whether the −R option
		 should be set.

       −r rejectfile
		 Override  the	default	 reject filename. In the default case,
		 the reject file shall have the same name as the output	 file,
		 with the suffix .rej appended to it; see Patch Application.

       −u	 Interpret the patch file as a unified context difference (the
		 output of the diff utility when the  −u  or  −U  options  are
		 specified).

OPERANDS
       The following operand shall be supported:

       file	 A pathname of a file to patch.

STDIN
       See the INPUT FILES section.

INPUT FILES
       Input files shall be text files.

ENVIRONMENT VARIABLES
       The  following  environment  variables  shall  affect  the execution of
       patch:

       LANG	 Provide a default value for  the  internationalization	 vari‐
		 ables	that are unset or null. (See the Base Definitions vol‐
		 ume of POSIX.1‐2008, Section 8.2, Internationalization	 Vari‐
		 ables	the  precedence of internationalization variables used
		 to determine the values of locale categories.)

       LC_ALL	 If set to a non-empty string value, override  the  values  of
		 all the other internationalization variables.

       LC_COLLATE
		 Determine  the locale for the behavior of ranges, equivalence
		 classes, and multi-character collating elements used  in  the
		 extended  regular  expression	defined for the yesexpr locale
		 keyword in the LC_MESSAGES category.

       LC_CTYPE	 Determine the locale for the interpretation of	 sequences  of
		 bytes of text data as characters (for example, single-byte as
		 opposed to  multi-byte	 characters  in	 arguments  and	 input
		 files),  and  the  behavior  of character classes used in the
		 extended regular expression defined for  the  yesexpr	locale
		 keyword in the LC_MESSAGES category.

       LC_MESSAGES
		 Determine  the	 locale used to process affirmative responses,
		 and the locale used to affect	the  format  and  contents  of
		 diagnostic messages and prompts written to standard error.

       NLSPATH	 Determine the location of message catalogs for the processing
		 of LC_MESSAGES.

       LC_TIME	 Determine the locale for recognizing the format of file time‐
		 stamps	 written  by  the diff utility in a context-difference
		 input file.

ASYNCHRONOUS EVENTS
       Default.

STDOUT
       Not used.

STDERR
       The standard error shall be used for diagnostic and informational  mes‐
       sages.

OUTPUT FILES
       The  output  of the patch utility, the save files (.orig suffixes), and
       the reject files (.rej suffixes) shall be text files.

EXTENDED DESCRIPTION
       A patch file may contain patching instructions for more than one	 file;
       filenames  shall	 be determined as specified in Filename Determination.
       When the −b option is specified, for each patched  file,	 the  original
       shall  be  saved	 in  a	file  of  the  same name with the suffix .orig
       appended to it.

       For each patched file, a reject file may also be created	 as  noted  in
       Patch  Application.   In	 the  absence of a −r option, the name of this
       file shall be formed by appending the suffix .rej to the original file‐
       name.

   Patch File Format
       The  patch  file shall contain zero or more lines of header information
       followed by one or more patches. Each patch shall contain zero or  more
       lines  of filename identification in the format produced by the −c, −C,
       −u, or −U options of the diff utility, and one or  more	sets  of  diff
       output, which are customarily called hunks.

       The  patch  utility  shall  recognize  the  following expression in the
       header information:

       Index: pathname
	     The file to be patched is named pathname.

       If all lines (including headers) within a patch	begin  with  the  same
       leading	sequence of <blank> characters, the patch utility shall remove
       this sequence before proceeding. Within each patch, if the type of dif‐
       ference	is  common context, the patch utility shall recognize the fol‐
       lowing expressions:

       *** filename timestamp
	     The patches arose from filename.

       −−− filename timestamp
	     The patches should be applied to filename.

       If the type of difference is unified context, the patch	utility	 shall
       recognize the following expressions:

       −−− filename timestamp
	     The patches arose from filename.

       +++ filename timestamp
	     The patches should be applied to filename.

       Each  hunk  within  a  patch  shall be the diff output to change a line
       range within the original file. The line numbers for  successive	 hunks
       within a patch shall occur in ascending order.

   Filename Determination
       If  no  file  operand  is  specified, patch shall perform the following
       steps to determine the filename to use:

	1. If the type of diff is context,  the	 patch	utility	 shall	delete
	   pathname  components (as specified by the −p option) from the file‐
	   name on the line beginning with "***" (if copied context) or	 "−−−"
	   (if unified context), then test for the existence of this file rel‐
	   ative to the current directory (or the directory specified with the
	   −d  option).	 If  the file exists, the patch utility shall use this
	   filename.

	2. If the type of diff is context, the patch utility shall delete  the
	   pathname  components (as specified by the −p option) from the file‐
	   name on the line beginning with "−−−" (if copied context) or	 "+++"
	   (if unified context), then test for the existence of this file rel‐
	   ative to the current directory (or the directory specified with the
	   −d  option).	 If  the file exists, the patch utility shall use this
	   filename.

	3. If the header information contains a line beginning with the string
	   Index:,  the	 patch	utility	 shall	delete pathname components (as
	   specified by the −p option) from this line, then test for the exis‐
	   tence of this file relative to the current directory (or the direc‐
	   tory specified with the −d option). If the file exists,  the	 patch
	   utility shall use this filename.

	4. If  an  SCCS directory exists in the current directory, patch shall
	   attempt to perform a get −e SCCS/s.filename command to retrieve  an
	   editable version of the file. If the file exists, the patch utility
	   shall use this filename.

	5. The patch utility shall write  a  prompt  to	 standard  output  and
	   request a filename interactively from the controlling terminal (for
	   example, /dev/tty).

   Patch Application
       If the −c, −e, −n, or −u option is present,  the	 patch	utility	 shall
       interpret  information within each hunk as a copied context difference,
       an ed difference, a normal difference, or a unified context difference,
       respectively. In the absence of any of these options, the patch utility
       shall determine the type of difference based on the format of  informa‐
       tion within the hunk.

       For each hunk, the patch utility shall begin to search for the place to
       apply the patch at the line number at the beginning of the  hunk,  plus
       or minus any offset used in applying the previous hunk. If lines match‐
       ing the hunk context are not found, patch shall scan both forwards  and
       backwards  at  least  1000 bytes for a set of lines that match the hunk
       context.

       If no such place is found and it is a context difference, then  another
       scan  shall take place, ignoring the first and last line of context. If
       that fails, the first two and  last  two	 lines	of  context  shall  be
       ignored and another scan shall be made. Implementations may search more
       extensively for installation locations.

       If no location can be found, the patch utility shall append the hunk to
       the  reject  file. A rejected hunk that is a copied context difference,
       an ed difference, or a normal difference shall be  written  in  copied-
       context-difference  format  regardless of the format of the patch file.
       It is implementation-defined whether a rejected hunk that is a  unified
       context difference is written in copied-context-difference format or in
       unified-context-difference format.  If the input was a  normal  or  ed-
       style  difference,  the	reject	file may contain differences with zero
       lines of context. The line numbers on the hunks in the reject file  may
       be  different  from the line numbers in the patch file since they shall
       reflect the approximate locations for the failed hunks in the new  file
       rather than the old one.

       If  the	type of patch is an ed diff, the implementation may accomplish
       the patching by invoking the ed utility.

EXIT STATUS
       The following exit values shall be returned:

	0    Successful completion.

	1    One or more lines were written to a reject file.

       >1    An error occurred.

CONSEQUENCES OF ERRORS
       Patches that cannot be correctly placed in the file shall be written to
       a reject file.

       The following sections are informative.

APPLICATION USAGE
       The −R option does not work with ed scripts because there is too little
       information to reconstruct the reverse operation.

       The −p option makes it possible to customize a patch file to local user
       directory structures without manually editing the patch file. For exam‐
       ple, if the filename in the patch file was:

	   /curds/whey/src/blurfl/blurfl.c

       Setting −p 0 gives the entire pathname unmodified; −p 1 gives:

	   curds/whey/src/blurfl/blurfl.c

       without the leading <slash>, −p 4 gives:

	   blurfl/blurfl.c

       and not specifying −p at all gives:

	   blurfl.c .

EXAMPLES
       None.

RATIONALE
       Some of the functionality in historical patch implementations  was  not
       specified. The following documents those features present in historical
       implementations that have not been specified.

       A deleted piece of functionality was the '+' pseudo-option allowing  an
       additional  set	of  options and a patch file operand to be given. This
       was seen as being insufficiently useful to standardize.

       In historical implementations, if the string "Prereq:" appeared in  the
       header,	the  patch  utility would search for the corresponding version
       information (the string specified in the header, delimited  by  <blank>
       characters  or  the beginning or end of a line or the file) anywhere in
       the original file. This was deleted  as	too  simplistic	 and  insuffi‐
       ciently trustworthy a mechanism to standardize. For example, if:

	   Prereq: 1.2

       were  in	 the  header,  the presence of a delimited 1.2 anywhere in the
       file would satisfy the prerequisite.

       The following options were dropped from historical  implementations  of
       patch as insufficiently useful to standardize:

       −b	 The −b option historically provided a method for changing the
		 name extension of the backup file  from  the  default	.orig.
		 This  option has been modified and retained in this volume of
		 POSIX.1‐2008.

       −F	 The −F option specified the number of lines of a context diff
		 to ignore when searching for a place to install a patch.

       −f	 The  −f option historically caused patch not to request addi‐
		 tional information from the user.

       −r	 The −r option historically provided a	method	of  overriding
		 the extension of the reject file from the default .rej.

       −s	 The  −s  option  historically	caused	patch to work silently
		 unless an error occurred.

       −x	 The −x option historically set internal debugging flags.

       In some file system implementations, the saving of  a  .orig  file  may
       produce	unwanted results. In the case of 12, 13, or 14-character file‐
       names (on file systems supporting 14-character maximum filenames),  the
       .orig  file  overwrites	the  new file. The reject file may also exceed
       this filename limit. It was suggested, due to some historical practice,
       that  a	<tilde>	 ('~')	suffix be used instead of .orig and some other
       character instead of the .rej suffix. This was rejected because	it  is
       not  obvious  to	 the  user which file is which. The suffixes .orig and
       .rej are clearer and more understandable.

       The −b option has the opposite sense  in	 some  historical  implementa‐
       tions—do	 not save the .orig file. The default case here is not to save
       the files, making patch behave more consistently with the  other	 stan‐
       dard utilities.

       The  −w option in early proposals was changed to −l to match historical
       practice.

       The −N option was included because without it, a non-interactive appli‐
       cation cannot reject previously applied patches. For example, if a user
       is piping the output of diff into the patch utility, and the user  only
       wants  to  patch	 a  file  to a newer version non-interactively, the −N
       option is required.

       Changes to the −l option description were proposed  to  allow  matching
       across  <newline>  characters  in  addition to just <blank> characters.
       Since this is not historical practice, and since some ambiguities could
       result,	it  is suggested that future developments in this area utilize
       another option letter, such as −L.

       The −u option of GNU patch has been added, along with support for  uni‐
       fied context formats.

FUTURE DIRECTIONS
       None.

SEE ALSO
       diff, ed

       The  Base  Definitions  volume  of POSIX.1‐2008, Chapter 8, Environment
       Variables, Section 12.2, Utility Syntax Guidelines

COPYRIGHT
       Portions of this text are reprinted and reproduced in  electronic  form
       from IEEE Std 1003.1, 2013 Edition, Standard for Information Technology
       -- Portable Operating System Interface (POSIX),	The  Open  Group  Base
       Specifications Issue 7, Copyright (C) 2013 by the Institute of Electri‐
       cal and Electronics Engineers,  Inc  and	 The  Open  Group.   (This  is
       POSIX.1-2008  with  the	2013  Technical Corrigendum 1 applied.) In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained	online
       at http://www.unix.org/online.html .

       Any  typographical  or  formatting  errors that appear in this page are
       most likely to have been introduced during the conversion of the source
       files  to  man page format. To report such errors, see https://www.ker‐
       nel.org/doc/man-pages/reporting_bugs.html .

IEEE/The Open Group		     2013			     PATCH(1P)
[top]

List of man pages available for Archlinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net