Comparing and Merging Files - 14. Invoking patch

Go to the first, previous, next, last section, table of contents.

# 14. Invoking `patch`

Normally `patch` is invoked like this:

    patch <patchfile

The full format for invoking `patch` is:

    patch options... [origfile [patchfile]] [+ options... [origfile]]...

If you do not specify patchfile, or if patchfile is ``-'`, `patch` reads the patch (that is, the `diff` output) from the standard input.

You can specify one or more of the original files as orig arguments; each one and options for interpreting it is separated from the others with a ``+'`. See section 9.4 Multiple Patches in a File, for more information.

If you do not specify an input file on the command line, `patch` tries to figure out from the leading text (any text in the patch that comes before the `diff` output) which file to edit. In the header of a context or unified diff, `patch` looks in lines beginning with ``***'`, ``---'`, or ``+++'`; among those, it chooses the shortest name of an existing file. Otherwise, if there is an ``Index:'` line in the leading text, `patch` tries to use the file name from that line. If `patch` cannot figure out the name of an existing file from the leading text, it prompts you for the name of the file to patch.

If the input file does not exist or is read-only, and a suitable RCS or SCCS file exists, `patch` attempts to check out or get the file before proceeding.

By default, `patch` replaces the original input file with the patched version, after renaming the original file into a backup file (see section 14.2 Backup File Names, for a description of how `patch` names backup files). You can also specify where to put the output with the ``-o output-file'` or ``--output=output-file'` option.

## 14.1 Applying Patches in Other Directories

The ``-d directory'` or ``--directory=directory'` option to `patch` makes directory directory the current directory for interpreting both file names in the patch file, and file names given as arguments to other options (such as ``-B'` and ``-o'`). For example, while in a news reading program, you can patch a file in the ``/usr/src/emacs'` directory directly from the article containing the patch like this:

    | patch -d /usr/src/emacs

Sometimes the file names given in a patch contain leading directories, but you keep your files in a directory different from the one given in the patch. In those cases, you can use the ``-p[number]'` or ``--strip[=number]'` option to set the file name strip count to number. The strip count tells `patch` how many slashes, along with the directory names between them, to strip from the front of file names. ``-p'` with no number given is equivalent to ``-p0'`. By default, `patch` strips off all leading directories, leaving just the base file names, except that when a file name given in the patch is a relative file name and all of its leading directories already exist, `patch` does not strip off the leading directory. (A relative file name is one that does not start with a slash.)

`patch` looks for each file (after any slashes have been stripped) in the current directory, or if you used the ``-d directory'` option, in that directory.

For example, suppose the file name in the patch file is ``/gnu/src/emacs/etc/NEWS'`. Using ``-p'` or ``-p0'` gives the entire file name unmodified, ``-p1'` gives ``gnu/src/emacs/etc/NEWS'` (no leading slash), ``-p4'` gives ``etc/NEWS'`, and not specifying ``-p'` at all gives ``NEWS'`.

## 14.2 Backup File Names

Normally, `patch` renames an original input file into a backup file by appending to its name the extension ``.orig'`, or ``~'` on systems that do not support long file names. The ``-b backup-suffix'` or ``--suffix=backup-suffix'` option uses backup-suffix as the backup extension instead.

Alternately, you can specify the extension for backup files with the `SIMPLE_BACKUP_SUFFIX` environment variable, which the options override.

`patch` can also create numbered backup files the way GNU Emacs does. With this method, instead of having a single backup of each file, `patch` makes a new backup file name each time it patches a file. For example, the backups of a file named ``sink'` would be called, successively, ``sink.~1~'`, ``sink.~2~'`, ``sink.~3~'`, etc.

The ``-V backup-style'` or ``--version-control=backup-style'` option takes as an argument a method for creating backup file names. You can alternately control the type of backups that `patch` makes with the `VERSION_CONTROL` environment variable, which the ``-V'` option overrides. The value of the `VERSION_CONTROL` environment variable and the argument to the ``-V'` option are like the GNU Emacs `version-control` variable (see section 14.2 Backup File Names, for more information on backup versions in Emacs). They also recognize synonyms that are more descriptive. The valid values are listed below; unique abbreviations are acceptable.

``t'`
``numbered'`
  Always make numbered backups.
``nil'`
``existing'`
  Make numbered backups of files that already have them, simple backups of the others. This is the default.
``never'`
``simple'`
  Always make simple backups.

Alternately, you can tell `patch` to prepend a prefix, such as a directory name, to produce backup file names. The ``-B backup-prefix'` or ``--prefix=backup-prefix'` option makes backup files by prepending backup-prefix to them. If you use this option, `patch` ignores any ``-b'` option that you give.

If the backup file already exists, `patch` creates a new backup file name by changing the first lowercase letter in the last component of the file name into uppercase. If there are no more lowercase letters in the name, it removes the first character from the name. It repeats this process until it comes up with a backup file name that does not already exist.

If you specify the output file with the ``-o'` option, that file is the one that is backed up, not the input file.

## 14.3 Reject File Names

The names for reject files (files containing patches that `patch` could not find a place to apply) are normally the name of the output file with ``.rej'` appended (or ``#'` on systems that do not support long file names).

Alternatively, you can tell `patch` to place all of the rejected patches in a single file. The ``-r reject-file'` or ``--reject-file=reject-file'` option uses reject-file as the reject file name.

## 14.4 Options to `patch`

Here is a summary of all of the options that `patch` accepts. Older versions of `patch` do not accept long-named options or the ``-t'`, ``-E'`, or ``-V'` options.

Multiple single-letter options that do not take an argument can be combined into a single command line argument (with only one dash). Brackets ([ and ]) indicate that an option takes an optional argument.

``-b backup-suffix'`
  Use backup-suffix as the backup extension instead of ``.orig'` or ``~'`. See section 14.2 Backup File Names.
``-B backup-prefix'`
  Use backup-prefix as a prefix to the backup file name. If this option is specified, any ``-b'` option is ignored. See section 14.2 Backup File Names.
``--batch'`
  Do not ask any questions. See section 9.5 Messages and Questions from `patch`.
``-c'`
``--context'`
  Interpret the patch file as a context diff. See section 9.1 Selecting the `patch` Input Format.
``-d directory'`
``--directory=directory'`
  Makes directory directory the current directory for interpreting both file names in the patch file, and file names given as arguments to other options. See section 14.1 Applying Patches in Other Directories.
``-D name'`
  Make merged if-then-else output using format. See section 2.7 Merging Files with If-then-else.
``--debug=number'`
  Set internal debugging flags. Of interest only to `patch` patchers.
``-e'`
``--ed'`
  Interpret the patch file as an `ed` script. See section 9.1 Selecting the `patch` Input Format.
``-E'`
  Remove output files that are empty after the patches have been applied. See section 9.3 Removing Empty Files.
``-f'`
  Assume that the user knows exactly what he or she is doing, and do not ask any questions. See section 9.5 Messages and Questions from `patch`.
``-F lines'`
  Set the maximum fuzz factor to lines. See section 9.2.3 Helping `patch` Find Inexact Matches.
``--force'`
  Assume that the user knows exactly what he or she is doing, and do not ask any questions. See section 9.5 Messages and Questions from `patch`.
``--forward'`
  Ignore patches that `patch` thinks are reversed or already applied. See also ``-R'`. See section 9.2.2 Applying Reversed Patches.
``--fuzz=lines'`
  Set the maximum fuzz factor to lines. See section 9.2.3 Helping `patch` Find Inexact Matches.
``--help'`
  Print a summary of the options that `patch` recognizes, then exit.
``--ifdef=name'`
  Make merged if-then-else output using format. See section 2.7 Merging Files with If-then-else.
``--ignore-white-space'`
``-l'`
  Let any sequence of white space in the patch file match any sequence of white space in the input file. See section 9.2.1 Applying Patches with Changed White Space.
``-n'`
``--normal'`
  Interpret the patch file as a normal diff. See section 9.1 Selecting the `patch` Input Format.
``-N'`
  Ignore patches that `patch` thinks are reversed or already applied. See also ``-R'`. See section 9.2.2 Applying Reversed Patches.
``-o output-file'`
``--output=output-file'`
  Use output-file as the output file name. See section 14.4 Options to `patch`.
``-p[number]'`
  Set the file name strip count to number. See section 14.1 Applying Patches in Other Directories.
``--prefix=backup-prefix'`
  Use backup-prefix as a prefix to the backup file name. If this option is specified, any ``-b'` option is ignored. See section 14.2 Backup File Names.
``--quiet'`
  Work silently unless an error occurs. See section 9.5 Messages and Questions from `patch`.
``-r reject-file'`
  Use reject-file as the reject file name. See section 14.3 Reject File Names.
``-R'`
  Assume that this patch was created with the old and new files swapped. See section 9.2.2 Applying Reversed Patches.
``--reject-file=reject-file'`
  Use reject-file as the reject file name. See section 14.3 Reject File Names.
``--remove-empty-files'`
  Remove output files that are empty after the patches have been applied. See section 9.3 Removing Empty Files.
``--reverse'`
  Assume that this patch was created with the old and new files swapped. See section 9.2.2 Applying Reversed Patches.
``-s'`
  Work silently unless an error occurs. See section 9.5 Messages and Questions from `patch`.
``-S'`
  Ignore this patch from the patch file, but continue looking for the next patch in the file. See section 9.4 Multiple Patches in a File.
``--silent'`
  Work silently unless an error occurs. See section 9.5 Messages and Questions from `patch`.
``--skip'`
  Ignore this patch from the patch file, but continue looking for the next patch in the file. See section 9.4 Multiple Patches in a File.
``--strip[=number]'`
  Set the file name strip count to number. See section 14.1 Applying Patches in Other Directories.
``--suffix=backup-suffix'`
  Use backup-suffix as the backup extension instead of ``.orig'` or ``~'`. See section 14.2 Backup File Names.
``-t'`
  Do not ask any questions. See section 9.5 Messages and Questions from `patch`.
``-u'`
``--unified'`
  Interpret the patch file as a unified diff. See section 9.1 Selecting the `patch` Input Format.
``-v'`
  Output the revision header and patch level of `patch`.
``-V backup-style'`
  Select the kind of backups to make. See section 14.2 Backup File Names.
``--version'`
  Output the revision header and patch level of `patch`, then exit.
``--version=control=backup-style'`
  Select the kind of backups to make. See section 14.2 Backup File Names.
``-x number'`
  Set internal debugging flags. Of interest only to `patch` patchers.

Go to the first, previous, next, last section, table of contents.