summaryrefslogtreecommitdiff
path: root/external/gpl2/diffutils/dist/doc
diff options
context:
space:
mode:
authorchristos <christos@NetBSD.org>2016-01-13 03:15:29 +0000
committerchristos <christos@NetBSD.org>2016-01-13 03:15:29 +0000
commiteec8fc77c4e0eb79f8d0dce344cf1200ede12bfe (patch)
tree0f84674d79cb0a0e6763dec26eb82850f961590f /external/gpl2/diffutils/dist/doc
parentceb99fff3a910a1efe2f446026eaf8d0ed4086b2 (diff)
Import latest gpl2 diffutils
Diffstat (limited to 'external/gpl2/diffutils/dist/doc')
-rw-r--r--external/gpl2/diffutils/dist/doc/Makefile.am24
-rw-r--r--external/gpl2/diffutils/dist/doc/Makefile.in359
-rw-r--r--external/gpl2/diffutils/dist/doc/diagmeet.note71
-rw-r--r--external/gpl2/diffutils/dist/doc/diff.info5084
-rw-r--r--external/gpl2/diffutils/dist/doc/diff.texi4557
-rw-r--r--external/gpl2/diffutils/dist/doc/fdl.texi404
-rw-r--r--external/gpl2/diffutils/dist/doc/stamp-vti4
-rw-r--r--external/gpl2/diffutils/dist/doc/version.texi5
8 files changed, 10508 insertions, 0 deletions
diff --git a/external/gpl2/diffutils/dist/doc/Makefile.am b/external/gpl2/diffutils/dist/doc/Makefile.am
new file mode 100644
index 00000000000..574fdab8705
--- /dev/null
+++ b/external/gpl2/diffutils/dist/doc/Makefile.am
@@ -0,0 +1,24 @@
+# Makefile for GNU diffutils documentation.
+
+# Copyright (C) 2001, 2002 Free Software Foundation, Inc.
+
+## This program is free software; you can redistribute it and/or modify
+## it under the terms of the GNU General Public License as published by
+## the Free Software Foundation; either version 2, or (at your option)
+## any later version.
+
+## This program is distributed in the hope that it will be useful,
+## but WITHOUT ANY WARRANTY; without even the implied warranty of
+## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+## GNU General Public License for more details.
+
+## You should have received a copy of the GNU General Public License
+## along with this program; if not, write to the Free Software Foundation,
+## Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+
+AM_MAKEINFOFLAGS = --no-split
+
+info_TEXINFOS = diff.texi
+diff_TEXINFOS = fdl.texi
+
+EXTRA_DIST = diagmeet.note
diff --git a/external/gpl2/diffutils/dist/doc/Makefile.in b/external/gpl2/diffutils/dist/doc/Makefile.in
new file mode 100644
index 00000000000..408013d8e2b
--- /dev/null
+++ b/external/gpl2/diffutils/dist/doc/Makefile.in
@@ -0,0 +1,359 @@
+# Makefile.in generated by automake 1.6 from Makefile.am.
+# @configure_input@
+
+# Copyright 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2001, 2002
+# Free Software Foundation, Inc.
+# This Makefile.in is free software; the Free Software Foundation
+# gives unlimited permission to copy and/or distribute it,
+# with or without modifications, as long as this notice is preserved.
+
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY, to the extent permitted by law; without
+# even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+# PARTICULAR PURPOSE.
+
+@SET_MAKE@
+
+# Makefile for GNU diffutils documentation.
+
+# Copyright (C) 2001, 2002 Free Software Foundation, Inc.
+SHELL = @SHELL@
+
+srcdir = @srcdir@
+top_srcdir = @top_srcdir@
+VPATH = @srcdir@
+prefix = @prefix@
+exec_prefix = @exec_prefix@
+
+bindir = @bindir@
+sbindir = @sbindir@
+libexecdir = @libexecdir@
+datadir = @datadir@
+sysconfdir = @sysconfdir@
+sharedstatedir = @sharedstatedir@
+localstatedir = @localstatedir@
+libdir = @libdir@
+infodir = @infodir@
+mandir = @mandir@
+includedir = @includedir@
+oldincludedir = /usr/include
+pkgdatadir = $(datadir)/@PACKAGE@
+pkglibdir = $(libdir)/@PACKAGE@
+pkgincludedir = $(includedir)/@PACKAGE@
+top_builddir = ..
+
+ACLOCAL = @ACLOCAL@
+AUTOCONF = @AUTOCONF@
+AUTOMAKE = @AUTOMAKE@
+AUTOHEADER = @AUTOHEADER@
+
+am__cd = CDPATH="$${ZSH_VERSION+.}$(PATH_SEPARATOR)" && cd
+INSTALL = @INSTALL@
+INSTALL_PROGRAM = @INSTALL_PROGRAM@
+INSTALL_DATA = @INSTALL_DATA@
+install_sh_DATA = $(install_sh) -c -m 644
+install_sh_PROGRAM = $(install_sh) -c
+INSTALL_SCRIPT = @INSTALL_SCRIPT@
+INSTALL_HEADER = $(INSTALL_DATA)
+transform = @program_transform_name@
+NORMAL_INSTALL = :
+PRE_INSTALL = :
+POST_INSTALL = :
+NORMAL_UNINSTALL = :
+PRE_UNINSTALL = :
+POST_UNINSTALL = :
+host_alias = @host_alias@
+host_triplet = @host@
+
+EXEEXT = @EXEEXT@
+OBJEXT = @OBJEXT@
+PATH_SEPARATOR = @PATH_SEPARATOR@
+AMTAR = @AMTAR@
+AWK = @AWK@
+BUILD_INCLUDED_LIBINTL = @BUILD_INCLUDED_LIBINTL@
+CATOBJEXT = @CATOBJEXT@
+CC = @CC@
+CPP = @CPP@
+DATADIRNAME = @DATADIRNAME@
+DEPDIR = @DEPDIR@
+GENCAT = @GENCAT@
+GLIBC21 = @GLIBC21@
+GMSGFMT = @GMSGFMT@
+HAVE_LIB = @HAVE_LIB@
+HELP2MAN = @HELP2MAN@
+INSTALL_STRIP_PROGRAM = @INSTALL_STRIP_PROGRAM@
+INSTOBJEXT = @INSTOBJEXT@
+INTLBISON = @INTLBISON@
+INTLLIBS = @INTLLIBS@
+INTLOBJS = @INTLOBJS@
+INTL_LIBTOOL_SUFFIX_PREFIX = @INTL_LIBTOOL_SUFFIX_PREFIX@
+LIB = @LIB@
+LIBICONV = @LIBICONV@
+LIBINTL = @LIBINTL@
+LIB_CLOCK_GETTIME = @LIB_CLOCK_GETTIME@
+LTLIB = @LTLIB@
+LTLIBICONV = @LTLIBICONV@
+LTLIBINTL = @LTLIBINTL@
+MKINSTALLDIRS = @MKINSTALLDIRS@
+PACKAGE = @PACKAGE@
+POSUB = @POSUB@
+PR_PROGRAM = @PR_PROGRAM@
+RANLIB = @RANLIB@
+STRIP = @STRIP@
+U = @U@
+USE_INCLUDED_LIBINTL = @USE_INCLUDED_LIBINTL@
+USE_NLS = @USE_NLS@
+VERSION = @VERSION@
+am__include = @am__include@
+am__quote = @am__quote@
+install_sh = @install_sh@
+
+AM_MAKEINFOFLAGS = --no-split
+
+info_TEXINFOS = diff.texi
+diff_TEXINFOS = fdl.texi
+
+EXTRA_DIST = diagmeet.note
+subdir = doc
+mkinstalldirs = $(SHELL) $(top_srcdir)/config/mkinstalldirs
+CONFIG_HEADER = $(top_builddir)/config.h
+CONFIG_CLEAN_FILES =
+DIST_SOURCES =
+TEXINFO_TEX = $(top_srcdir)/config/texinfo.tex
+INFO_DEPS = diff.info
+DVIS = diff.dvi
+TEXINFOS = diff.texi
+DIST_COMMON = $(diff_TEXINFOS) Makefile.am Makefile.in stamp-vti \
+ version.texi
+all: all-am
+
+.SUFFIXES:
+.SUFFIXES: .dvi .info .ps .texi
+$(srcdir)/Makefile.in: Makefile.am $(top_srcdir)/configure.ac $(ACLOCAL_M4)
+ cd $(top_srcdir) && \
+ $(AUTOMAKE) --gnits doc/Makefile
+Makefile: $(srcdir)/Makefile.in $(top_builddir)/config.status
+ cd $(top_builddir) && $(SHELL) ./config.status $(subdir)/$@ $(am__depfiles_maybe)
+
+$(srcdir)/version.texi: $(srcdir)/stamp-vti
+ @:
+$(srcdir)/stamp-vti: diff.texi $(top_srcdir)/configure.ac
+ @(set `$(SHELL) $(top_srcdir)/config/mdate-sh $(srcdir)/diff.texi`; \
+ echo "@set UPDATED $$1 $$2 $$3"; \
+ echo "@set UPDATED-MONTH $$2 $$3"; \
+ echo "@set EDITION $(VERSION)"; \
+ echo "@set VERSION $(VERSION)") > vti.tmp
+ @cmp -s vti.tmp $(srcdir)/version.texi \
+ || (echo "Updating $(srcdir)/version.texi"; \
+ cp vti.tmp $(srcdir)/version.texi)
+ -@rm -f vti.tmp
+ @cp $(srcdir)/version.texi $@
+
+mostlyclean-vti:
+ -rm -f vti.tmp
+
+maintainer-clean-vti:
+ -rm -f $(srcdir)/stamp-vti $(srcdir)/version.texi
+
+diff.info: diff.texi $(srcdir)/version.texi $(diff_TEXINFOS)
+diff.dvi: diff.texi $(srcdir)/version.texi $(diff_TEXINFOS)
+
+.texi.info:
+ @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ cd $(srcdir) \
+ && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \
+ `echo $< | sed 's,.*/,,'`
+
+.texi.dvi:
+ TEXINPUTS="$(top_srcdir)/config$(PATH_SEPARATOR)$$TEXINPUTS" \
+ MAKEINFO='$(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) -I $(srcdir)' \
+ $(TEXI2DVI) $<
+
+.texi:
+ @cd $(srcdir) && rm -f $@ $@-[0-9] $@-[0-9][0-9]
+ cd $(srcdir) \
+ && $(MAKEINFO) $(AM_MAKEINFOFLAGS) $(MAKEINFOFLAGS) \
+ `echo $< | sed 's,.*/,,'`
+
+MAKEINFO = @MAKEINFO@
+TEXI2DVI = texi2dvi
+DVIPS = dvips
+.dvi.ps:
+ $(DVIPS) $< -o $@
+
+uninstall-info-am:
+ $(PRE_UNINSTALL)
+ @if (install-info --version && \
+ install-info --version | fgrep -i -v debian) >/dev/null 2>&1; then \
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ echo " install-info --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$file"; \
+ install-info --info-dir=$(DESTDIR)$(infodir) --remove $(DESTDIR)$(infodir)/$$file; \
+ done; \
+ else :; fi
+ @$(NORMAL_UNINSTALL)
+ @list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ (if cd $(DESTDIR)$(infodir); then \
+ echo " rm -f $$file $$file-[0-9] $$file-[0-9][0-9])"; \
+ rm -f $$file $$file-[0-9] $$file-[0-9][0-9]; \
+ else :; fi); \
+ done
+
+dist-info: $(INFO_DEPS)
+ list='$(INFO_DEPS)'; \
+ for base in $$list; do \
+ d=$(srcdir); \
+ for file in $$d/$$base*; do \
+ relfile=`expr "$$file" : "$$d/\(.*\)"`; \
+ test -f $(distdir)/$$relfile || \
+ cp -p $$file $(distdir)/$$relfile; \
+ done; \
+ done
+
+mostlyclean-aminfo:
+ -rm -f diff.aux diff.cp diff.cps diff.dvi diff.fn diff.ky diff.log diff.pg \
+ diff.ps diff.toc diff.tp diff.vr
+
+maintainer-clean-aminfo:
+ cd $(srcdir) && \
+ for i in $(INFO_DEPS); do \
+ rm -f $$i; \
+ if test "`echo $$i-[0-9]*`" != "$$i-[0-9]*"; then \
+ rm -f $$i-[0-9]*; \
+ fi; \
+ done
+tags: TAGS
+TAGS:
+
+DISTFILES = $(DIST_COMMON) $(DIST_SOURCES) $(TEXINFOS) $(EXTRA_DIST)
+
+top_distdir = ..
+distdir = $(top_distdir)/$(PACKAGE)-$(VERSION)
+
+distdir: $(DISTFILES)
+ @for file in $(DISTFILES); do \
+ if test -f $$file || test -d $$file; then d=.; else d=$(srcdir); fi; \
+ dir=`echo "$$file" | sed -e 's,/[^/]*$$,,'`; \
+ if test "$$dir" != "$$file" && test "$$dir" != "."; then \
+ dir="/$$dir"; \
+ $(mkinstalldirs) "$(distdir)$$dir"; \
+ else \
+ dir=''; \
+ fi; \
+ if test -d $$d/$$file; then \
+ cp -pR $$d/$$file $(distdir)$$dir \
+ || exit 1; \
+ else \
+ test -f $(distdir)/$$file \
+ || cp -p $$d/$$file $(distdir)/$$file \
+ || exit 1; \
+ fi; \
+ done
+ $(MAKE) $(AM_MAKEFLAGS) \
+ top_distdir="${top_distdir}" distdir="$(distdir)" \
+ dist-info
+check-am: all-am
+check: check-am
+all-am: Makefile $(INFO_DEPS)
+
+installdirs:
+ $(mkinstalldirs) $(DESTDIR)$(infodir)
+
+install: install-am
+install-exec: install-exec-am
+install-data: install-data-am
+uninstall: uninstall-am
+
+install-am: all-am
+ @$(MAKE) $(AM_MAKEFLAGS) install-exec-am install-data-am
+
+installcheck: installcheck-am
+install-strip:
+ $(MAKE) $(AM_MAKEFLAGS) INSTALL_PROGRAM="$(INSTALL_STRIP_PROGRAM)" \
+ INSTALL_STRIP_FLAG=-s \
+ `test -z '$(STRIP)' || \
+ echo "INSTALL_PROGRAM_ENV=STRIPPROG='$(STRIP)'"` install
+mostlyclean-generic:
+
+clean-generic:
+
+distclean-generic:
+ -rm -f Makefile $(CONFIG_CLEAN_FILES) stamp-h stamp-h[0-9]*
+
+maintainer-clean-generic:
+ @echo "This command is intended for maintainers to use"
+ @echo "it deletes files that may require special tools to rebuild."
+clean: clean-am
+
+clean-am: clean-generic mostlyclean-am
+
+distclean: distclean-am
+
+distclean-am: clean-am distclean-generic
+
+dvi: dvi-am
+
+dvi-am: $(DVIS)
+
+info: info-am
+
+info-am: $(INFO_DEPS)
+
+install-data-am: install-info-am
+
+install-exec-am:
+
+install-info: install-info-am
+
+install-info-am: $(INFO_DEPS)
+ @$(NORMAL_INSTALL)
+ $(mkinstalldirs) $(DESTDIR)$(infodir)
+ @list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ d=$(srcdir); \
+ for ifile in echo $$d/$$file $$d/$$file-[0-9] $$d/$$file-[0-9][0-9]; do \
+ if test -f $$ifile; then \
+ relfile=`expr "$$ifile" : "$$d/\(.*\)"`; \
+ echo " $(INSTALL_DATA) $$ifile $(DESTDIR)$(infodir)/$$relfile"; \
+ $(INSTALL_DATA) $$ifile $(DESTDIR)$(infodir)/$$relfile; \
+ else : ; fi; \
+ done; \
+ done
+ @$(POST_INSTALL)
+ @if (install-info --version && \
+ install-info --version | fgrep -i -v debian) >/dev/null 2>&1; then \
+ list='$(INFO_DEPS)'; \
+ for file in $$list; do \
+ echo " install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file";\
+ install-info --info-dir=$(DESTDIR)$(infodir) $(DESTDIR)$(infodir)/$$file || :;\
+ done; \
+ else : ; fi
+install-man:
+
+installcheck-am:
+
+maintainer-clean: maintainer-clean-am
+
+maintainer-clean-am: distclean-am maintainer-clean-aminfo \
+ maintainer-clean-generic maintainer-clean-vti
+
+mostlyclean: mostlyclean-am
+
+mostlyclean-am: mostlyclean-aminfo mostlyclean-generic mostlyclean-vti
+
+uninstall-am: uninstall-info-am
+
+.PHONY: all all-am check check-am clean clean-generic dist-info \
+ distclean distclean-generic distdir dvi dvi-am info info-am \
+ install install-am install-data install-data-am install-exec \
+ install-exec-am install-info install-info-am install-man \
+ install-strip installcheck installcheck-am installdirs \
+ maintainer-clean maintainer-clean-aminfo \
+ maintainer-clean-generic maintainer-clean-vti mostlyclean \
+ mostlyclean-aminfo mostlyclean-generic mostlyclean-vti \
+ uninstall uninstall-am uninstall-info-am
+
+# Tell versions [3.59,3.63) of GNU make to not export all variables.
+# Otherwise a system limit (for SysV at least) may be exceeded.
+.NOEXPORT:
diff --git a/external/gpl2/diffutils/dist/doc/diagmeet.note b/external/gpl2/diffutils/dist/doc/diagmeet.note
new file mode 100644
index 00000000000..8f7242c7356
--- /dev/null
+++ b/external/gpl2/diffutils/dist/doc/diagmeet.note
@@ -0,0 +1,71 @@
+Here is a comparison matrix which shows a case in which
+it is possible for the forward and backward scan in `diag'
+to meet along a nonzero length of diagonal simultaneous
+(so that bdiag[d] and fdiag[d] are not equal)
+even though there is no snake on that diagonal at the meeting point.
+
+
+ 85 1 1 1 159 1 1 17
+ 1 2 3 4
+60
+ 1 2
+1
+ 2 2 3 4
+71
+ 3 3 4 5
+85
+ 4 3 4 5
+17
+ 5 4 5
+1
+ 6 4 5 6
+183
+ 7 5 6 7
+10
+ 8 6 7
+1
+ 9 6 7 8
+12
+ 7 8 9 10
+13
+ 10 8 9 10
+14
+ 10 9 10
+17
+ 10 10
+1
+ 10 9 10
+1
+ 8 10 10 10
+183
+ 8 7 9 9 9
+10
+ 7 6 8 9 8 8
+1
+ 6 5 7 7
+1
+ 5 6 6
+1
+ 5 5 5
+50
+ 5 4 4 4
+1
+ 4 3 3
+85
+ 5 4 3 2 2
+1
+ 2 1
+17
+ 5 4 3 2 1 1
+1
+ 1 0
+ 85 1 1 1 159 1 1 17
+
+
+
+
+
+
+
+
+
diff --git a/external/gpl2/diffutils/dist/doc/diff.info b/external/gpl2/diffutils/dist/doc/diff.info
new file mode 100644
index 00000000000..d58accf7ea9
--- /dev/null
+++ b/external/gpl2/diffutils/dist/doc/diff.info
@@ -0,0 +1,5084 @@
+This is diff.info, produced by makeinfo version 4.2 from diff.texi.
+
+This manual is for GNU Diffutils (version 2.8.1, 5 April 2002), and
+documents the GNU `diff', `diff3', `sdiff', and `cmp' commands for
+showing the differences between files and the GNU `patch' command for
+using their output to update files.
+
+ Copyright (C) 1992, 1993, 1994, 1998, 2001, 2002 Free Software
+Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.1 or any later version published by the Free Software
+ Foundation; with no Invariant Sections, with the Front-Cover texts
+ being "A GNU Manual," and with the Back-Cover Texts as in (a)
+ below. A copy of the license is included in the section entitled
+ "GNU Free Documentation License."
+
+ (a) The FSF's Back-Cover Text is: "You have freedom to copy and
+ modify this GNU Manual, like GNU software. Copies published by
+ the Free Software Foundation raise funds for GNU development."
+
+INFO-DIR-SECTION Individual utilities
+START-INFO-DIR-ENTRY
+* cmp: (diff)Invoking cmp. Compare 2 files byte by byte.
+* diff: (diff)Invoking diff. Compare 2 files line by line.
+* diff3: (diff)Invoking diff3. Compare 3 files line by line.
+* patch: (diff)Invoking patch. Apply a patch to a file.
+* sdiff: (diff)Invoking sdiff. Merge 2 files side-by-side.
+END-INFO-DIR-ENTRY
+
+INFO-DIR-SECTION GNU packages
+START-INFO-DIR-ENTRY
+* Diff: (diff). Comparing and merging files.
+END-INFO-DIR-ENTRY
+
+
+File: diff.info, Node: Top, Next: Overview, Up: (dir)
+
+Comparing and Merging Files
+***************************
+
+This manual is for GNU Diffutils (version 2.8.1, 5 April 2002), and
+documents the GNU `diff', `diff3', `sdiff', and `cmp' commands for
+showing the differences between files and the GNU `patch' command for
+using their output to update files.
+
+ Copyright (C) 1992, 1993, 1994, 1998, 2001, 2002 Free Software
+Foundation, Inc.
+
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the GNU Free Documentation License,
+ Version 1.1 or any later version published by the Free Software
+ Foundation; with no Invariant Sections, with the Front-Cover texts
+ being "A GNU Manual," and with the Back-Cover Texts as in (a)
+ below. A copy of the license is included in the section entitled
+ "GNU Free Documentation License."
+
+ (a) The FSF's Back-Cover Text is: "You have freedom to copy and
+ modify this GNU Manual, like GNU software. Copies published by
+ the Free Software Foundation raise funds for GNU development."
+
+* Menu:
+
+* Overview:: Preliminary information.
+* Comparison:: What file comparison means.
+
+* Output Formats:: Formats for two-way difference reports.
+* Incomplete Lines:: Lines that lack trailing newlines.
+* Comparing Directories:: Comparing files and directories.
+* Adjusting Output:: Making `diff' output prettier.
+* diff Performance:: Making `diff' smarter or faster.
+
+* Comparing Three Files:: Formats for three-way difference reports.
+* diff3 Merging:: Merging from a common ancestor.
+
+* Interactive Merging:: Interactive merging with `sdiff'.
+
+* Merging with patch:: Using `patch' to change old files into new ones.
+* Making Patches:: Tips for making and using patch distributions.
+
+* Invoking cmp:: Compare two files byte by byte.
+* Invoking diff:: Compare two files line by line.
+* Invoking diff3:: Compare three files line by line.
+* Invoking patch:: Apply a diff file to an original.
+* Invoking sdiff:: Side-by-side merge of file differences.
+
+* Standards conformance:: Conformance to the POSIX standard.
+* Projects:: If you've found a bug or other shortcoming.
+
+* Copying This Manual:: How to make copies of this manual.
+* Index:: Index.
+
+
+File: diff.info, Node: Overview, Next: Comparison, Prev: Top, Up: Top
+
+Overview
+********
+
+ Computer users often find occasion to ask how two files differ.
+Perhaps one file is a newer version of the other file. Or maybe the
+two files started out as identical copies but were changed by different
+people.
+
+ You can use the `diff' command to show differences between two
+files, or each corresponding file in two directories. `diff' outputs
+differences between files line by line in any of several formats,
+selectable by command line options. This set of differences is often
+called a "diff" or "patch". For files that are identical, `diff'
+normally produces no output; for binary (non-text) files, `diff'
+normally reports only that they are different.
+
+ You can use the `cmp' command to show the byte and line numbers
+where two files differ. `cmp' can also show all the bytes that differ
+between the two files, side by side. A way to compare two files
+character by character is the Emacs command `M-x compare-windows'.
+*Note Other Window: (emacs)Other Window, for more information on that
+command.
+
+ You can use the `diff3' command to show differences among three
+files. When two people have made independent changes to a common
+original, `diff3' can report the differences between the original and
+the two changed versions, and can produce a merged file that contains
+both persons' changes together with warnings about conflicts.
+
+ You can use the `sdiff' command to merge two files interactively.
+
+ You can use the set of differences produced by `diff' to distribute
+updates to text files (such as program source code) to other people.
+This method is especially useful when the differences are small compared
+to the complete files. Given `diff' output, you can use the `patch'
+program to update, or "patch", a copy of the file. If you think of
+`diff' as subtracting one file from another to produce their
+difference, you can think of `patch' as adding the difference to one
+file to reproduce the other.
+
+ This manual first concentrates on making diffs, and later shows how
+to use diffs to update files.
+
+ GNU `diff' was written by Paul Eggert, Mike Haertel, David Hayes,
+Richard Stallman, and Len Tower. Wayne Davison designed and
+implemented the unified output format. The basic algorithm is described
+in "An O(ND) Difference Algorithm and its Variations", Eugene W. Myers,
+`Algorithmica' Vol. 1 No. 2, 1986, pp. 251-266; and in "A File
+Comparison Program", Webb Miller and Eugene W. Myers,
+`Software--Practice and Experience' Vol. 15 No. 11, 1985, pp. 1025-1040.
+The algorithm was independently discovered as described in "Algorithms
+for Approximate String Matching", E. Ukkonen, `Information and Control'
+Vol. 64, 1985, pp. 100-118.
+
+ GNU `diff3' was written by Randy Smith. GNU `sdiff' was written by
+Thomas Lord. GNU `cmp' was written by Torbjorn Granlund and David
+MacKenzie.
+
+ `patch' was written mainly by Larry Wall and Paul Eggert; several
+GNU enhancements were contributed by Wayne Davison and David MacKenzie.
+Parts of this manual are adapted from a manual page written by Larry
+Wall, with his permission.
+
+
+File: diff.info, Node: Comparison, Next: Output Formats, Prev: Overview, Up: Top
+
+What Comparison Means
+*********************
+
+ There are several ways to think about the differences between two
+files. One way to think of the differences is as a series of lines
+that were deleted from, inserted in, or changed in one file to produce
+the other file. `diff' compares two files line by line, finds groups of
+lines that differ, and reports each group of differing lines. It can
+report the differing lines in several formats, which have different
+purposes.
+
+ GNU `diff' can show whether files are different without detailing
+the differences. It also provides ways to suppress certain kinds of
+differences that are not important to you. Most commonly, such
+differences are changes in the amount of white space between words or
+lines. `diff' also provides ways to suppress differences in alphabetic
+case or in lines that match a regular expression that you provide.
+These options can accumulate; for example, you can ignore changes in
+both white space and alphabetic case.
+
+ Another way to think of the differences between two files is as a
+sequence of pairs of bytes that can be either identical or different.
+`cmp' reports the differences between two files byte by byte, instead
+of line by line. As a result, it is often more useful than `diff' for
+comparing binary files. For text files, `cmp' is useful mainly when
+you want to know only whether two files are identical, or whether one
+file is a prefix of the other.
+
+ To illustrate the effect that considering changes byte by byte can
+have compared with considering them line by line, think of what happens
+if a single newline character is added to the beginning of a file. If
+that file is then compared with an otherwise identical file that lacks
+the newline at the beginning, `diff' will report that a blank line has
+been added to the file, while `cmp' will report that almost every byte
+of the two files differs.
+
+ `diff3' normally compares three input files line by line, finds
+groups of lines that differ, and reports each group of differing lines.
+Its output is designed to make it easy to inspect two different sets of
+changes to the same file.
+
+* Menu:
+
+* Hunks:: Groups of differing lines.
+* White Space:: Suppressing differences in white space.
+* Blank Lines:: Suppressing differences in blank lines.
+* Case Folding:: Suppressing differences in alphabetic case.
+* Specified Folding:: Suppressing differences that match regular expressions.
+* Brief:: Summarizing which files are different.
+* Binary:: Comparing binary files or forcing text comparisons.
+
+
+File: diff.info, Node: Hunks, Next: White Space, Up: Comparison
+
+Hunks
+=====
+
+ When comparing two files, `diff' finds sequences of lines common to
+both files, interspersed with groups of differing lines called "hunks".
+Comparing two identical files yields one sequence of common lines and
+no hunks, because no lines differ. Comparing two entirely different
+files yields no common lines and one large hunk that contains all lines
+of both files. In general, there are many ways to match up lines
+between two given files. `diff' tries to minimize the total hunk size
+by finding large sequences of common lines interspersed with small
+hunks of differing lines.
+
+ For example, suppose the file `F' contains the three lines `a', `b',
+`c', and the file `G' contains the same three lines in reverse order
+`c', `b', `a'. If `diff' finds the line `c' as common, then the command
+`diff F G' produces this output:
+
+ 1,2d0
+ < a
+ < b
+ 3a2,3
+ > b
+ > a
+
+But if `diff' notices the common line `b' instead, it produces this
+output:
+
+ 1c1
+ < a
+ ---
+ > c
+ 3c3
+ < c
+ ---
+ > a
+
+It is also possible to find `a' as the common line. `diff' does not
+always find an optimal matching between the files; it takes shortcuts
+to run faster. But its output is usually close to the shortest
+possible. You can adjust this tradeoff with the `--minimal' option
+(*note diff Performance::).
+
+
+File: diff.info, Node: White Space, Next: Blank Lines, Prev: Hunks, Up: Comparison
+
+Suppressing Differences in Blank and Tab Spacing
+================================================
+
+ The `-E' and `--ignore-tab-expansion' options ignore the distinction
+between tabs and spaces on input. A tab is considered to be equivalent
+to the number of spaces to the next tab stop. `diff' assumes that tab
+stops are set every 8 print columns.
+
+ The `-b' and `--ignore-space-change' options are stronger. They
+ignore white space at line end, and consider all other sequences of one
+or more white space characters to be equivalent. With these options,
+`diff' considers the following two lines to be equivalent, where `$'
+denotes the line end:
+
+ Here lyeth muche rychnesse in lytell space. -- John Heywood$
+ Here lyeth muche rychnesse in lytell space. -- John Heywood $
+
+ The `-w' and `--ignore-all-space' options are stronger still. They
+ignore difference even if one line has white space where the other line
+has none. "White space" characters include tab, newline, vertical tab,
+form feed, carriage return, and space; some locales may define
+additional characters to be white space. With these options, `diff'
+considers the following two lines to be equivalent, where `$' denotes
+the line end and `^M' denotes a carriage return:
+
+ Here lyeth muche rychnesse in lytell space.-- John Heywood$
+ He relyeth much erychnes seinly tells pace. --John Heywood ^M$
+
+
+File: diff.info, Node: Blank Lines, Next: Case Folding, Prev: White Space, Up: Comparison
+
+Suppressing Differences in Blank Lines
+======================================
+
+ The `-B' and `--ignore-blank-lines' options ignore insertions or
+deletions of blank lines. These options affect only lines that are
+completely empty; they do not affect lines that look empty but contain
+space or tab characters. With these options, for example, a file
+containing
+ 1. A point is that which has no part.
+
+ 2. A line is breadthless length.
+ -- Euclid, The Elements, I
+
+is considered identical to a file containing
+ 1. A point is that which has no part.
+ 2. A line is breadthless length.
+
+
+ -- Euclid, The Elements, I
+
+
+File: diff.info, Node: Case Folding, Next: Specified Folding, Prev: Blank Lines, Up: Comparison
+
+Suppressing Case Differences
+============================
+
+ GNU `diff' can treat lower case letters as equivalent to their upper
+case counterparts, so that, for example, it considers `Funky Stuff',
+`funky STUFF', and `fUNKy stuFf' to all be the same. To request this,
+use the `-i' or `--ignore-case' option.
+
+
+File: diff.info, Node: Specified Folding, Next: Brief, Prev: Case Folding, Up: Comparison
+
+Suppressing Lines Matching a Regular Expression
+===============================================
+
+ To ignore insertions and deletions of lines that match a
+`grep'-style regular expression, use the `-I REGEXP' or
+`--ignore-matching-lines=REGEXP' option. You should escape regular
+expressions that contain shell metacharacters to prevent the shell from
+expanding them. For example, `diff -I '^[[:digit:]]'' ignores all
+changes to lines beginning with a digit.
+
+ However, `-I' only ignores the insertion or deletion of lines that
+contain the regular expression if every changed line in the hunk--every
+insertion and every deletion--matches the regular expression. In other
+words, for each nonignorable change, `diff' prints the complete set of
+changes in its vicinity, including the ignorable ones.
+
+ You can specify more than one regular expression for lines to ignore
+by using more than one `-I' option. `diff' tries to match each line
+against each regular expression.
+
+
+File: diff.info, Node: Brief, Next: Binary, Prev: Specified Folding, Up: Comparison
+
+Summarizing Which Files Differ
+==============================
+
+ When you only want to find out whether files are different, and you
+don't care what the differences are, you can use the summary output
+format. In this format, instead of showing the differences between the
+files, `diff' simply reports whether files differ. The `-q' and
+`--brief' options select this output format.
+
+ This format is especially useful when comparing the contents of two
+directories. It is also much faster than doing the normal line by line
+comparisons, because `diff' can stop analyzing the files as soon as it
+knows that there are any differences.
+
+ You can also get a brief indication of whether two files differ by
+using `cmp'. For files that are identical, `cmp' produces no output.
+When the files differ, by default, `cmp' outputs the byte and line
+number where the first difference occurs. You can use the `-s' option
+to suppress that information, so that `cmp' produces no output and
+reports whether the files differ using only its exit status (*note
+Invoking cmp::).
+
+ Unlike `diff', `cmp' cannot compare directories; it can only compare
+two files.
+
+
+File: diff.info, Node: Binary, Prev: Brief, Up: Comparison
+
+Binary Files and Forcing Text Comparisons
+=========================================
+
+ If `diff' thinks that either of the two files it is comparing is
+binary (a non-text file), it normally treats that pair of files much as
+if the summary output format had been selected (*note Brief::), and
+reports only that the binary files are different. This is because line
+by line comparisons are usually not meaningful for binary files.
+
+ `diff' determines whether a file is text or binary by checking the
+first few bytes in the file; the exact number of bytes is system
+dependent, but it is typically several thousand. If every byte in that
+part of the file is non-null, `diff' considers the file to be text;
+otherwise it considers the file to be binary.
+
+ Sometimes you might want to force `diff' to consider files to be
+text. For example, you might be comparing text files that contain null
+characters; `diff' would erroneously decide that those are non-text
+files. Or you might be comparing documents that are in a format used
+by a word processing system that uses null characters to indicate
+special formatting. You can force `diff' to consider all files to be
+text files, and compare them line by line, by using the `-a' or
+`--text' option. If the files you compare using this option do not in
+fact contain text, they will probably contain few newline characters,
+and the `diff' output will consist of hunks showing differences between
+long lines of whatever characters the files contain.
+
+ You can also force `diff' to consider all files to be binary files,
+and report only whether they differ (but not how). Use the `-q' or
+`--brief' option for this.
+
+ Differing binary files are considered to cause trouble because the
+resulting `diff' output does not capture all the differences. This
+trouble causes `diff' to exit with status 2. However, this trouble
+cannot occur with the `--a' or `--text' option, or with the `-q' or
+`--brief' option, as these options both cause `diff' to treat binary
+files like text files.
+
+ In operating systems that distinguish between text and binary files,
+`diff' normally reads and writes all data as text. Use the `--binary'
+option to force `diff' to read and write binary data instead. This
+option has no effect on a POSIX-compliant system like GNU or
+traditional Unix. However, many personal computer operating systems
+represent the end of a line with a carriage return followed by a
+newline. On such systems, `diff' normally ignores these carriage
+returns on input and generates them at the end of each output line, but
+with the `--binary' option `diff' treats each carriage return as just
+another input character, and does not generate a carriage return at the
+end of each output line. This can be useful when dealing with non-text
+files that are meant to be interchanged with POSIX-compliant systems.
+
+ The `--strip-trailing-cr' causes `diff' to treat input lines that
+end in carriage return followed by newline as if they end in plain
+newline. This can be useful when comparing text that is imperfectly
+imported from many personal computer operating systems. This option
+affects how lines are read, which in turn affects how they are compared
+and output.
+
+ If you want to compare two files byte by byte, you can use the `cmp'
+program with the `-l' option to show the values of each differing byte
+in the two files. With GNU `cmp', you can also use the `-b' option to
+show the ASCII representation of those bytes. *Note Invoking cmp::,
+for more information.
+
+ If `diff3' thinks that any of the files it is comparing is binary (a
+non-text file), it normally reports an error, because such comparisons
+are usually not useful. `diff3' uses the same test as `diff' to decide
+whether a file is binary. As with `diff', if the input files contain a
+few non-text bytes but otherwise are like text files, you can force
+`diff3' to consider all files to be text files and compare them line by
+line by using the `-a' or `--text' options.
+
+
+File: diff.info, Node: Output Formats, Next: Incomplete Lines, Prev: Comparison, Up: Top
+
+`diff' Output Formats
+*********************
+
+ `diff' has several mutually exclusive options for output format.
+The following sections describe each format, illustrating how `diff'
+reports the differences between two sample input files.
+
+* Menu:
+
+* Sample diff Input:: Sample `diff' input files for examples.
+* Normal:: Showing differences without surrounding text.
+* Context:: Showing differences with the surrounding text.
+* Side by Side:: Showing differences in two columns.
+* Scripts:: Generating scripts for other programs.
+* If-then-else:: Merging files with if-then-else.
+
+
+File: diff.info, Node: Sample diff Input, Next: Normal, Up: Output Formats
+
+Two Sample Input Files
+======================
+
+ Here are two sample files that we will use in numerous examples to
+illustrate the output of `diff' and how various options can change it.
+
+ This is the file `lao':
+
+ The Way that can be told of is not the eternal Way;
+ The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+ The Named is the mother of all things.
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+ so we may see their outcome.
+ The two are the same,
+ But after they are produced,
+ they have different names.
+
+ This is the file `tzu':
+
+ The Nameless is the origin of Heaven and Earth;
+ The named is the mother of all things.
+
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+ so we may see their outcome.
+ The two are the same,
+ But after they are produced,
+ they have different names.
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
+
+ In this example, the first hunk contains just the first two lines of
+`lao', the second hunk contains the fourth line of `lao' opposing the
+second and third lines of `tzu', and the last hunk contains just the
+last three lines of `tzu'.
+
+
+File: diff.info, Node: Normal, Next: Context, Prev: Sample diff Input, Up: Output Formats
+
+Showing Differences Without Context
+===================================
+
+ The "normal" `diff' output format shows each hunk of differences
+without any surrounding context. Sometimes such output is the clearest
+way to see how lines have changed, without the clutter of nearby
+unchanged lines (although you can get similar results with the context
+or unified formats by using 0 lines of context). However, this format
+is no longer widely used for sending out patches; for that purpose, the
+context format (*note Context Format::) and the unified format (*note
+Unified Format::) are superior. Normal format is the default for
+compatibility with older versions of `diff' and the POSIX standard.
+Use the `--normal' option to select this output format explicitly.
+
+* Menu:
+
+* Detailed Normal:: A detailed description of normal output format.
+* Example Normal:: Sample output in the normal format.
+
+
+File: diff.info, Node: Detailed Normal, Next: Example Normal, Up: Normal
+
+Detailed Description of Normal Format
+-------------------------------------
+
+ The normal output format consists of one or more hunks of
+differences; each hunk shows one area where the files differ. Normal
+format hunks look like this:
+
+ CHANGE-COMMAND
+ < FROM-FILE-LINE
+ < FROM-FILE-LINE...
+ ---
+ > TO-FILE-LINE
+ > TO-FILE-LINE...
+
+ There are three types of change commands. Each consists of a line
+number or comma-separated range of lines in the first file, a single
+character indicating the kind of change to make, and a line number or
+comma-separated range of lines in the second file. All line numbers are
+the original line numbers in each file. The types of change commands
+are:
+
+`LaR'
+ Add the lines in range R of the second file after line L of the
+ first file. For example, `8a12,15' means append lines 12-15 of
+ file 2 after line 8 of file 1; or, if changing file 2 into file 1,
+ delete lines 12-15 of file 2.
+
+`FcT'
+ Replace the lines in range F of the first file with lines in range
+ T of the second file. This is like a combined add and delete, but
+ more compact. For example, `5,7c8,10' means change lines 5-7 of
+ file 1 to read as lines 8-10 of file 2; or, if changing file 2 into
+ file 1, change lines 8-10 of file 2 to read as lines 5-7 of file 1.
+
+`RdL'
+ Delete the lines in range R from the first file; line L is where
+ they would have appeared in the second file had they not been
+ deleted. For example, `5,7d3' means delete lines 5-7 of file 1;
+ or, if changing file 2 into file 1, append lines 5-7 of file 1
+ after line 3 of file 2.
+
+
+File: diff.info, Node: Example Normal, Prev: Detailed Normal, Up: Normal
+
+An Example of Normal Format
+---------------------------
+
+ Here is the output of the command `diff lao tzu' (*note Sample diff
+Input::, for the complete contents of the two files). Notice that it
+shows only the lines that are different between the two files.
+
+ 1,2d0
+ < The Way that can be told of is not the eternal Way;
+ < The name that can be named is not the eternal name.
+ 4c2,3
+ < The Named is the mother of all things.
+ ---
+ > The named is the mother of all things.
+ >
+ 11a11,13
+ > They both may be called deep and profound.
+ > Deeper and more profound,
+ > The door of all subtleties!
+
+
+File: diff.info, Node: Context, Next: Side by Side, Prev: Normal, Up: Output Formats
+
+Showing Differences in Their Context
+====================================
+
+ Usually, when you are looking at the differences between files, you
+will also want to see the parts of the files near the lines that
+differ, to help you understand exactly what has changed. These nearby
+parts of the files are called the "context".
+
+ GNU `diff' provides two output formats that show context around the
+differing lines: "context format" and "unified format". It can
+optionally show in which function or section of the file the differing
+lines are found.
+
+ If you are distributing new versions of files to other people in the
+form of `diff' output, you should use one of the output formats that
+show context so that they can apply the diffs even if they have made
+small changes of their own to the files. `patch' can apply the diffs
+in this case by searching in the files for the lines of context around
+the differing lines; if those lines are actually a few lines away from
+where the diff says they are, `patch' can adjust the line numbers
+accordingly and still apply the diff correctly. *Note Imperfect::, for
+more information on using `patch' to apply imperfect diffs.
+
+* Menu:
+
+* Context Format:: An output format that shows surrounding lines.
+* Unified Format:: A more compact output format that shows context.
+* Sections:: Showing which sections of the files differences are in.
+* Alternate Names:: Showing alternate file names in context headers.
+
+
+File: diff.info, Node: Context Format, Next: Unified Format, Up: Context
+
+Context Format
+--------------
+
+ The context output format shows several lines of context around the
+lines that differ. It is the standard format for distributing updates
+to source code.
+
+ To select this output format, use the `-C LINES',
+`--context[=LINES]', or `-c' option. The argument LINES that some of
+these options take is the number of lines of context to show. If you
+do not specify LINES, it defaults to three. For proper operation,
+`patch' typically needs at least two lines of context.
+
+* Menu:
+
+* Detailed Context:: A detailed description of the context output format.
+* Example Context:: Sample output in context format.
+* Less Context:: Another sample with less context.
+
+
+File: diff.info, Node: Detailed Context, Next: Example Context, Up: Context Format
+
+Detailed Description of Context Format
+......................................
+
+ The context output format starts with a two-line header, which looks
+like this:
+
+ *** FROM-FILE FROM-FILE-MODIFICATION-TIME
+ --- TO-FILE TO-FILE-MODIFICATION TIME
+
+The time stamp normally looks like `2002-02-21 23:30:39.942229878
+-0800' to indicate the date, time with fractional seconds, and time
+zone in Internet RFC 2822 format
+(ftp://ftp.isi.edu/in-notes/rfc2822.txt). However, a traditional time
+stamp like `Thu Feb 21 23:30:39 2002' is used if the `LC_TIME' locale
+category is either `C' or `POSIX'.
+
+ You can change the header's content with the `--label=LABEL' option;
+see *Note Alternate Names::.
+
+ Next come one or more hunks of differences; each hunk shows one area
+where the files differ. Context format hunks look like this:
+
+ ***************
+ *** FROM-FILE-LINE-RANGE ****
+ FROM-FILE-LINE
+ FROM-FILE-LINE...
+ --- TO-FILE-LINE-RANGE ----
+ TO-FILE-LINE
+ TO-FILE-LINE...
+
+ The lines of context around the lines that differ start with two
+space characters. The lines that differ between the two files start
+with one of the following indicator characters, followed by a space
+character:
+
+`!'
+ A line that is part of a group of one or more lines that changed
+ between the two files. There is a corresponding group of lines
+ marked with `!' in the part of this hunk for the other file.
+
+`+'
+ An "inserted" line in the second file that corresponds to nothing
+ in the first file.
+
+`-'
+ A "deleted" line in the first file that corresponds to nothing in
+ the second file.
+
+ If all of the changes in a hunk are insertions, the lines of
+FROM-FILE are omitted. If all of the changes are deletions, the lines
+of TO-FILE are omitted.
+
+
+File: diff.info, Node: Example Context, Next: Less Context, Prev: Detailed Context, Up: Context Format
+
+An Example of Context Format
+............................
+
+ Here is the output of `diff -c lao tzu' (*note Sample diff Input::,
+for the complete contents of the two files). Notice that up to three
+lines that are not different are shown around each line that is
+different; they are the context lines. Also notice that the first two
+hunks have run together, because their contents overlap.
+
+ *** lao 2002-02-21 23:30:39.942229878 -0800
+ --- tzu 2002-02-21 23:30:50.442260588 -0800
+ ***************
+ *** 1,7 ****
+ - The Way that can be told of is not the eternal Way;
+ - The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+ ! The Named is the mother of all things.
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+ --- 1,6 ----
+ The Nameless is the origin of Heaven and Earth;
+ ! The named is the mother of all things.
+ !
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+ ***************
+ *** 9,11 ****
+ --- 8,13 ----
+ The two are the same,
+ But after they are produced,
+ they have different names.
+ + They both may be called deep and profound.
+ + Deeper and more profound,
+ + The door of all subtleties!
+
+
+File: diff.info, Node: Less Context, Prev: Example Context, Up: Context Format
+
+An Example of Context Format with Less Context
+..............................................
+
+ Here is the output of `diff -C 1 lao tzu' (*note Sample diff
+Input::, for the complete contents of the two files). Notice that at
+most one context line is reported here.
+
+ *** lao 2002-02-21 23:30:39.942229878 -0800
+ --- tzu 2002-02-21 23:30:50.442260588 -0800
+ ***************
+ *** 1,5 ****
+ - The Way that can be told of is not the eternal Way;
+ - The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+ ! The Named is the mother of all things.
+ Therefore let there always be non-being,
+ --- 1,4 ----
+ The Nameless is the origin of Heaven and Earth;
+ ! The named is the mother of all things.
+ !
+ Therefore let there always be non-being,
+ ***************
+ *** 11 ****
+ --- 10,13 ----
+ they have different names.
+ + They both may be called deep and profound.
+ + Deeper and more profound,
+ + The door of all subtleties!
+
+
+File: diff.info, Node: Unified Format, Next: Sections, Prev: Context Format, Up: Context
+
+Unified Format
+--------------
+
+ The unified output format is a variation on the context format that
+is more compact because it omits redundant context lines. To select
+this output format, use the `-U LINES', `--unified[=LINES]', or `-u'
+option. The argument LINES is the number of lines of context to show.
+When it is not given, it defaults to three.
+
+ At present, only GNU `diff' can produce this format and only GNU
+`patch' can automatically apply diffs in this format. For proper
+operation, `patch' typically needs at least three lines of context.
+
+* Menu:
+
+* Detailed Unified:: A detailed description of unified format.
+* Example Unified:: Sample output in unified format.
+
+
+File: diff.info, Node: Detailed Unified, Next: Example Unified, Up: Unified Format
+
+Detailed Description of Unified Format
+......................................
+
+ The unified output format starts with a two-line header, which looks
+like this:
+
+ --- FROM-FILE FROM-FILE-MODIFICATION-TIME
+ +++ TO-FILE TO-FILE-MODIFICATION-TIME
+
+The time stamp looks like `2002-02-21 23:30:39.942229878 -0800' to
+indicate the date, time with fractional seconds, and time zone.
+
+ You can change the header's content with the `--label=LABEL' option;
+see *Note Alternate Names::.
+
+ Next come one or more hunks of differences; each hunk shows one area
+where the files differ. Unified format hunks look like this:
+
+ @@ FROM-FILE-RANGE TO-FILE-RANGE @@
+ LINE-FROM-EITHER-FILE
+ LINE-FROM-EITHER-FILE...
+
+ The lines common to both files begin with a space character. The
+lines that actually differ between the two files have one of the
+following indicator characters in the left print column:
+
+`+'
+ A line was added here to the first file.
+
+`-'
+ A line was removed here from the first file.
+
+
+File: diff.info, Node: Example Unified, Prev: Detailed Unified, Up: Unified Format
+
+An Example of Unified Format
+............................
+
+ Here is the output of the command `diff -u lao tzu' (*note Sample
+diff Input::, for the complete contents of the two files):
+
+ --- lao 2002-02-21 23:30:39.942229878 -0800
+ +++ tzu 2002-02-21 23:30:50.442260588 -0800
+ @@ -1,7 +1,6 @@
+ -The Way that can be told of is not the eternal Way;
+ -The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+ -The Named is the mother of all things.
+ +The named is the mother of all things.
+ +
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+ @@ -9,3 +8,6 @@
+ The two are the same,
+ But after they are produced,
+ they have different names.
+ +They both may be called deep and profound.
+ +Deeper and more profound,
+ +The door of all subtleties!
+
+
+File: diff.info, Node: Sections, Next: Alternate Names, Prev: Unified Format, Up: Context
+
+Showing Which Sections Differences Are in
+-----------------------------------------
+
+ Sometimes you might want to know which part of the files each change
+falls in. If the files are source code, this could mean which function
+was changed. If the files are documents, it could mean which chapter or
+appendix was changed. GNU `diff' can show this by displaying the
+nearest section heading line that precedes the differing lines. Which
+lines are "section headings" is determined by a regular expression.
+
+* Menu:
+
+* Specified Headings:: Showing headings that match regular expressions.
+* C Function Headings:: Showing headings of C functions.
+
+
+File: diff.info, Node: Specified Headings, Next: C Function Headings, Up: Sections
+
+Showing Lines That Match Regular Expressions
+............................................
+
+ To show in which sections differences occur for files that are not
+source code for C or similar languages, use the `-F REGEXP' or
+`--show-function-line=REGEXP' option. `diff' considers lines that
+match the `grep'-style regular expression REGEXP to be the beginning of
+a section of the file. Here are suggested regular expressions for some
+common languages:
+
+`^[[:alpha:]$_]'
+ C, C++, Prolog
+
+`^('
+ Lisp
+
+`^@node'
+ Texinfo
+
+ This option does not automatically select an output format; in order
+to use it, you must select the context format (*note Context Format::)
+or unified format (*note Unified Format::). In other output formats it
+has no effect.
+
+ The `-F' and `--show-function-line' options find the nearest
+unchanged line that precedes each hunk of differences and matches the
+given regular expression. Then they add that line to the end of the
+line of asterisks in the context format, or to the `@@' line in unified
+format. If no matching line exists, they leave the output for that
+hunk unchanged. If that line is more than 40 characters long, they
+output only the first 40 characters. You can specify more than one
+regular expression for such lines; `diff' tries to match each line
+against each regular expression, starting with the last one given. This
+means that you can use `-p' and `-F' together, if you wish.
+
+
+File: diff.info, Node: C Function Headings, Prev: Specified Headings, Up: Sections
+
+Showing C Function Headings
+...........................
+
+ To show in which functions differences occur for C and similar
+languages, you can use the `-p' or `--show-c-function' option. This
+option automatically defaults to the context output format (*note
+Context Format::), with the default number of lines of context. You
+can override that number with `-C LINES' elsewhere in the command line.
+You can override both the format and the number with `-U LINES'
+elsewhere in the command line.
+
+ The `-p' and `--show-c-function' options are equivalent to `-F
+'^[[:alpha:]$_]'' if the unified format is specified, otherwise `-c -F
+'^[[:alpha:]$_]'' (*note Specified Headings::). GNU `diff' provides
+them for the sake of convenience.
+
+
+File: diff.info, Node: Alternate Names, Prev: Sections, Up: Context
+
+Showing Alternate File Names
+----------------------------
+
+ If you are comparing two files that have meaningless or uninformative
+names, you might want `diff' to show alternate names in the header of
+the context and unified output formats. To do this, use the
+`--label=LABEL' option. The first time you give this option, its
+argument replaces the name and date of the first file in the header;
+the second time, its argument replaces the name and date of the second
+file. If you give this option more than twice, `diff' reports an
+error. The `--label' option does not affect the file names in the `pr'
+header when the `-l' or `--paginate' option is used (*note
+Pagination::).
+
+ Here are the first two lines of the output from `diff -C 2
+--label=original --label=modified lao tzu':
+
+ *** original
+ --- modified
+
+
+File: diff.info, Node: Side by Side, Next: Scripts, Prev: Context, Up: Output Formats
+
+Showing Differences Side by Side
+================================
+
+ `diff' can produce a side by side difference listing of two files.
+The files are listed in two columns with a gutter between them. The
+gutter contains one of the following markers:
+
+white space
+ The corresponding lines are in common. That is, either the lines
+ are identical, or the difference is ignored because of one of the
+ `--ignore' options (*note White Space::).
+
+`|'
+ The corresponding lines differ, and they are either both complete
+ or both incomplete.
+
+`<'
+ The files differ and only the first file contains the line.
+
+`>'
+ The files differ and only the second file contains the line.
+
+`('
+ Only the first file contains the line, but the difference is
+ ignored.
+
+`)'
+ Only the second file contains the line, but the difference is
+ ignored.
+
+`\'
+ The corresponding lines differ, and only the first line is
+ incomplete.
+
+`/'
+ The corresponding lines differ, and only the second line is
+ incomplete.
+
+ Normally, an output line is incomplete if and only if the lines that
+it contains are incomplete; *Note Incomplete Lines::. However, when an
+output line represents two differing lines, one might be incomplete
+while the other is not. In this case, the output line is complete, but
+its the gutter is marked `\' if the first line is incomplete, `/' if
+the second line is.
+
+ Side by side format is sometimes easiest to read, but it has
+limitations. It generates much wider output than usual, and truncates
+lines that are too long to fit. Also, it relies on lining up output
+more heavily than usual, so its output looks particularly bad if you
+use varying width fonts, nonstandard tab stops, or nonprinting
+characters.
+
+ You can use the `sdiff' command to interactively merge side by side
+differences. *Note Interactive Merging::, for more information on
+merging files.
+
+* Menu:
+
+* Side by Side Format:: Controlling side by side output format.
+* Example Side by Side:: Sample side by side output.
+
+
+File: diff.info, Node: Side by Side Format, Next: Example Side by Side, Up: Side by Side
+
+Controlling Side by Side Format
+-------------------------------
+
+ The `-y' or `--side-by-side' option selects side by side format.
+Because side by side output lines contain two input lines, the output
+is wider than usual: normally 130 print columns, which can fit onto a
+traditional printer line. You can set the width of the output with the
+`-W COLUMNS' or `--width=COLUMNS' option. The output is split into two
+halves of equal width, separated by a small gutter to mark differences;
+the right half is aligned to a tab stop so that tabs line up. Input
+lines that are too long to fit in half of an output line are truncated
+for output.
+
+ The `--left-column' option prints only the left column of two common
+lines. The `--suppress-common-lines' option suppresses common lines
+entirely.
+
+
+File: diff.info, Node: Example Side by Side, Prev: Side by Side Format, Up: Side by Side
+
+An Example of Side by Side Format
+---------------------------------
+
+ Here is the output of the command `diff -y -W 72 lao tzu' (*note
+Sample diff Input::, for the complete contents of the two files).
+
+ The Way that can be told of is n <
+ The name that can be named is no <
+ The Nameless is the origin of He The Nameless is the origin of He
+ The Named is the mother of all t | The named is the mother of all t
+ >
+ Therefore let there always be no Therefore let there always be no
+ so we may see their subtlety, so we may see their subtlety,
+ And let there always be being, And let there always be being,
+ so we may see their outcome. so we may see their outcome.
+ The two are the same, The two are the same,
+ But after they are produced, But after they are produced,
+ they have different names. they have different names.
+ > They both may be called deep and
+ > Deeper and more profound,
+ > The door of all subtleties!
+
+
+File: diff.info, Node: Scripts, Next: If-then-else, Prev: Side by Side, Up: Output Formats
+
+Making Edit Scripts
+===================
+
+ Several output modes produce command scripts for editing FROM-FILE
+to produce TO-FILE.
+
+* Menu:
+
+* ed Scripts:: Using `diff' to produce commands for `ed'.
+* Forward ed:: Making forward `ed' scripts.
+* RCS:: A special `diff' output format used by RCS.
+
+
+File: diff.info, Node: ed Scripts, Next: Forward ed, Up: Scripts
+
+`ed' Scripts
+------------
+
+ `diff' can produce commands that direct the `ed' text editor to
+change the first file into the second file. Long ago, this was the
+only output mode that was suitable for editing one file into another
+automatically; today, with `patch', it is almost obsolete. Use the
+`-e' or `--ed' option to select this output format.
+
+ Like the normal format (*note Normal::), this output format does not
+show any context; unlike the normal format, it does not include the
+information necessary to apply the diff in reverse (to produce the first
+file if all you have is the second file and the diff).
+
+ If the file `d' contains the output of `diff -e old new', then the
+command `(cat d && echo w) | ed - old' edits `old' to make it a copy of
+`new'. More generally, if `d1', `d2', ..., `dN' contain the outputs of
+`diff -e old new1', `diff -e new1 new2', ..., `diff -e newN-1 newN',
+respectively, then the command `(cat d1 d2 ... dN && echo w) | ed -
+old' edits `old' to make it a copy of `newN'.
+
+* Menu:
+
+* Detailed ed:: A detailed description of `ed' format.
+* Example ed:: A sample `ed' script.
+
+
+File: diff.info, Node: Detailed ed, Next: Example ed, Up: ed Scripts
+
+Detailed Description of `ed' Format
+...................................
+
+ The `ed' output format consists of one or more hunks of differences.
+The changes closest to the ends of the files come first so that
+commands that change the number of lines do not affect how `ed'
+interprets line numbers in succeeding commands. `ed' format hunks look
+like this:
+
+ CHANGE-COMMAND
+ TO-FILE-LINE
+ TO-FILE-LINE...
+ .
+
+ Because `ed' uses a single period on a line to indicate the end of
+input, GNU `diff' protects lines of changes that contain a single
+period on a line by writing two periods instead, then writing a
+subsequent `ed' command to change the two periods into one. The `ed'
+format cannot represent an incomplete line, so if the second file ends
+in a changed incomplete line, `diff' reports an error and then pretends
+that a newline was appended.
+
+ There are three types of change commands. Each consists of a line
+number or comma-separated range of lines in the first file and a single
+character indicating the kind of change to make. All line numbers are
+the original line numbers in the file. The types of change commands
+are:
+
+`La'
+ Add text from the second file after line L in the first file. For
+ example, `8a' means to add the following lines after line 8 of file
+ 1.
+
+`Rc'
+ Replace the lines in range R in the first file with the following
+ lines. Like a combined add and delete, but more compact. For
+ example, `5,7c' means change lines 5-7 of file 1 to read as the
+ text file 2.
+
+`Rd'
+ Delete the lines in range R from the first file. For example,
+ `5,7d' means delete lines 5-7 of file 1.
+
+
+File: diff.info, Node: Example ed, Prev: Detailed ed, Up: ed Scripts
+
+Example `ed' Script
+...................
+
+ Here is the output of `diff -e lao tzu' (*note Sample diff Input::,
+for the complete contents of the two files):
+
+ 11a
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
+ .
+ 4c
+ The named is the mother of all things.
+
+ .
+ 1,2d
+
+
+File: diff.info, Node: Forward ed, Next: RCS, Prev: ed Scripts, Up: Scripts
+
+Forward `ed' Scripts
+--------------------
+
+ `diff' can produce output that is like an `ed' script, but with
+hunks in forward (front to back) order. The format of the commands is
+also changed slightly: command characters precede the lines they
+modify, spaces separate line numbers in ranges, and no attempt is made
+to disambiguate hunk lines consisting of a single period. Like `ed'
+format, forward `ed' format cannot represent incomplete lines.
+
+ Forward `ed' format is not very useful, because neither `ed' nor
+`patch' can apply diffs in this format. It exists mainly for
+compatibility with older versions of `diff'. Use the `-f' or
+`--forward-ed' option to select it.
+
+
+File: diff.info, Node: RCS, Prev: Forward ed, Up: Scripts
+
+RCS Scripts
+-----------
+
+ The RCS output format is designed specifically for use by the
+Revision Control System, which is a set of free programs used for
+organizing different versions and systems of files. Use the `-n' or
+`--rcs' option to select this output format. It is like the forward
+`ed' format (*note Forward ed::), but it can represent arbitrary
+changes to the contents of a file because it avoids the forward `ed'
+format's problems with lines consisting of a single period and with
+incomplete lines. Instead of ending text sections with a line
+consisting of a single period, each command specifies the number of
+lines it affects; a combination of the `a' and `d' commands are used
+instead of `c'. Also, if the second file ends in a changed incomplete
+line, then the output also ends in an incomplete line.
+
+ Here is the output of `diff -n lao tzu' (*note Sample diff Input::,
+for the complete contents of the two files):
+
+ d1 2
+ d4 1
+ a4 2
+ The named is the mother of all things.
+
+ a11 3
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
+
+
+File: diff.info, Node: If-then-else, Prev: Scripts, Up: Output Formats
+
+Merging Files with If-then-else
+===============================
+
+ You can use `diff' to merge two files of C source code. The output
+of `diff' in this format contains all the lines of both files. Lines
+common to both files are output just once; the differing parts are
+separated by the C preprocessor directives `#ifdef NAME' or `#ifndef
+NAME', `#else', and `#endif'. When compiling the output, you select
+which version to use by either defining or leaving undefined the macro
+NAME.
+
+ To merge two files, use `diff' with the `-D NAME' or `--ifdef=NAME'
+option. The argument NAME is the C preprocessor identifier to use in
+the `#ifdef' and `#ifndef' directives.
+
+ For example, if you change an instance of `wait (&s)' to `waitpid
+(-1, &s, 0)' and then merge the old and new files with the
+`--ifdef=HAVE_WAITPID' option, then the affected part of your code
+might look like this:
+
+ do {
+ #ifndef HAVE_WAITPID
+ if ((w = wait (&s)) < 0 && errno != EINTR)
+ #else /* HAVE_WAITPID */
+ if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR)
+ #endif /* HAVE_WAITPID */
+ return w;
+ } while (w != child);
+
+ You can specify formats for languages other than C by using line
+group formats and line formats, as described in the next sections.
+
+* Menu:
+
+* Line Group Formats:: Formats for general if-then-else line groups.
+* Line Formats:: Formats for each line in a line group.
+* Detailed If-then-else:: A detailed description of if-then-else format.
+* Example If-then-else:: Sample if-then-else format output.
+
+
+File: diff.info, Node: Line Group Formats, Next: Line Formats, Up: If-then-else
+
+Line Group Formats
+------------------
+
+ Line group formats let you specify formats suitable for many
+applications that allow if-then-else input, including programming
+languages and text formatting languages. A line group format specifies
+the output format for a contiguous group of similar lines.
+
+ For example, the following command compares the TeX files `old' and
+`new', and outputs a merged file in which old regions are surrounded by
+`\begin{em}'-`\end{em}' lines, and new regions are surrounded by
+`\begin{bf}'-`\end{bf}' lines.
+
+ diff \
+ --old-group-format='\begin{em}
+ %<\end{em}
+ ' \
+ --new-group-format='\begin{bf}
+ %>\end{bf}
+ ' \
+ old new
+
+ The following command is equivalent to the above example, but it is a
+little more verbose, because it spells out the default line group
+formats.
+
+ diff \
+ --old-group-format='\begin{em}
+ %<\end{em}
+ ' \
+ --new-group-format='\begin{bf}
+ %>\end{bf}
+ ' \
+ --unchanged-group-format='%=' \
+ --changed-group-format='\begin{em}
+ %<\end{em}
+ \begin{bf}
+ %>\end{bf}
+ ' \
+ old new
+
+ Here is a more advanced example, which outputs a diff listing with
+headers containing line numbers in a "plain English" style.
+
+ diff \
+ --unchanged-group-format='' \
+ --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
+ %<' \
+ --new-group-format='-------- %dN line%(N=1?:s) added after %de:
+ %>' \
+ --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
+ %<-------- to:
+ %>' \
+ old new
+
+ To specify a line group format, use `diff' with one of the options
+listed below. You can specify up to four line group formats, one for
+each kind of line group. You should quote FORMAT, because it typically
+contains shell metacharacters.
+
+`--old-group-format=FORMAT'
+ These line groups are hunks containing only lines from the first
+ file. The default old group format is the same as the changed
+ group format if it is specified; otherwise it is a format that
+ outputs the line group as-is.
+
+`--new-group-format=FORMAT'
+ These line groups are hunks containing only lines from the second
+ file. The default new group format is same as the changed group
+ format if it is specified; otherwise it is a format that outputs
+ the line group as-is.
+
+`--changed-group-format=FORMAT'
+ These line groups are hunks containing lines from both files. The
+ default changed group format is the concatenation of the old and
+ new group formats.
+
+`--unchanged-group-format=FORMAT'
+ These line groups contain lines common to both files. The default
+ unchanged group format is a format that outputs the line group
+ as-is.
+
+ In a line group format, ordinary characters represent themselves;
+conversion specifications start with `%' and have one of the following
+forms.
+
+`%<'
+ stands for the lines from the first file, including the trailing
+ newline. Each line is formatted according to the old line format
+ (*note Line Formats::).
+
+`%>'
+ stands for the lines from the second file, including the trailing
+ newline. Each line is formatted according to the new line format.
+
+`%='
+ stands for the lines common to both files, including the trailing
+ newline. Each line is formatted according to the unchanged line
+ format.
+
+`%%'
+ stands for `%'.
+
+`%c'C''
+ where C is a single character, stands for C. C may not be a
+ backslash or an apostrophe. For example, `%c':'' stands for a
+ colon, even inside the then-part of an if-then-else format, which
+ a colon would normally terminate.
+
+`%c'\O''
+ where O is a string of 1, 2, or 3 octal digits, stands for the
+ character with octal code O. For example, `%c'\0'' stands for a
+ null character.
+
+`FN'
+ where F is a `printf' conversion specification and N is one of the
+ following letters, stands for N's value formatted with F.
+
+ `e'
+ The line number of the line just before the group in the old
+ file.
+
+ `f'
+ The line number of the first line in the group in the old
+ file; equals E + 1.
+
+ `l'
+ The line number of the last line in the group in the old file.
+
+ `m'
+ The line number of the line just after the group in the old
+ file; equals L + 1.
+
+ `n'
+ The number of lines in the group in the old file; equals L -
+ F + 1.
+
+ `E, F, L, M, N'
+ Likewise, for lines in the new file.
+
+ The `printf' conversion specification can be `%d', `%o', `%x', or
+ `%X', specifying decimal, octal, lower case hexadecimal, or upper
+ case hexadecimal output respectively. After the `%' the following
+ options can appear in sequence: a series of zero or more flags; an
+ integer specifying the minimum field width; and a period followed
+ by an optional integer specifying the minimum number of digits.
+ The flags are `-' for left-justification, `'' for separating the
+ digit into groups as specified by the `LC_NUMERIC' locale category,
+ and `0' for padding with zeros instead of spaces. For example,
+ `%5dN' prints the number of new lines in the group in a field of
+ width 5 characters, using the `printf' format `"%5d"'.
+
+`(A=B?T:E)'
+ If A equals B then T else E. A and B are each either a decimal
+ constant or a single letter interpreted as above. This format
+ spec is equivalent to T if A's value equals B's; otherwise it is
+ equivalent to E.
+
+ For example, `%(N=0?no:%dN) line%(N=1?:s)' is equivalent to `no
+ lines' if N (the number of lines in the group in the the new file)
+ is 0, to `1 line' if N is 1, and to `%dN lines' otherwise.
+
+
+File: diff.info, Node: Line Formats, Next: Detailed If-then-else, Prev: Line Group Formats, Up: If-then-else
+
+Line Formats
+------------
+
+ Line formats control how each line taken from an input file is
+output as part of a line group in if-then-else format.
+
+ For example, the following command outputs text with a one-character
+change indicator to the left of the text. The first character of output
+is `-' for deleted lines, `|' for added lines, and a space for
+unchanged lines. The formats contain newline characters where newlines
+are desired on output.
+
+ diff \
+ --old-line-format='-%l
+ ' \
+ --new-line-format='|%l
+ ' \
+ --unchanged-line-format=' %l
+ ' \
+ old new
+
+ To specify a line format, use one of the following options. You
+should quote FORMAT, since it often contains shell metacharacters.
+
+`--old-line-format=FORMAT'
+ formats lines just from the first file.
+
+`--new-line-format=FORMAT'
+ formats lines just from the second file.
+
+`--unchanged-line-format=FORMAT'
+ formats lines common to both files.
+
+`--line-format=FORMAT'
+ formats all lines; in effect, it sets all three above options
+ simultaneously.
+
+ In a line format, ordinary characters represent themselves;
+conversion specifications start with `%' and have one of the following
+forms.
+
+`%l'
+ stands for the contents of the line, not counting its trailing
+ newline (if any). This format ignores whether the line is
+ incomplete; *Note Incomplete Lines::.
+
+`%L'
+ stands for the contents of the line, including its trailing newline
+ (if any). If a line is incomplete, this format preserves its
+ incompleteness.
+
+`%%'
+ stands for `%'.
+
+`%c'C''
+ where C is a single character, stands for C. C may not be a
+ backslash or an apostrophe. For example, `%c':'' stands for a
+ colon.
+
+`%c'\O''
+ where O is a string of 1, 2, or 3 octal digits, stands for the
+ character with octal code O. For example, `%c'\0'' stands for a
+ null character.
+
+`Fn'
+ where F is a `printf' conversion specification, stands for the
+ line number formatted with F. For example, `%.5dn' prints the
+ line number using the `printf' format `"%.5d"'. *Note Line Group
+ Formats::, for more about printf conversion specifications.
+
+ The default line format is `%l' followed by a newline character.
+
+ If the input contains tab characters and it is important that they
+line up on output, you should ensure that `%l' or `%L' in a line format
+is just after a tab stop (e.g. by preceding `%l' or `%L' with a tab
+character), or you should use the `-t' or `--expand-tabs' option.
+
+ Taken together, the line and line group formats let you specify many
+different formats. For example, the following command uses a format
+similar to normal `diff' format. You can tailor this command to get
+fine control over `diff' output.
+
+ diff \
+ --old-line-format='< %l
+ ' \
+ --new-line-format='> %l
+ ' \
+ --old-group-format='%df%(f=l?:,%dl)d%dE
+ %<' \
+ --new-group-format='%dea%dF%(F=L?:,%dL)
+ %>' \
+ --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
+ %<---
+ %>' \
+ --unchanged-group-format='' \
+ old new
+
+
+File: diff.info, Node: Detailed If-then-else, Next: Example If-then-else, Prev: Line Formats, Up: If-then-else
+
+Detailed Description of If-then-else Format
+-------------------------------------------
+
+ For lines common to both files, `diff' uses the unchanged line group
+format. For each hunk of differences in the merged output format, if
+the hunk contains only lines from the first file, `diff' uses the old
+line group format; if the hunk contains only lines from the second
+file, `diff' uses the new group format; otherwise, `diff' uses the
+changed group format.
+
+ The old, new, and unchanged line formats specify the output format of
+lines from the first file, lines from the second file, and lines common
+to both files, respectively.
+
+ The option `--ifdef=NAME' is equivalent to the following sequence of
+options using shell syntax:
+
+ --old-group-format='#ifndef NAME
+ %<#endif /* ! NAME */
+ ' \
+ --new-group-format='#ifdef NAME
+ %>#endif /* NAME */
+ ' \
+ --unchanged-group-format='%=' \
+ --changed-group-format='#ifndef NAME
+ %<#else /* NAME */
+ %>#endif /* NAME */
+ '
+
+ You should carefully check the `diff' output for proper nesting.
+For example, when using the `-D NAME' or `--ifdef=NAME' option, you
+should check that if the differing lines contain any of the C
+preprocessor directives `#ifdef', `#ifndef', `#else', `#elif', or
+`#endif', they are nested properly and match. If they don't, you must
+make corrections manually. It is a good idea to carefully check the
+resulting code anyway to make sure that it really does what you want it
+to; depending on how the input files were produced, the output might
+contain duplicate or otherwise incorrect code.
+
+ The `patch' `-D NAME' option behaves like the `diff' `-D NAME'
+option, except it operates on a file and a diff to produce a merged
+file; *Note patch Options::.
+
+
+File: diff.info, Node: Example If-then-else, Prev: Detailed If-then-else, Up: If-then-else
+
+An Example of If-then-else Format
+---------------------------------
+
+ Here is the output of `diff -DTWO lao tzu' (*note Sample diff
+Input::, for the complete contents of the two files):
+
+ #ifndef TWO
+ The Way that can be told of is not the eternal Way;
+ The name that can be named is not the eternal name.
+ #endif /* ! TWO */
+ The Nameless is the origin of Heaven and Earth;
+ #ifndef TWO
+ The Named is the mother of all things.
+ #else /* TWO */
+ The named is the mother of all things.
+
+ #endif /* TWO */
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+ so we may see their outcome.
+ The two are the same,
+ But after they are produced,
+ they have different names.
+ #ifdef TWO
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
+ #endif /* TWO */
+
+
+File: diff.info, Node: Incomplete Lines, Next: Comparing Directories, Prev: Output Formats, Up: Top
+
+Incomplete Lines
+****************
+
+ When an input file ends in a non-newline character, its last line is
+called an "incomplete line" because its last character is not a
+newline. All other lines are called "full lines" and end in a newline
+character. Incomplete lines do not match full lines unless differences
+in white space are ignored (*note White Space::).
+
+ An incomplete line is normally distinguished on output from a full
+line by a following line that starts with `\'. However, the RCS format
+(*note RCS::) outputs the incomplete line as-is, without any trailing
+newline or following line. The side by side format normally represents
+incomplete lines as-is, but in some cases uses a `\' or `/' gutter
+marker; *Note Side by Side::. The if-then-else line format preserves a
+line's incompleteness with `%L', and discards the newline with `%l';
+*Note Line Formats::. Finally, with the `ed' and forward `ed' output
+formats (*note Output Formats::) `diff' cannot represent an incomplete
+line, so it pretends there was a newline and reports an error.
+
+ For example, suppose `F' and `G' are one-byte files that contain
+just `f' and `g', respectively. Then `diff F G' outputs
+
+ 1c1
+ < f
+ \ No newline at end of file
+ ---
+ > g
+ \ No newline at end of file
+
+(The exact message may differ in non-English locales.) `diff -n F G'
+outputs the following without a trailing newline:
+
+ d1 1
+ a1 1
+ g
+
+`diff -e F G' reports two errors and outputs the following:
+
+ 1c
+ g
+ .
+
+
+File: diff.info, Node: Comparing Directories, Next: Adjusting Output, Prev: Incomplete Lines, Up: Top
+
+Comparing Directories
+*********************
+
+ You can use `diff' to compare some or all of the files in two
+directory trees. When both file name arguments to `diff' are
+directories, it compares each file that is contained in both
+directories, examining file names in alphabetical order as specified by
+the `LC_COLLATE' locale category. Normally `diff' is silent about
+pairs of files that contain no differences, but if you use the `-s' or
+`--report-identical-files' option, it reports pairs of identical files.
+Normally `diff' reports subdirectories common to both directories
+without comparing subdirectories' files, but if you use the `-r' or
+`--recursive' option, it compares every corresponding pair of files in
+the directory trees, as many levels deep as they go.
+
+ For file names that are in only one of the directories, `diff'
+normally does not show the contents of the file that exists; it reports
+only that the file exists in that directory and not in the other. You
+can make `diff' act as though the file existed but was empty in the
+other directory, so that it outputs the entire contents of the file that
+actually exists. (It is output as either an insertion or a deletion,
+depending on whether it is in the first or the second directory given.)
+To do this, use the `-N' or `--new-file' option.
+
+ If the older directory contains one or more large files that are not
+in the newer directory, you can make the patch smaller by using the
+`--unidirectional-new-file' option instead of `-N'. This option is
+like `-N' except that it only inserts the contents of files that appear
+in the second directory but not the first (that is, files that were
+added). At the top of the patch, write instructions for the user
+applying the patch to remove the files that were deleted before
+applying the patch. *Note Making Patches::, for more discussion of
+making patches for distribution.
+
+ To ignore some files while comparing directories, use the `-x
+PATTERN' or `--exclude=PATTERN' option. This option ignores any files
+or subdirectories whose base names match the shell pattern PATTERN.
+Unlike in the shell, a period at the start of the base of a file name
+matches a wildcard at the start of a pattern. You should enclose
+PATTERN in quotes so that the shell does not expand it. For example,
+the option `-x '*.[ao]'' ignores any file whose name ends with `.a' or
+`.o'.
+
+ This option accumulates if you specify it more than once. For
+example, using the options `-x 'RCS' -x '*,v'' ignores any file or
+subdirectory whose base name is `RCS' or ends with `,v'.
+
+ If you need to give this option many times, you can instead put the
+patterns in a file, one pattern per line, and use the `-X FILE' or
+`--exclude-from=FILE' option.
+
+ If you have been comparing two directories and stopped partway
+through, later you might want to continue where you left off. You can
+do this by using the `-S FILE' or `--starting-file=FILE' option. This
+compares only the file FILE and all alphabetically later files in the
+topmost directory level.
+
+ If two directories differ only in that file names are lower case in
+one directory and upper case in the upper, `diff' normally reports many
+differences because it compares file names in a case sensitive way.
+With the `--ignore-file-name-case' option, `diff' ignores case
+differences in file names, so that for example the contents of the file
+`Tao' in one directory are compared to the contents of the file `TAO'
+in the other. The `--no-ignore-file-name-case' option cancels the
+effect of the `--ignore-file-name-case' option, reverting to the default
+behavior.
+
+ If an `-x PATTERN', `--exclude=PATTERN', `-X FILE', or
+`--exclude-from=FILE' option is specified while the
+`--ignore-file-name-case' option is in effect, case is ignored when
+excluding file names matching the specified patterns.
+
+
+File: diff.info, Node: Adjusting Output, Next: diff Performance, Prev: Comparing Directories, Up: Top
+
+Making `diff' Output Prettier
+*****************************
+
+ `diff' provides several ways to adjust the appearance of its output.
+These adjustments can be applied to any output format.
+
+* Menu:
+
+* Tabs:: Preserving the alignment of tab stops.
+* Pagination:: Page numbering and time-stamping `diff' output.
+
+
+File: diff.info, Node: Tabs, Next: Pagination, Up: Adjusting Output
+
+Preserving Tab Stop Alignment
+=============================
+
+ The lines of text in some of the `diff' output formats are preceded
+by one or two characters that indicate whether the text is inserted,
+deleted, or changed. The addition of those characters can cause tabs to
+move to the next tab stop, throwing off the alignment of columns in the
+line. GNU `diff' provides two ways to make tab-aligned columns line up
+correctly.
+
+ The first way is to have `diff' convert all tabs into the correct
+number of spaces before outputting them; select this method with the
+`-t' or `--expand-tabs' option. `diff' assumes that tab stops are set
+every 8 print columns. To use this form of output with `patch', you
+must give `patch' the `-l' or `--ignore-white-space' option (*note
+Changed White Space::, for more information).
+
+ The other method for making tabs line up correctly is to add a tab
+character instead of a space after the indicator character at the
+beginning of the line. This ensures that all following tab characters
+are in the same position relative to tab stops that they were in the
+original files, so that the output is aligned correctly. Its
+disadvantage is that it can make long lines too long to fit on one line
+of the screen or the paper. It also does not work with the unified
+output format, which does not have a space character after the change
+type indicator character. Select this method with the `-T' or
+`--initial-tab' option.
+
+
+File: diff.info, Node: Pagination, Prev: Tabs, Up: Adjusting Output
+
+Paginating `diff' Output
+========================
+
+ It can be convenient to have long output page-numbered and
+time-stamped. The `-l' and `--paginate' options do this by sending the
+`diff' output through the `pr' program. Here is what the page header
+might look like for `diff -lc lao tzu':
+
+ 2002-02-22 14:20 diff -lc lao tzu Page 1
+
+
+File: diff.info, Node: diff Performance, Next: Comparing Three Files, Prev: Adjusting Output, Up: Top
+
+`diff' Performance Tradeoffs
+****************************
+
+ GNU `diff' runs quite efficiently; however, in some circumstances
+you can cause it to run faster or produce a more compact set of changes.
+
+ One way to improve `diff' performance is to use hard or symbolic
+links to files instead of copies. This improves performance because
+`diff' normally does not need to read two hard or symbolic links to the
+same file, since their contents must be identical. For example,
+suppose you copy a large directory hierarchy, make a few changes to the
+copy, and then often use `diff -r' to compare the original to the copy.
+If the original files are read-only, you can greatly improve
+performance by creating the copy using hard or symbolic links (e.g.,
+with GNU `cp -lR' or `cp -sR'). Before editing a file in the copy for
+the first time, you should break the link and replace it with a regular
+copy.
+
+ You can also affect the performance of GNU `diff' by giving it
+options that change the way it compares files. Performance has more
+than one dimension. These options improve one aspect of performance at
+the cost of another, or they improve performance in some cases while
+hurting it in others.
+
+ The way that GNU `diff' determines which lines have changed always
+comes up with a near-minimal set of differences. Usually it is good
+enough for practical purposes. If the `diff' output is large, you
+might want `diff' to use a modified algorithm that sometimes produces a
+smaller set of differences. The `-d' or `--minimal' option does this;
+however, it can also cause `diff' to run more slowly than usual, so it
+is not the default behavior.
+
+ When the files you are comparing are large and have small groups of
+changes scattered throughout them, you can use the
+`--speed-large-files' option to make a different modification to the
+algorithm that `diff' uses. If the input files have a constant small
+density of changes, this option speeds up the comparisons without
+changing the output. If not, `diff' might produce a larger set of
+differences; however, the output will still be correct.
+
+ Normally `diff' discards the prefix and suffix that is common to
+both files before it attempts to find a minimal set of differences.
+This makes `diff' run faster, but occasionally it may produce
+non-minimal output. The `--horizon-lines=LINES' option prevents `diff'
+from discarding the last LINES lines of the prefix and the first LINES
+lines of the suffix. This gives `diff' further opportunities to find a
+minimal output.
+
+ Suppose a run of changed lines includes a sequence of lines at one
+end and there is an identical sequence of lines just outside the other
+end. The `diff' command is free to choose which identical sequence is
+included in the hunk. In this case, `diff' normally shifts the hunk's
+boundaries when this merges adjacent hunks, or shifts a hunk's lines
+towards the end of the file. Merging hunks can make the output look
+nicer in some cases.
+
+
+File: diff.info, Node: Comparing Three Files, Next: diff3 Merging, Prev: diff Performance, Up: Top
+
+Comparing Three Files
+*********************
+
+ Use the program `diff3' to compare three files and show any
+differences among them. (`diff3' can also merge files; see *Note diff3
+Merging::).
+
+ The "normal" `diff3' output format shows each hunk of differences
+without surrounding context. Hunks are labeled depending on whether
+they are two-way or three-way, and lines are annotated by their
+location in the input files.
+
+ *Note Invoking diff3::, for more information on how to run `diff3'.
+
+* Menu:
+
+* Sample diff3 Input:: Sample `diff3' input for examples.
+* Detailed diff3 Normal:: A detailed description of normal output format.
+* diff3 Hunks:: The format of normal output format.
+* Example diff3 Normal:: Sample output in the normal format.
+
+
+File: diff.info, Node: Sample diff3 Input, Next: Detailed diff3 Normal, Up: Comparing Three Files
+
+A Third Sample Input File
+=========================
+
+ Here is a third sample file that will be used in examples to
+illustrate the output of `diff3' and how various options can change it.
+The first two files are the same that we used for `diff' (*note Sample
+diff Input::). This is the third sample file, called `tao':
+
+ The Way that can be told of is not the eternal Way;
+ The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+ The named is the mother of all things.
+
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+ so we may see their result.
+ The two are the same,
+ But after they are produced,
+ they have different names.
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+
+
+File: diff.info, Node: Detailed diff3 Normal, Next: diff3 Hunks, Prev: Sample diff3 Input, Up: Comparing Three Files
+
+Detailed Description of `diff3' Normal Format
+=============================================
+
+ Each hunk begins with a line marked `===='. Three-way hunks have
+plain `====' lines, and two-way hunks have `1', `2', or `3' appended to
+specify which of the three input files differ in that hunk. The hunks
+contain copies of two or three sets of input lines each preceded by one
+or two commands identifying where the lines came from.
+
+ Normally, two spaces precede each copy of an input line to
+distinguish it from the commands. But with the `-T' or `--initial-tab'
+option, `diff3' uses a tab instead of two spaces; this lines up tabs
+correctly. *Note Tabs::, for more information.
+
+ Commands take the following forms:
+
+`FILE:La'
+ This hunk appears after line L of file FILE, and contains no lines
+ in that file. To edit this file to yield the other files, one
+ must append hunk lines taken from the other files. For example,
+ `1:11a' means that the hunk follows line 11 in the first file and
+ contains no lines from that file.
+
+`FILE:Rc'
+ This hunk contains the lines in the range R of file FILE. The
+ range R is a comma-separated pair of line numbers, or just one
+ number if the range is a singleton. To edit this file to yield the
+ other files, one must change the specified lines to be the lines
+ taken from the other files. For example, `2:11,13c' means that
+ the hunk contains lines 11 through 13 from the second file.
+
+ If the last line in a set of input lines is incomplete (*note
+Incomplete Lines::), it is distinguished on output from a full line by
+a following line that starts with `\'.
+
+
+File: diff.info, Node: diff3 Hunks, Next: Example diff3 Normal, Prev: Detailed diff3 Normal, Up: Comparing Three Files
+
+`diff3' Hunks
+=============
+
+ Groups of lines that differ in two or three of the input files are
+called "diff3 hunks", by analogy with `diff' hunks (*note Hunks::). If
+all three input files differ in a `diff3' hunk, the hunk is called a
+"three-way hunk"; if just two input files differ, it is a "two-way
+hunk".
+
+ As with `diff', several solutions are possible. When comparing the
+files `A', `B', and `C', `diff3' normally finds `diff3' hunks by
+merging the two-way hunks output by the two commands `diff A B' and
+`diff A C'. This does not necessarily minimize the size of the output,
+but exceptions should be rare.
+
+ For example, suppose `F' contains the three lines `a', `b', `f', `G'
+contains the lines `g', `b', `g', and `H' contains the lines `a', `b',
+`h'. `diff3 F G H' might output the following:
+
+ ====2
+ 1:1c
+ 3:1c
+ a
+ 2:1c
+ g
+ ====
+ 1:3c
+ f
+ 2:3c
+ g
+ 3:3c
+ h
+
+because it found a two-way hunk containing `a' in the first and third
+files and `g' in the second file, then the single line `b' common to
+all three files, then a three-way hunk containing the last line of each
+file.
+
+
+File: diff.info, Node: Example diff3 Normal, Prev: diff3 Hunks, Up: Comparing Three Files
+
+An Example of `diff3' Normal Format
+===================================
+
+ Here is the output of the command `diff3 lao tzu tao' (*note Sample
+diff3 Input::, for the complete contents of the files). Notice that it
+shows only the lines that are different among the three files.
+
+ ====2
+ 1:1,2c
+ 3:1,2c
+ The Way that can be told of is not the eternal Way;
+ The name that can be named is not the eternal name.
+ 2:0a
+ ====1
+ 1:4c
+ The Named is the mother of all things.
+ 2:2,3c
+ 3:4,5c
+ The named is the mother of all things.
+
+ ====3
+ 1:8c
+ 2:7c
+ so we may see their outcome.
+ 3:9c
+ so we may see their result.
+ ====
+ 1:11a
+ 2:11,13c
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
+ 3:13,14c
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+
+
+File: diff.info, Node: diff3 Merging, Next: Interactive Merging, Prev: Comparing Three Files, Up: Top
+
+Merging From a Common Ancestor
+******************************
+
+ When two people have made changes to copies of the same file,
+`diff3' can produce a merged output that contains both sets of changes
+together with warnings about conflicts.
+
+ One might imagine programs with names like `diff4' and `diff5' to
+compare more than three files simultaneously, but in practice the need
+rarely arises. You can use `diff3' to merge three or more sets of
+changes to a file by merging two change sets at a time.
+
+ `diff3' can incorporate changes from two modified versions into a
+common preceding version. This lets you merge the sets of changes
+represented by the two newer files. Specify the common ancestor version
+as the second argument and the two newer versions as the first and third
+arguments, like this:
+
+ diff3 MINE OLDER YOURS
+
+You can remember the order of the arguments by noting that they are in
+alphabetical order.
+
+ You can think of this as subtracting OLDER from YOURS and adding the
+result to MINE, or as merging into MINE the changes that would turn
+OLDER into YOURS. This merging is well-defined as long as MINE and
+OLDER match in the neighborhood of each such change. This fails to be
+true when all three input files differ or when only OLDER differs; we
+call this a "conflict". When all three input files differ, we call the
+conflict an "overlap".
+
+ `diff3' gives you several ways to handle overlaps and conflicts.
+You can omit overlaps or conflicts, or select only overlaps, or mark
+conflicts with special `<<<<<<<' and `>>>>>>>' lines.
+
+ `diff3' can output the merge results as an `ed' script that that can
+be applied to the first file to yield the merged output. However, it
+is usually better to have `diff3' generate the merged output directly;
+this bypasses some problems with `ed'.
+
+* Menu:
+
+* Which Changes:: Selecting changes to incorporate.
+* Marking Conflicts:: Marking conflicts.
+* Bypassing ed:: Generating merged output directly.
+* Merging Incomplete Lines:: How `diff3' merges incomplete lines.
+* Saving the Changed File:: Emulating System V behavior.
+
+
+File: diff.info, Node: Which Changes, Next: Marking Conflicts, Up: diff3 Merging
+
+Selecting Which Changes to Incorporate
+======================================
+
+ You can select all unmerged changes from OLDER to YOURS for merging
+into MINE with the `-e' or `--ed' option. You can select only the
+nonoverlapping unmerged changes with `-3' or `--easy-only', and you can
+select only the overlapping changes with `-x' or `--overlap-only'.
+
+ The `-e', `-3' and `-x' options select only "unmerged changes", i.e.
+changes where MINE and YOURS differ; they ignore changes from OLDER to
+YOURS where MINE and YOURS are identical, because they assume that such
+changes have already been merged. If this assumption is not a safe
+one, you can use the `-A' or `--show-all' option (*note Marking
+Conflicts::).
+
+ Here is the output of the command `diff3' with each of these three
+options (*note Sample diff3 Input::, for the complete contents of the
+files). Notice that `-e' outputs the union of the disjoint sets of
+changes output by `-3' and `-x'.
+
+ Output of `diff3 -e lao tzu tao':
+ 11a
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+ .
+ 8c
+ so we may see their result.
+ .
+
+ Output of `diff3 -3 lao tzu tao':
+ 8c
+ so we may see their result.
+ .
+
+ Output of `diff3 -x lao tzu tao':
+ 11a
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+ .
+
+
+File: diff.info, Node: Marking Conflicts, Next: Bypassing ed, Prev: Which Changes, Up: diff3 Merging
+
+Marking Conflicts
+=================
+
+ `diff3' can mark conflicts in the merged output by bracketing them
+with special marker lines. A conflict that comes from two files A and
+B is marked as follows:
+
+ <<<<<<< A
+ lines from A
+ =======
+ lines from B
+ >>>>>>> B
+
+ A conflict that comes from three files A, B and C is marked as
+follows:
+
+ <<<<<<< A
+ lines from A
+ ||||||| B
+ lines from B
+ =======
+ lines from C
+ >>>>>>> C
+
+ The `-A' or `--show-all' option acts like the `-e' option, except
+that it brackets conflicts, and it outputs all changes from OLDER to
+YOURS, not just the unmerged changes. Thus, given the sample input
+files (*note Sample diff3 Input::), `diff3 -A lao tzu tao' puts
+brackets around the conflict where only `tzu' differs:
+
+ <<<<<<< tzu
+ =======
+ The Way that can be told of is not the eternal Way;
+ The name that can be named is not the eternal name.
+ >>>>>>> tao
+
+ And it outputs the three-way conflict as follows:
+
+ <<<<<<< lao
+ ||||||| tzu
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
+ =======
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+ >>>>>>> tao
+
+ The `-E' or `--show-overlap' option outputs less information than
+the `-A' or `--show-all' option, because it outputs only unmerged
+changes, and it never outputs the contents of the second file. Thus
+the `-E' option acts like the `-e' option, except that it brackets the
+first and third files from three-way overlapping changes. Similarly,
+`-X' acts like `-x', except it brackets all its (necessarily
+overlapping) changes. For example, for the three-way overlapping
+change above, the `-E' and `-X' options output the following:
+
+ <<<<<<< lao
+ =======
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+ >>>>>>> tao
+
+ If you are comparing files that have meaningless or uninformative
+names, you can use the `-L LABEL' or `--label=LABEL' option to show
+alternate names in the `<<<<<<<', `|||||||' and `>>>>>>>' brackets.
+This option can be given up to three times, once for each input file.
+Thus `diff3 -A -L X -L Y -L Z A B C' acts like `diff3 -A A B C', except
+that the output looks like it came from files named `X', `Y' and `Z'
+rather than from files named `A', `B' and `C'.
+
+
+File: diff.info, Node: Bypassing ed, Next: Merging Incomplete Lines, Prev: Marking Conflicts, Up: diff3 Merging
+
+Generating the Merged Output Directly
+=====================================
+
+ With the `-m' or `--merge' option, `diff3' outputs the merged file
+directly. This is more efficient than using `ed' to generate it, and
+works even with non-text files that `ed' would reject. If you specify
+`-m' without an `ed' script option, `-A' (`--show-all') is assumed.
+
+ For example, the command `diff3 -m lao tzu tao' (*note Sample diff3
+Input:: for a copy of the input files) would output the following:
+
+ <<<<<<< tzu
+ =======
+ The Way that can be told of is not the eternal Way;
+ The name that can be named is not the eternal name.
+ >>>>>>> tao
+ The Nameless is the origin of Heaven and Earth;
+ The Named is the mother of all things.
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+ so we may see their result.
+ The two are the same,
+ But after they are produced,
+ they have different names.
+ <<<<<<< lao
+ ||||||| tzu
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
+ =======
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+ >>>>>>> tao
+
+
+File: diff.info, Node: Merging Incomplete Lines, Next: Saving the Changed File, Prev: Bypassing ed, Up: diff3 Merging
+
+How `diff3' Merges Incomplete Lines
+===================================
+
+ With `-m', incomplete lines (*note Incomplete Lines::) are simply
+copied to the output as they are found; if the merged output ends in an
+conflict and one of the input files ends in an incomplete line,
+succeeding `|||||||', `=======' or `>>>>>>>' brackets appear somewhere
+other than the start of a line because they are appended to the
+incomplete line.
+
+ Without `-m', if an `ed' script option is specified and an
+incomplete line is found, `diff3' generates a warning and acts as if a
+newline had been present.
+
+
+File: diff.info, Node: Saving the Changed File, Prev: Merging Incomplete Lines, Up: diff3 Merging
+
+Saving the Changed File
+=======================
+
+ Traditional Unix `diff3' generates an `ed' script without the
+trailing `w' and `q' commands that save the changes. System V `diff3'
+generates these extra commands. GNU `diff3' normally behaves like
+traditional Unix `diff3', but with the `-i' option it behaves like
+System V `diff3' and appends the `w' and `q' commands.
+
+ The `-i' option requires one of the `ed' script options `-AeExX3',
+and is incompatible with the merged output option `-m'.
+
+
+File: diff.info, Node: Interactive Merging, Next: Merging with patch, Prev: diff3 Merging, Up: Top
+
+Interactive Merging with `sdiff'
+********************************
+
+ With `sdiff', you can merge two files interactively based on a
+side-by-side `-y' format comparison (*note Side by Side::). Use `-o
+FILE' or `--output=FILE' to specify where to put the merged text.
+*Note Invoking sdiff::, for more details on the options to `sdiff'.
+
+ Another way to merge files interactively is to use the Emacs Lisp
+package `emerge'. *Note emerge: (emacs)emerge, for more information.
+
+* Menu:
+
+* sdiff Option Summary:: Summary of `sdiff' options.
+* Merge Commands:: Merging two files interactively.
+
+
+File: diff.info, Node: sdiff Option Summary, Next: Merge Commands, Up: Interactive Merging
+
+Specifying `diff' Options to `sdiff'
+====================================
+
+ The following `sdiff' options have the same meaning as for `diff'.
+*Note diff Options::, for the use of these options.
+
+ -a -b -d -i -t -v
+ -B -E -I REGEXP
+
+ --ignore-blank-lines --ignore-case
+ --ignore-matching-lines=REGEXP --ignore-space-change
+ --ignore-tab-expansion
+ --left-column --minimal --speed-large-files
+ --strip-trailing-cr --suppress-common-lines --expand-tabs
+ --text --version --width=COLUMNS
+
+ For historical reasons, `sdiff' has alternate names for some
+options. The `-l' option is equivalent to the `--left-column' option,
+and similarly `-s' is equivalent to `--suppress-common-lines'. The
+meaning of the `sdiff' `-w' and `-W' options is interchanged from that
+of `diff': with `sdiff', `-w COLUMNS' is equivalent to
+`--width=COLUMNS', and `-W' is equivalent to `--ignore-all-space'.
+`sdiff' without the `-o' option is equivalent to `diff' with the `-y'
+or `--side-by-side' option (*note Side by Side::).
+
+
+File: diff.info, Node: Merge Commands, Prev: sdiff Option Summary, Up: Interactive Merging
+
+Merge Commands
+==============
+
+ Groups of common lines, with a blank gutter, are copied from the
+first file to the output. After each group of differing lines, `sdiff'
+prompts with `%' and pauses, waiting for one of the following commands.
+Follow each command with <RET>.
+
+`e'
+ Discard both versions. Invoke a text editor on an empty temporary
+ file, then copy the resulting file to the output.
+
+`eb'
+ Concatenate the two versions, edit the result in a temporary file,
+ then copy the edited result to the output.
+
+`ed'
+ Like `eb', except precede each version with a header that shows
+ what file and lines the version came from.
+
+`el'
+ Edit a copy of the left version, then copy the result to the
+ output.
+
+`er'
+ Edit a copy of the right version, then copy the result to the
+ output.
+
+`l'
+ Copy the left version to the output.
+
+`q'
+ Quit.
+
+`r'
+ Copy the right version to the output.
+
+`s'
+ Silently copy common lines.
+
+`v'
+ Verbosely copy common lines. This is the default.
+
+ The text editor invoked is specified by the `EDITOR' environment
+variable if it is set. The default is system-dependent.
+
+
+File: diff.info, Node: Merging with patch, Next: Making Patches, Prev: Interactive Merging, Up: Top
+
+Merging with `patch'
+********************
+
+ `patch' takes comparison output produced by `diff' and applies the
+differences to a copy of the original file, producing a patched
+version. With `patch', you can distribute just the changes to a set of
+files instead of distributing the entire file set; your correspondents
+can apply `patch' to update their copy of the files with your changes.
+`patch' automatically determines the diff format, skips any leading or
+trailing headers, and uses the headers to determine which file to
+patch. This lets your correspondents feed a mail message containing a
+difference listing directly to `patch'.
+
+ `patch' detects and warns about common problems like forward
+patches. It saves any patches that it could not apply. It can also
+maintain a `patchlevel.h' file to ensure that your correspondents apply
+diffs in the proper order.
+
+ `patch' accepts a series of diffs in its standard input, usually
+separated by headers that specify which file to patch. It applies
+`diff' hunks (*note Hunks::) one by one. If a hunk does not exactly
+match the original file, `patch' uses heuristics to try to patch the
+file as well as it can. If no approximate match can be found, `patch'
+rejects the hunk and skips to the next hunk. `patch' normally replaces
+each file F with its new version, putting reject hunks (if any) into
+`F.rej'.
+
+ *Note Invoking patch::, for detailed information on the options to
+`patch'.
+
+* Menu:
+
+* patch Input:: Selecting the type of `patch' input.
+* Revision Control:: Getting files from RCS, SCCS, etc.
+* Imperfect:: Dealing with imperfect patches.
+* Creating and Removing:: Creating and removing files with a patch.
+* Patching Time Stamps:: Updating time stamps on patched files.
+* Multiple Patches:: Handling multiple patches in a file.
+* patch Directories:: Changing directory and stripping directories.
+* Backups:: Whether backup files are made.
+* Backup Names:: Backup file names.
+* Reject Names:: Reject file names.
+* patch Messages:: Messages and questions `patch' can produce.
+* patch and POSIX:: Conformance to the POSIX standard.
+* patch and Tradition:: GNU versus traditional `patch'.
+
+
+File: diff.info, Node: patch Input, Next: Revision Control, Up: Merging with patch
+
+Selecting the `patch' Input Format
+==================================
+
+ `patch' normally determines which `diff' format the patch file uses
+by examining its contents. For patch files that contain particularly
+confusing leading text, you might need to use one of the following
+options to force `patch' to interpret the patch file as a certain
+format of diff. The output formats listed here are the only ones that
+`patch' can understand.
+
+`-c'
+`--context'
+ context diff.
+
+`-e'
+`--ed'
+ `ed' script.
+
+`-n'
+`--normal'
+ normal diff.
+
+`-u'
+`--unified'
+ unified diff.
+
+
+File: diff.info, Node: Revision Control, Next: Imperfect, Prev: patch Input, Up: Merging with patch
+
+Revision Control
+================
+
+ If a nonexistent input file is under a revision control system
+supported by `patch', `patch' normally asks the user whether to get (or
+check out) the file from the revision control system. Patch currently
+supports RCS, ClearCase and SCCS. Under RCS and SCCS, `patch' also
+asks when the input file is read-only and matches the default version
+in the revision control system.
+
+ The `-g NUM' or `--get=NUM' affects access to files under supported
+revision control systems. If NUM is positive, `patch' gets the file
+without asking the user; if zero, `patch' neither asks the user nor
+gets the file; and if negative, `patch' asks the user before getting
+the file. The default value of NUM is given by the value of the
+`PATCH_GET' environment variable if it is set; if not, the default
+value is zero if `patch' is conforming to POSIX, negative otherwise.
+*Note patch and POSIX::.
+
+ The choice of revision control system is unaffected by the
+`VERSION_CONTROL' environment variable (*note Backup Names::).
+
+
+File: diff.info, Node: Imperfect, Next: Creating and Removing, Prev: Revision Control, Up: Merging with patch
+
+Applying Imperfect Patches
+==========================
+
+ `patch' tries to skip any leading text in the patch file, apply the
+diff, and then skip any trailing text. Thus you can feed a mail
+message directly to `patch', and it should work. If the entire diff is
+indented by a constant amount of white space, `patch' automatically
+ignores the indentation. If a context diff contains trailing carriage
+return on each line, `patch' automatically ignores the carriage return.
+If a context diff has been encapsulated by prepending `- ' to lines
+beginning with `-' as per Internet RFC 934
+(ftp://ftp.isi.edu/in-notes/rfc934.txt), `patch' automatically
+unencapsulates the input.
+
+ However, certain other types of imperfect input require user
+intervention or testing.
+
+* Menu:
+
+* Changed White Space:: When tabs and spaces don't match exactly.
+* Reversed Patches:: Applying reversed patches correctly.
+* Inexact:: Helping `patch' find close matches.
+* Dry Runs:: Predicting what `patch' will do.
+
+
+File: diff.info, Node: Changed White Space, Next: Reversed Patches, Up: Imperfect
+
+Applying Patches with Changed White Space
+-----------------------------------------
+
+ Sometimes mailers, editors, or other programs change spaces into
+tabs, or vice versa. If this happens to a patch file or an input file,
+the files might look the same, but `patch' will not be able to match
+them properly. If this problem occurs, use the `-l' or
+`--ignore-white-space' option, which makes `patch' compare blank
+characters (i.e. spaces and tabs) loosely so that any nonempty sequence
+of blanks in the patch file matches any nonempty sequence of blanks in
+the input files. Non-blank characters must still match exactly. Each
+line of the context must still match a line in the input file.
+
+
+File: diff.info, Node: Reversed Patches, Next: Inexact, Prev: Changed White Space, Up: Imperfect
+
+Applying Reversed Patches
+-------------------------
+
+ Sometimes people run `diff' with the new file first instead of
+second. This creates a diff that is "reversed". To apply such
+patches, give `patch' the `-R' or `--reverse' option. `patch' then
+attempts to swap each hunk around before applying it. Rejects come out
+in the swapped format.
+
+ Often `patch' can guess that the patch is reversed. If the first
+hunk of a patch fails, `patch' reverses the hunk to see if it can apply
+it that way. If it can, `patch' asks you if you want to have the `-R'
+option set; if it can't, `patch' continues to apply the patch normally.
+This method cannot detect a reversed patch if it is a normal diff and
+the first command is an append (which should have been a delete) since
+appends always succeed, because a null context matches anywhere. But
+most patches add or change lines rather than delete them, so most
+reversed normal diffs begin with a delete, which fails, and `patch'
+notices.
+
+ If you apply a patch that you have already applied, `patch' thinks
+it is a reversed patch and offers to un-apply the patch. This could be
+construed as a feature. If you did this inadvertently and you don't
+want to un-apply the patch, just answer `n' to this offer and to the
+subsequent "apply anyway" question--or type `C-c' to kill the `patch'
+process.
+
+
+File: diff.info, Node: Inexact, Next: Dry Runs, Prev: Reversed Patches, Up: Imperfect
+
+Helping `patch' Find Inexact Matches
+------------------------------------
+
+ For context diffs, and to a lesser extent normal diffs, `patch' can
+detect when the line numbers mentioned in the patch are incorrect, and
+it attempts to find the correct place to apply each hunk of the patch.
+As a first guess, it takes the line number mentioned in the hunk, plus
+or minus any offset used in applying the previous hunk. If that is not
+the correct place, `patch' scans both forward and backward for a set of
+lines matching the context given in the hunk.
+
+ First `patch' looks for a place where all lines of the context
+match. If it cannot find such a place, and it is reading a context or
+unified diff, and the maximum fuzz factor is set to 1 or more, then
+`patch' makes another scan, ignoring the first and last line of
+context. If that fails, and the maximum fuzz factor is set to 2 or
+more, it makes another scan, ignoring the first two and last two lines
+of context are ignored. It continues similarly if the maximum fuzz
+factor is larger.
+
+ The `-F LINES' or `--fuzz=LINES' option sets the maximum fuzz factor
+to LINES. This option only applies to context and unified diffs; it
+ignores up to LINES lines while looking for the place to install a
+hunk. Note that a larger fuzz factor increases the odds of making a
+faulty patch. The default fuzz factor is 2; there is no point to
+setting it to more than the number of lines of context in the diff,
+ordinarily 3.
+
+ If `patch' cannot find a place to install a hunk of the patch, it
+writes the hunk out to a reject file (*note Reject Names::, for
+information on how reject files are named). It writes out rejected
+hunks in context format no matter what form the input patch is in. If
+the input is a normal or `ed' diff, many of the contexts are simply
+null. The line numbers on the hunks in the reject file may be
+different from those in the patch file: they show the approximate
+location where `patch' thinks the failed hunks belong in the new file
+rather than in the old one.
+
+ If the `--verbose' option is given, then as it completes each hunk
+`patch' tells you whether the hunk succeeded or failed, and if it
+failed, on which line (in the new file) `patch' thinks the hunk should
+go. If this is different from the line number specified in the diff,
+it tells you the offset. A single large offset _may_ indicate that
+`patch' installed a hunk in the wrong place. `patch' also tells you if
+it used a fuzz factor to make the match, in which case you should also
+be slightly suspicious.
+
+ `patch' cannot tell if the line numbers are off in an `ed' script,
+and can only detect wrong line numbers in a normal diff when it finds a
+change or delete command. It may have the same problem with a context
+diff using a fuzz factor equal to or greater than the number of lines
+of context shown in the diff (typically 3). In these cases, you should
+probably look at a context diff between your original and patched input
+files to see if the changes make sense. Compiling without errors is a
+pretty good indication that the patch worked, but not a guarantee.
+
+ A patch against an empty file applies to a nonexistent file, and vice
+versa. *Note Creating and Removing::.
+
+ `patch' usually produces the correct results, even when it must make
+many guesses. However, the results are guaranteed only when the patch
+is applied to an exact copy of the file that the patch was generated
+from.
+
+
+File: diff.info, Node: Dry Runs, Prev: Inexact, Up: Imperfect
+
+Predicting what `patch' will do
+-------------------------------
+
+ It may not be obvious in advance what `patch' will do with a
+complicated or poorly formatted patch. If you are concerned that the
+input might cause `patch' to modify the wrong files, you can use the
+`--dry-run' option, which causes `patch' to print the results of
+applying patches without actually changing any files. You can then
+inspect the diagnostics generated by the dry run to see whether `patch'
+will modify the files that you expect. If the patch does not do what
+you want, you can modify the patch (or the other options to `patch')
+and try another dry run. Once you are satisfied with the proposed
+patch you can apply it by invoking `patch' as before, but this time
+without the `--dry-run' option.
+
+
+File: diff.info, Node: Creating and Removing, Next: Patching Time Stamps, Prev: Imperfect, Up: Merging with patch
+
+Creating and Removing Files
+===========================
+
+ Sometimes when comparing two directories, a file may exist in one
+directory but not the other. If you give `diff' the `-N' or
+`--new-file' option, or if you supply an old or new file that is named
+`/dev/null' or is empty and is dated the Epoch (1970-01-01 00:00:00
+UTC), `diff' outputs a patch that adds or deletes the contents of this
+file. When given such a patch, `patch' normally creates a new file or
+removes the old file. However, when conforming to POSIX (*note patch
+and POSIX::), `patch' does not remove the old file, but leaves it empty.
+The `-E' or `--remove-empty-files' option causes `patch' to remove
+output files that are empty after applying a patch, even if the patch
+does not appear to be one that removed the file.
+
+ If the patch appears to create a file that already exists, `patch'
+asks for confirmation before applying the patch.
+
+
+File: diff.info, Node: Patching Time Stamps, Next: Multiple Patches, Prev: Creating and Removing, Up: Merging with patch
+
+Updating Time Stamps on Patched Files
+=====================================
+
+ When `patch' updates a file, it normally sets the file's
+last-modified time stamp to the current time of day. If you are using
+`patch' to track a software distribution, this can cause `make' to
+incorrectly conclude that a patched file is out of date. For example,
+if `syntax.c' depends on `syntax.y', and `patch' updates `syntax.c' and
+then `syntax.y', then `syntax.c' will normally appear to be out of date
+with respect to `syntax.y' even though its contents are actually up to
+date.
+
+ The `-Z' or `--set-utc' option causes `patch' to set a patched
+file's modification and access times to the time stamps given in
+context diff headers. If the context diff headers do not specify a
+time zone, they are assumed to use Coordinated Universal Time (UTC,
+often known as GMT).
+
+ The `-T' or `--set-time' option acts like `-Z' or `--set-utc',
+except that it assumes that the context diff headers' time stamps use
+local time instead of UTC. This option is not recommended, because
+patches using local time cannot easily be used by people in other time
+zones, and because local time stamps are ambiguous when local clocks
+move backwards during daylight-saving time adjustments. If the context
+diff headers specify a time zone, this option is equivalent to `-Z' or
+`--set-utc'.
+
+ `patch' normally refrains from setting a file's time stamps if the
+file's original last-modified time stamp does not match the time given
+in the diff header, of if the file's contents do not exactly match the
+patch. However, if the `-f' or `--force' option is given, the file's
+time stamps are set regardless.
+
+ Due to the limitations of the current `diff' format, `patch' cannot
+update the times of files whose contents have not changed. Also, if
+you set file time stamps to values other than the current time of day,
+you should also remove (e.g., with `make clean') all files that depend
+on the patched files, so that later invocations of `make' do not get
+confused by the patched files' times.
+
+
+File: diff.info, Node: Multiple Patches, Next: patch Directories, Prev: Patching Time Stamps, Up: Merging with patch
+
+Multiple Patches in a File
+==========================
+
+ If the patch file contains more than one patch, and if you do not
+specify an input file on the command line, `patch' tries to apply each
+patch as if they came from separate patch files. This means that it
+determines the name of the file to patch for each patch, and that it
+examines the leading text before each patch for file names and
+prerequisite revision level (*note Making Patches::, for more on that
+topic).
+
+ `patch' uses the following rules to intuit a file name from the
+leading text before a patch. First, `patch' takes an ordered list of
+candidate file names as follows:
+
+ * If the header is that of a context diff, `patch' takes the old and
+ new file names in the header. A name is ignored if it does not
+ have enough slashes to satisfy the `-pNUM' or `--strip=NUM'
+ option. The name `/dev/null' is also ignored.
+
+ * If there is an `Index:' line in the leading garbage and if either
+ the old and new names are both absent or if `patch' is conforming
+ to POSIX, `patch' takes the name in the `Index:' line.
+
+ * For the purpose of the following rules, the candidate file names
+ are considered to be in the order (old, new, index), regardless of
+ the order that they appear in the header.
+
+Then `patch' selects a file name from the candidate list as follows:
+
+ * If some of the named files exist, `patch' selects the first name
+ if conforming to POSIX, and the best name otherwise.
+
+ * If `patch' is not ignoring RCS, ClearCase, and SCCS (*note
+ Revision Control::), and no named files exist but an RCS,
+ ClearCase, or SCCS master is found, `patch' selects the first
+ named file with an RCS, ClearCase, or SCCS master.
+
+ * If no named files exist, no RCS, ClearCase, or SCCS master was
+ found, some names are given, `patch' is not conforming to POSIX,
+ and the patch appears to create a file, `patch' selects the best
+ name requiring the creation of the fewest directories.
+
+ * If no file name results from the above heuristics, you are asked
+ for the name of the file to patch, and `patch' selects that name.
+
+ To determine the "best" of a nonempty list of file names, `patch'
+first takes all the names with the fewest path name components; of
+those, it then takes all the names with the shortest basename; of
+those, it then takes all the shortest names; finally, it takes the
+first remaining name.
+
+ *Note patch and POSIX::, to see whether `patch' is conforming to
+POSIX.
+
+
+File: diff.info, Node: patch Directories, Next: Backups, Prev: Multiple Patches, Up: Merging with patch
+
+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 mail
+reading program, you can patch a file in the `/usr/src/emacs' directory
+directly from a message 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 `-pNUMBER' 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. A sequence
+of one or more adjacent slashes is counted as a single slash. By
+default, `patch' strips off all leading directories, leaving just the
+base file names.
+
+ For example, suppose the file name in the patch file is
+`/gnu/src/emacs/etc/NEWS'. Using `-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'.
+
+ `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.
+
+
+File: diff.info, Node: Backups, Next: Backup Names, Prev: patch Directories, Up: Merging with patch
+
+Backup Files
+============
+
+ Normally, `patch' creates a backup file if the patch does not
+exactly match the original input file, because in that case the
+original data might not be recovered if you undo the patch with `patch
+-R' (*note Reversed Patches::). However, when conforming to POSIX,
+`patch' does not create backup files by default. *Note patch and
+POSIX::.
+
+ The `-b' or `--backup' option causes `patch' to make a backup file
+regardless of whether the patch matches the original input. The
+`--backup-if-mismatch' option causes `patch' to create backup files for
+mismatches files; this is the default when not conforming to POSIX. The
+`--no-backup-if-mismatch' option causes `patch' to not create backup
+files, even for mismatched patches; this is the default when conforming
+to POSIX.
+
+ When backing up a file that does not exist, an empty, unreadable
+backup file is created as a placeholder to represent the nonexistent
+file.
+
+
+File: diff.info, Node: Backup Names, Next: Reject Names, Prev: Backups, Up: Merging with patch
+
+Backup File Names
+=================
+
+ Normally, `patch' renames an original input file into a backup file
+by appending to its name the extension `.orig', or `~' if using `.orig'
+would make the backup file name too long.(1) The `-z BACKUP-SUFFIX' or
+`--suffix=BACKUP-SUFFIX' option causes `patch' to use 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
+`PATCH_VERSION_CONTROL' environment variable, which the `-V' option
+overrides. If `PATCH_VERSION_CONTROL' is not set, the
+`VERSION_CONTROL' environment variable is used instead. Please note
+that these options and variables control backup file names; they do not
+affect the choice of revision control system (*note Revision Control::).
+
+ The values of these environment variables and the argument to the
+`-V' option are like the GNU Emacs `version-control' variable (*note
+Backup Names: (emacs)Backup 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.
+
+ You can also tell `patch' to prepend a prefix, such as a directory
+name, to produce backup file names. The `-B PREFIX' or
+`--prefix=PREFIX' option makes backup files by prepending PREFIX to
+them. The `-Y PREFIX' or `--basename-prefix=PREFIX' prepends PREFIX to
+the last file name component of backup file names instead; for example,
+`-Y ~' causes the backup name for `dir/file.c' to be `dir/~file.c'. If
+you use either of these prefix options, the suffix-based options are
+ignored.
+
+ If you specify the output file with the `-o' option, that file is
+the one that is backed up, not the input file.
+
+ Options that affect the names of backup files do not affect whether
+backups are made. For example, if you specify the
+`--no-backup-if-mismatch' option, none of the options described in this
+section have any affect, because no backups are made.
+
+ ---------- Footnotes ----------
+
+ (1) A coding error in GNU `patch' version 2.5.4 causes it to always
+use `~', but this should be fixed in the next release.
+
+
+File: diff.info, Node: Reject Names, Next: patch Messages, Prev: Backup Names, Up: Merging with patch
+
+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 `#' if if using `.rej' would make the
+backup file name too long).
+
+ 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.
+
+
+File: diff.info, Node: patch Messages, Next: patch and POSIX, Prev: Reject Names, Up: Merging with patch
+
+Messages and Questions from `patch'
+===================================
+
+ `patch' can produce a variety of messages, especially if it has
+trouble decoding its input. In a few situations where it's not sure
+how to proceed, `patch' normally prompts you for more information from
+the keyboard. There are options to produce more or fewer messages, to
+have it not ask for keyboard input, and to affect the way that file
+names are quoted in messages.
+
+* Menu:
+
+* More or Fewer Messages:: Controlling the verbosity of `patch'.
+* patch and Keyboard Input:: Inhibiting keyboard input.
+* patch Quoting Style:: Quoting file names in diagnostics.
+
+ `patch' exits with status 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, you should check the exit
+status, so you don't apply a later patch to a partially patched file.
+
+
+File: diff.info, Node: More or Fewer Messages, Next: patch and Keyboard Input, Up: patch Messages
+
+Controlling the Verbosity of `patch'
+------------------------------------
+
+ You can cause `patch' to produce more messages by using the
+`--verbose' option. For example, when you give this option, the
+message `Hmm...' indicates that `patch' is reading text in the patch
+file, attempting to determine whether there is a patch in that text,
+and if so, what kind of patch it is.
+
+ You can inhibit all terminal output from `patch', unless an error
+occurs, by using the `-s', `--quiet', or `--silent' option.
+
+
+File: diff.info, Node: patch and Keyboard Input, Next: patch Quoting Style, Prev: More or Fewer Messages, Up: patch Messages
+
+Inhibiting Keyboard Input
+-------------------------
+
+ There are two ways you can prevent `patch' from asking you any
+questions. The `-f' or `--force' option assumes that you know what you
+are doing. It causes `patch' to do the following:
+
+ * Skip patches that do not contain file names in their headers.
+
+ * Patch files even though they have the wrong version for the
+ `Prereq:' line in the patch;
+
+ * Assume that patches are not reversed even if they look like they
+ are.
+
+The `-t' or `--batch' option is similar to `-f', in that it suppresses
+questions, but it makes somewhat different assumptions:
+
+ * Skip patches that do not contain file names in their headers (the
+ same as `-f').
+
+ * Skip patches for which the file has the wrong version for the
+ `Prereq:' line in the patch;
+
+ * Assume that patches are reversed if they look like they are.
+
+
+File: diff.info, Node: patch Quoting Style, Prev: patch and Keyboard Input, Up: patch Messages
+
+`patch' Quoting Style
+---------------------
+
+ When `patch' outputs a file name in a diagnostic message, it can
+format the name in any of several ways. This can be useful to output
+file names unambiguously, even if they contain punctuation or special
+characters like newlines. The `--quoting-style=WORD' option controls
+how names are output. The WORD should be one of the following:
+
+`literal'
+ Output names as-is.
+
+`shell'
+ Quote names for the shell if they contain shell metacharacters or
+ would cause ambiguous output.
+
+`shell-always'
+ Quote names for the shell, even if they would normally not require
+ quoting.
+
+`c'
+ Quote names as for a C language string.
+
+`escape'
+ Quote as with `c' except omit the surrounding double-quote
+ characters.
+
+ You can specify the default value of the `--quoting-style' option
+with the environment variable `QUOTING_STYLE'. If that environment
+variable is not set, the default value is `shell', but this default may
+change in a future version of `patch'.
+
+
+File: diff.info, Node: patch and POSIX, Next: patch and Tradition, Prev: patch Messages, Up: Merging with patch
+
+`patch' and the POSIX Standard
+==============================
+
+ If you specify the `--posix' option, or set the `POSIXLY_CORRECT'
+environment variable, `patch' conforms more strictly to the POSIX
+standard, as follows:
+
+ * Take the first existing file from the list (old, new, index) when
+ intuiting file names from diff headers. *Note Multiple Patches::.
+
+ * Do not remove files that are removed by a diff. *Note Creating
+ and Removing::.
+
+ * Do not ask whether to get files from RCS, ClearCase, or SCCS.
+ *Note Revision Control::.
+
+ * Require that all options precede the files in the command line.
+
+ * Do not backup files, even when there is a mismatch. *Note
+ Backups::.
+
+
+
+File: diff.info, Node: patch and Tradition, Prev: patch and POSIX, Up: Merging with patch
+
+GNU `patch' and Traditional `patch'
+===================================
+
+ The current version of GNU `patch' normally follows the POSIX
+standard. *Note patch and POSIX::, for the few exceptions to this
+general rule.
+
+ Unfortunately, POSIX redefined the behavior of `patch' in several
+important ways. You should be aware of the following differences if
+you must interoperate with traditional `patch', or with GNU `patch'
+version 2.1 and earlier.
+
+ * In traditional `patch', the `-p' option's 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 compatibility, 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
+ behavior 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.
+
+ 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 better 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 identical after prefix-stripping. Your
+ patch is normally compatible if each header's file names all
+ contain the same number of slashes.
+
+ * When traditional `patch' asked the user a question, it sent the
+ question 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'
+
+
+
+File: diff.info, Node: Making Patches, Next: Invoking cmp, Prev: Merging with patch, Up: Top
+
+Tips for Making and Using Patches
+*********************************
+
+ Use some common sense when making and using patches. For example,
+when sending bug fixes to a program's maintainer, send several small
+patches, one per independent subject, instead of one large,
+harder-to-digest patch that covers all the subjects.
+
+ Here are some other things you should keep in mind if you are going
+to distribute patches for updating a software package.
+
+* Menu:
+
+* Tips for Patch Producers:: Advice for making patches.
+* Tips for Patch Consumers:: Advice for using patches.
+* Avoiding Common Mistakes:: Avoiding common mistakes when using `patch'.
+* Generating Smaller Patches:: How to generate smaller patches.
+
+
+File: diff.info, Node: Tips for Patch Producers, Next: Tips for Patch Consumers, Up: Making Patches
+
+Tips for Patch Producers
+========================
+
+ To create a patch that changes an older version of a package into a
+newer version, first make a copy of the older and newer versions in
+adjacent subdirectories. It is common to do that by unpacking `tar'
+archives of the two versions.
+
+ To generate the patch, use the command `diff -Naur OLD NEW' where
+OLD and NEW identify the old and new directories. The names OLD and
+NEW should not contain any slashes. The `-N' option lets the patch
+create and remove files; `-a' lets the patch update non-text files; `-u'
+generates useful time stamps and enough context; and `-r' lets the
+patch update subdirectories. Here is an example command, using Bourne
+shell syntax:
+
+ diff -Naur gcc-3.0.3 gcc-3.0.4
+
+ Tell your recipients how to apply the patches. This should include
+which working directory to use, and which `patch' options to use; the
+option `-p1' is recommended. Test your procedure by pretending to be a
+recipient and applying your patches to a copy of the original files.
+
+ *Note Avoiding Common Mistakes::, for how to avoid common mistakes
+when generating a patch.
+
+
+File: diff.info, Node: Tips for Patch Consumers, Next: Avoiding Common Mistakes, Prev: Tips for Patch Producers, Up: Making Patches
+
+Tips for Patch Consumers
+========================
+
+ A patch producer should tell recipients how to apply the patches, so
+the first rule of thumb for a patch consumer is to follow the
+instructions supplied with the patch.
+
+ GNU `diff' can analyze files with arbitrarily long lines and files
+that end in incomplete lines. However, older versions of `patch'
+cannot patch such files. If you are having trouble applying such
+patches, try upgrading to a recent version of GNU `patch'.
+
+
+File: diff.info, Node: Avoiding Common Mistakes, Next: Generating Smaller Patches, Prev: Tips for Patch Consumers, Up: Making Patches
+
+Avoiding Common Mistakes
+========================
+
+ When producing a patch for multiple files, apply `diff' to
+directories whose names do not have slashes. This reduces confusion
+when the patch consumer specifies the `-pNUMBER' option, since this
+option can have surprising results when the old and new file names have
+different numbers of slashes. For example, do not send a patch with a
+header that looks like this:
+
+ diff -Naur v2.0.29/prog/README prog/README
+ --- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800
+ +++ prog/README 2002-03-17 20:49:32.442260588 -0800
+
+because the two file names have different numbers of slashes, and
+different 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 2002-03-10 23:30:39.942229878 -0800
+ +++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800
+
+ Make sure you have specified the file names correctly, either in a
+context diff header or with an `Index:' line. Take care to not send out
+reversed patches, since these make people wonder whether they have
+already applied the patch.
+
+ Avoid sending patches that compare backup file names like
+`README.orig' or `README~', 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'.
+
+ To save people from partially applying a patch before other patches
+that should have gone before it, you can make the first patch in the
+patch file update a file with a name like `patchlevel.h' or
+`version.c', which contains a patch level or version number. If the
+input file contains the wrong version number, `patch' will complain
+immediately.
+
+ An even clearer way to prevent this problem is to put a `Prereq:'
+line before the patch. If the leading text in the patch file contains a
+line that starts with `Prereq:', `patch' takes the next word from that
+line (normally a version number) and checks whether the next input file
+contains that word, preceded and followed by either white space or a
+newline. If not, `patch' prompts you for confirmation before
+proceeding. This makes it difficult to accidentally apply patches in
+the wrong order.
+
+
+File: diff.info, Node: Generating Smaller Patches, Prev: Avoiding Common Mistakes, Up: Making Patches
+
+Generating Smaller Patches
+==========================
+
+ The simplest way to generate a patch is to use `diff -Naur' (*note
+Tips for Patch Producers::), but you might be able to reduce the size
+of the patch by renaming or removing some files before making the
+patch. If the older version of the package contains any files that the
+newer version does not, or if any files have been renamed between the
+two versions, make a list of `rm' and `mv' commands for the user to
+execute in the old version directory before applying the patch. Then
+run those commands yourself in the scratch directory.
+
+ If there are any files that you don't need to include in the patch
+because they can easily be rebuilt from other files (for example,
+`TAGS' and output from `yacc' and `makeinfo'), exclude them from the
+patch by giving `diff' the `-x PATTERN' option (*note Comparing
+Directories::). If you want your patch to modify a derived file
+because your recipients lack tools to build it, make sure that the
+patch for the derived file follows any patches for files that it
+depends on, so that the recipients' time stamps will not confuse `make'.
+
+ Now you can create the patch using `diff -Naur'. Make sure to
+specify the scratch directory first and the newer directory second.
+
+ Add to the top of the patch a note telling the user any `rm' and
+`mv' commands to run before applying the patch. Then you can remove
+the scratch directory.
+
+ You can also shrink the patch size by using fewer lines of context,
+but bear in mind that `patch' typically needs at least two lines for
+proper operation when patches do not exactly match the input files.
+
+
+File: diff.info, Node: Invoking cmp, Next: Invoking diff, Prev: Making Patches, Up: Top
+
+Invoking `cmp'
+**************
+
+ The `cmp' command compares two files, and if they differ, tells the
+first byte and line number where they differ. Bytes and lines are
+numbered starting with 1. The arguments of `cmp' are as follows:
+
+ cmp OPTIONS... FROM-FILE [TO-FILE [FROM-SKIP [TO-SKIP]]]
+
+ The file name `-' is always the standard input. `cmp' also uses the
+standard input if one file name is omitted. The FROM-SKIP and TO-SKIP
+operands specify how many bytes to ignore at the start of each file;
+they are equivalent to the `--ignore-initial=FROM-SKIP:TO-SKIP' option.
+
+ An exit status of 0 means no differences were found, 1 means some
+differences were found, and 2 means trouble.
+
+* Menu:
+
+* cmp Options:: Summary of options to `cmp'.
+
+
+File: diff.info, Node: cmp Options, Up: Invoking cmp
+
+Options to `cmp'
+================
+
+ Below is a summary of all of the options that GNU `cmp' accepts.
+Most options have two equivalent names, one of which is a single letter
+preceded by `-', and the other of which is a long name preceded by
+`--'. Multiple single letter options (unless they take an argument)
+can be combined into a single command line word: `-bl' is equivalent to
+`-b -l'.
+
+`-b'
+`--print-bytes'
+ Print the differing bytes. Display control bytes as a `^'
+ followed by a letter of the alphabet and precede bytes that have
+ the high bit set with `M-' (which stands for "meta").
+
+`--help'
+ Output a summary of usage and then exit.
+
+`-i SKIP'
+`--ignore-initial=SKIP'
+ Ignore any differences in the first SKIP bytes of the input files.
+ Treat files with fewer than SKIP bytes as if they are empty. If
+ SKIP is of the form `FROM-SKIP:TO-SKIP', skip the first FROM-SKIP
+ bytes of the first input file and the first TO-SKIP bytes of the
+ second.
+
+`-l'
+`--verbose'
+ Print the (decimal) byte numbers and (octal) values of all
+ differing bytes.
+
+`-n COUNT'
+`--bytes=COUNT'
+ Compare at most COUNT input bytes.
+
+`-s'
+`--quiet'
+`--silent'
+ Do not print anything; only return an exit status indicating
+ whether the files differ.
+
+`-v'
+`--version'
+ Output version information and then exit.
+
+ In the above table, operands that are byte counts are normally
+decimal, but may be preceded by `0' for octal and `0x' for hexadecimal.
+
+ A byte count can be followed by a suffix to specify a multiple of
+that count; in this case an omitted integer is understood to be 1. A
+bare size letter, or one followed by `iB', specifies a multiple using
+powers of 1024. A size letter followed by `B' specifies powers of 1000
+instead. For example, `-n 4M' and `-n 4MiB' are equivalent to `-n
+4194304', whereas `-n 4MB' is equivalent to `-n 4000000'. This
+notation is upward compatible with the SI prefixes
+(http://www.bipm.fr/enus/3_SI/si-prefixes.html) for decimal multiples
+and with the IEC 60027-2 prefixes for binary multiples
+(http://physics.nist.gov/cuu/Units/binary.html).
+
+ The following suffixes are defined. Large sizes like `1Y' may be
+rejected by your computer due to limitations of its arithmetic.
+
+`kB'
+ kilobyte: 10^3 = 1000.
+
+`k'
+`K'
+`KiB'
+ kibibyte: 2^10 = 1024. `K' is special: the SI prefix is `k' and
+ the IEC 60027-2 prefix is `Ki', but tradition and POSIX use `k' to
+ mean `KiB'.
+
+`MB'
+ megabyte: 10^6 = 1,000,000.
+
+`M'
+`MiB'
+ mebibyte: 2^20 = 1,048,576.
+
+`GB'
+ gigabyte: 10^9 = 1,000,000,000.
+
+`G'
+`GiB'
+ gibibyte: 2^30 = 1,073,741,824.
+
+`TB'
+ terabyte: 10^12 = 1,000,000,000,000.
+
+`T'
+`TiB'
+ tebibyte: 2^40 = 1,099,511,627,776.
+
+`PB'
+ petabyte: 10^15 = 1,000,000,000,000,000.
+
+`P'
+`PiB'
+ pebibyte: 2^50 = 1,125,899,906,842,624.
+
+`EB'
+ exabyte: 10^18 = 1,000,000,000,000,000,000.
+
+`E'
+`EiB'
+ exbibyte: 2^60 = 1,152,921,504,606,846,976.
+
+`ZB'
+ zettabyte: 10^21 = 1,000,000,000,000,000,000,000
+
+`Z'
+`ZiB'
+ 2^70 = 1,180,591,620,717,411,303,424. (`Zi' is a GNU extension to
+ IEC 60027-2.)
+
+`YB'
+ yottabyte: 10^24 = 1,000,000,000,000,000,000,000,000.
+
+`Y'
+`YiB'
+ 2^80 = 1,208,925,819,614,629,174,706,176. (`Yi' is a GNU
+ extension to IEC 60027-2.)
+
+
+File: diff.info, Node: Invoking diff, Next: Invoking diff3, Prev: Invoking cmp, Up: Top
+
+Invoking `diff'
+***************
+
+ The format for running the `diff' command is:
+
+ diff OPTIONS... FILES...
+
+ In the simplest case, two file names FROM-FILE and TO-FILE are
+given, and `diff' compares the contents of FROM-FILE and TO-FILE. A
+file name of `-' stands for text read from the standard input. As a
+special case, `diff - -' compares a copy of standard input to itself.
+
+ If one file is a directory and the other is not, `diff' compares the
+file in the directory whose name is that of the non-directory. The
+non-directory file must not be `-'.
+
+ If two file names are given and both are directories, `diff'
+compares corresponding files in both directories, in alphabetical
+order; this comparison is not recursive unless the `-r' or
+`--recursive' option is given. `diff' never compares the actual
+contents of a directory as if it were a file. The file that is fully
+specified may not be standard input, because standard input is nameless
+and the notion of "file with the same name" does not apply.
+
+ If the `--from-file=FILE' option is given, the number of file names
+is arbitrary, and FILE is compared to each named file. Similarly, if
+the `--to-file=FILE' option is given, each named file is compared to
+FILE.
+
+ `diff' options begin with `-', so normally file names may not begin
+with `-'. However, `--' as an argument by itself treats the remaining
+arguments as file names even if they begin with `-'.
+
+ An exit status of 0 means no differences were found, 1 means some
+differences were found, and 2 means trouble.
+
+* Menu:
+
+* diff Options:: Summary of options to `diff'.
+
+
+File: diff.info, Node: diff Options, Up: Invoking diff
+
+Options to `diff'
+=================
+
+ Below is a summary of all of the options that GNU `diff' accepts.
+Most options have two equivalent names, one of which is a single letter
+preceded by `-', and the other of which is a long name preceded by
+`--'. Multiple single letter options (unless they take an argument)
+can be combined into a single command line word: `-ac' is equivalent to
+`-a -c'. Long named options can be abbreviated to any unique prefix of
+their name. Brackets ([ and ]) indicate that an option takes an
+optional argument.
+
+`-a'
+`--text'
+ Treat all files as text and compare them line-by-line, even if they
+ do not seem to be text. *Note Binary::.
+
+`-b'
+`--ignore-space-change'
+ Ignore changes in amount of white space. *Note White Space::.
+
+`-B'
+`--ignore-blank-lines'
+ Ignore changes that just insert or delete blank lines. *Note
+ Blank Lines::.
+
+`--binary'
+ Read and write data in binary mode. *Note Binary::.
+
+`-c'
+ Use the context output format, showing three lines of context.
+ *Note Context Format::.
+
+`-C LINES'
+`--context[=LINES]'
+ Use the context output format, showing LINES (an integer) lines of
+ context, or three if LINES is not given. *Note Context Format::.
+ For proper operation, `patch' typically needs at least two lines of
+ context.
+
+ On older systems, `diff' supports an obsolete option `-LINES' that
+ has effect when combined with `-c' or `-p'. POSIX 1003.1-2001
+ (*note Standards conformance::) does not allow this; use `-C LINES'
+ instead.
+
+`--changed-group-format=FORMAT'
+ Use FORMAT to output a line group containing differing lines from
+ both files in if-then-else format. *Note Line Group Formats::.
+
+`-d'
+`--minimal'
+ Change the algorithm perhaps find a smaller set of changes. This
+ makes `diff' slower (sometimes much slower). *Note diff
+ Performance::.
+
+`-D NAME'
+`--ifdef=NAME'
+ Make merged `#ifdef' format output, conditional on the preprocessor
+ macro NAME. *Note If-then-else::.
+
+`-e'
+`--ed'
+ Make output that is a valid `ed' script. *Note ed Scripts::.
+
+`-E'
+`--ignore-tab-expansion'
+ Ignore changes due to tab expansion. *Note White Space::.
+
+`-f'
+`--forward-ed'
+ Make output that looks vaguely like an `ed' script but has changes
+ in the order they appear in the file. *Note Forward ed::.
+
+`-F REGEXP'
+`--show-function-line=REGEXP'
+ In context and unified format, for each hunk of differences, show
+ some of the last preceding line that matches REGEXP. *Note
+ Specified Headings::.
+
+`--from-file=FILE'
+ Compare FILE to each operand; FILE may be a directory.
+
+`--help'
+ Output a summary of usage and then exit.
+
+`--horizon-lines=LINES'
+ Do not discard the last LINES lines of the common prefix and the
+ first LINES lines of the common suffix. *Note diff Performance::.
+
+`-i'
+`--ignore-case'
+ Ignore changes in case; consider upper- and lower-case letters
+ equivalent. *Note Case Folding::.
+
+`-I REGEXP'
+`--ignore-matching-lines=REGEXP'
+ Ignore changes that just insert or delete lines that match REGEXP.
+ *Note Specified Folding::.
+
+`--ignore-file-name-case'
+ Ignore case when comparing file names during recursive comparison.
+ *Note Comparing Directories::.
+
+`-l'
+`--paginate'
+ Pass the output through `pr' to paginate it. *Note Pagination::.
+
+`--label=LABEL'
+ Use LABEL instead of the file name in the context format (*note
+ Context Format::) and unified format (*note Unified Format::)
+ headers. *Note RCS::.
+
+`--left-column'
+ Print only the left column of two common lines in side by side
+ format. *Note Side by Side Format::.
+
+`--line-format=FORMAT'
+ Use FORMAT to output all input lines in if-then-else format.
+ *Note Line Formats::.
+
+`-n'
+`--rcs'
+ Output RCS-format diffs; like `-f' except that each command
+ specifies the number of lines affected. *Note RCS::.
+
+`-N'
+`--new-file'
+ In directory comparison, if a file is found in only one directory,
+ treat it as present but empty in the other directory. *Note
+ Comparing Directories::.
+
+`--new-group-format=FORMAT'
+ Use FORMAT to output a group of lines taken from just the second
+ file in if-then-else format. *Note Line Group Formats::.
+
+`--new-line-format=FORMAT'
+ Use FORMAT to output a line taken from just the second file in
+ if-then-else format. *Note Line Formats::.
+
+`--old-group-format=FORMAT'
+ Use FORMAT to output a group of lines taken from just the first
+ file in if-then-else format. *Note Line Group Formats::.
+
+`--old-line-format=FORMAT'
+ Use FORMAT to output a line taken from just the first file in
+ if-then-else format. *Note Line Formats::.
+
+`-p'
+`--show-c-function'
+ Show which C function each change is in. *Note C Function
+ Headings::.
+
+`-q'
+`--brief'
+ Report only whether the files differ, not the details of the
+ differences. *Note Brief::.
+
+`-r'
+`--recursive'
+ When comparing directories, recursively compare any subdirectories
+ found. *Note Comparing Directories::.
+
+`-s'
+`--report-identical-files'
+ Report when two files are the same. *Note Comparing Directories::.
+
+`-S FILE'
+`--starting-file=FILE'
+ When comparing directories, start with the file FILE. This is
+ used for resuming an aborted comparison. *Note Comparing
+ Directories::.
+
+`--speed-large-files'
+ Use heuristics to speed handling of large files that have numerous
+ scattered small changes. *Note diff Performance::.
+
+`--strip-trailing-cr'
+ Strip any trailing carriage return at the end of an input line.
+ *Note Binary::.
+
+`--suppress-common-lines'
+ Do not print common lines in side by side format. *Note Side by
+ Side Format::.
+
+`-t'
+`--expand-tabs'
+ Expand tabs to spaces in the output, to preserve the alignment of
+ tabs in the input files. *Note Tabs::.
+
+`-T'
+`--initial-tab'
+ Output a tab rather than a space before the text of a line in
+ normal or context format. This causes the alignment of tabs in
+ the line to look normal. *Note Tabs::.
+
+`--to-file=FILE'
+ Compare each operand to FILE; FILE may be a directory.
+
+`-u'
+ Use the unified output format, showing three lines of context.
+ *Note Unified Format::.
+
+`--unchanged-group-format=FORMAT'
+ Use FORMAT to output a group of common lines taken from both files
+ in if-then-else format. *Note Line Group Formats::.
+
+`--unchanged-line-format=FORMAT'
+ Use FORMAT to output a line common to both files in if-then-else
+ format. *Note Line Formats::.
+
+`--unidirectional-new-file'
+ When comparing directories, if a file appears only in the second
+ directory of the two, treat it as present but empty in the other.
+ *Note Comparing Directories::.
+
+`-U LINES'
+`--unified[=LINES]'
+ Use the unified output format, showing LINES (an integer) lines of
+ context, or three if LINES is not given. *Note Unified Format::.
+ For proper operation, `patch' typically needs at least two lines of
+ context.
+
+ On older systems, `diff' supports an obsolete option `-LINES' that
+ has effect when combined with `-u'. POSIX 1003.1-2001 (*note
+ Standards conformance::) does not allow this; use `-U LINES'
+ instead.
+
+`-v'
+`--version'
+ Output version information and then exit.
+
+`-w'
+`--ignore-all-space'
+ Ignore white space when comparing lines. *Note White Space::.
+
+`-W COLUMNS'
+`--width=COLUMNS'
+ Output at most COLUMNS (default 130) print columns per line in
+ side by side format. *Note Side by Side Format::.
+
+`-x PATTERN'
+`--exclude=PATTERN'
+ When comparing directories, ignore files and subdirectories whose
+ basenames match PATTERN. *Note Comparing Directories::.
+
+`-X FILE'
+`--exclude-from=FILE'
+ When comparing directories, ignore files and subdirectories whose
+ basenames match any pattern contained in FILE. *Note Comparing
+ Directories::.
+
+`-y'
+`--side-by-side'
+ Use the side by side output format. *Note Side by Side Format::.
+
+
+File: diff.info, Node: Invoking diff3, Next: Invoking patch, Prev: Invoking diff, Up: Top
+
+Invoking `diff3'
+****************
+
+ The `diff3' command compares three files and outputs descriptions of
+their differences. Its arguments are as follows:
+
+ diff3 OPTIONS... MINE OLDER YOURS
+
+ The files to compare are MINE, OLDER, and YOURS. At most one of
+these three file names may be `-', which tells `diff3' to read the
+standard input for that file.
+
+ An exit status of 0 means `diff3' was successful, 1 means some
+conflicts were found, and 2 means trouble.
+
+* Menu:
+
+* diff3 Options:: Summary of options to `diff3'.
+
+
+File: diff.info, Node: diff3 Options, Up: Invoking diff3
+
+Options to `diff3'
+==================
+
+ Below is a summary of all of the options that GNU `diff3' accepts.
+Multiple single letter options (unless they take an argument) can be
+combined into a single command line argument.
+
+`-a'
+`--text'
+ Treat all files as text and compare them line-by-line, even if they
+ do not appear to be text. *Note Binary::.
+
+`-A'
+`--show-all'
+ Incorporate all unmerged changes from OLDER to YOURS into MINE,
+ surrounding conflicts with bracket lines. *Note Marking
+ Conflicts::.
+
+`--diff-program=PROGRAM'
+ Use the compatible comparison program PROGRAM to compare files
+ instead of `diff'.
+
+`-e'
+`--ed'
+ Generate an `ed' script that incorporates all the changes from
+ OLDER to YOURS into MINE. *Note Which Changes::.
+
+`-E'
+`--show-overlap'
+ Like `-e', except bracket lines from overlapping changes' first
+ and third files. *Note Marking Conflicts::. With `-E', an
+ overlapping change looks like this:
+
+ <<<<<<< MINE
+ lines from MINE
+ =======
+ lines from YOURS
+ >>>>>>> YOURS
+
+`--help'
+ Output a summary of usage and then exit.
+
+`-i'
+ Generate `w' and `q' commands at the end of the `ed' script for
+ System V compatibility. This option must be combined with one of
+ the `-AeExX3' options, and may not be combined with `-m'. *Note
+ Saving the Changed File::.
+
+`-L LABEL'
+`--label=LABEL'
+ Use the label LABEL for the brackets output by the `-A', `-E' and
+ `-X' options. This option may be given up to three times, one for
+ each input file. The default labels are the names of the input
+ files. Thus `diff3 -L X -L Y -L Z -m A B C' acts like `diff3 -m A
+ B C', except that the output looks like it came from files named
+ `X', `Y' and `Z' rather than from files named `A', `B' and `C'.
+ *Note Marking Conflicts::.
+
+`-m'
+`--merge'
+ Apply the edit script to the first file and send the result to
+ standard output. Unlike piping the output from `diff3' to `ed',
+ this works even for binary files and incomplete lines. `-A' is
+ assumed if no edit script option is specified. *Note Bypassing
+ ed::.
+
+`-T'
+`--initial-tab'
+ Output a tab rather than two spaces before the text of a line in
+ normal format. This causes the alignment of tabs in the line to
+ look normal. *Note Tabs::.
+
+`-v'
+`--version'
+ Output version information and then exit.
+
+`-x'
+`--overlap-only'
+ Like `-e', except output only the overlapping changes. *Note
+ Which Changes::.
+
+`-X'
+ Like `-E', except output only the overlapping changes. In other
+ words, like `-x', except bracket changes as in `-E'. *Note
+ Marking Conflicts::.
+
+`-3'
+`--easy-only'
+ Like `-e', except output only the nonoverlapping changes. *Note
+ Which Changes::.
+
+
+File: diff.info, Node: Invoking patch, Next: Invoking sdiff, Prev: Invoking diff3, Up: Top
+
+Invoking `patch'
+****************
+
+ Normally `patch' is invoked like this:
+
+ patch <PATCHFILE
+
+ The full format for invoking `patch' is:
+
+ patch OPTIONS... [ORIGFILE [PATCHFILE]]
+
+ You can also specify where to read the patch from with the `-i
+PATCHFILE' or `--input=PATCHFILE' option. If you do not specify
+PATCHFILE, or if PATCHFILE is `-', `patch' reads the patch (that is,
+the `diff' output) from the standard input.
+
+ If you do not specify an input file on the command line, `patch'
+tries to intuit from the "leading text" (any text in the patch that
+comes before the `diff' output) which file to edit. *Note Multiple
+Patches::.
+
+ By default, `patch' replaces the original input file with the
+patched version, possibly after renaming the original file into a
+backup file (*note Backup Names::, for a description of how `patch'
+names backup files). You can also specify where to put the output with
+the `-o FILE' or `--output=FILE' option; however, do not use this option
+if FILE is one of the input files.
+
+* Menu:
+
+* patch Options:: Summary table of options to `patch'.
+
+
+File: diff.info, Node: patch Options, Up: Invoking patch
+
+Options to `patch'
+==================
+
+ Here is a summary of all of the options that GNU `patch' accepts.
+*Note patch and Tradition::, for which of these options are safe to use
+in older versions of `patch'.
+
+ Multiple single-letter options that do not take an argument can be
+combined into a single command line argument with only one dash.
+
+`-b'
+`--backup'
+ Back up the original contents of each file, even if backups would
+ normally not be made. *Note Backups::.
+
+`-B PREFIX'
+`--prefix=PREFIX'
+ Prepend PREFIX to backup file names. *Note Backup Names::.
+
+`--backup-if-mismatch'
+ Back up the original contents of each file if the patch does not
+ exactly match the file. This is the default behavior when not
+ conforming to POSIX. *Note Backups::.
+
+`--binary'
+ Read and write all files in binary mode, except for standard output
+ and `/dev/tty'. This option has no effect on POSIX-conforming
+ systems like GNU/Linux. On systems where this option makes a
+ difference, the patch should be generated by `diff -a --binary'.
+ *Note Binary::.
+
+`-c'
+`--context'
+ Interpret the patch file as a context diff. *Note patch Input::.
+
+`-d DIRECTORY'
+`--directory=DIRECTORY'
+ Make directory DIRECTORY the current directory for interpreting
+ both file names in the patch file, and file names given as
+ arguments to other options. *Note patch Directories::.
+
+`-D NAME'
+`--ifdef=NAME'
+ Make merged if-then-else output using NAME. *Note If-then-else::.
+
+`--dry-run'
+ Print the results of applying the patches without actually changing
+ any files. *Note Dry Runs::.
+
+`-e'
+`--ed'
+ Interpret the patch file as an `ed' script. *Note patch Input::.
+
+`-E'
+`--remove-empty-files'
+ Remove output files that are empty after the patches have been
+ applied. *Note Creating and Removing::.
+
+`-f'
+`--force'
+ Assume that the user knows exactly what he or she is doing, and do
+ not ask any questions. *Note patch Messages::.
+
+`-F LINES'
+`--fuzz=LINES'
+ Set the maximum fuzz factor to LINES. *Note Inexact::.
+
+`-g NUM'
+`--get=NUM'
+ If NUM is positive, get input files from a revision control system
+ as necessary; if zero, do not get the files; if negative, ask the
+ user whether to get the files. *Note Revision Control::.
+
+`--help'
+ Output a summary of usage and then exit.
+
+`-i PATCHFILE'
+`--input=PATCHFILE'
+ Read the patch from PATCHFILE rather than from standard input.
+ *Note patch Options::.
+
+`-l'
+`--ignore-white-space'
+ Let any sequence of blanks (spaces or tabs) in the patch file match
+ any sequence of blanks in the input file. *Note Changed White
+ Space::.
+
+`-n'
+`--normal'
+ Interpret the patch file as a normal diff. *Note patch Input::.
+
+`-N'
+`--forward'
+ Ignore patches that `patch' thinks are reversed or already applied.
+ See also `-R'. *Note Reversed Patches::.
+
+`--no-backup-if-mismatch'
+ Do not back up the original contents of files. This is the default
+ behavior when conforming to POSIX. *Note Backups::.
+
+`-o FILE'
+`--output=FILE'
+ Use FILE as the output file name. *Note patch Options::.
+
+`-pNUMBER'
+`--strip=NUMBER'
+ Set the file name strip count to NUMBER. *Note patch
+ Directories::.
+
+`--posix'
+ Conform to POSIX, as if the `POSIXLY_CORRECT' environment variable
+ had been set. *Note patch and POSIX::.
+
+`--quoting-style=WORD'
+ Use style WORD to quote names in diagnostics, as if the
+ `QUOTING_STYLE' environment variable had been set to WORD. *Note
+ patch Quoting Style::.
+
+`-r REJECT-FILE'
+`--reject-file=REJECT-FILE'
+ Use REJECT-FILE as the reject file name. *Note Reject Names::.
+
+`-R'
+`--reverse'
+ Assume that this patch was created with the old and new files
+ swapped. *Note Reversed Patches::.
+
+`-s'
+`--quiet'
+`--silent'
+ Work silently unless an error occurs. *Note patch Messages::.
+
+`-t'
+`--batch'
+ Do not ask any questions. *Note patch Messages::.
+
+`-T'
+`--set-time'
+ Set the modification and access times of patched files from time
+ stamps given in context diff headers, assuming that the context
+ diff headers use local time. *Note Patching Time Stamps::.
+
+`-u'
+`--unified'
+ Interpret the patch file as a unified diff. *Note patch Input::.
+
+`-v'
+`--version'
+ Output version information and then exit.
+
+`-V BACKUP-STYLE'
+`--version=control=BACKUP-STYLE'
+ Select the naming convention for backup file names. *Note Backup
+ Names::.
+
+`--verbose'
+ Print more diagnostics than usual. *Note patch Messages::.
+
+`-x NUMBER'
+`--debug=NUMBER'
+ Set internal debugging flags. Of interest only to `patch'
+ patchers.
+
+`-Y PREFIX'
+`--basename-prefix=PREFIX'
+ Prepend PREFIX to base names of backup files. *Note Backup
+ Names::.
+
+`-z SUFFIX'
+`--suffix=SUFFIX'
+ Use SUFFIX as the backup extension instead of `.orig' or `~'.
+ *Note Backup Names::.
+
+`-Z'
+`--set-utc'
+ Set the modification and access times of patched files from time
+ stamps given in context diff headers, assuming that the context
+ diff headers use UTC. *Note Patching Time Stamps::.
+
+
+File: diff.info, Node: Invoking sdiff, Next: Standards conformance, Prev: Invoking patch, Up: Top
+
+Invoking `sdiff'
+****************
+
+ The `sdiff' command merges two files and interactively outputs the
+results. Its arguments are as follows:
+
+ sdiff -o OUTFILE OPTIONS... FROM-FILE TO-FILE
+
+ This merges FROM-FILE with TO-FILE, with output to OUTFILE. If
+FROM-FILE is a directory and TO-FILE is not, `sdiff' compares the file
+in FROM-FILE whose file name is that of TO-FILE, and vice versa.
+FROM-FILE and TO-FILE may not both be directories.
+
+ `sdiff' options begin with `-', so normally FROM-FILE and TO-FILE
+may not begin with `-'. However, `--' as an argument by itself treats
+the remaining arguments as file names even if they begin with `-'. You
+may not use `-' as an input file.
+
+ `sdiff' without `-o' (or `--output') produces a side-by-side
+difference. This usage is obsolete; use the `-y' or `--side-by-side'
+option of `diff' instead.
+
+ An exit status of 0 means no differences were found, 1 means some
+differences were found, and 2 means trouble.
+
+* Menu:
+
+* sdiff Options:: Summary of options to `diff'.
+
+
+File: diff.info, Node: sdiff Options, Up: Invoking sdiff
+
+Options to `sdiff'
+==================
+
+ Below is a summary of all of the options that GNU `sdiff' accepts.
+Each option has two equivalent names, one of which is a single letter
+preceded by `-', and the other of which is a long name preceded by
+`--'. Multiple single letter options (unless they take an argument)
+can be combined into a single command line argument. Long named
+options can be abbreviated to any unique prefix of their name.
+
+`-a'
+`--text'
+ Treat all files as text and compare them line-by-line, even if they
+ do not appear to be text. *Note Binary::.
+
+`-b'
+`--ignore-space-change'
+ Ignore changes in amount of white space. *Note White Space::.
+
+`-B'
+`--ignore-blank-lines'
+ Ignore changes that just insert or delete blank lines. *Note
+ Blank Lines::.
+
+`-d'
+`--minimal'
+ Change the algorithm to perhaps find a smaller set of changes.
+ This makes `sdiff' slower (sometimes much slower). *Note diff
+ Performance::.
+
+`--diff-program=PROGRAM'
+ Use the compatible comparison program PROGRAM to compare files
+ instead of `diff'.
+
+`-E'
+`--ignore-tab-expansion'
+ Ignore changes due to tab expansion. *Note White Space::.
+
+`--help'
+ Output a summary of usage and then exit.
+
+`-i'
+`--ignore-case'
+ Ignore changes in case; consider upper- and lower-case to be the
+ same. *Note Case Folding::.
+
+`-I REGEXP'
+`--ignore-matching-lines=REGEXP'
+ Ignore changes that just insert or delete lines that match REGEXP.
+ *Note Specified Folding::.
+
+`-l'
+`--left-column'
+ Print only the left column of two common lines. *Note Side by
+ Side Format::.
+
+`-o FILE'
+`--output=FILE'
+ Put merged output into FILE. This option is required for merging.
+
+`-s'
+`--suppress-common-lines'
+ Do not print common lines. *Note Side by Side Format::.
+
+`--speed-large-files'
+ Use heuristics to speed handling of large files that have numerous
+ scattered small changes. *Note diff Performance::.
+
+`--strip-trailing-cr'
+ Strip any trailing carriage return at the end of an input line.
+ *Note Binary::.
+
+`-t'
+`--expand-tabs'
+ Expand tabs to spaces in the output, to preserve the alignment of
+ tabs in the input files. *Note Tabs::.
+
+`-v'
+`--version'
+ Output version information and then exit.
+
+`-w COLUMNS'
+`--width=COLUMNS'
+ Output at most COLUMNS (default 130) print columns per line.
+ *Note Side by Side Format::. Note that for historical reasons,
+ this option is `-W' in `diff', `-w' in `sdiff'.
+
+`-W'
+`--ignore-all-space'
+ Ignore white space when comparing lines. *Note White Space::.
+ Note that for historical reasons, this option is `-w' in `diff',
+ `-W' in `sdiff'.
+
+
+File: diff.info, Node: Standards conformance, Next: Projects, Prev: Invoking sdiff, Up: Top
+
+Standards conformance
+*********************
+
+ In a few cases, the GNU utilities' default behavior is incompatible
+with the POSIX standard. To suppress these incompatibilities, define
+the `POSIXLY_CORRECT' environment variable. Unless you are checking
+for POSIX conformance, you probably do not need to define
+`POSIXLY_CORRECT'.
+
+ Normally options and operands can appear in any order, and programs
+act as if all the options appear before any operands. For example,
+`diff lao tzu -C 2' acts like `diff -C 2 lao tzu', since `2' is an
+option-argument of `-C'. However, if the `POSIXLY_CORRECT' environment
+variable is set, options must appear before operands, unless otherwise
+specified for a particular command.
+
+ Newer versions of POSIX are occasionally incompatible with older
+versions. For example, older versions of POSIX allowed the command
+`diff -c -10' to have the same meaning as `diff -C 10', but POSIX
+1003.1-2001 `diff' no longer allows digit-string options like `-10'.
+
+ The GNU utilities normally conform to the version of POSIX that is
+standard for your system. To cause them to conform to a different
+version of POSIX, define the `_POSIX2_VERSION' environment variable to
+a value of the form YYYYMM specifying the year and month the standard
+was adopted. Two values are currently supported for `_POSIX2_VERSION':
+`199209' stands for POSIX 1003.2-1992, and `200112' stands for POSIX
+1003.1-2001. For example, if you are running older software that
+assumes an older version of POSIX and uses `diff -c -10', you can work
+around the compatibility problems by setting `_POSIX2_VERSION=199209'
+in your environment.
+
+
+File: diff.info, Node: Projects, Next: Copying This Manual, Prev: Standards conformance, Up: Top
+
+Future Projects
+***************
+
+ Here are some ideas for improving GNU `diff' and `patch'. The GNU
+project has identified some improvements as potential programming
+projects for volunteers. You can also help by reporting any bugs that
+you find.
+
+ If you are a programmer and would like to contribute something to the
+GNU project, please consider volunteering for one of these projects.
+If you are seriously contemplating work, please write to <gnu@gnu.org>
+to coordinate with other volunteers.
+
+* Menu:
+
+* Shortcomings:: Suggested projects for improvements.
+* Bugs:: Reporting bugs.
+
+
+File: diff.info, Node: Shortcomings, Next: Bugs, Up: Projects
+
+Suggested Projects for Improving GNU `diff' and `patch'
+=======================================================
+
+ One should be able to use GNU `diff' to generate a patch from any
+pair of directory trees, and given the patch and a copy of one such
+tree, use `patch' to generate a faithful copy of the other.
+Unfortunately, some changes to directory trees cannot be expressed using
+current patch formats; also, `patch' does not handle some of the
+existing formats. These shortcomings motivate the following suggested
+projects.
+
+* Menu:
+
+* Internationalization:: Handling multibyte and varying-width characters.
+* Changing Structure:: Handling changes to the directory structure.
+* Special Files:: Handling symbolic links, device special files, etc.
+* Unusual File Names:: Handling file names that contain unusual characters.
+* Time Stamp Order:: Outputting diffs in time stamp order.
+* Ignoring Changes:: Ignoring certain changes while showing others.
+* Speedups:: Improving performance.
+
+
+File: diff.info, Node: Internationalization, Next: Changing Structure, Up: Shortcomings
+
+Handling Multibyte and Varying-Width Characters
+-----------------------------------------------
+
+ `diff', `diff3' and `sdiff' treat each line of input as a string of
+unibyte characters. This can mishandle multibyte characters in some
+cases. For example, when asked to ignore spaces, `diff' does not
+properly ignore a multibyte space character.
+
+ Also, `diff' currently assumes that each byte is one column wide,
+and this assumption is incorrect in some locales, e.g., locales that
+use UTF-8 encoding. This causes problems with the `-y' or
+`--side-by-side' option of `diff'.
+
+ These problems need to be fixed without unduly affecting the
+performance of the utilities in unibyte environments.
+
+ The IBM GNU/Linux Technology Center Internationalization Team has
+proposed some patches to support internationalized `diff'
+`http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz'.
+Unfortunately, these patches are incomplete and are to an older version
+of `diff', so more work needs to be done in this area.
+
+
+File: diff.info, Node: Changing Structure, Next: Special Files, Prev: Internationalization, Up: Shortcomings
+
+Handling Changes to the Directory Structure
+-------------------------------------------
+
+ `diff' and `patch' do not handle some changes to directory
+structure. For example, suppose one directory tree contains a directory
+named `D' with some subsidiary files, and another contains a file with
+the same name `D'. `diff -r' does not output enough information for
+`patch' to transform the directory subtree into the file.
+
+ There should be a way to specify that a file has been removed without
+having to include its entire contents in the patch file. There should
+also be a way to tell `patch' that a file was renamed, even if there is
+no way for `diff' to generate such information. There should be a way
+to tell `patch' that a file's time stamp has changed, even if its
+contents have not changed.
+
+ These problems can be fixed by extending the `diff' output format to
+represent changes in directory structure, and extending `patch' to
+understand these extensions.
+
+
+File: diff.info, Node: Special Files, Next: Unusual File Names, Prev: Changing Structure, Up: Shortcomings
+
+Files that are Neither Directories Nor Regular Files
+----------------------------------------------------
+
+ Some files are neither directories nor regular files: they are
+unusual files like symbolic links, device special files, named pipes,
+and sockets. Currently, `diff' treats symbolic links like regular
+files; it treats other special files like regular files if they are
+specified at the top level, but simply reports their presence when
+comparing directories. This means that `patch' cannot represent changes
+to such files. For example, if you change which file a symbolic link
+points to, `diff' outputs the difference between the two files, instead
+of the change to the symbolic link.
+
+ `diff' should optionally report changes to special files specially,
+and `patch' should be extended to understand these extensions.
+
+
+File: diff.info, Node: Unusual File Names, Next: Time Stamp Order, Prev: Special Files, Up: Shortcomings
+
+File Names that Contain Unusual Characters
+------------------------------------------
+
+ When a file name contains an unusual character like a newline or
+white space, `diff -r' generates a patch that `patch' cannot parse.
+The problem is with format of `diff' output, not just with `patch',
+because with odd enough file names one can cause `diff' to generate a
+patch that is syntactically correct but patches the wrong files. The
+format of `diff' output should be extended to handle all possible file
+names.
+
+
+File: diff.info, Node: Time Stamp Order, Next: Ignoring Changes, Prev: Unusual File Names, Up: Shortcomings
+
+Outputting Diffs in Time Stamp Order
+------------------------------------
+
+ Applying `patch' to a multiple-file diff can result in files whose
+time stamps are out of order. GNU `patch' has options to restore the
+time stamps of the updated files (*note Patching Time Stamps::), but
+sometimes it is useful to generate a patch that works even if the
+recipient does not have GNU patch, or does not use these options. One
+way to do this would be to implement a `diff' option to output diffs in
+time stamp order.
+
+
+File: diff.info, Node: Ignoring Changes, Next: Speedups, Prev: Time Stamp Order, Up: Shortcomings
+
+Ignoring Certain Changes
+------------------------
+
+ It would be nice to have a feature for specifying two strings, one in
+FROM-FILE and one in TO-FILE, which should be considered to match.
+Thus, if the two strings are `foo' and `bar', then if two lines differ
+only in that `foo' in file 1 corresponds to `bar' in file 2, the lines
+are treated as identical.
+
+ It is not clear how general this feature can or should be, or what
+syntax should be used for it.
+
+ A partial substitute is to filter one or both files before comparing,
+e.g.:
+
+ sed 's/foo/bar/g' file1 | diff - file2
+
+ However, this outputs the filtered text, not the original.
+
+
+File: diff.info, Node: Speedups, Prev: Ignoring Changes, Up: Shortcomings
+
+Improving Performance
+---------------------
+
+ When comparing two large directory structures, one of which was
+originally copied from the other with time stamps preserved (e.g., with
+`cp -pR'), it would greatly improve performance if an option told
+`diff' to assume that two files with the same size and time stamps have
+the same content. *Note diff Performance::.
+
+
+File: diff.info, Node: Bugs, Prev: Shortcomings, Up: Projects
+
+Reporting Bugs
+==============
+
+ If you think you have found a bug in GNU `cmp', `diff', `diff3', or
+`sdiff', please report it by electronic mail to the GNU utilities bug
+report mailing list
+(http://mail.gnu.org/mailman/listinfo/bug-gnu-utils)
+<bug-gnu-utils@gnu.org>. Please send bug reports for GNU `patch' to
+<bug-patch@gnu.org>. Send as precise a description of the problem as
+you can, including the output of the `--version' option and sample
+input files that produce the bug, if applicable. If you have a
+nontrivial fix for the bug, please send it as well. If you have a
+patch, please send it too. It may simplify the maintainer's job if the
+patch is relative to a recent test release, which you can find in the
+directory `ftp://alpha.gnu.org/gnu/diffutils/'.
+
+
+File: diff.info, Node: Copying This Manual, Next: Index, Prev: Projects, Up: Top
+
+Copying This Manual
+*******************
+
+* Menu:
+
+* GNU Free Documentation License:: License for copying this manual.
+
+
+File: diff.info, Node: GNU Free Documentation License, Up: Copying This Manual
+
+GNU Free Documentation License
+==============================
+
+ Version 1.1, March 2000
+ Copyright (C) 2000 Free Software Foundation, Inc.
+ 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+ 0. PREAMBLE
+
+ The purpose of this License is to make a manual, textbook, or other
+ written document "free" in the sense of freedom: to assure everyone
+ the effective freedom to copy and redistribute it, with or without
+ modifying it, either commercially or noncommercially. Secondarily,
+ this License preserves for the author and publisher a way to get
+ credit for their work, while not being considered responsible for
+ modifications made by others.
+
+ This License is a kind of "copyleft", which means that derivative
+ works of the document must themselves be free in the same sense.
+ It complements the GNU General Public License, which is a copyleft
+ license designed for free software.
+
+ We have designed this License in order to use it for manuals for
+ free software, because free software needs free documentation: a
+ free program should come with manuals providing the same freedoms
+ that the software does. But this License is not limited to
+ software manuals; it can be used for any textual work, regardless
+ of subject matter or whether it is published as a printed book.
+ We recommend this License principally for works whose purpose is
+ instruction or reference.
+
+ 1. APPLICABILITY AND DEFINITIONS
+
+ This License applies to any manual or other work that contains a
+ notice placed by the copyright holder saying it can be distributed
+ under the terms of this License. The "Document", below, refers to
+ any such manual or work. Any member of the public is a licensee,
+ and is addressed as "you".
+
+ A "Modified Version" of the Document means any work containing the
+ Document or a portion of it, either copied verbatim, or with
+ modifications and/or translated into another language.
+
+ A "Secondary Section" is a named appendix or a front-matter
+ section of the Document that deals exclusively with the
+ relationship of the publishers or authors of the Document to the
+ Document's overall subject (or to related matters) and contains
+ nothing that could fall directly within that overall subject.
+ (For example, if the Document is in part a textbook of
+ mathematics, a Secondary Section may not explain any mathematics.)
+ The relationship could be a matter of historical connection with
+ the subject or with related matters, or of legal, commercial,
+ philosophical, ethical or political position regarding them.
+
+ The "Invariant Sections" are certain Secondary Sections whose
+ titles are designated, as being those of Invariant Sections, in
+ the notice that says that the Document is released under this
+ License.
+
+ The "Cover Texts" are certain short passages of text that are
+ listed, as Front-Cover Texts or Back-Cover Texts, in the notice
+ that says that the Document is released under this License.
+
+ A "Transparent" copy of the Document means a machine-readable copy,
+ represented in a format whose specification is available to the
+ general public, whose contents can be viewed and edited directly
+ and straightforwardly with generic text editors or (for images
+ composed of pixels) generic paint programs or (for drawings) some
+ widely available drawing editor, and that is suitable for input to
+ text formatters or for automatic translation to a variety of
+ formats suitable for input to text formatters. A copy made in an
+ otherwise Transparent file format whose markup has been designed
+ to thwart or discourage subsequent modification by readers is not
+ Transparent. A copy that is not "Transparent" is called "Opaque".
+
+ Examples of suitable formats for Transparent copies include plain
+ ASCII without markup, Texinfo input format, LaTeX input format,
+ SGML or XML using a publicly available DTD, and
+ standard-conforming simple HTML designed for human modification.
+ Opaque formats include PostScript, PDF, proprietary formats that
+ can be read and edited only by proprietary word processors, SGML
+ or XML for which the DTD and/or processing tools are not generally
+ available, and the machine-generated HTML produced by some word
+ processors for output purposes only.
+
+ The "Title Page" means, for a printed book, the title page itself,
+ plus such following pages as are needed to hold, legibly, the
+ material this License requires to appear in the title page. For
+ works in formats which do not have any title page as such, "Title
+ Page" means the text near the most prominent appearance of the
+ work's title, preceding the beginning of the body of the text.
+
+ 2. VERBATIM COPYING
+
+ You may copy and distribute the Document in any medium, either
+ commercially or noncommercially, provided that this License, the
+ copyright notices, and the license notice saying this License
+ applies to the Document are reproduced in all copies, and that you
+ add no other conditions whatsoever to those of this License. You
+ may not use technical measures to obstruct or control the reading
+ or further copying of the copies you make or distribute. However,
+ you may accept compensation in exchange for copies. If you
+ distribute a large enough number of copies you must also follow
+ the conditions in section 3.
+
+ You may also lend copies, under the same conditions stated above,
+ and you may publicly display copies.
+
+ 3. COPYING IN QUANTITY
+
+ If you publish printed copies of the Document numbering more than
+ 100, and the Document's license notice requires Cover Texts, you
+ must enclose the copies in covers that carry, clearly and legibly,
+ all these Cover Texts: Front-Cover Texts on the front cover, and
+ Back-Cover Texts on the back cover. Both covers must also clearly
+ and legibly identify you as the publisher of these copies. The
+ front cover must present the full title with all words of the
+ title equally prominent and visible. You may add other material
+ on the covers in addition. Copying with changes limited to the
+ covers, as long as they preserve the title of the Document and
+ satisfy these conditions, can be treated as verbatim copying in
+ other respects.
+
+ If the required texts for either cover are too voluminous to fit
+ legibly, you should put the first ones listed (as many as fit
+ reasonably) on the actual cover, and continue the rest onto
+ adjacent pages.
+
+ If you publish or distribute Opaque copies of the Document
+ numbering more than 100, you must either include a
+ machine-readable Transparent copy along with each Opaque copy, or
+ state in or with each Opaque copy a publicly-accessible
+ computer-network location containing a complete Transparent copy
+ of the Document, free of added material, which the general
+ network-using public has access to download anonymously at no
+ charge using public-standard network protocols. If you use the
+ latter option, you must take reasonably prudent steps, when you
+ begin distribution of Opaque copies in quantity, to ensure that
+ this Transparent copy will remain thus accessible at the stated
+ location until at least one year after the last time you
+ distribute an Opaque copy (directly or through your agents or
+ retailers) of that edition to the public.
+
+ It is requested, but not required, that you contact the authors of
+ the Document well before redistributing any large number of
+ copies, to give them a chance to provide you with an updated
+ version of the Document.
+
+ 4. MODIFICATIONS
+
+ You may copy and distribute a Modified Version of the Document
+ under the conditions of sections 2 and 3 above, provided that you
+ release the Modified Version under precisely this License, with
+ the Modified Version filling the role of the Document, thus
+ licensing distribution and modification of the Modified Version to
+ whoever possesses a copy of it. In addition, you must do these
+ things in the Modified Version:
+
+ A. Use in the Title Page (and on the covers, if any) a title
+ distinct from that of the Document, and from those of
+ previous versions (which should, if there were any, be listed
+ in the History section of the Document). You may use the
+ same title as a previous version if the original publisher of
+ that version gives permission.
+
+ B. List on the Title Page, as authors, one or more persons or
+ entities responsible for authorship of the modifications in
+ the Modified Version, together with at least five of the
+ principal authors of the Document (all of its principal
+ authors, if it has less than five).
+
+ C. State on the Title page the name of the publisher of the
+ Modified Version, as the publisher.
+
+ D. Preserve all the copyright notices of the Document.
+
+ E. Add an appropriate copyright notice for your modifications
+ adjacent to the other copyright notices.
+
+ F. Include, immediately after the copyright notices, a license
+ notice giving the public permission to use the Modified
+ Version under the terms of this License, in the form shown in
+ the Addendum below.
+
+ G. Preserve in that license notice the full lists of Invariant
+ Sections and required Cover Texts given in the Document's
+ license notice.
+
+ H. Include an unaltered copy of this License.
+
+ I. Preserve the section entitled "History", and its title, and
+ add to it an item stating at least the title, year, new
+ authors, and publisher of the Modified Version as given on
+ the Title Page. If there is no section entitled "History" in
+ the Document, create one stating the title, year, authors,
+ and publisher of the Document as given on its Title Page,
+ then add an item describing the Modified Version as stated in
+ the previous sentence.
+
+ J. Preserve the network location, if any, given in the Document
+ for public access to a Transparent copy of the Document, and
+ likewise the network locations given in the Document for
+ previous versions it was based on. These may be placed in
+ the "History" section. You may omit a network location for a
+ work that was published at least four years before the
+ Document itself, or if the original publisher of the version
+ it refers to gives permission.
+
+ K. In any section entitled "Acknowledgments" or "Dedications",
+ preserve the section's title, and preserve in the section all
+ the substance and tone of each of the contributor
+ acknowledgments and/or dedications given therein.
+
+ L. Preserve all the Invariant Sections of the Document,
+ unaltered in their text and in their titles. Section numbers
+ or the equivalent are not considered part of the section
+ titles.
+
+ M. Delete any section entitled "Endorsements". Such a section
+ may not be included in the Modified Version.
+
+ N. Do not retitle any existing section as "Endorsements" or to
+ conflict in title with any Invariant Section.
+
+ If the Modified Version includes new front-matter sections or
+ appendices that qualify as Secondary Sections and contain no
+ material copied from the Document, you may at your option
+ designate some or all of these sections as invariant. To do this,
+ add their titles to the list of Invariant Sections in the Modified
+ Version's license notice. These titles must be distinct from any
+ other section titles.
+
+ You may add a section entitled "Endorsements", provided it contains
+ nothing but endorsements of your Modified Version by various
+ parties--for example, statements of peer review or that the text
+ has been approved by an organization as the authoritative
+ definition of a standard.
+
+ You may add a passage of up to five words as a Front-Cover Text,
+ and a passage of up to 25 words as a Back-Cover Text, to the end
+ of the list of Cover Texts in the Modified Version. Only one
+ passage of Front-Cover Text and one of Back-Cover Text may be
+ added by (or through arrangements made by) any one entity. If the
+ Document already includes a cover text for the same cover,
+ previously added by you or by arrangement made by the same entity
+ you are acting on behalf of, you may not add another; but you may
+ replace the old one, on explicit permission from the previous
+ publisher that added the old one.
+
+ The author(s) and publisher(s) of the Document do not by this
+ License give permission to use their names for publicity for or to
+ assert or imply endorsement of any Modified Version.
+
+ 5. COMBINING DOCUMENTS
+
+ You may combine the Document with other documents released under
+ this License, under the terms defined in section 4 above for
+ modified versions, provided that you include in the combination
+ all of the Invariant Sections of all of the original documents,
+ unmodified, and list them all as Invariant Sections of your
+ combined work in its license notice.
+
+ The combined work need only contain one copy of this License, and
+ multiple identical Invariant Sections may be replaced with a single
+ copy. If there are multiple Invariant Sections with the same name
+ but different contents, make the title of each such section unique
+ by adding at the end of it, in parentheses, the name of the
+ original author or publisher of that section if known, or else a
+ unique number. Make the same adjustment to the section titles in
+ the list of Invariant Sections in the license notice of the
+ combined work.
+
+ In the combination, you must combine any sections entitled
+ "History" in the various original documents, forming one section
+ entitled "History"; likewise combine any sections entitled
+ "Acknowledgments", and any sections entitled "Dedications". You
+ must delete all sections entitled "Endorsements."
+
+ 6. COLLECTIONS OF DOCUMENTS
+
+ You may make a collection consisting of the Document and other
+ documents released under this License, and replace the individual
+ copies of this License in the various documents with a single copy
+ that is included in the collection, provided that you follow the
+ rules of this License for verbatim copying of each of the
+ documents in all other respects.
+
+ You may extract a single document from such a collection, and
+ distribute it individually under this License, provided you insert
+ a copy of this License into the extracted document, and follow
+ this License in all other respects regarding verbatim copying of
+ that document.
+
+ 7. AGGREGATION WITH INDEPENDENT WORKS
+
+ A compilation of the Document or its derivatives with other
+ separate and independent documents or works, in or on a volume of
+ a storage or distribution medium, does not as a whole count as a
+ Modified Version of the Document, provided no compilation
+ copyright is claimed for the compilation. Such a compilation is
+ called an "aggregate", and this License does not apply to the
+ other self-contained works thus compiled with the Document, on
+ account of their being thus compiled, if they are not themselves
+ derivative works of the Document.
+
+ If the Cover Text requirement of section 3 is applicable to these
+ copies of the Document, then if the Document is less than one
+ quarter of the entire aggregate, the Document's Cover Texts may be
+ placed on covers that surround only the Document within the
+ aggregate. Otherwise they must appear on covers around the whole
+ aggregate.
+
+ 8. TRANSLATION
+
+ Translation is considered a kind of modification, so you may
+ distribute translations of the Document under the terms of section
+ 4. Replacing Invariant Sections with translations requires special
+ permission from their copyright holders, but you may include
+ translations of some or all Invariant Sections in addition to the
+ original versions of these Invariant Sections. You may include a
+ translation of this License provided that you also include the
+ original English version of this License. In case of a
+ disagreement between the translation and the original English
+ version of this License, the original English version will prevail.
+
+ 9. TERMINATION
+
+ You may not copy, modify, sublicense, or distribute the Document
+ except as expressly provided for under this License. Any other
+ attempt to copy, modify, sublicense or distribute the Document is
+ void, and will automatically terminate your rights under this
+ License. However, parties who have received copies, or rights,
+ from you under this License will not have their licenses
+ terminated so long as such parties remain in full compliance.
+
+ 10. FUTURE REVISIONS OF THIS LICENSE
+
+ The Free Software Foundation may publish new, revised versions of
+ the GNU Free Documentation License from time to time. Such new
+ versions will be similar in spirit to the present version, but may
+ differ in detail to address new problems or concerns. See
+ `http://www.gnu.org/copyleft/'.
+
+ Each version of the License is given a distinguishing version
+ number. If the Document specifies that a particular numbered
+ version of this License "or any later version" applies to it, you
+ have the option of following the terms and conditions either of
+ that specified version or of any later version that has been
+ published (not as a draft) by the Free Software Foundation. If
+ the Document does not specify a version number of this License,
+ you may choose any version ever published (not as a draft) by the
+ Free Software Foundation.
+
+ADDENDUM: How to use this License for your documents
+----------------------------------------------------
+
+ To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and license
+notices just after the title page:
+
+ Copyright (C) YEAR YOUR NAME.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being LIST THEIR TITLES, with the
+ Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+
+ If you have no Invariant Sections, write "with no Invariant Sections"
+instead of saying which ones are invariant. If you have no Front-Cover
+Texts, write "no Front-Cover Texts" instead of "Front-Cover Texts being
+LIST"; likewise for Back-Cover Texts.
+
+ If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License, to
+permit their use in free software.
+
+
+File: diff.info, Node: Index, Prev: Copying This Manual, Up: Top
+
+Index
+*****
+
+* Menu:
+
+* ! output format: Context.
+* +- output format: Unified Format.
+* < output format: Normal.
+* <<<<<<< for marking conflicts: Marking Conflicts.
+* _POSIX2_VERSION: Standards conformance.
+* aligning tab stops: Tabs.
+* alternate file names: Alternate Names.
+* backup file names: Backup Names.
+* backup file strategy: Backups.
+* binary file diff: Binary.
+* blank and tab difference suppression: White Space.
+* blank line difference suppression: Blank Lines.
+* brief difference reports: Brief.
+* bug reports: Bugs.
+* C function headings: C Function Headings.
+* C if-then-else output format: If-then-else.
+* case difference suppression: Case Folding.
+* ClearCase: Revision Control.
+* cmp invocation: Invoking cmp.
+* cmp options: cmp Options.
+* columnar output: Side by Side.
+* common mistakes with patches: Avoiding Common Mistakes.
+* comparing three files: Comparing Three Files.
+* conflict: diff3 Merging.
+* conflict marking: Marking Conflicts.
+* context output format: Context.
+* creating files: Creating and Removing.
+* diagnostics from patch: patch Messages.
+* diff invocation: Invoking diff.
+* diff merging: Interactive Merging.
+* diff options: diff Options.
+* diff sample input: Sample diff Input.
+* diff3 hunks: diff3 Hunks.
+* diff3 invocation: Invoking diff3.
+* diff3 options: diff3 Options.
+* diff3 sample input: Sample diff3 Input.
+* directories and patch: patch Directories.
+* directory structure changes: Changing Structure.
+* dry runs for patch: Dry Runs.
+* ed script output format: ed Scripts.
+* EDITOR: Merge Commands.
+* empty files, removing: Creating and Removing.
+* exabyte, definition of: cmp Options.
+* exbibyte, definition of: cmp Options.
+* FDL, GNU Free Documentation License: GNU Free Documentation License.
+* file name alternates: Alternate Names.
+* file names with unusual characters: Unusual File Names.
+* format of diff output: Output Formats.
+* format of diff3 output: Comparing Three Files.
+* formats for if-then-else line groups: Line Group Formats.
+* forward ed script output format: Forward ed.
+* full lines: Incomplete Lines.
+* function headings, C: C Function Headings.
+* fuzz factor when patching: Inexact.
+* gibibyte, definition of: cmp Options.
+* gigabyte, definition of: cmp Options.
+* headings: Sections.
+* hunks: Hunks.
+* hunks for diff3: diff3 Hunks.
+* if-then-else output format: If-then-else.
+* ifdef output format: If-then-else.
+* imperfect patch application: Imperfect.
+* incomplete line merging: Merging Incomplete Lines.
+* incomplete lines: Incomplete Lines.
+* inexact patches: Inexact.
+* inhibit messages from patch: More or Fewer Messages.
+* interactive merging: Interactive Merging.
+* introduction: Comparison.
+* intuiting file names from patches: Multiple Patches.
+* invoking cmp: Invoking cmp.
+* invoking diff: Invoking diff.
+* invoking diff3: Invoking diff3.
+* invoking patch: Invoking patch.
+* invoking sdiff: Invoking sdiff.
+* keyboard input to patch: patch and Keyboard Input.
+* kibibyte, definition of: cmp Options.
+* kilobyte, definition of: cmp Options.
+* LC_COLLATE: Comparing Directories.
+* LC_NUMERIC: Line Group Formats.
+* LC_TIME: Detailed Context.
+* line formats: Line Formats.
+* line group formats: Line Group Formats.
+* mebibyte, definition of: cmp Options.
+* megabyte, definition of: cmp Options.
+* merge commands: Merge Commands.
+* merged diff3 format: Bypassing ed.
+* merged output format: If-then-else.
+* merging from a common ancestor: diff3 Merging.
+* merging interactively: Merge Commands.
+* messages from patch: patch Messages.
+* multibyte characters: Internationalization.
+* multiple patches: Multiple Patches.
+* newline treatment by diff: Incomplete Lines.
+* normal output format: Normal.
+* options for cmp: cmp Options.
+* options for diff: diff Options.
+* options for diff3: diff3 Options.
+* options for patch: patch Options.
+* options for sdiff: sdiff Options.
+* output formats: Output Formats.
+* overlap: diff3 Merging.
+* overlapping change, selection of: Which Changes.
+* overview of diff and patch: Overview.
+* paginating diff output: Pagination.
+* patch consumer tips: Tips for Patch Consumers.
+* patch input format: patch Input.
+* patch invocation: Invoking patch.
+* patch messages and questions: patch Messages.
+* patch options: patch Options.
+* patch producer tips: Tips for Patch Producers.
+* patch, common mistakes: Avoiding Common Mistakes.
+* PATCH_GET: Revision Control.
+* PATCH_VERSION_CONTROL: Backup Names.
+* patches, shrinking: Generating Smaller Patches.
+* patching directories: patch Directories.
+* pebibyte, definition of: cmp Options.
+* performance of diff: diff Performance.
+* petabyte, definition of: cmp Options.
+* POSIX <1>: Standards conformance.
+* POSIX: patch and POSIX.
+* POSIXLY_CORRECT <1>: patch and POSIX.
+* POSIXLY_CORRECT: Standards conformance.
+* projects for directories: Shortcomings.
+* quoting style: patch Quoting Style.
+* QUOTING_STYLE: patch Quoting Style.
+* RCS: Revision Control.
+* RCS script output format: RCS.
+* regular expression matching headings: Specified Headings.
+* regular expression suppression: Specified Folding.
+* reject file names: Reject Names.
+* removing empty files: Creating and Removing.
+* reporting bugs: Bugs.
+* reversed patches: Reversed Patches.
+* revision control: Revision Control.
+* sample input for diff: Sample diff Input.
+* sample input for diff3: Sample diff3 Input.
+* SCCS: Revision Control.
+* script output formats: Scripts.
+* sdiff invocation: Invoking sdiff.
+* sdiff options: sdiff Options.
+* sdiff output format: sdiff Option Summary.
+* section headings: Sections.
+* side by side: Side by Side.
+* side by side format: Side by Side Format.
+* SIMPLE_BACKUP_SUFFIX: Backup Names.
+* special files: Special Files.
+* specified headings: Specified Headings.
+* summarizing which files differ: Brief.
+* System V diff3 compatibility: Saving the Changed File.
+* tab and blank difference suppression: White Space.
+* tab stop alignment: Tabs.
+* tebibyte, definition of: cmp Options.
+* terabyte, definition of: cmp Options.
+* testing patch: Dry Runs.
+* text versus binary diff: Binary.
+* time stamp format, context diffs: Detailed Context.
+* time stamp format, unified diffs: Detailed Unified.
+* time stamps on patched files: Patching Time Stamps.
+* traditional patch: patch and Tradition.
+* two-column output: Side by Side.
+* unified output format: Unified Format.
+* unmerged change: Which Changes.
+* varying-width characters: Internationalization.
+* verbose messages from patch: More or Fewer Messages.
+* version control: Revision Control.
+* VERSION_CONTROL <1>: Backup Names.
+* VERSION_CONTROL: Revision Control.
+* white space in patches: Changed White Space.
+* yottabyte, definition of: cmp Options.
+* zettabyte, definition of: cmp Options.
+
+
+
+Tag Table:
+Node: Top1653
+Node: Overview4045
+Node: Comparison7202
+Node: Hunks9888
+Node: White Space11313
+Node: Blank Lines12807
+Node: Case Folding13562
+Node: Specified Folding13977
+Node: Brief15052
+Node: Binary16295
+Node: Output Formats20358
+Node: Sample diff Input21076
+Node: Normal22569
+Node: Detailed Normal23564
+Node: Example Normal25289
+Node: Context26011
+Node: Context Format27567
+Node: Detailed Context28345
+Node: Example Context30234
+Node: Less Context31748
+Node: Unified Format32894
+Node: Detailed Unified33676
+Node: Example Unified34787
+Node: Sections35807
+Node: Specified Headings36552
+Node: C Function Headings38083
+Node: Alternate Names38908
+Node: Side by Side39808
+Node: Side by Side Format41947
+Node: Example Side by Side42836
+Node: Scripts44162
+Node: ed Scripts44563
+Node: Detailed ed45756
+Node: Example ed47497
+Node: Forward ed47934
+Node: RCS48696
+Node: If-then-else49904
+Node: Line Group Formats51572
+Node: Line Formats57437
+Node: Detailed If-then-else60693
+Node: Example If-then-else62583
+Node: Incomplete Lines63632
+Node: Comparing Directories65263
+Node: Adjusting Output69220
+Node: Tabs69645
+Node: Pagination71177
+Node: diff Performance71626
+Node: Comparing Three Files74708
+Node: Sample diff3 Input75580
+Node: Detailed diff3 Normal76528
+Node: diff3 Hunks78307
+Node: Example diff3 Normal79593
+Node: diff3 Merging80616
+Node: Which Changes82854
+Node: Marking Conflicts84258
+Node: Bypassing ed86714
+Node: Merging Incomplete Lines88068
+Node: Saving the Changed File88784
+Node: Interactive Merging89390
+Node: sdiff Option Summary90094
+Node: Merge Commands91242
+Node: Merging with patch92503
+Node: patch Input94867
+Node: Revision Control95537
+Node: Imperfect96689
+Node: Changed White Space97825
+Node: Reversed Patches98606
+Node: Inexact100056
+Node: Dry Runs103599
+Node: Creating and Removing104447
+Node: Patching Time Stamps105486
+Node: Multiple Patches107677
+Node: patch Directories110328
+Node: Backups111942
+Node: Backup Names112996
+Ref: Backup Names-Footnote-1115955
+Node: Reject Names116082
+Node: patch Messages116660
+Node: More or Fewer Messages117706
+Node: patch and Keyboard Input118319
+Node: patch Quoting Style119332
+Node: patch and POSIX120464
+Node: patch and Tradition121290
+Node: Making Patches124734
+Node: Tips for Patch Producers125552
+Node: Tips for Patch Consumers126796
+Node: Avoiding Common Mistakes127421
+Node: Generating Smaller Patches129934
+Node: Invoking cmp131683
+Node: cmp Options132532
+Node: Invoking diff135896
+Node: diff Options137599
+Node: Invoking diff3145722
+Node: diff3 Options146352
+Node: Invoking patch149255
+Node: patch Options150455
+Node: Invoking sdiff155669
+Node: sdiff Options156808
+Node: Standards conformance159561
+Node: Projects161299
+Node: Shortcomings162002
+Node: Internationalization163092
+Node: Changing Structure164247
+Node: Special Files165336
+Node: Unusual File Names166282
+Node: Time Stamp Order166904
+Node: Ignoring Changes167531
+Node: Speedups168285
+Node: Bugs168733
+Node: Copying This Manual169574
+Node: GNU Free Documentation License169782
+Node: Index189646
+
+End Tag Table
diff --git a/external/gpl2/diffutils/dist/doc/diff.texi b/external/gpl2/diffutils/dist/doc/diff.texi
new file mode 100644
index 00000000000..63537a65935
--- /dev/null
+++ b/external/gpl2/diffutils/dist/doc/diff.texi
@@ -0,0 +1,4557 @@
+\input texinfo @c -*-texinfo-*-
+@c $NetBSD: diff.texi,v 1.1.1.1 2016/01/13 03:15:29 christos Exp $
+@comment Id
+@comment %**start of header
+@setfilename diff.info
+@include version.texi
+@settitle Comparing and Merging Files
+@syncodeindex vr cp
+@setchapternewpage odd
+@comment %**end of header
+@copying
+This manual is for GNU Diffutils
+(version @value{VERSION}, @value{UPDATED}),
+and documents the @sc{gnu} @command{diff}, @command{diff3},
+@command{sdiff}, and @command{cmp} commands for showing the
+differences between files and the @sc{gnu} @command{patch} command for
+using their output to update files.
+
+Copyright @copyright{} 1992, 1993, 1994, 1998, 2001, 2002 Free
+Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.1 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
+and with the Back-Cover Texts as in (a) below. A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License.''
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software. Copies published by the Free
+Software Foundation raise funds for GNU development.''
+@end quotation
+@end copying
+
+@c Debian install-info (up through at least version 1.9.20) uses only the
+@c first dircategory. Put this one first, as it is more useful in practice.
+@dircategory Individual utilities
+@direntry
+* cmp: (diff)Invoking cmp. Compare 2 files byte by byte.
+* diff: (diff)Invoking diff. Compare 2 files line by line.
+* diff3: (diff)Invoking diff3. Compare 3 files line by line.
+* patch: (diff)Invoking patch. Apply a patch to a file.
+* sdiff: (diff)Invoking sdiff. Merge 2 files side-by-side.
+@end direntry
+
+@dircategory GNU packages
+@direntry
+* Diff: (diff). Comparing and merging files.
+@end direntry
+
+@titlepage
+@title Comparing and Merging Files
+@subtitle for Diffutils @value{VERSION} and @code{patch} 2.5.4
+@subtitle @value{UPDATED}
+@author David MacKenzie, Paul Eggert, and Richard Stallman
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@shortcontents
+@contents
+
+@ifnottex
+@node Top
+@top Comparing and Merging Files
+
+@insertcopying
+@end ifnottex
+
+@menu
+* Overview:: Preliminary information.
+* Comparison:: What file comparison means.
+
+* Output Formats:: Formats for two-way difference reports.
+* Incomplete Lines:: Lines that lack trailing newlines.
+* Comparing Directories:: Comparing files and directories.
+* Adjusting Output:: Making @command{diff} output prettier.
+* diff Performance:: Making @command{diff} smarter or faster.
+
+* Comparing Three Files:: Formats for three-way difference reports.
+* diff3 Merging:: Merging from a common ancestor.
+
+* Interactive Merging:: Interactive merging with @command{sdiff}.
+
+* Merging with patch:: Using @command{patch} to change old files into new ones.
+* Making Patches:: Tips for making and using patch distributions.
+
+* Invoking cmp:: Compare two files byte by byte.
+* Invoking diff:: Compare two files line by line.
+* Invoking diff3:: Compare three files line by line.
+* Invoking patch:: Apply a diff file to an original.
+* Invoking sdiff:: Side-by-side merge of file differences.
+
+* Standards conformance:: Conformance to the @sc{posix} standard.
+* Projects:: If you've found a bug or other shortcoming.
+
+* Copying This Manual:: How to make copies of this manual.
+* Index:: Index.
+@end menu
+
+@node Overview
+@unnumbered Overview
+@cindex overview of @command{diff} and @command{patch}
+
+Computer users often find occasion to ask how two files differ. Perhaps
+one file is a newer version of the other file. Or maybe the two files
+started out as identical copies but were changed by different people.
+
+You can use the @command{diff} command to show differences between two
+files, or each corresponding file in two directories. @command{diff}
+outputs differences between files line by line in any of several
+formats, selectable by command line options. This set of differences is
+often called a @dfn{diff} or @dfn{patch}. For files that are identical,
+@command{diff} normally produces no output; for binary (non-text) files,
+@command{diff} normally reports only that they are different.
+
+You can use the @command{cmp} command to show the byte and line numbers
+where two files differ. @command{cmp} can also show all the bytes
+that differ between the two files, side by side. A way to compare
+two files character by character is the Emacs command @kbd{M-x
+compare-windows}. @xref{Other Window, , Other Window, emacs, The @sc{gnu}
+Emacs Manual}, for more information on that command.
+
+You can use the @command{diff3} command to show differences among three
+files. When two people have made independent changes to a common
+original, @command{diff3} can report the differences between the original
+and the two changed versions, and can produce a merged file that
+contains both persons' changes together with warnings about conflicts.
+
+You can use the @command{sdiff} command to merge two files interactively.
+
+You can use the set of differences produced by @command{diff} to distribute
+updates to text files (such as program source code) to other people.
+This method is especially useful when the differences are small compared
+to the complete files. Given @command{diff} output, you can use the
+@command{patch} program to update, or @dfn{patch}, a copy of the file. If you
+think of @command{diff} as subtracting one file from another to produce
+their difference, you can think of @command{patch} as adding the difference
+to one file to reproduce the other.
+
+This manual first concentrates on making diffs, and later shows how to
+use diffs to update files.
+
+@sc{gnu} @command{diff} was written by Paul Eggert, Mike Haertel,
+David Hayes, Richard Stallman, and Len Tower. Wayne Davison designed and
+implemented the unified output format. The basic algorithm is described
+in ``An O(ND) Difference Algorithm and its Variations'', Eugene W. Myers,
+@cite{Algorithmica} Vol.@: 1 No.@: 2, 1986, pp.@: 251--266; and in ``A File
+Comparison Program'', Webb Miller and Eugene W. Myers,
+@cite{Software---Practice and Experience} Vol.@: 15 No.@: 11, 1985,
+pp.@: 1025--1040.
+@c From: "Gene Myers" <gene@cs.arizona.edu>
+@c They are about the same basic algorithm; the Algorithmica
+@c paper gives a rigorous treatment and the sub-algorithm for
+@c delivering scripts and should be the primary reference, but
+@c both should be mentioned.
+The algorithm was independently discovered as described in
+``Algorithms for Approximate String Matching'',
+E. Ukkonen, @cite{Information and Control} Vol.@: 64, 1985, pp.@: 100--118.
+@c From: "Gene Myers" <gene@cs.arizona.edu>
+@c Date: Wed, 29 Sep 1993 08:27:55 MST
+@c Ukkonen should be given credit for also discovering the algorithm used
+@c in GNU diff.
+
+@sc{gnu} @command{diff3} was written by Randy Smith. @sc{gnu}
+@command{sdiff} was written by Thomas Lord. @sc{gnu} @command{cmp}
+was written by Torbjorn Granlund and David MacKenzie.
+
+@command{patch} was written mainly by Larry Wall and Paul Eggert;
+several @sc{gnu} enhancements were contributed by Wayne Davison and
+David MacKenzie. Parts of this manual are adapted from a manual page
+written by Larry Wall, with his permission.
+
+@node Comparison
+@chapter What Comparison Means
+@cindex introduction
+
+There are several ways to think about the differences between two files.
+One way to think of the differences is as a series of lines that were
+deleted from, inserted in, or changed in one file to produce the other
+file. @command{diff} compares two files line by line, finds groups of
+lines that differ, and reports each group of differing lines. It can
+report the differing lines in several formats, which have different
+purposes.
+
+@sc{gnu} @command{diff} can show whether files are different without detailing
+the differences. It also provides ways to suppress certain kinds of
+differences that are not important to you. Most commonly, such
+differences are changes in the amount of white space between words or
+lines. @command{diff} also provides ways to suppress differences in
+alphabetic case or in lines that match a regular expression that you
+provide. These options can accumulate; for example, you can ignore
+changes in both white space and alphabetic case.
+
+Another way to think of the differences between two files is as a
+sequence of pairs of bytes that can be either identical or
+different. @command{cmp} reports the differences between two files
+byte by byte, instead of line by line. As a result, it is often
+more useful than @command{diff} for comparing binary files. For text
+files, @command{cmp} is useful mainly when you want to know only whether
+two files are identical, or whether one file is a prefix of the other.
+
+To illustrate the effect that considering changes byte by byte
+can have compared with considering them line by line, think of what
+happens if a single newline character is added to the beginning of a
+file. If that file is then compared with an otherwise identical file
+that lacks the newline at the beginning, @command{diff} will report that a
+blank line has been added to the file, while @command{cmp} will report that
+almost every byte of the two files differs.
+
+@command{diff3} normally compares three input files line by line, finds
+groups of lines that differ, and reports each group of differing lines.
+Its output is designed to make it easy to inspect two different sets of
+changes to the same file.
+
+@menu
+* Hunks:: Groups of differing lines.
+* White Space:: Suppressing differences in white space.
+* Blank Lines:: Suppressing differences in blank lines.
+* Case Folding:: Suppressing differences in alphabetic case.
+* Specified Folding:: Suppressing differences that match regular expressions.
+* Brief:: Summarizing which files are different.
+* Binary:: Comparing binary files or forcing text comparisons.
+@end menu
+
+@node Hunks
+@section Hunks
+@cindex hunks
+
+When comparing two files, @command{diff} finds sequences of lines common to
+both files, interspersed with groups of differing lines called
+@dfn{hunks}. Comparing two identical files yields one sequence of
+common lines and no hunks, because no lines differ. Comparing two
+entirely different files yields no common lines and one large hunk that
+contains all lines of both files. In general, there are many ways to
+match up lines between two given files. @command{diff} tries to minimize
+the total hunk size by finding large sequences of common lines
+interspersed with small hunks of differing lines.
+
+For example, suppose the file @file{F} contains the three lines
+@samp{a}, @samp{b}, @samp{c}, and the file @file{G} contains the same
+three lines in reverse order @samp{c}, @samp{b}, @samp{a}. If
+@command{diff} finds the line @samp{c} as common, then the command
+@samp{diff F G} produces this output:
+
+@example
+1,2d0
+< a
+< b
+3a2,3
+> b
+> a
+@end example
+
+@noindent
+But if @command{diff} notices the common line @samp{b} instead, it produces
+this output:
+
+@example
+1c1
+< a
+---
+> c
+3c3
+< c
+---
+> a
+@end example
+
+@noindent
+It is also possible to find @samp{a} as the common line. @command{diff}
+does not always find an optimal matching between the files; it takes
+shortcuts to run faster. But its output is usually close to the
+shortest possible. You can adjust this tradeoff with the
+@option{--minimal} option (@pxref{diff Performance}).
+
+@node White Space
+@section Suppressing Differences in Blank and Tab Spacing
+@cindex blank and tab difference suppression
+@cindex tab and blank difference suppression
+
+The @option{-E} and @option{--ignore-tab-expansion} options ignore the
+distinction between tabs and spaces on input. A tab is considered to be
+equivalent to the number of spaces to the next tab stop. @command{diff}
+assumes that tab stops are set every 8 print columns.
+
+The @option{-b} and @option{--ignore-space-change} options are stronger.
+They ignore white space at line end, and consider all other sequences of
+one or more white space characters to be equivalent. With these
+options, @command{diff} considers the following two lines to be equivalent,
+where @samp{$} denotes the line end:
+
+@example
+Here lyeth muche rychnesse in lytell space. -- John Heywood$
+Here lyeth muche rychnesse in lytell space. -- John Heywood $
+@end example
+
+The @option{-w} and @option{--ignore-all-space} options are stronger still.
+They ignore difference even if one line has white space where
+the other line has none. @dfn{White space} characters include
+tab, newline, vertical tab, form feed, carriage return, and space;
+some locales may define additional characters to be white space.
+With these options, @command{diff} considers the
+following two lines to be equivalent, where @samp{$} denotes the line
+end and @samp{^M} denotes a carriage return:
+
+@example
+Here lyeth muche rychnesse in lytell space.-- John Heywood$
+ He relyeth much erychnes seinly tells pace. --John Heywood ^M$
+@end example
+
+@node Blank Lines
+@section Suppressing Differences in Blank Lines
+@cindex blank line difference suppression
+
+The @option{-B} and @option{--ignore-blank-lines} options ignore insertions
+or deletions of blank lines. These options affect only lines
+that are completely empty; they do not affect lines that look empty but
+contain space or tab characters. With these options, for example, a
+file containing
+@example
+1. A point is that which has no part.
+
+2. A line is breadthless length.
+-- Euclid, The Elements, I
+@end example
+@noindent
+is considered identical to a file containing
+@example
+1. A point is that which has no part.
+2. A line is breadthless length.
+
+
+-- Euclid, The Elements, I
+@end example
+
+@node Case Folding
+@section Suppressing Case Differences
+@cindex case difference suppression
+
+@sc{gnu} @command{diff} can treat lower case letters as equivalent to their
+upper case counterparts, so that, for example, it considers @samp{Funky
+Stuff}, @samp{funky STUFF}, and @samp{fUNKy stuFf} to all be the same.
+To request this, use the @option{-i} or @option{--ignore-case} option.
+
+@node Specified Folding
+@section Suppressing Lines Matching a Regular Expression
+@cindex regular expression suppression
+
+To ignore insertions and deletions of lines that match a
+@command{grep}-style regular expression, use the @option{-I
+@var{regexp}} or @option{--ignore-matching-lines=@var{regexp}} option.
+You should escape
+regular expressions that contain shell metacharacters to prevent the
+shell from expanding them. For example, @samp{diff -I '^[[:digit:]]'} ignores
+all changes to lines beginning with a digit.
+
+However, @option{-I} only ignores the insertion or deletion of lines that
+contain the regular expression if every changed line in the hunk---every
+insertion and every deletion---matches the regular expression. In other
+words, for each nonignorable change, @command{diff} prints the complete set
+of changes in its vicinity, including the ignorable ones.
+
+You can specify more than one regular expression for lines to ignore by
+using more than one @option{-I} option. @command{diff} tries to match each
+line against each regular expression.
+
+@node Brief
+@section Summarizing Which Files Differ
+@cindex summarizing which files differ
+@cindex brief difference reports
+
+When you only want to find out whether files are different, and you
+don't care what the differences are, you can use the summary output
+format. In this format, instead of showing the differences between the
+files, @command{diff} simply reports whether files differ. The @option{-q}
+and @option{--brief} options select this output format.
+
+This format is especially useful when comparing the contents of two
+directories. It is also much faster than doing the normal line by line
+comparisons, because @command{diff} can stop analyzing the files as soon as
+it knows that there are any differences.
+
+You can also get a brief indication of whether two files differ by using
+@command{cmp}. For files that are identical, @command{cmp} produces no
+output. When the files differ, by default, @command{cmp} outputs the byte
+and line number where the first difference occurs. You can use
+the @option{-s} option to suppress that information, so that @command{cmp}
+produces no output and reports whether the files differ using only its
+exit status (@pxref{Invoking cmp}).
+
+@c Fix this.
+Unlike @command{diff}, @command{cmp} cannot compare directories; it can only
+compare two files.
+
+@node Binary
+@section Binary Files and Forcing Text Comparisons
+@cindex binary file diff
+@cindex text versus binary diff
+
+If @command{diff} thinks that either of the two files it is comparing is
+binary (a non-text file), it normally treats that pair of files much as
+if the summary output format had been selected (@pxref{Brief}), and
+reports only that the binary files are different. This is because line
+by line comparisons are usually not meaningful for binary files.
+
+@command{diff} determines whether a file is text or binary by checking the
+first few bytes in the file; the exact number of bytes is system
+dependent, but it is typically several thousand. If every byte in
+that part of the file is non-null, @command{diff} considers the file to be
+text; otherwise it considers the file to be binary.
+
+Sometimes you might want to force @command{diff} to consider files to be
+text. For example, you might be comparing text files that contain
+null characters; @command{diff} would erroneously decide that those are
+non-text files. Or you might be comparing documents that are in a
+format used by a word processing system that uses null characters to
+indicate special formatting. You can force @command{diff} to consider all
+files to be text files, and compare them line by line, by using the
+@option{-a} or @option{--text} option. If the files you compare using this
+option do not in fact contain text, they will probably contain few
+newline characters, and the @command{diff} output will consist of hunks
+showing differences between long lines of whatever characters the files
+contain.
+
+You can also force @command{diff} to consider all files to be binary files,
+and report only whether they differ (but not how). Use the
+@option{-q} or @option{--brief} option for this.
+
+Differing binary files are considered to cause trouble because the
+resulting @command{diff} output does not capture all the differences.
+This trouble causes @command{diff} to exit with status 2. However,
+this trouble cannot occur with the @option{--a} or @option{--text}
+option, or with the @option{-q} or @option{--brief} option, as these
+options both cause @command{diff} to treat binary files like text
+files.
+
+In operating systems that distinguish between text and binary files,
+@command{diff} normally reads and writes all data as text. Use the
+@option{--binary} option to force @command{diff} to read and write binary
+data instead. This option has no effect on a @sc{posix}-compliant system
+like @sc{gnu} or traditional Unix. However, many personal computer
+operating systems represent the end of a line with a carriage return
+followed by a newline. On such systems, @command{diff} normally ignores
+these carriage returns on input and generates them at the end of each
+output line, but with the @option{--binary} option @command{diff} treats
+each carriage return as just another input character, and does not
+generate a carriage return at the end of each output line. This can be
+useful when dealing with non-text files that are meant to be
+interchanged with @sc{posix}-compliant systems.
+
+The @option{--strip-trailing-cr} causes @command{diff} to treat input
+lines that end in carriage return followed by newline as if they end
+in plain newline. This can be useful when comparing text that is
+imperfectly imported from many personal computer operating systems.
+This option affects how lines are read, which in turn affects how they
+are compared and output.
+
+If you want to compare two files byte by byte, you can use the
+@command{cmp} program with the @option{-l} option to show the values
+of each differing byte in the two files. With @sc{gnu} @command{cmp},
+you can also use the @option{-b} option to show the @sc{ascii}
+representation of those bytes. @xref{Invoking cmp}, for more
+information.
+
+If @command{diff3} thinks that any of the files it is comparing is binary
+(a non-text file), it normally reports an error, because such
+comparisons are usually not useful. @command{diff3} uses the same test as
+@command{diff} to decide whether a file is binary. As with @command{diff}, if
+the input files contain a few non-text bytes but otherwise are like
+text files, you can force @command{diff3} to consider all files to be text
+files and compare them line by line by using the @option{-a} or
+@option{--text} options.
+
+@node Output Formats
+@chapter @command{diff} Output Formats
+@cindex output formats
+@cindex format of @command{diff} output
+
+@command{diff} has several mutually exclusive options for output format.
+The following sections describe each format, illustrating how
+@command{diff} reports the differences between two sample input files.
+
+@menu
+* Sample diff Input:: Sample @command{diff} input files for examples.
+* Normal:: Showing differences without surrounding text.
+* Context:: Showing differences with the surrounding text.
+* Side by Side:: Showing differences in two columns.
+* Scripts:: Generating scripts for other programs.
+* If-then-else:: Merging files with if-then-else.
+@end menu
+
+@node Sample diff Input
+@section Two Sample Input Files
+@cindex @command{diff} sample input
+@cindex sample input for @command{diff}
+
+Here are two sample files that we will use in numerous examples to
+illustrate the output of @command{diff} and how various options can change
+it.
+
+This is the file @file{lao}:
+
+@example
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+The Nameless is the origin of Heaven and Earth;
+The Named is the mother of all things.
+Therefore let there always be non-being,
+ so we may see their subtlety,
+And let there always be being,
+ so we may see their outcome.
+The two are the same,
+But after they are produced,
+ they have different names.
+@end example
+
+This is the file @file{tzu}:
+
+@example
+The Nameless is the origin of Heaven and Earth;
+The named is the mother of all things.
+
+Therefore let there always be non-being,
+ so we may see their subtlety,
+And let there always be being,
+ so we may see their outcome.
+The two are the same,
+But after they are produced,
+ they have different names.
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+@end example
+
+In this example, the first hunk contains just the first two lines of
+@file{lao}, the second hunk contains the fourth line of @file{lao}
+opposing the second and third lines of @file{tzu}, and the last hunk
+contains just the last three lines of @file{tzu}.
+
+@node Normal
+@section Showing Differences Without Context
+@cindex normal output format
+@cindex @samp{<} output format
+
+The ``normal'' @command{diff} output format shows each hunk of differences
+without any surrounding context. Sometimes such output is the clearest
+way to see how lines have changed, without the clutter of nearby
+unchanged lines (although you can get similar results with the context
+or unified formats by using 0 lines of context). However, this format
+is no longer widely used for sending out patches; for that purpose, the
+context format (@pxref{Context Format}) and the unified format
+(@pxref{Unified Format}) are superior. Normal format is the default for
+compatibility with older versions of @command{diff} and the @sc{posix}
+standard. Use the @option{--normal} option to select this output
+format explicitly.
+
+@menu
+* Detailed Normal:: A detailed description of normal output format.
+* Example Normal:: Sample output in the normal format.
+@end menu
+
+@node Detailed Normal
+@subsection Detailed Description of Normal Format
+
+The normal output format consists of one or more hunks of differences;
+each hunk shows one area where the files differ. Normal format hunks
+look like this:
+
+@example
+@var{change-command}
+< @var{from-file-line}
+< @var{from-file-line}@dots{}
+---
+> @var{to-file-line}
+> @var{to-file-line}@dots{}
+@end example
+
+There are three types of change commands. Each consists of a line
+number or comma-separated range of lines in the first file, a single
+character indicating the kind of change to make, and a line number or
+comma-separated range of lines in the second file. All line numbers are
+the original line numbers in each file. The types of change commands
+are:
+
+@table @samp
+@item @var{l}a@var{r}
+Add the lines in range @var{r} of the second file after line @var{l} of
+the first file. For example, @samp{8a12,15} means append lines 12--15
+of file 2 after line 8 of file 1; or, if changing file 2 into file 1,
+delete lines 12--15 of file 2.
+
+@item @var{f}c@var{t}
+Replace the lines in range @var{f} of the first file with lines in range
+@var{t} of the second file. This is like a combined add and delete, but
+more compact. For example, @samp{5,7c8,10} means change lines 5--7 of
+file 1 to read as lines 8--10 of file 2; or, if changing file 2 into
+file 1, change lines 8--10 of file 2 to read as lines 5--7 of file 1.
+
+@item @var{r}d@var{l}
+Delete the lines in range @var{r} from the first file; line @var{l} is where
+they would have appeared in the second file had they not been deleted.
+For example, @samp{5,7d3} means delete lines 5--7 of file 1; or, if
+changing file 2 into file 1, append lines 5--7 of file 1 after line 3 of
+file 2.
+@end table
+
+@node Example Normal
+@subsection An Example of Normal Format
+
+Here is the output of the command @samp{diff lao tzu}
+(@pxref{Sample diff Input}, for the complete contents of the two files).
+Notice that it shows only the lines that are different between the two
+files.
+
+@example
+1,2d0
+< The Way that can be told of is not the eternal Way;
+< The name that can be named is not the eternal name.
+4c2,3
+< The Named is the mother of all things.
+---
+> The named is the mother of all things.
+>
+11a11,13
+> They both may be called deep and profound.
+> Deeper and more profound,
+> The door of all subtleties!
+@end example
+
+@node Context
+@section Showing Differences in Their Context
+@cindex context output format
+@cindex @samp{!} output format
+
+Usually, when you are looking at the differences between files, you will
+also want to see the parts of the files near the lines that differ, to
+help you understand exactly what has changed. These nearby parts of the
+files are called the @dfn{context}.
+
+@sc{gnu} @command{diff} provides two output formats that show context
+around the differing lines: @dfn{context format} and @dfn{unified
+format}. It can optionally show in which function or section of the
+file the differing lines are found.
+
+If you are distributing new versions of files to other people in the
+form of @command{diff} output, you should use one of the output formats
+that show context so that they can apply the diffs even if they have
+made small changes of their own to the files. @command{patch} can apply
+the diffs in this case by searching in the files for the lines of
+context around the differing lines; if those lines are actually a few
+lines away from where the diff says they are, @command{patch} can adjust
+the line numbers accordingly and still apply the diff correctly.
+@xref{Imperfect}, for more information on using @command{patch} to apply
+imperfect diffs.
+
+@menu
+* Context Format:: An output format that shows surrounding lines.
+* Unified Format:: A more compact output format that shows context.
+* Sections:: Showing which sections of the files differences are in.
+* Alternate Names:: Showing alternate file names in context headers.
+@end menu
+
+@node Context Format
+@subsection Context Format
+
+The context output format shows several lines of context around the
+lines that differ. It is the standard format for distributing updates
+to source code.
+
+To select this output format, use the @option{-C @var{lines}},
+@option{--context@r{[}=@var{lines}@r{]}}, or @option{-c} option. The
+argument @var{lines} that some of these options take is the number of
+lines of context to show. If you do not specify @var{lines}, it
+defaults to three. For proper operation, @command{patch} typically needs
+at least two lines of context.
+
+@menu
+* Detailed Context:: A detailed description of the context output format.
+* Example Context:: Sample output in context format.
+* Less Context:: Another sample with less context.
+@end menu
+
+@node Detailed Context
+@subsubsection Detailed Description of Context Format
+
+The context output format starts with a two-line header, which looks
+like this:
+
+@example
+*** @var{from-file} @var{from-file-modification-time}
+--- @var{to-file} @var{to-file-modification time}
+@end example
+
+@noindent
+@vindex LC_TIME
+@cindex time stamp format, context diffs
+The time stamp normally looks like @samp{2002-02-21 23:30:39.942229878
+-0800} to indicate the date, time with fractional seconds, and time
+zone in @uref{ftp://ftp.isi.edu/in-notes/rfc2822.txt, Internet RFC
+2822 format}. However, a traditional time stamp like @samp{Thu Feb 21
+23:30:39 2002} is used if the @env{LC_TIME} locale category is either
+@samp{C} or @samp{POSIX}.
+
+You can change the header's content with the
+@option{--label=@var{label}} option; see @ref{Alternate Names}.
+
+Next come one or more hunks of differences; each hunk shows one area
+where the files differ. Context format hunks look like this:
+
+@example
+***************
+*** @var{from-file-line-range} ****
+ @var{from-file-line}
+ @var{from-file-line}@dots{}
+--- @var{to-file-line-range} ----
+ @var{to-file-line}
+ @var{to-file-line}@dots{}
+@end example
+
+The lines of context around the lines that differ start with two space
+characters. The lines that differ between the two files start with one
+of the following indicator characters, followed by a space character:
+
+@table @samp
+@item !
+A line that is part of a group of one or more lines that changed between
+the two files. There is a corresponding group of lines marked with
+@samp{!} in the part of this hunk for the other file.
+
+@item +
+An ``inserted'' line in the second file that corresponds to nothing in
+the first file.
+
+@item -
+A ``deleted'' line in the first file that corresponds to nothing in the
+second file.
+@end table
+
+If all of the changes in a hunk are insertions, the lines of
+@var{from-file} are omitted. If all of the changes are deletions, the
+lines of @var{to-file} are omitted.
+
+@node Example Context
+@subsubsection An Example of Context Format
+
+Here is the output of @samp{diff -c lao tzu} (@pxref{Sample diff Input},
+for the complete contents of the two files). Notice that up to three
+lines that are not different are shown around each line that is
+different; they are the context lines. Also notice that the first two
+hunks have run together, because their contents overlap.
+
+@example
+*** lao 2002-02-21 23:30:39.942229878 -0800
+--- tzu 2002-02-21 23:30:50.442260588 -0800
+***************
+*** 1,7 ****
+- The Way that can be told of is not the eternal Way;
+- The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+! The Named is the mother of all things.
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+--- 1,6 ----
+ The Nameless is the origin of Heaven and Earth;
+! The named is the mother of all things.
+!
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+***************
+*** 9,11 ****
+--- 8,13 ----
+ The two are the same,
+ But after they are produced,
+ they have different names.
++ They both may be called deep and profound.
++ Deeper and more profound,
++ The door of all subtleties!
+@end example
+
+@node Less Context
+@subsubsection An Example of Context Format with Less Context
+
+Here is the output of @samp{diff -C 1 lao tzu} (@pxref{Sample diff
+Input}, for the complete contents of the two files). Notice that at
+most one context line is reported here.
+
+@example
+*** lao 2002-02-21 23:30:39.942229878 -0800
+--- tzu 2002-02-21 23:30:50.442260588 -0800
+***************
+*** 1,5 ****
+- The Way that can be told of is not the eternal Way;
+- The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+! The Named is the mother of all things.
+ Therefore let there always be non-being,
+--- 1,4 ----
+ The Nameless is the origin of Heaven and Earth;
+! The named is the mother of all things.
+!
+ Therefore let there always be non-being,
+***************
+*** 11 ****
+--- 10,13 ----
+ they have different names.
++ They both may be called deep and profound.
++ Deeper and more profound,
++ The door of all subtleties!
+@end example
+
+@node Unified Format
+@subsection Unified Format
+@cindex unified output format
+@cindex @samp{+-} output format
+
+The unified output format is a variation on the context format that is
+more compact because it omits redundant context lines. To select this
+output format, use the @option{-U @var{lines}},
+@option{--unified@r{[}=@var{lines}@r{]}}, or @option{-u}
+option. The argument @var{lines} is the number of lines of context to
+show. When it is not given, it defaults to three.
+
+At present, only @sc{gnu} @command{diff} can produce this format and
+only @sc{gnu} @command{patch} can automatically apply diffs in this
+format. For proper operation, @command{patch} typically needs at
+least three lines of context.
+
+@menu
+* Detailed Unified:: A detailed description of unified format.
+* Example Unified:: Sample output in unified format.
+@end menu
+
+@node Detailed Unified
+@subsubsection Detailed Description of Unified Format
+
+The unified output format starts with a two-line header, which looks
+like this:
+
+@example
+--- @var{from-file} @var{from-file-modification-time}
++++ @var{to-file} @var{to-file-modification-time}
+@end example
+
+@noindent
+@cindex time stamp format, unified diffs
+The time stamp looks like @samp{2002-02-21 23:30:39.942229878 -0800}
+to indicate the date, time with fractional seconds, and time zone.
+
+You can change the header's content with the
+@option{--label=@var{label}} option; see @xref{Alternate Names}.
+
+Next come one or more hunks of differences; each hunk shows one area
+where the files differ. Unified format hunks look like this:
+
+@example
+@@@@ @var{from-file-range} @var{to-file-range} @@@@
+ @var{line-from-either-file}
+ @var{line-from-either-file}@dots{}
+@end example
+
+The lines common to both files begin with a space character. The lines
+that actually differ between the two files have one of the following
+indicator characters in the left print column:
+
+@table @samp
+@item +
+A line was added here to the first file.
+
+@item -
+A line was removed here from the first file.
+@end table
+
+@node Example Unified
+@subsubsection An Example of Unified Format
+
+Here is the output of the command @samp{diff -u lao tzu}
+(@pxref{Sample diff Input}, for the complete contents of the two files):
+
+@example
+--- lao 2002-02-21 23:30:39.942229878 -0800
++++ tzu 2002-02-21 23:30:50.442260588 -0800
+@@@@ -1,7 +1,6 @@@@
+-The Way that can be told of is not the eternal Way;
+-The name that can be named is not the eternal name.
+ The Nameless is the origin of Heaven and Earth;
+-The Named is the mother of all things.
++The named is the mother of all things.
++
+ Therefore let there always be non-being,
+ so we may see their subtlety,
+ And let there always be being,
+@@@@ -9,3 +8,6 @@@@
+ The two are the same,
+ But after they are produced,
+ they have different names.
++They both may be called deep and profound.
++Deeper and more profound,
++The door of all subtleties!
+@end example
+
+@node Sections
+@subsection Showing Which Sections Differences Are in
+@cindex headings
+@cindex section headings
+
+Sometimes you might want to know which part of the files each change
+falls in. If the files are source code, this could mean which function
+was changed. If the files are documents, it could mean which chapter or
+appendix was changed. @sc{gnu} @command{diff} can show this by displaying the
+nearest section heading line that precedes the differing lines. Which
+lines are ``section headings'' is determined by a regular expression.
+
+@menu
+* Specified Headings:: Showing headings that match regular expressions.
+* C Function Headings:: Showing headings of C functions.
+@end menu
+
+@node Specified Headings
+@subsubsection Showing Lines That Match Regular Expressions
+@cindex specified headings
+@cindex regular expression matching headings
+
+To show in which sections differences occur for files that are not
+source code for C or similar languages, use the @option{-F @var{regexp}}
+or @option{--show-function-line=@var{regexp}} option. @command{diff}
+considers lines that match the @command{grep}-style regular expression
+@var{regexp} to be the beginning
+of a section of the file. Here are suggested regular expressions for
+some common languages:
+
+@c Please add to this list, e.g. Fortran, Pascal, Perl, Python.
+@table @samp
+@item ^[[:alpha:]$_]
+C, C++, Prolog
+@item ^(
+Lisp
+@item ^@@node
+Texinfo
+@end table
+
+This option does not automatically select an output format; in order to
+use it, you must select the context format (@pxref{Context Format}) or
+unified format (@pxref{Unified Format}). In other output formats it
+has no effect.
+
+The @option{-F} and @option{--show-function-line} options find the nearest
+unchanged line that precedes each hunk of differences and matches the
+given regular expression. Then they add that line to the end of the
+line of asterisks in the context format, or to the @samp{@@@@} line in
+unified format. If no matching line exists, they leave the output for
+that hunk unchanged. If that line is more than 40 characters long, they
+output only the first 40 characters. You can specify more than one
+regular expression for such lines; @command{diff} tries to match each line
+against each regular expression, starting with the last one given. This
+means that you can use @option{-p} and @option{-F} together, if you wish.
+
+@node C Function Headings
+@subsubsection Showing C Function Headings
+@cindex C function headings
+@cindex function headings, C
+
+To show in which functions differences occur for C and similar
+languages, you can use the @option{-p} or @option{--show-c-function} option.
+This option automatically defaults to the context output format
+(@pxref{Context Format}), with the default number of lines of context.
+You can override that number with @option{-C @var{lines}} elsewhere in the
+command line. You can override both the format and the number with
+@option{-U @var{lines}} elsewhere in the command line.
+
+The @option{-p} and @option{--show-c-function} options are equivalent to
+@option{-F '^[[:alpha:]$_]'} if the unified format is specified, otherwise
+@option{-c -F '^[[:alpha:]$_]'} (@pxref{Specified Headings}). @sc{gnu}
+@command{diff} provides them for the sake of convenience.
+
+@node Alternate Names
+@subsection Showing Alternate File Names
+@cindex alternate file names
+@cindex file name alternates
+
+If you are comparing two files that have meaningless or uninformative
+names, you might want @command{diff} to show alternate names in the header
+of the context and unified output formats. To do this, use the
+@option{--label=@var{label}} option. The first time
+you give this option, its argument replaces the name and date of the
+first file in the header; the second time, its argument replaces the
+name and date of the second file. If you give this option more than
+twice, @command{diff} reports an error. The @option{--label} option does not
+affect the file names in the @command{pr} header when the @option{-l} or
+@option{--paginate} option is used (@pxref{Pagination}).
+
+Here are the first two lines of the output from @samp{diff -C 2
+--label=original --label=modified lao tzu}:
+
+@example
+*** original
+--- modified
+@end example
+
+@node Side by Side
+@section Showing Differences Side by Side
+@cindex side by side
+@cindex two-column output
+@cindex columnar output
+
+@command{diff} can produce a side by side difference listing of two files.
+The files are listed in two columns with a gutter between them. The
+gutter contains one of the following markers:
+
+@table @asis
+@item white space
+The corresponding lines are in common. That is, either the lines are
+identical, or the difference is ignored because of one of the
+@option{--ignore} options (@pxref{White Space}).
+
+@item @samp{|}
+The corresponding lines differ, and they are either both complete
+or both incomplete.
+
+@item @samp{<}
+The files differ and only the first file contains the line.
+
+@item @samp{>}
+The files differ and only the second file contains the line.
+
+@item @samp{(}
+Only the first file contains the line, but the difference is ignored.
+
+@item @samp{)}
+Only the second file contains the line, but the difference is ignored.
+
+@item @samp{\}
+The corresponding lines differ, and only the first line is incomplete.
+
+@item @samp{/}
+The corresponding lines differ, and only the second line is incomplete.
+@end table
+
+Normally, an output line is incomplete if and only if the lines that it
+contains are incomplete; @xref{Incomplete Lines}. However, when an
+output line represents two differing lines, one might be incomplete
+while the other is not. In this case, the output line is complete,
+but its the gutter is marked @samp{\} if the first line is incomplete,
+@samp{/} if the second line is.
+
+Side by side format is sometimes easiest to read, but it has limitations.
+It generates much wider output than usual, and truncates lines that are
+too long to fit. Also, it relies on lining up output more heavily than
+usual, so its output looks particularly bad if you use varying
+width fonts, nonstandard tab stops, or nonprinting characters.
+
+You can use the @command{sdiff} command to interactively merge side by side
+differences. @xref{Interactive Merging}, for more information on merging files.
+
+@menu
+* Side by Side Format:: Controlling side by side output format.
+* Example Side by Side:: Sample side by side output.
+@end menu
+
+@node Side by Side Format
+@subsection Controlling Side by Side Format
+@cindex side by side format
+
+The @option{-y} or @option{--side-by-side} option selects side by side
+format. Because side by side output lines contain two input lines, the
+output is wider than usual: normally 130 print columns, which can fit
+onto a traditional printer line. You can set the width of the output
+with the @option{-W @var{columns}} or @option{--width=@var{columns}}
+option. The output is split into two halves of equal width, separated by a
+small gutter to mark differences; the right half is aligned to a tab
+stop so that tabs line up. Input lines that are too long to fit in half
+of an output line are truncated for output.
+
+The @option{--left-column} option prints only the left column of two
+common lines. The @option{--suppress-common-lines} option suppresses
+common lines entirely.
+
+@node Example Side by Side
+@subsection An Example of Side by Side Format
+
+Here is the output of the command @samp{diff -y -W 72 lao tzu}
+(@pxref{Sample diff Input}, for the complete contents of the two files).
+
+@example
+The Way that can be told of is n <
+The name that can be named is no <
+The Nameless is the origin of He The Nameless is the origin of He
+The Named is the mother of all t | The named is the mother of all t
+ >
+Therefore let there always be no Therefore let there always be no
+ so we may see their subtlety, so we may see their subtlety,
+And let there always be being, And let there always be being,
+ so we may see their outcome. so we may see their outcome.
+The two are the same, The two are the same,
+But after they are produced, But after they are produced,
+ they have different names. they have different names.
+ > They both may be called deep and
+ > Deeper and more profound,
+ > The door of all subtleties!
+@end example
+
+@node Scripts
+@section Making Edit Scripts
+@cindex script output formats
+
+Several output modes produce command scripts for editing @var{from-file}
+to produce @var{to-file}.
+
+@menu
+* ed Scripts:: Using @command{diff} to produce commands for @command{ed}.
+* Forward ed:: Making forward @command{ed} scripts.
+* RCS:: A special @command{diff} output format used by @sc{rcs}.
+@end menu
+
+@node ed Scripts
+@subsection @command{ed} Scripts
+@cindex @command{ed} script output format
+
+@command{diff} can produce commands that direct the @command{ed} text editor
+to change the first file into the second file. Long ago, this was the
+only output mode that was suitable for editing one file into another
+automatically; today, with @command{patch}, it is almost obsolete. Use the
+@option{-e} or @option{--ed} option to select this output format.
+
+Like the normal format (@pxref{Normal}), this output format does not
+show any context; unlike the normal format, it does not include the
+information necessary to apply the diff in reverse (to produce the first
+file if all you have is the second file and the diff).
+
+If the file @file{d} contains the output of @samp{diff -e old new}, then
+the command @samp{(cat d && echo w) | ed - old} edits @file{old} to make
+it a copy of @file{new}. More generally, if @file{d1}, @file{d2},
+@dots{}, @file{dN} contain the outputs of @samp{diff -e old new1},
+@samp{diff -e new1 new2}, @dots{}, @samp{diff -e newN-1 newN},
+respectively, then the command @samp{(cat d1 d2 @dots{} dN && echo w) |
+ed - old} edits @file{old} to make it a copy of @file{newN}.
+
+@menu
+* Detailed ed:: A detailed description of @command{ed} format.
+* Example ed:: A sample @command{ed} script.
+@end menu
+
+@node Detailed ed
+@subsubsection Detailed Description of @command{ed} Format
+
+The @command{ed} output format consists of one or more hunks of
+differences. The changes closest to the ends of the files come first so
+that commands that change the number of lines do not affect how
+@command{ed} interprets line numbers in succeeding commands. @command{ed}
+format hunks look like this:
+
+@example
+@var{change-command}
+@var{to-file-line}
+@var{to-file-line}@dots{}
+.
+@end example
+
+Because @command{ed} uses a single period on a line to indicate the end of
+input, @sc{gnu} @command{diff} protects lines of changes that contain a single
+period on a line by writing two periods instead, then writing a
+subsequent @command{ed} command to change the two periods into one. The
+@command{ed} format cannot represent an incomplete line, so if the second
+file ends in a changed incomplete line, @command{diff} reports an error and
+then pretends that a newline was appended.
+
+There are three types of change commands. Each consists of a line
+number or comma-separated range of lines in the first file and a single
+character indicating the kind of change to make. All line numbers are
+the original line numbers in the file. The types of change commands
+are:
+
+@table @samp
+@item @var{l}a
+Add text from the second file after line @var{l} in the first file. For
+example, @samp{8a} means to add the following lines after line 8 of file
+1.
+
+@item @var{r}c
+Replace the lines in range @var{r} in the first file with the following
+lines. Like a combined add and delete, but more compact. For example,
+@samp{5,7c} means change lines 5--7 of file 1 to read as the text file
+2.
+
+@item @var{r}d
+Delete the lines in range @var{r} from the first file. For example,
+@samp{5,7d} means delete lines 5--7 of file 1.
+@end table
+
+@node Example ed
+@subsubsection Example @command{ed} Script
+
+Here is the output of @samp{diff -e lao tzu} (@pxref{Sample
+diff Input}, for the complete contents of the two files):
+
+@example
+11a
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+.
+4c
+The named is the mother of all things.
+
+.
+1,2d
+@end example
+
+@node Forward ed
+@subsection Forward @command{ed} Scripts
+@cindex forward @command{ed} script output format
+
+@command{diff} can produce output that is like an @command{ed} script, but
+with hunks in forward (front to back) order. The format of the commands
+is also changed slightly: command characters precede the lines they
+modify, spaces separate line numbers in ranges, and no attempt is made
+to disambiguate hunk lines consisting of a single period. Like
+@command{ed} format, forward @command{ed} format cannot represent incomplete
+lines.
+
+Forward @command{ed} format is not very useful, because neither @command{ed}
+nor @command{patch} can apply diffs in this format. It exists mainly for
+compatibility with older versions of @command{diff}. Use the @option{-f} or
+@option{--forward-ed} option to select it.
+
+@node RCS
+@subsection @sc{rcs} Scripts
+@cindex @sc{rcs} script output format
+
+The @sc{rcs} output format is designed specifically for use by the Revision
+Control System, which is a set of free programs used for organizing
+different versions and systems of files. Use the @option{-n} or
+@option{--rcs} option to select this output format. It is like the
+forward @command{ed} format (@pxref{Forward ed}), but it can represent
+arbitrary changes to the contents of a file because it avoids the
+forward @command{ed} format's problems with lines consisting of a single
+period and with incomplete lines. Instead of ending text sections with
+a line consisting of a single period, each command specifies the number
+of lines it affects; a combination of the @samp{a} and @samp{d}
+commands are used instead of @samp{c}. Also, if the second file ends
+in a changed incomplete line, then the output also ends in an
+incomplete line.
+
+Here is the output of @samp{diff -n lao tzu} (@pxref{Sample
+diff Input}, for the complete contents of the two files):
+
+@example
+d1 2
+d4 1
+a4 2
+The named is the mother of all things.
+
+a11 3
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+@end example
+
+@node If-then-else
+@section Merging Files with If-then-else
+@cindex merged output format
+@cindex if-then-else output format
+@cindex C if-then-else output format
+@cindex @command{ifdef} output format
+
+You can use @command{diff} to merge two files of C source code. The output
+of @command{diff} in this format contains all the lines of both files.
+Lines common to both files are output just once; the differing parts are
+separated by the C preprocessor directives @code{#ifdef @var{name}} or
+@code{#ifndef @var{name}}, @code{#else}, and @code{#endif}. When
+compiling the output, you select which version to use by either defining
+or leaving undefined the macro @var{name}.
+
+To merge two files, use @command{diff} with the @option{-D @var{name}} or
+@option{--ifdef=@var{name}} option. The argument @var{name} is the C
+preprocessor identifier to use in the @code{#ifdef} and @code{#ifndef}
+directives.
+
+For example, if you change an instance of @code{wait (&s)} to
+@code{waitpid (-1, &s, 0)} and then merge the old and new files with
+the @option{--ifdef=HAVE_WAITPID} option, then the affected part of your code
+might look like this:
+
+@example
+ do @{
+#ifndef HAVE_WAITPID
+ if ((w = wait (&s)) < 0 && errno != EINTR)
+#else /* HAVE_WAITPID */
+ if ((w = waitpid (-1, &s, 0)) < 0 && errno != EINTR)
+#endif /* HAVE_WAITPID */
+ return w;
+ @} while (w != child);
+@end example
+
+You can specify formats for languages other than C by using line group
+formats and line formats, as described in the next sections.
+
+@menu
+* Line Group Formats:: Formats for general if-then-else line groups.
+* Line Formats:: Formats for each line in a line group.
+* Detailed If-then-else:: A detailed description of if-then-else format.
+* Example If-then-else:: Sample if-then-else format output.
+@end menu
+
+@node Line Group Formats
+@subsection Line Group Formats
+@cindex line group formats
+@cindex formats for if-then-else line groups
+
+Line group formats let you specify formats suitable for many
+applications that allow if-then-else input, including programming
+languages and text formatting languages. A line group format specifies
+the output format for a contiguous group of similar lines.
+
+For example, the following command compares the TeX files @file{old}
+and @file{new}, and outputs a merged file in which old regions are
+surrounded by @samp{\begin@{em@}}-@samp{\end@{em@}} lines, and new
+regions are surrounded by @samp{\begin@{bf@}}-@samp{\end@{bf@}} lines.
+
+@example
+diff \
+ --old-group-format='\begin@{em@}
+%<\end@{em@}
+' \
+ --new-group-format='\begin@{bf@}
+%>\end@{bf@}
+' \
+ old new
+@end example
+
+The following command is equivalent to the above example, but it is a
+little more verbose, because it spells out the default line group formats.
+
+@example
+diff \
+ --old-group-format='\begin@{em@}
+%<\end@{em@}
+' \
+ --new-group-format='\begin@{bf@}
+%>\end@{bf@}
+' \
+ --unchanged-group-format='%=' \
+ --changed-group-format='\begin@{em@}
+%<\end@{em@}
+\begin@{bf@}
+%>\end@{bf@}
+' \
+ old new
+@end example
+
+Here is a more advanced example, which outputs a diff listing with
+headers containing line numbers in a ``plain English'' style.
+
+@example
+diff \
+ --unchanged-group-format='' \
+ --old-group-format='-------- %dn line%(n=1?:s) deleted at %df:
+%<' \
+ --new-group-format='-------- %dN line%(N=1?:s) added after %de:
+%>' \
+ --changed-group-format='-------- %dn line%(n=1?:s) changed at %df:
+%<-------- to:
+%>' \
+ old new
+@end example
+
+To specify a line group format, use @command{diff} with one of the options
+listed below. You can specify up to four line group formats, one for
+each kind of line group. You should quote @var{format}, because it
+typically contains shell metacharacters.
+
+@table @option
+@item --old-group-format=@var{format}
+These line groups are hunks containing only lines from the first file.
+The default old group format is the same as the changed group format if
+it is specified; otherwise it is a format that outputs the line group as-is.
+
+@item --new-group-format=@var{format}
+These line groups are hunks containing only lines from the second
+file. The default new group format is same as the changed group
+format if it is specified; otherwise it is a format that outputs the
+line group as-is.
+
+@item --changed-group-format=@var{format}
+These line groups are hunks containing lines from both files. The
+default changed group format is the concatenation of the old and new
+group formats.
+
+@item --unchanged-group-format=@var{format}
+These line groups contain lines common to both files. The default
+unchanged group format is a format that outputs the line group as-is.
+@end table
+
+In a line group format, ordinary characters represent themselves;
+conversion specifications start with @samp{%} and have one of the
+following forms.
+
+@table @samp
+@item %<
+stands for the lines from the first file, including the trailing newline.
+Each line is formatted according to the old line format (@pxref{Line Formats}).
+
+@item %>
+stands for the lines from the second file, including the trailing newline.
+Each line is formatted according to the new line format.
+
+@item %=
+stands for the lines common to both files, including the trailing newline.
+Each line is formatted according to the unchanged line format.
+
+@item %%
+stands for @samp{%}.
+
+@item %c'@var{C}'
+where @var{C} is a single character, stands for @var{C}.
+@var{C} may not be a backslash or an apostrophe.
+For example, @samp{%c':'} stands for a colon, even inside
+the then-part of an if-then-else format, which a colon would
+normally terminate.
+
+@item %c'\@var{O}'
+where @var{O} is a string of 1, 2, or 3 octal digits,
+stands for the character with octal code @var{O}.
+For example, @samp{%c'\0'} stands for a null character.
+
+@item @var{F}@var{n}
+where @var{F} is a @code{printf} conversion specification and @var{n} is one
+of the following letters, stands for @var{n}'s value formatted with @var{F}.
+
+@table @samp
+@item e
+The line number of the line just before the group in the old file.
+
+@item f
+The line number of the first line in the group in the old file;
+equals @var{e} + 1.
+
+@item l
+The line number of the last line in the group in the old file.
+
+@item m
+The line number of the line just after the group in the old file;
+equals @var{l} + 1.
+
+@item n
+The number of lines in the group in the old file; equals @var{l} - @var{f} + 1.
+
+@item E, F, L, M, N
+Likewise, for lines in the new file.
+
+@end table
+
+@vindex LC_NUMERIC
+The @code{printf} conversion specification can be @samp{%d},
+@samp{%o}, @samp{%x}, or @samp{%X}, specifying decimal, octal,
+lower case hexadecimal, or upper case hexadecimal output
+respectively. After the @samp{%} the following options can appear in
+sequence: a series of zero or more flags; an integer
+specifying the minimum field width; and a period followed by an
+optional integer specifying the minimum number of digits.
+The flags are @samp{-} for left-justification, @samp{'} for separating
+the digit into groups as specified by the @env{LC_NUMERIC} locale category,
+and @samp{0} for padding with zeros instead of spaces.
+For example, @samp{%5dN} prints the number of new lines in the group
+in a field of width 5 characters, using the @code{printf} format @code{"%5d"}.
+
+@item (@var{A}=@var{B}?@var{T}:@var{E})
+If @var{A} equals @var{B} then @var{T} else @var{E}.
+@var{A} and @var{B} are each either a decimal constant
+or a single letter interpreted as above.
+This format spec is equivalent to @var{T} if
+@var{A}'s value equals @var{B}'s; otherwise it is equivalent to @var{E}.
+
+For example, @samp{%(N=0?no:%dN) line%(N=1?:s)} is equivalent to
+@samp{no lines} if @var{N} (the number of lines in the group in the the
+new file) is 0, to @samp{1 line} if @var{N} is 1, and to @samp{%dN lines}
+otherwise.
+@end table
+
+@node Line Formats
+@subsection Line Formats
+@cindex line formats
+
+Line formats control how each line taken from an input file is
+output as part of a line group in if-then-else format.
+
+For example, the following command outputs text with a one-character
+change indicator to the left of the text. The first character of output
+is @samp{-} for deleted lines, @samp{|} for added lines, and a space for
+unchanged lines. The formats contain newline characters where newlines
+are desired on output.
+
+@example
+diff \
+ --old-line-format='-%l
+' \
+ --new-line-format='|%l
+' \
+ --unchanged-line-format=' %l
+' \
+ old new
+@end example
+
+To specify a line format, use one of the following options. You should
+quote @var{format}, since it often contains shell metacharacters.
+
+@table @option
+@item --old-line-format=@var{format}
+formats lines just from the first file.
+
+@item --new-line-format=@var{format}
+formats lines just from the second file.
+
+@item --unchanged-line-format=@var{format}
+formats lines common to both files.
+
+@item --line-format=@var{format}
+formats all lines; in effect, it sets all three above options simultaneously.
+@end table
+
+In a line format, ordinary characters represent themselves;
+conversion specifications start with @samp{%} and have one of the
+following forms.
+
+@table @samp
+@item %l
+stands for the contents of the line, not counting its trailing
+newline (if any). This format ignores whether the line is incomplete;
+@xref{Incomplete Lines}.
+
+@item %L
+stands for the contents of the line, including its trailing newline
+(if any). If a line is incomplete, this format preserves its
+incompleteness.
+
+@item %%
+stands for @samp{%}.
+
+@item %c'@var{C}'
+where @var{C} is a single character, stands for @var{C}.
+@var{C} may not be a backslash or an apostrophe.
+For example, @samp{%c':'} stands for a colon.
+
+@item %c'\@var{O}'
+where @var{O} is a string of 1, 2, or 3 octal digits,
+stands for the character with octal code @var{O}.
+For example, @samp{%c'\0'} stands for a null character.
+
+@item @var{F}n
+where @var{F} is a @code{printf} conversion specification,
+stands for the line number formatted with @var{F}.
+For example, @samp{%.5dn} prints the line number using the
+@code{printf} format @code{"%.5d"}. @xref{Line Group Formats}, for
+more about printf conversion specifications.
+
+@end table
+
+The default line format is @samp{%l} followed by a newline character.
+
+If the input contains tab characters and it is important that they line
+up on output, you should ensure that @samp{%l} or @samp{%L} in a line
+format is just after a tab stop (e.g.@: by preceding @samp{%l} or
+@samp{%L} with a tab character), or you should use the @option{-t} or
+@option{--expand-tabs} option.
+
+Taken together, the line and line group formats let you specify many
+different formats. For example, the following command uses a format
+similar to normal @command{diff} format. You can tailor this command
+to get fine control over @command{diff} output.
+
+@example
+diff \
+ --old-line-format='< %l
+' \
+ --new-line-format='> %l
+' \
+ --old-group-format='%df%(f=l?:,%dl)d%dE
+%<' \
+ --new-group-format='%dea%dF%(F=L?:,%dL)
+%>' \
+ --changed-group-format='%df%(f=l?:,%dl)c%dF%(F=L?:,%dL)
+%<---
+%>' \
+ --unchanged-group-format='' \
+ old new
+@end example
+
+@node Detailed If-then-else
+@subsection Detailed Description of If-then-else Format
+
+For lines common to both files, @command{diff} uses the unchanged line
+group format. For each hunk of differences in the merged output
+format, if the hunk contains only lines from the first file,
+@command{diff} uses the old line group format; if the hunk contains only
+lines from the second file, @command{diff} uses the new group format;
+otherwise, @command{diff} uses the changed group format.
+
+The old, new, and unchanged line formats specify the output format of
+lines from the first file, lines from the second file, and lines common
+to both files, respectively.
+
+The option @option{--ifdef=@var{name}} is equivalent to
+the following sequence of options using shell syntax:
+
+@example
+--old-group-format='#ifndef @var{name}
+%<#endif /* ! @var{name} */
+' \
+--new-group-format='#ifdef @var{name}
+%>#endif /* @var{name} */
+' \
+--unchanged-group-format='%=' \
+--changed-group-format='#ifndef @var{name}
+%<#else /* @var{name} */
+%>#endif /* @var{name} */
+'
+@end example
+
+You should carefully check the @command{diff} output for proper nesting.
+For example, when using the @option{-D @var{name}} or
+@option{--ifdef=@var{name}} option, you should check that if the
+differing lines contain any of the C preprocessor directives
+@samp{#ifdef}, @samp{#ifndef}, @samp{#else}, @samp{#elif}, or
+@samp{#endif}, they are nested properly and match. If they don't, you
+must make corrections manually. It is a good idea to carefully check
+the resulting code anyway to make sure that it really does what you
+want it to; depending on how the input files were produced, the output
+might contain duplicate or otherwise incorrect code.
+
+The @command{patch} @option{-D @var{name}} option behaves like
+the @command{diff} @option{-D @var{name}} option, except it operates on
+a file and a diff to produce a merged file; @xref{patch Options}.
+
+@node Example If-then-else
+@subsection An Example of If-then-else Format
+
+Here is the output of @samp{diff -DTWO lao tzu} (@pxref{Sample
+diff Input}, for the complete contents of the two files):
+
+@example
+#ifndef TWO
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+#endif /* ! TWO */
+The Nameless is the origin of Heaven and Earth;
+#ifndef TWO
+The Named is the mother of all things.
+#else /* TWO */
+The named is the mother of all things.
+
+#endif /* TWO */
+Therefore let there always be non-being,
+ so we may see their subtlety,
+And let there always be being,
+ so we may see their outcome.
+The two are the same,
+But after they are produced,
+ they have different names.
+#ifdef TWO
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+#endif /* TWO */
+@end example
+
+@node Incomplete Lines
+@chapter Incomplete Lines
+@cindex incomplete lines
+@cindex full lines
+@cindex newline treatment by @command{diff}
+
+When an input file ends in a non-newline character, its last line is
+called an @dfn{incomplete line} because its last character is not a
+newline. All other lines are called @dfn{full lines} and end in a
+newline character. Incomplete lines do not match full lines unless
+differences in white space are ignored (@pxref{White Space}).
+
+An incomplete line is normally distinguished on output from a full line
+by a following line that starts with @samp{\}. However, the @sc{rcs} format
+(@pxref{RCS}) outputs the incomplete line as-is, without any trailing
+newline or following line. The side by side format normally represents
+incomplete lines as-is, but in some cases uses a @samp{\} or @samp{/}
+gutter marker; @xref{Side by Side}. The if-then-else line format
+preserves a line's incompleteness with @samp{%L}, and discards the
+newline with @samp{%l}; @xref{Line Formats}. Finally, with the
+@command{ed} and forward @command{ed} output formats (@pxref{Output Formats})
+@command{diff} cannot represent an incomplete line, so it pretends there
+was a newline and reports an error.
+
+For example, suppose @file{F} and @file{G} are one-byte files that
+contain just @samp{f} and @samp{g}, respectively. Then @samp{diff F G}
+outputs
+
+@example
+1c1
+< f
+\ No newline at end of file
+---
+> g
+\ No newline at end of file
+@end example
+
+@noindent
+(The exact message may differ in non-English locales.)
+@samp{diff -n F G} outputs the following without a trailing newline:
+
+@example
+d1 1
+a1 1
+g
+@end example
+
+@noindent
+@samp{diff -e F G} reports two errors and outputs the following:
+
+@example
+1c
+g
+.
+@end example
+
+@node Comparing Directories
+@chapter Comparing Directories
+
+@vindex LC_COLLATE
+You can use @command{diff} to compare some or all of the files in two
+directory trees. When both file name arguments to @command{diff} are
+directories, it compares each file that is contained in both
+directories, examining file names in alphabetical order as specified by
+the @env{LC_COLLATE} locale category. Normally
+@command{diff} is silent about pairs of files that contain no differences,
+but if you use the @option{-s} or @option{--report-identical-files} option,
+it reports pairs of identical files. Normally @command{diff} reports
+subdirectories common to both directories without comparing
+subdirectories' files, but if you use the @option{-r} or
+@option{--recursive} option, it compares every corresponding pair of files
+in the directory trees, as many levels deep as they go.
+
+For file names that are in only one of the directories, @command{diff}
+normally does not show the contents of the file that exists; it reports
+only that the file exists in that directory and not in the other. You
+can make @command{diff} act as though the file existed but was empty in the
+other directory, so that it outputs the entire contents of the file that
+actually exists. (It is output as either an insertion or a
+deletion, depending on whether it is in the first or the second
+directory given.) To do this, use the @option{-N} or @option{--new-file}
+option.
+
+If the older directory contains one or more large files that are not in
+the newer directory, you can make the patch smaller by using the
+@option{--unidirectional-new-file} option instead of @option{-N}.
+This option is like @option{-N} except that it only inserts the contents
+of files that appear in the second directory but not the first (that is,
+files that were added). At the top of the patch, write instructions for
+the user applying the patch to remove the files that were deleted before
+applying the patch. @xref{Making Patches}, for more discussion of
+making patches for distribution.
+
+To ignore some files while comparing directories, use the @option{-x
+@var{pattern}} or @option{--exclude=@var{pattern}} option. This option
+ignores any files or subdirectories whose base names match the shell
+pattern @var{pattern}. Unlike in the shell, a period at the start of
+the base of a file name matches a wildcard at the start of a pattern.
+You should enclose @var{pattern} in quotes so that the shell does not
+expand it. For example, the option @option{-x '*.[ao]'} ignores any file
+whose name ends with @samp{.a} or @samp{.o}.
+
+This option accumulates if you specify it more than once. For example,
+using the options @option{-x 'RCS' -x '*,v'} ignores any file or
+subdirectory whose base name is @samp{RCS} or ends with @samp{,v}.
+
+If you need to give this option many times, you can instead put the
+patterns in a file, one pattern per line, and use the @option{-X
+@var{file}} or @option{--exclude-from=@var{file}} option.
+
+If you have been comparing two directories and stopped partway through,
+later you might want to continue where you left off. You can do this by
+using the @option{-S @var{file}} or @option{--starting-file=@var{file}}
+option. This compares only the file @var{file} and all alphabetically
+later files in the topmost directory level.
+
+If two directories differ only in that file names are lower case in
+one directory and upper case in the upper, @command{diff} normally
+reports many differences because it compares file names in a
+case sensitive way. With the @option{--ignore-file-name-case} option,
+@command{diff} ignores case differences in file names, so that for example
+the contents of the file @file{Tao} in one directory are compared to
+the contents of the file @file{TAO} in the other. The
+@option{--no-ignore-file-name-case} option cancels the effect of the
+@option{--ignore-file-name-case} option, reverting to the default
+behavior.
+
+If an @option{-x @var{pattern}}, @option{--exclude=@var{pattern}},
+@option{-X @var{file}}, or @option{--exclude-from=@var{file}} option
+is specified while the @option{--ignore-file-name-case} option is in
+effect, case is ignored when excluding file names matching the
+specified patterns.
+
+@node Adjusting Output
+@chapter Making @command{diff} Output Prettier
+
+@command{diff} provides several ways to adjust the appearance of its output.
+These adjustments can be applied to any output format.
+
+@menu
+* Tabs:: Preserving the alignment of tab stops.
+* Pagination:: Page numbering and time-stamping @command{diff} output.
+@end menu
+
+@node Tabs
+@section Preserving Tab Stop Alignment
+@cindex tab stop alignment
+@cindex aligning tab stops
+
+The lines of text in some of the @command{diff} output formats are preceded
+by one or two characters that indicate whether the text is inserted,
+deleted, or changed. The addition of those characters can cause tabs to
+move to the next tab stop, throwing off the alignment of columns in the
+line. @sc{gnu} @command{diff} provides two ways to make tab-aligned columns
+line up correctly.
+
+The first way is to have @command{diff} convert all tabs into the correct
+number of spaces before outputting them; select this method with the
+@option{-t} or @option{--expand-tabs} option. @command{diff} assumes that
+tab stops are set every 8 print columns. To use this form of output with
+@command{patch}, you must give @command{patch} the @option{-l} or
+@option{--ignore-white-space} option (@pxref{Changed White Space}, for more
+information).
+
+The other method for making tabs line up correctly is to add a tab
+character instead of a space after the indicator character at the
+beginning of the line. This ensures that all following tab characters
+are in the same position relative to tab stops that they were in the
+original files, so that the output is aligned correctly. Its
+disadvantage is that it can make long lines too long to fit on one line
+of the screen or the paper. It also does not work with the unified
+output format, which does not have a space character after the change
+type indicator character. Select this method with the @option{-T} or
+@option{--initial-tab} option.
+
+@node Pagination
+@section Paginating @command{diff} Output
+@cindex paginating @command{diff} output
+
+It can be convenient to have long output page-numbered and time-stamped.
+The @option{-l} and @option{--paginate} options do this by sending the
+@command{diff} output through the @command{pr} program. Here is what the page
+header might look like for @samp{diff -lc lao tzu}:
+
+@example
+2002-02-22 14:20 diff -lc lao tzu Page 1
+@end example
+
+@node diff Performance
+@chapter @command{diff} Performance Tradeoffs
+@cindex performance of @command{diff}
+
+@sc{gnu} @command{diff} runs quite efficiently; however, in some circumstances
+you can cause it to run faster or produce a more compact set of changes.
+
+One way to improve @command{diff} performance is to use hard or
+symbolic links to files instead of copies. This improves performance
+because @command{diff} normally does not need to read two hard or
+symbolic links to the same file, since their contents must be
+identical. For example, suppose you copy a large directory hierarchy,
+make a few changes to the copy, and then often use @samp{diff -r} to
+compare the original to the copy. If the original files are
+read-only, you can greatly improve performance by creating the copy
+using hard or symbolic links (e.g., with @sc{gnu} @samp{cp -lR} or
+@samp{cp -sR}). Before editing a file in the copy for the first time,
+you should break the link and replace it with a regular copy.
+
+You can also affect the performance of @sc{gnu} @command{diff} by
+giving it options that change the way it compares files.
+Performance has more than one dimension. These options improve one
+aspect of performance at the cost of another, or they improve
+performance in some cases while hurting it in others.
+
+The way that @sc{gnu} @command{diff} determines which lines have changed always
+comes up with a near-minimal set of differences. Usually it is good
+enough for practical purposes. If the @command{diff} output is large, you
+might want @command{diff} to use a modified algorithm that sometimes
+produces a smaller set of differences. The @option{-d} or
+@option{--minimal} option does this; however, it can also cause
+@command{diff} to run more slowly than usual, so it is not the default
+behavior.
+
+When the files you are comparing are large and have small groups of
+changes scattered throughout them, you can use the
+@option{--speed-large-files} option to make a different modification to
+the algorithm that @command{diff} uses. If the input files have a constant
+small density of changes, this option speeds up the comparisons without
+changing the output. If not, @command{diff} might produce a larger set of
+differences; however, the output will still be correct.
+
+Normally @command{diff} discards the prefix and suffix that is common to
+both files before it attempts to find a minimal set of differences.
+This makes @command{diff} run faster, but occasionally it may produce
+non-minimal output. The @option{--horizon-lines=@var{lines}} option
+prevents @command{diff} from discarding the last @var{lines} lines of the
+prefix and the first @var{lines} lines of the suffix. This gives
+@command{diff} further opportunities to find a minimal output.
+
+Suppose a run of changed lines includes a sequence of lines at one end
+and there is an identical sequence of lines just outside the other end.
+The @command{diff} command is free to choose which identical sequence is
+included in the hunk. In this case, @command{diff} normally shifts the
+hunk's boundaries when this merges adjacent hunks, or shifts a hunk's
+lines towards the end of the file. Merging hunks can make the output
+look nicer in some cases.
+
+@node Comparing Three Files
+@chapter Comparing Three Files
+@cindex comparing three files
+@cindex format of @command{diff3} output
+
+Use the program @command{diff3} to compare three files and show any
+differences among them. (@command{diff3} can also merge files; see
+@ref{diff3 Merging}).
+
+The ``normal'' @command{diff3} output format shows each hunk of
+differences without surrounding context. Hunks are labeled depending
+on whether they are two-way or three-way, and lines are annotated by
+their location in the input files.
+
+@xref{Invoking diff3}, for more information on how to run @command{diff3}.
+
+@menu
+* Sample diff3 Input:: Sample @command{diff3} input for examples.
+* Detailed diff3 Normal:: A detailed description of normal output format.
+* diff3 Hunks:: The format of normal output format.
+* Example diff3 Normal:: Sample output in the normal format.
+@end menu
+
+@node Sample diff3 Input
+@section A Third Sample Input File
+@cindex @command{diff3} sample input
+@cindex sample input for @command{diff3}
+
+Here is a third sample file that will be used in examples to illustrate
+the output of @command{diff3} and how various options can change it. The
+first two files are the same that we used for @command{diff} (@pxref{Sample
+diff Input}). This is the third sample file, called @file{tao}:
+
+@example
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+The Nameless is the origin of Heaven and Earth;
+The named is the mother of all things.
+
+Therefore let there always be non-being,
+ so we may see their subtlety,
+And let there always be being,
+ so we may see their result.
+The two are the same,
+But after they are produced,
+ they have different names.
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+@end example
+
+@node Detailed diff3 Normal
+@section Detailed Description of @command{diff3} Normal Format
+
+Each hunk begins with a line marked @samp{====}. Three-way hunks have
+plain @samp{====} lines, and two-way hunks have @samp{1}, @samp{2}, or
+@samp{3} appended to specify which of the three input files differ in
+that hunk. The hunks contain copies of two or three sets of input
+lines each preceded by one or two commands identifying where the lines
+came from.
+
+Normally, two spaces precede each copy of an input line to distinguish
+it from the commands. But with the @option{-T} or @option{--initial-tab}
+option, @command{diff3} uses a tab instead of two spaces; this lines up
+tabs correctly. @xref{Tabs}, for more information.
+
+Commands take the following forms:
+
+@table @samp
+@item @var{file}:@var{l}a
+This hunk appears after line @var{l} of file @var{file}, and
+contains no lines in that file. To edit this file to yield the other
+files, one must append hunk lines taken from the other files. For
+example, @samp{1:11a} means that the hunk follows line 11 in the first
+file and contains no lines from that file.
+
+@item @var{file}:@var{r}c
+This hunk contains the lines in the range @var{r} of file @var{file}.
+The range @var{r} is a comma-separated pair of line numbers, or just one
+number if the range is a singleton. To edit this file to yield the
+other files, one must change the specified lines to be the lines taken
+from the other files. For example, @samp{2:11,13c} means that the hunk
+contains lines 11 through 13 from the second file.
+@end table
+
+If the last line in a set of input lines is incomplete
+(@pxref{Incomplete Lines}), it is distinguished on output from a full
+line by a following line that starts with @samp{\}.
+
+@node diff3 Hunks
+@section @command{diff3} Hunks
+@cindex hunks for @command{diff3}
+@cindex @command{diff3} hunks
+
+Groups of lines that differ in two or three of the input files are
+called @dfn{diff3 hunks}, by analogy with @command{diff} hunks
+(@pxref{Hunks}). If all three input files differ in a @command{diff3}
+hunk, the hunk is called a @dfn{three-way hunk}; if just two input files
+differ, it is a @dfn{two-way hunk}.
+
+As with @command{diff}, several solutions are possible. When comparing the
+files @samp{A}, @samp{B}, and @samp{C}, @command{diff3} normally finds
+@command{diff3} hunks by merging the two-way hunks output by the two
+commands @samp{diff A B} and @samp{diff A C}. This does not necessarily
+minimize the size of the output, but exceptions should be rare.
+
+For example, suppose @file{F} contains the three lines @samp{a},
+@samp{b}, @samp{f}, @file{G} contains the lines @samp{g}, @samp{b},
+@samp{g}, and @file{H} contains the lines @samp{a}, @samp{b},
+@samp{h}. @samp{diff3 F G H} might output the following:
+
+@example
+====2
+1:1c
+3:1c
+ a
+2:1c
+ g
+====
+1:3c
+ f
+2:3c
+ g
+3:3c
+ h
+@end example
+
+@noindent
+because it found a two-way hunk containing @samp{a} in the first and
+third files and @samp{g} in the second file, then the single line
+@samp{b} common to all three files, then a three-way hunk containing
+the last line of each file.
+
+@node Example diff3 Normal
+@section An Example of @command{diff3} Normal Format
+
+Here is the output of the command @samp{diff3 lao tzu tao}
+(@pxref{Sample diff3 Input}, for the complete contents of the files).
+Notice that it shows only the lines that are different among the three
+files.
+
+@example
+====2
+1:1,2c
+3:1,2c
+ The Way that can be told of is not the eternal Way;
+ The name that can be named is not the eternal name.
+2:0a
+====1
+1:4c
+ The Named is the mother of all things.
+2:2,3c
+3:4,5c
+ The named is the mother of all things.
+
+====3
+1:8c
+2:7c
+ so we may see their outcome.
+3:9c
+ so we may see their result.
+====
+1:11a
+2:11,13c
+ They both may be called deep and profound.
+ Deeper and more profound,
+ The door of all subtleties!
+3:13,14c
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+@end example
+
+@node diff3 Merging
+@chapter Merging From a Common Ancestor
+@cindex merging from a common ancestor
+
+When two people have made changes to copies of the same file,
+@command{diff3} can produce a merged output that contains both sets of
+changes together with warnings about conflicts.
+
+One might imagine programs with names like @command{diff4} and @command{diff5}
+to compare more than three files simultaneously, but in practice the
+need rarely arises. You can use @command{diff3} to merge three or more
+sets of changes to a file by merging two change sets at a time.
+
+@command{diff3} can incorporate changes from two modified versions into a
+common preceding version. This lets you merge the sets of changes
+represented by the two newer files. Specify the common ancestor version
+as the second argument and the two newer versions as the first and third
+arguments, like this:
+
+@example
+diff3 @var{mine} @var{older} @var{yours}
+@end example
+
+@noindent
+You can remember the order of the arguments by noting that they are in
+alphabetical order.
+
+@cindex conflict
+@cindex overlap
+You can think of this as subtracting @var{older} from @var{yours} and
+adding the result to @var{mine}, or as merging into @var{mine} the
+changes that would turn @var{older} into @var{yours}. This merging is
+well-defined as long as @var{mine} and @var{older} match in the
+neighborhood of each such change. This fails to be true when all three
+input files differ or when only @var{older} differs; we call this
+a @dfn{conflict}. When all three input files differ, we call the
+conflict an @dfn{overlap}.
+
+@command{diff3} gives you several ways to handle overlaps and conflicts.
+You can omit overlaps or conflicts, or select only overlaps,
+or mark conflicts with special @samp{<<<<<<<} and @samp{>>>>>>>} lines.
+
+@command{diff3} can output the merge results as an @command{ed} script that
+that can be applied to the first file to yield the merged output.
+However, it is usually better to have @command{diff3} generate the merged
+output directly; this bypasses some problems with @command{ed}.
+
+@menu
+* Which Changes:: Selecting changes to incorporate.
+* Marking Conflicts:: Marking conflicts.
+* Bypassing ed:: Generating merged output directly.
+* Merging Incomplete Lines:: How @command{diff3} merges incomplete lines.
+* Saving the Changed File:: Emulating System V behavior.
+@end menu
+
+@node Which Changes
+@section Selecting Which Changes to Incorporate
+@cindex overlapping change, selection of
+@cindex unmerged change
+
+You can select all unmerged changes from @var{older} to @var{yours} for merging
+into @var{mine} with the @option{-e} or @option{--ed} option. You can
+select only the nonoverlapping unmerged changes with @option{-3} or
+@option{--easy-only}, and you can select only the overlapping changes with
+@option{-x} or @option{--overlap-only}.
+
+The @option{-e}, @option{-3} and @option{-x} options select only
+@dfn{unmerged changes}, i.e.@: changes where @var{mine} and @var{yours}
+differ; they ignore changes from @var{older} to @var{yours} where
+@var{mine} and @var{yours} are identical, because they assume that such
+changes have already been merged. If this assumption is not a safe
+one, you can use the @option{-A} or @option{--show-all} option
+(@pxref{Marking Conflicts}).
+
+Here is the output of the command @command{diff3} with each of these three
+options (@pxref{Sample diff3 Input}, for the complete contents of the files).
+Notice that @option{-e} outputs the union of the disjoint sets of changes
+output by @option{-3} and @option{-x}.
+
+Output of @samp{diff3 -e lao tzu tao}:
+@example
+11a
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+.
+8c
+ so we may see their result.
+.
+@end example
+
+Output of @samp{diff3 -3 lao tzu tao}:
+@example
+8c
+ so we may see their result.
+.
+@end example
+
+Output of @samp{diff3 -x lao tzu tao}:
+@example
+11a
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+.
+@end example
+
+@node Marking Conflicts
+@section Marking Conflicts
+@cindex conflict marking
+@cindex @samp{<<<<<<<} for marking conflicts
+
+@command{diff3} can mark conflicts in the merged output by
+bracketing them with special marker lines. A conflict
+that comes from two files @var{A} and @var{B} is marked as follows:
+
+@example
+<<<<<<< @var{A}
+@r{lines from @var{A}}
+=======
+@r{lines from @var{B}}
+>>>>>>> @var{B}
+@end example
+
+A conflict that comes from three files @var{A}, @var{B} and @var{C} is
+marked as follows:
+
+@example
+<<<<<<< @var{A}
+@r{lines from @var{A}}
+||||||| @var{B}
+@r{lines from @var{B}}
+=======
+@r{lines from @var{C}}
+>>>>>>> @var{C}
+@end example
+
+The @option{-A} or @option{--show-all} option acts like the @option{-e}
+option, except that it brackets conflicts, and it outputs all changes
+from @var{older} to @var{yours}, not just the unmerged changes. Thus,
+given the sample input files (@pxref{Sample diff3 Input}), @samp{diff3
+-A lao tzu tao} puts brackets around the conflict where only @file{tzu}
+differs:
+
+@example
+<<<<<<< tzu
+=======
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+>>>>>>> tao
+@end example
+
+And it outputs the three-way conflict as follows:
+
+@example
+<<<<<<< lao
+||||||| tzu
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+=======
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+>>>>>>> tao
+@end example
+
+The @option{-E} or @option{--show-overlap} option outputs less information
+than the @option{-A} or @option{--show-all} option, because it outputs only
+unmerged changes, and it never outputs the contents of the second
+file. Thus the @option{-E} option acts like the @option{-e} option,
+except that it brackets the first and third files from three-way
+overlapping changes. Similarly, @option{-X} acts like @option{-x}, except
+it brackets all its (necessarily overlapping) changes. For example,
+for the three-way overlapping change above, the @option{-E} and @option{-X}
+options output the following:
+
+@example
+<<<<<<< lao
+=======
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+>>>>>>> tao
+@end example
+
+If you are comparing files that have meaningless or uninformative names,
+you can use the @option{-L @var{label}} or @option{--label=@var{label}}
+option to show alternate names in the @samp{<<<<<<<}, @samp{|||||||}
+and @samp{>>>>>>>} brackets. This option can be given up to three
+times, once for each input file. Thus @samp{diff3 -A -L X -L Y -L Z A
+B C} acts like @samp{diff3 -A A B C}, except that the output looks like
+it came from files named @samp{X}, @samp{Y} and @samp{Z} rather than
+from files named @samp{A}, @samp{B} and @samp{C}.
+
+@node Bypassing ed
+@section Generating the Merged Output Directly
+@cindex merged @command{diff3} format
+
+With the @option{-m} or @option{--merge} option, @command{diff3} outputs the
+merged file directly. This is more efficient than using @command{ed} to
+generate it, and works even with non-text files that @command{ed} would
+reject. If you specify @option{-m} without an @command{ed} script option,
+@option{-A} (@option{--show-all}) is assumed.
+
+For example, the command @samp{diff3 -m lao tzu tao}
+(@pxref{Sample diff3 Input} for a copy of the input files) would output
+the following:
+
+@example
+<<<<<<< tzu
+=======
+The Way that can be told of is not the eternal Way;
+The name that can be named is not the eternal name.
+>>>>>>> tao
+The Nameless is the origin of Heaven and Earth;
+The Named is the mother of all things.
+Therefore let there always be non-being,
+ so we may see their subtlety,
+And let there always be being,
+ so we may see their result.
+The two are the same,
+But after they are produced,
+ they have different names.
+<<<<<<< lao
+||||||| tzu
+They both may be called deep and profound.
+Deeper and more profound,
+The door of all subtleties!
+=======
+
+ -- The Way of Lao-Tzu, tr. Wing-tsit Chan
+>>>>>>> tao
+@end example
+
+@node Merging Incomplete Lines
+@section How @command{diff3} Merges Incomplete Lines
+@cindex incomplete line merging
+
+With @option{-m}, incomplete lines (@pxref{Incomplete Lines}) are simply
+copied to the output as they are found; if the merged output ends in an
+conflict and one of the input files ends in an incomplete
+line, succeeding @samp{|||||||}, @samp{=======} or @samp{>>>>>>>}
+brackets appear somewhere other than the start of a line because
+they are appended to the incomplete line.
+
+Without @option{-m}, if an @command{ed} script option is specified and an
+incomplete line is found, @command{diff3} generates a warning and acts as
+if a newline had been present.
+
+@node Saving the Changed File
+@section Saving the Changed File
+@cindex System V @command{diff3} compatibility
+
+Traditional Unix @command{diff3} generates an @command{ed} script without the
+trailing @samp{w} and @samp{q} commands that save the changes.
+System V @command{diff3} generates these extra commands. @sc{gnu}
+@command{diff3} normally behaves like traditional Unix
+@command{diff3}, but with the @option{-i} option it behaves like
+System V @command{diff3} and appends the @samp{w} and @samp{q}
+commands.
+
+The @option{-i} option requires one of the @command{ed} script options
+@option{-AeExX3}, and is incompatible with the merged output option
+@option{-m}.
+
+@node Interactive Merging
+@chapter Interactive Merging with @command{sdiff}
+@cindex diff merging
+@cindex interactive merging
+
+With @command{sdiff}, you can merge two files interactively based on a
+side-by-side @option{-y} format comparison (@pxref{Side by Side}). Use
+@option{-o @var{file}} or @option{--output=@var{file}} to specify where to
+put the merged text. @xref{Invoking sdiff}, for more details on the
+options to @command{sdiff}.
+
+Another way to merge files interactively is to use the Emacs Lisp
+package @command{emerge}. @xref{emerge, , emerge, emacs, The @sc{gnu} Emacs
+Manual}, for more information.
+
+@menu
+* sdiff Option Summary:: Summary of @command{sdiff} options.
+* Merge Commands:: Merging two files interactively.
+@end menu
+
+@node sdiff Option Summary
+@section Specifying @command{diff} Options to @command{sdiff}
+@cindex @command{sdiff} output format
+
+The following @command{sdiff} options have the same meaning as for
+@command{diff}. @xref{diff Options}, for the use of these options.
+
+@example
+-a -b -d -i -t -v
+-B -E -I @var{regexp}
+
+--ignore-blank-lines --ignore-case
+--ignore-matching-lines=@var{regexp} --ignore-space-change
+--ignore-tab-expansion
+--left-column --minimal --speed-large-files
+--strip-trailing-cr --suppress-common-lines --expand-tabs
+--text --version --width=@var{columns}
+@end example
+
+For historical reasons, @command{sdiff} has alternate names for some
+options. The @option{-l} option is equivalent to the
+@option{--left-column} option, and similarly @option{-s} is equivalent
+to @option{--suppress-common-lines}. The meaning of the @command{sdiff}
+@option{-w} and @option{-W} options is interchanged from that of
+@command{diff}: with @command{sdiff}, @option{-w @var{columns}} is
+equivalent to @option{--width=@var{columns}}, and @option{-W} is
+equivalent to @option{--ignore-all-space}. @command{sdiff} without the
+@option{-o} option is equivalent to @command{diff} with the @option{-y}
+or @option{--side-by-side} option (@pxref{Side by Side}).
+
+@node Merge Commands
+@section Merge Commands
+@cindex merge commands
+@cindex merging interactively
+
+Groups of common lines, with a blank gutter, are copied from the first
+file to the output. After each group of differing lines, @command{sdiff}
+prompts with @samp{%} and pauses, waiting for one of the following
+commands. Follow each command with @key{RET}.
+
+@table @samp
+@item e
+Discard both versions.
+Invoke a text editor on an empty temporary file,
+then copy the resulting file to the output.
+
+@item eb
+Concatenate the two versions, edit the result in a temporary file,
+then copy the edited result to the output.
+
+@item ed
+Like @samp{eb}, except precede each version with a header that
+shows what file and lines the version came from.
+
+@item el
+Edit a copy of the left version, then copy the result to the output.
+
+@item er
+Edit a copy of the right version, then copy the result to the output.
+
+@item l
+Copy the left version to the output.
+
+@item q
+Quit.
+
+@item r
+Copy the right version to the output.
+
+@item s
+Silently copy common lines.
+
+@item v
+Verbosely copy common lines. This is the default.
+@end table
+
+@vindex EDITOR
+The text editor invoked is specified by the @env{EDITOR} environment
+variable if it is set. The default is system-dependent.
+
+@node Merging with patch
+@chapter Merging with @command{patch}
+
+@command{patch} takes comparison output produced by @command{diff} and applies
+the differences to a copy of the original file, producing a patched
+version. With @command{patch}, you can distribute just the changes to a
+set of files instead of distributing the entire file set; your
+correspondents can apply @command{patch} to update their copy of the files
+with your changes. @command{patch} automatically determines the diff
+format, skips any leading or trailing headers, and uses the headers to
+determine which file to patch. This lets your correspondents feed a
+mail message containing a difference listing directly to
+@command{patch}.
+
+@command{patch} detects and warns about common problems like forward
+patches. It saves any patches that it could not apply. It can also maintain a
+@code{patchlevel.h} file to ensure that your correspondents apply
+diffs in the proper order.
+
+@command{patch} accepts a series of diffs in its standard input, usually
+separated by headers that specify which file to patch. It applies
+@command{diff} hunks (@pxref{Hunks}) one by one. If a hunk does not
+exactly match the original file, @command{patch} uses heuristics to try to
+patch the file as well as it can. If no approximate match can be found,
+@command{patch} rejects the hunk and skips to the next hunk. @command{patch}
+normally replaces each file @var{f} with its new version, putting reject
+hunks (if any) into @samp{@var{f}.rej}.
+
+@xref{Invoking patch}, for detailed information on the options to
+@command{patch}.
+
+@menu
+* patch Input:: Selecting the type of @command{patch} input.
+* Revision Control:: Getting files from @sc{rcs}, @sc{sccs}, etc.
+* Imperfect:: Dealing with imperfect patches.
+* Creating and Removing:: Creating and removing files with a patch.
+* Patching Time Stamps:: Updating time stamps on patched files.
+* Multiple Patches:: Handling multiple patches in a file.
+* patch Directories:: Changing directory and stripping directories.
+* Backups:: Whether backup files are made.
+* Backup Names:: Backup file names.
+* Reject Names:: Reject file names.
+* patch Messages:: Messages and questions @command{patch} can produce.
+* patch and POSIX:: Conformance to the @sc{posix} standard.
+* patch and Tradition:: @sc{gnu} versus traditional @command{patch}.
+@end menu
+
+@node patch Input
+@section Selecting the @command{patch} Input Format
+@cindex @command{patch} input format
+
+@command{patch} normally determines which @command{diff} format the patch
+file uses by examining its contents. For patch files that contain
+particularly confusing leading text, you might need to use one of the
+following options to force @command{patch} to interpret the patch file as a
+certain format of diff. The output formats listed here are the only
+ones that @command{patch} can understand.
+
+@table @option
+@item -c
+@itemx --context
+context diff.
+
+@item -e
+@itemx --ed
+@command{ed} script.
+
+@item -n
+@itemx --normal
+normal diff.
+
+@item -u
+@itemx --unified
+unified diff.
+@end table
+
+@node Revision Control
+@section Revision Control
+@cindex revision control
+@cindex version control
+@cindex @sc{rcs}
+@cindex ClearCase
+@cindex @sc{sccs}
+
+If a nonexistent input file is under a revision control system
+supported by @command{patch}, @command{patch} normally asks the user
+whether to get (or check out) the file from the revision control
+system. Patch currently supports @sc{rcs}, ClearCase and @sc{sccs}.
+Under @sc{rcs} and @sc{sccs}, @command{patch} also asks when the input
+file is read-only and matches the default version in the revision
+control system.
+
+@vindex PATCH_GET
+The @option{-g @var{num}} or @option{--get=@var{num}} affects access
+to files under supported revision control systems. If @var{num} is
+positive, @command{patch} gets the file without asking the user; if
+zero, @command{patch} neither asks the user nor gets the file; and if
+negative, @command{patch} asks the user before getting the file. The
+default value of @var{num} is given by the value of the
+@env{PATCH_GET} environment variable if it is set; if not, the default
+value is zero if @command{patch} is conforming to @sc{posix}, negative
+otherwise. @xref{patch and POSIX}.
+
+@vindex VERSION_CONTROL
+The choice of revision control system is unaffected by the
+@env{VERSION_CONTROL} environment variable (@pxref{Backup Names}).
+
+@node Imperfect
+@section Applying Imperfect Patches
+@cindex imperfect patch application
+
+@command{patch} tries to skip any leading text in the patch file,
+apply the diff, and then skip any trailing text. Thus you can feed a
+mail message directly to @command{patch}, and it should work. If the
+entire diff is indented by a constant amount of white space,
+@command{patch} automatically ignores the indentation. If a context
+diff contains trailing carriage return on each line, @command{patch}
+automatically ignores the carriage return. If a context diff has been
+encapsulated by prepending @w{@samp{- }} to lines beginning with @samp{-}
+as per @uref{ftp://ftp.isi.edu/in-notes/rfc934.txt, Internet RFC 934},
+@command{patch} automatically unencapsulates the input.
+
+However, certain other types of imperfect input require user
+intervention or testing.
+
+@menu
+* Changed White Space:: When tabs and spaces don't match exactly.
+* Reversed Patches:: Applying reversed patches correctly.
+* Inexact:: Helping @command{patch} find close matches.
+* Dry Runs:: Predicting what @command{patch} will do.
+@end menu
+
+@node Changed White Space
+@subsection Applying Patches with Changed White Space
+@cindex white space in patches
+
+Sometimes mailers, editors, or other programs change spaces into tabs,
+or vice versa. If this happens to a patch file or an input file, the
+files might look the same, but @command{patch} will not be able to match
+them properly. If this problem occurs, use the @option{-l} or
+@option{--ignore-white-space} option, which makes @command{patch} compare
+blank characters (i.e.@: spaces and tabs) loosely so that any nonempty
+sequence of blanks in the patch file matches any nonempty sequence of
+blanks in the input files. Non-blank
+characters must still match exactly. Each line of the context must
+still match a line in the input file.
+
+@node Reversed Patches
+@subsection Applying Reversed Patches
+@cindex reversed patches
+
+Sometimes people run @command{diff} with the new file first instead of
+second. This creates a diff that is ``reversed''. To apply such
+patches, give @command{patch} the @option{-R} or @option{--reverse} option.
+@command{patch} then attempts to swap each hunk around before applying it.
+Rejects come out in the swapped format.
+
+Often @command{patch} can guess that the patch is reversed. If the first
+hunk of a patch fails, @command{patch} reverses the hunk to see if it can
+apply it that way. If it can, @command{patch} asks you if you want to have
+the @option{-R} option set; if it can't, @command{patch} continues to apply
+the patch normally. This method cannot detect a reversed patch if it is
+a normal diff and the first command is an append (which should have been
+a delete) since appends always succeed, because a null context matches
+anywhere. But most patches add or change lines rather than delete them,
+so most reversed normal diffs begin with a delete, which fails, and
+@command{patch} notices.
+
+If you apply a patch that you have already applied, @command{patch} thinks
+it is a reversed patch and offers to un-apply the patch. This could be
+construed as a feature. If you did this inadvertently and you don't
+want to un-apply the patch, just answer @samp{n} to this offer and to
+the subsequent ``apply anyway'' question---or type @kbd{C-c} to kill the
+@command{patch} process.
+
+@node Inexact
+@subsection Helping @command{patch} Find Inexact Matches
+@cindex inexact patches
+@cindex fuzz factor when patching
+
+For context diffs, and to a lesser extent normal diffs, @command{patch} can
+detect when the line numbers mentioned in the patch are incorrect, and
+it attempts to find the correct place to apply each hunk of the patch.
+As a first guess, it takes the line number mentioned in the hunk, plus
+or minus any offset used in applying the previous hunk. If that is not
+the correct place, @command{patch} scans both forward and backward for a
+set of lines matching the context given in the hunk.
+
+First @command{patch} looks for a place where all lines of the context
+match. If it cannot find such a place, and it is reading a context or
+unified diff, and the maximum fuzz factor is set to 1 or more, then
+@command{patch} makes another scan, ignoring the first and last line of
+context. If that fails, and the maximum fuzz factor is set to 2 or
+more, it makes another scan, ignoring the first two and last two lines
+of context are ignored. It continues similarly if the maximum fuzz
+factor is larger.
+
+The @option{-F @var{lines}} or @option{--fuzz=@var{lines}} option sets the
+maximum fuzz factor to @var{lines}. This option only applies to context
+and unified diffs; it ignores up to @var{lines} lines while looking for
+the place to install a hunk. Note that a larger fuzz factor increases
+the odds of making a faulty patch. The default fuzz factor is 2; there
+is no point to setting it to more than the number of lines of context
+in the diff, ordinarily 3.
+
+If @command{patch} cannot find a place to install a hunk of the patch, it
+writes the hunk out to a reject file (@pxref{Reject Names}, for information
+on how reject files are named). It writes out rejected hunks in context
+format no matter what form the input patch is in. If the input is a
+normal or @command{ed} diff, many of the contexts are simply null. The
+line numbers on the hunks in the reject file may be different from those
+in the patch file: they show the approximate location where @command{patch}
+thinks the failed hunks belong in the new file rather than in the old
+one.
+
+If the @option{--verbose} option is given, then
+as it completes each hunk @command{patch} tells you whether the hunk
+succeeded or failed, and if it failed, on which line (in the new file)
+@command{patch} thinks the hunk should go. If this is different from the
+line number specified in the diff, it tells you the offset. A single
+large offset @emph{may} indicate that @command{patch} installed a hunk in
+the wrong place. @command{patch} also tells you if it used a fuzz factor
+to make the match, in which case you should also be slightly suspicious.
+
+@command{patch} cannot tell if the line numbers are off in an @command{ed}
+script, and can only detect wrong line numbers in a normal diff when it
+finds a change or delete command. It may have the same problem with a
+context diff using a fuzz factor equal to or greater than the number of
+lines of context shown in the diff (typically 3). In these cases, you
+should probably look at a context diff between your original and patched
+input files to see if the changes make sense. Compiling without errors
+is a pretty good indication that the patch worked, but not a guarantee.
+
+A patch against an empty file applies to a nonexistent file, and vice
+versa. @xref{Creating and Removing}.
+
+@command{patch} usually produces the correct results, even when it must
+make many guesses. However, the results are guaranteed only when
+the patch is applied to an exact copy of the file that the patch was
+generated from.
+
+@node Dry Runs
+@subsection Predicting what @command{patch} will do
+@cindex testing @command{patch}
+@cindex dry runs for @command{patch}
+
+It may not be obvious in advance what @command{patch} will do with a
+complicated or poorly formatted patch. If you are concerned that the
+input might cause @command{patch} to modify the wrong files, you can
+use the @option{--dry-run} option, which causes @command{patch} to
+print the results of applying patches without actually changing any
+files. You can then inspect the diagnostics generated by the dry run
+to see whether @command{patch} will modify the files that you expect.
+If the patch does not do what you want, you can modify the patch (or
+the other options to @command{patch}) and try another dry run. Once
+you are satisfied with the proposed patch you can apply it by invoking
+@command{patch} as before, but this time without the
+@option{--dry-run} option.
+
+@node Creating and Removing
+@section Creating and Removing Files
+@cindex creating files
+@cindex empty files, removing
+@cindex removing empty files
+
+Sometimes when comparing two directories, a file may exist in one
+directory but not the other. If you give @command{diff} the
+@option{-N} or @option{--new-file} option, or if you supply an old or
+new file that is named @file{/dev/null} or is empty and is dated the
+Epoch (1970-01-01 00:00:00 UTC), @command{diff} outputs a patch that
+adds or deletes the contents of this file. When given such a patch,
+@command{patch} normally creates a new file or removes the old file.
+However, when conforming to @sc{posix} (@pxref{patch and POSIX}),
+@command{patch} does not remove the old file, but leaves it empty.
+The @option{-E} or @option{--remove-empty-files} option causes
+@command{patch} to remove output files that are empty after applying a
+patch, even if the patch does not appear to be one that removed the
+file.
+
+If the patch appears to create a file that already exists,
+@command{patch} asks for confirmation before applying the patch.
+
+@node Patching Time Stamps
+@section Updating Time Stamps on Patched Files
+@cindex time stamps on patched files
+
+When @command{patch} updates a file, it normally sets the file's
+last-modified time stamp to the current time of day. If you are using
+@command{patch} to track a software distribution, this can cause
+@command{make} to incorrectly conclude that a patched file is out of
+date. For example, if @file{syntax.c} depends on @file{syntax.y}, and
+@command{patch} updates @file{syntax.c} and then @file{syntax.y}, then
+@file{syntax.c} will normally appear to be out of date with respect to
+@file{syntax.y} even though its contents are actually up to date.
+
+The @option{-Z} or @option{--set-utc} option causes @command{patch} to
+set a patched file's modification and access times to the time stamps
+given in context diff headers. If the context diff headers do not
+specify a time zone, they are assumed to use Coordinated Universal
+Time (@sc{utc}, often known as @sc{gmt}).
+
+The @option{-T} or @option{--set-time} option acts like @option{-Z} or
+@option{--set-utc}, except that it assumes that the context diff
+headers' time stamps use local time instead of @sc{utc}. This option
+is not recommended, because patches using local time cannot easily be
+used by people in other time zones, and because local time stamps are
+ambiguous when local clocks move backwards during daylight-saving time
+adjustments. If the context diff headers specify a time zone, this
+option is equivalent to @option{-Z} or @option{--set-utc}.
+
+@command{patch} normally refrains from setting a file's time stamps if
+the file's original last-modified time stamp does not match the time
+given in the diff header, of if the file's contents do not exactly
+match the patch. However, if the @option{-f} or @option{--force}
+option is given, the file's time stamps are set regardless.
+
+Due to the limitations of the current @command{diff} format,
+@command{patch} cannot update the times of files whose contents have
+not changed. Also, if you set file time stamps to values other than
+the current time of day, you should also remove (e.g., with @samp{make
+clean}) all files that depend on the patched files, so that later
+invocations of @command{make} do not get confused by the patched
+files' times.
+
+@node Multiple Patches
+@section Multiple Patches in a File
+@cindex multiple patches
+@cindex intuiting file names from patches
+
+If the patch file contains more than one patch, and if you do not
+specify an input file on the command line, @command{patch} tries to
+apply each patch as if they came from separate patch files. This
+means that it determines the name of the file to patch for each patch,
+and that it examines the leading text before each patch for file names
+and prerequisite revision level (@pxref{Making Patches}, for more on
+that topic).
+
+@command{patch} uses the following rules to intuit a file name from
+the leading text before a patch. First, @command{patch} takes an
+ordered list of candidate file names as follows:
+
+@itemize @bullet
+@item
+If the header is that of a context diff, @command{patch} takes the old
+and new file names in the header. A name is ignored if it does not
+have enough slashes to satisfy the @option{-p@var{num}} or
+@option{--strip=@var{num}} option. The name @file{/dev/null} is also
+ignored.
+
+@item
+If there is an @samp{Index:} line in the leading garbage and if either
+the old and new names are both absent or if @command{patch} is
+conforming to @sc{posix}, @command{patch} takes the name in the
+@samp{Index:} line.
+
+@item
+For the purpose of the following rules, the candidate file names are
+considered to be in the order (old, new, index), regardless of the
+order that they appear in the header.
+@end itemize
+
+@noindent
+Then @command{patch} selects a file name from the candidate list as
+follows:
+
+@itemize @bullet
+@item
+If some of the named files exist, @command{patch} selects the first
+name if conforming to @sc{posix}, and the best name otherwise.
+
+@item
+If @command{patch} is not ignoring @sc{rcs}, ClearCase, and @sc{sccs}
+(@pxref{Revision Control}), and no named files exist but an @sc{rcs},
+ClearCase, or @sc{sccs} master is found, @command{patch} selects the
+first named file with an @sc{rcs}, ClearCase, or @sc{sccs} master.
+
+@item
+If no named files exist, no @sc{rcs}, ClearCase, or @sc{sccs} master
+was found, some names are given, @command{patch} is not conforming to
+@sc{posix}, and the patch appears to create a file, @command{patch}
+selects the best name requiring the creation of the fewest
+directories.
+
+@item
+If no file name results from the above heuristics, you are asked for
+the name of the file to patch, and @command{patch} selects that name.
+@end itemize
+
+To determine the @dfn{best} of a nonempty list of file names,
+@command{patch} first takes all the names with the fewest path name
+components; of those, it then takes all the names with the shortest
+basename; of those, it then takes all the shortest names; finally, it
+takes the first remaining name.
+
+@xref{patch and POSIX}, to see whether @command{patch} is conforming
+to @sc{posix}.
+
+@node patch Directories
+@section Applying Patches in Other Directories
+@cindex directories and patch
+@cindex patching directories
+
+The @option{-d @var{directory}} or @option{--directory=@var{directory}}
+option to @command{patch} makes directory @var{directory} the current
+directory for interpreting both file names in the patch file, and file
+names given as arguments to other options (such as @option{-B} and
+@option{-o}). For example, while in a mail reading program, you can patch
+a file in the @file{/usr/src/emacs} directory directly from a message
+containing the patch like this:
+
+@example
+| patch -d /usr/src/emacs
+@end example
+
+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
+@option{-p@var{number}} or @option{--strip=@var{number}}
+option to set the file name strip count to @var{number}. The strip
+count tells @command{patch} how many slashes, along with the directory
+names between them, to strip from the front of file names. A sequence
+of one or more adjacent slashes is counted as a single slash. By
+default, @command{patch} strips off all leading directories, leaving
+just the base file names.
+
+For example, suppose the file name in the patch file is
+@file{/gnu/src/emacs/etc/NEWS}. Using @option{-p0} gives the
+entire file name unmodified, @option{-p1} gives
+@file{gnu/src/emacs/etc/NEWS} (no leading slash), @option{-p4} gives
+@file{etc/NEWS}, and not specifying @option{-p} at all gives @file{NEWS}.
+
+@command{patch} looks for each file (after any slashes have been stripped)
+in the current directory, or if you used the @option{-d @var{directory}}
+option, in that directory.
+
+@node Backups
+@section Backup Files
+@cindex backup file strategy
+
+Normally, @command{patch} creates a backup file if the patch does not
+exactly match the original input file, because in that case the
+original data might not be recovered if you undo the patch with
+@samp{patch -R} (@pxref{Reversed Patches}). However, when conforming
+to @sc{posix}, @command{patch} does not create backup files by
+default. @xref{patch and POSIX}.
+
+The @option{-b} or @option{--backup} option causes @command{patch} to
+make a backup file regardless of whether the patch matches the
+original input. The @option{--backup-if-mismatch} option causes
+@command{patch} to create backup files for mismatches files; this is
+the default when not conforming to @sc{posix}. The
+@option{--no-backup-if-mismatch} option causes @command{patch} to not
+create backup files, even for mismatched patches; this is the default
+when conforming to @sc{posix}.
+
+When backing up a file that does not exist, an empty, unreadable
+backup file is created as a placeholder to represent the nonexistent
+file.
+
+@node Backup Names
+@section Backup File Names
+@cindex backup file names
+
+Normally, @command{patch} renames an original input file into a backup
+file by appending to its name the extension @samp{.orig}, or @samp{~}
+if using @samp{.orig} would make the backup file name too
+long.@footnote{A coding error in @sc{gnu} @command{patch} version
+2.5.4 causes it to always use @samp{~}, but this should be fixed in
+the next release.} The @option{-z @var{backup-suffix}} or
+@option{--suffix=@var{backup-suffix}} option causes @command{patch} to
+use @var{backup-suffix} as the backup extension instead.
+
+@vindex SIMPLE_BACKUP_SUFFIX
+Alternately, you can specify the extension for backup files with the
+@env{SIMPLE_BACKUP_SUFFIX} environment variable, which the options
+override.
+
+@command{patch} can also create numbered backup files the way @sc{gnu} Emacs
+does. With this method, instead of having a single backup of each file,
+@command{patch} makes a new backup file name each time it patches a file.
+For example, the backups of a file named @file{sink} would be called,
+successively, @file{sink.~1~}, @file{sink.~2~}, @file{sink.~3~}, etc.
+
+@vindex PATCH_VERSION_CONTROL
+@vindex VERSION_CONTROL
+The @option{-V @var{backup-style}} or
+@option{--version-control=@var{backup-style}} option takes as an
+argument a method for creating backup file names. You can alternately
+control the type of backups that @command{patch} makes with the
+@env{PATCH_VERSION_CONTROL} environment variable, which the
+@option{-V} option overrides. If @env{PATCH_VERSION_CONTROL} is not
+set, the @env{VERSION_CONTROL} environment variable is used instead.
+Please note that these options and variables control backup file
+names; they do not affect the choice of revision control system
+(@pxref{Revision Control}).
+
+The values of these environment variables and the argument to the
+@option{-V} option are like the @sc{gnu} Emacs @code{version-control}
+variable (@pxref{Backup Names, , , emacs, The @sc{gnu} Emacs Manual},
+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.
+
+@table @option
+@item t
+@itemx numbered
+Always make numbered backups.
+
+@item nil
+@itemx existing
+Make numbered backups of files that already have them, simple backups of
+the others. This is the default.
+
+@item never
+@itemx simple
+Always make simple backups.
+@end table
+
+You can also tell @command{patch} to prepend a prefix, such as a
+directory name, to produce backup file names. The @option{-B
+@var{prefix}} or @option{--prefix=@var{prefix}} option makes backup
+files by prepending @var{prefix} to them. The @option{-Y
+@var{prefix}} or @option{--basename-prefix=@var{prefix}} prepends
+@var{prefix} to the last file name component of backup file names
+instead; for example, @option{-Y ~} causes the backup name for
+@file{dir/file.c} to be @file{dir/~file.c}. If you use either of
+these prefix options, the suffix-based options are ignored.
+
+If you specify the output file with the @option{-o} option, that file is
+the one that is backed up, not the input file.
+
+Options that affect the names of backup files do not affect whether
+backups are made. For example, if you specify the
+@option{--no-backup-if-mismatch} option, none of the options described
+in this section have any affect, because no backups are made.
+
+@node Reject Names
+@section Reject File Names
+@cindex reject file names
+
+The names for reject files (files containing patches that
+@command{patch} could not find a place to apply) are normally the name
+of the output file with @samp{.rej} appended (or @samp{#} if if using
+@samp{.rej} would make the backup file name too long).
+
+Alternatively, you can tell @command{patch} to place all of the rejected
+patches in a single file. The @option{-r @var{reject-file}} or
+@option{--reject-file=@var{reject-file}} option uses @var{reject-file} as
+the reject file name.
+
+@node patch Messages
+@section Messages and Questions from @command{patch}
+@cindex @command{patch} messages and questions
+@cindex diagnostics from @command{patch}
+@cindex messages from @command{patch}
+
+@command{patch} can produce a variety of messages, especially if it
+has trouble decoding its input. In a few situations where it's not
+sure how to proceed, @command{patch} normally prompts you for more
+information from the keyboard. There are options to produce more or
+fewer messages, to have it not ask for keyboard input, and to
+affect the way that file names are quoted in messages.
+
+@menu
+* More or Fewer Messages:: Controlling the verbosity of @command{patch}.
+* patch and Keyboard Input:: Inhibiting keyboard input.
+* patch Quoting Style:: Quoting file names in diagnostics.
+@end menu
+
+@command{patch} exits with status 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, you should check the
+exit status, so you don't apply a later patch to a partially patched
+file.
+
+@node More or Fewer Messages
+@subsection Controlling the Verbosity of @command{patch}
+@cindex verbose messages from @command{patch}
+@cindex inhibit messages from @command{patch}
+
+You can cause @command{patch} to produce more messages by using the
+@option{--verbose} option. For example, when you give this option,
+the message @samp{Hmm...} indicates that @command{patch} is reading text in
+the patch file, attempting to determine whether there is a patch in that
+text, and if so, what kind of patch it is.
+
+You can inhibit all terminal output from @command{patch}, unless an error
+occurs, by using the @option{-s}, @option{--quiet}, or @option{--silent}
+option.
+
+@node patch and Keyboard Input
+@subsection Inhibiting Keyboard Input
+@cindex keyboard input to @command{patch}
+
+There are two ways you can prevent @command{patch} from asking you any
+questions. The @option{-f} or @option{--force} option assumes that you know
+what you are doing. It causes @command{patch} to do the following:
+
+@itemize @bullet
+@item
+Skip patches that do not contain file names in their headers.
+
+@item
+Patch files even though they have the wrong version for the
+@samp{Prereq:} line in the patch;
+
+@item
+Assume that patches are not reversed even if they look like they are.
+@end itemize
+
+@noindent
+The @option{-t} or @option{--batch} option is similar to @option{-f}, in that
+it suppresses questions, but it makes somewhat different assumptions:
+
+@itemize @bullet
+@item
+Skip patches that do not contain file names in their headers
+(the same as @option{-f}).
+
+@item
+Skip patches for which the file has the wrong version for the
+@samp{Prereq:} line in the patch;
+
+@item
+Assume that patches are reversed if they look like they are.
+@end itemize
+
+@node patch Quoting Style
+@subsection @command{patch} Quoting Style
+@cindex quoting style
+
+When @command{patch} outputs a file name in a diagnostic message, it
+can format the name in any of several ways. This can be useful to
+output file names unambiguously, even if they contain punctuation or
+special characters like newlines. The
+@option{--quoting-style=@var{word}} option controls how names are
+output. The @var{word} should be one of the following:
+
+@table @samp
+@item literal
+Output names as-is.
+@item shell
+Quote names for the shell if they contain shell metacharacters or would
+cause ambiguous output.
+@item shell-always
+Quote names for the shell, even if they would normally not require quoting.
+@item c
+Quote names as for a C language string.
+@item escape
+Quote as with @samp{c} except omit the surrounding double-quote
+characters.
+@c The following are not yet implemented in patch 2.5.4.
+@c @item clocale
+@c Quote as with @samp{c} except use quotation marks appropriate for the
+@c locale.
+@c @item locale
+@c @c Use @t instead of @samp to avoid duplicate quoting in some output styles.
+@c Like @samp{clocale}, but quote @t{`like this'} instead of @t{"like
+@c this"} in the default C locale. This looks nicer on many displays.
+@end table
+
+@vindex QUOTING_STYLE
+You can specify the default value of the @option{--quoting-style}
+option with the environment variable @env{QUOTING_STYLE}. If that
+environment variable is not set, the default value is @samp{shell},
+but this default may change in a future version of @command{patch}.
+
+@node patch and POSIX
+@section @command{patch} and the @sc{posix} Standard
+@cindex @sc{posix}
+
+@vindex POSIXLY_CORRECT
+If you specify the @option{--posix} option, or set the
+@env{POSIXLY_CORRECT} environment variable, @command{patch} conforms
+more strictly to the @sc{posix} standard, as follows:
+
+@itemize @bullet
+@item
+Take the first existing file from the list (old, new, index)
+when intuiting file names from diff headers. @xref{Multiple Patches}.
+
+@item
+Do not remove files that are removed by a diff.
+@xref{Creating and Removing}.
+
+@item
+Do not ask whether to get files from @sc{rcs}, ClearCase, or
+@sc{sccs}. @xref{Revision Control}.
+
+@item
+Require that all options precede the files in the command line.
+
+@item
+Do not backup files, even when there is a mismatch. @xref{Backups}.
+
+@end itemize
+
+@node patch and Tradition
+@section @sc{gnu} @command{patch} and Traditional @command{patch}
+@cindex traditional @command{patch}
+
+The current version of @sc{gnu} @command{patch} normally follows the
+@sc{posix} standard. @xref{patch and POSIX}, for the few exceptions
+to this general rule.
+
+Unfortunately, @sc{posix} redefined the behavior of @command{patch} in
+several important ways. You should be aware of the following
+differences if you must interoperate with traditional @command{patch},
+or with @sc{gnu} @command{patch} version 2.1 and earlier.
+
+@itemize @bullet
+@item
+In traditional @command{patch}, the @option{-p} option's operand was
+optional, and a bare @option{-p} was equivalent to @option{-p0}. The
+@option{-p} option now requires an operand, and @option{-p@ 0} is now
+equivalent to @option{-p0}. For maximum compatibility, use options
+like @option{-p0} and @option{-p1}.
+
+Also, traditional @command{patch} simply counted slashes when
+stripping path prefixes; @command{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 @file{//} in file names.
+
+@item
+In traditional @command{patch}, backups were enabled by default. This
+behavior is now enabled with the @option{-b} or @option{--backup}
+option.
+
+Conversely, in @sc{posix} @command{patch}, backups are never made,
+even when there is a mismatch. In @sc{gnu} @command{patch}, this
+behavior is enabled with the @option{--no-backup-if-mismatch} option,
+or by conforming to @sc{posix}.
+
+The @option{-b@ @var{suffix}} option of traditional @command{patch} is
+equivalent to the @samp{-b -z@ @var{suffix}} options of @sc{gnu}
+@command{patch}.
+
+@item
+Traditional @command{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 @sc{posix}, and had
+a few gotchas. Now @command{patch} uses a different, equally
+complicated (but better documented) method that is optionally
+@sc{posix}-conforming; we hope it has fewer gotchas. The two methods
+are compatible if the file names in the context diff header and the
+@samp{Index:} line are all identical after prefix-stripping. Your
+patch is normally compatible if each header's file names all contain
+the same number of slashes.
+
+@item
+When traditional @command{patch} asked the user a question, it sent
+the question to standard error and looked for an answer from the first
+file in the following list that was a terminal: standard error,
+standard output, @file{/dev/tty}, and standard input. Now
+@command{patch} sends questions to standard output and gets answers
+from @file{/dev/tty}. Defaults for some answers have been changed so
+that @command{patch} never goes into an infinite loop when using
+default answers.
+
+@item
+Traditional @command{patch} exited with a status value that counted
+the number of bad hunks, or with status 1 if there was real trouble.
+Now @command{patch} exits with status 1 if some hunks failed, or with
+2 if there was real trouble.
+
+@item
+Limit yourself to the following options when sending instructions
+meant to be executed by anyone running @sc{gnu} @command{patch},
+traditional @command{patch}, or a @command{patch} that conforms to
+@sc{posix}. Spaces are significant in the following list, and
+operands are required.
+
+@example
+@option{-c}
+@option{-d @var{dir}}
+@option{-D @var{define}}
+@option{-e}
+@option{-l}
+@option{-n}
+@option{-N}
+@option{-o @var{outfile}}
+@option{-p@var{num}}
+@option{-R}
+@option{-r @var{rejectfile}}
+@end example
+
+@end itemize
+
+@node Making Patches
+@chapter Tips for Making and Using Patches
+
+Use some common sense when making and using patches. For example,
+when sending bug fixes to a program's maintainer, send several small
+patches, one per independent subject, instead of one large,
+harder-to-digest patch that covers all the subjects.
+
+Here are some other things you should keep in mind if you are going to
+distribute patches for updating a software package.
+
+@menu
+* Tips for Patch Producers:: Advice for making patches.
+* Tips for Patch Consumers:: Advice for using patches.
+* Avoiding Common Mistakes:: Avoiding common mistakes when using @command{patch}.
+* Generating Smaller Patches:: How to generate smaller patches.
+@end menu
+
+@node Tips for Patch Producers
+@section Tips for Patch Producers
+@cindex patch producer tips
+
+To create a patch that changes an older version of a package into a
+newer version, first make a copy of the older and newer versions in
+adjacent subdirectories. It is common to do that by unpacking
+@command{tar} archives of the two versions.
+
+To generate the patch, use the command @samp{diff -Naur @var{old}
+@var{new}} where @var{old} and @var{new} identify the old and new
+directories. The names @var{old} and @var{new} should not contain any
+slashes. The @option{-N} option lets the patch create and remove
+files; @option{-a} lets the patch update non-text files; @option{-u}
+generates useful time stamps and enough context; and @option{-r} lets
+the patch update subdirectories. Here is an example command, using
+Bourne shell syntax:
+
+@example
+diff -Naur gcc-3.0.3 gcc-3.0.4
+@end example
+
+Tell your recipients how to apply the patches. This should include
+which working directory to use, and which @command{patch} options to
+use; the option @samp{-p1} is recommended. Test your procedure by
+pretending to be a recipient and applying your patches to a copy of
+the original files.
+
+@xref{Avoiding Common Mistakes}, for how to avoid common mistakes when
+generating a patch.
+
+@node Tips for Patch Consumers
+@section Tips for Patch Consumers
+@cindex patch consumer tips
+
+A patch producer should tell recipients how to apply the patches, so
+the first rule of thumb for a patch consumer is to follow the
+instructions supplied with the patch.
+
+@sc{gnu} @command{diff} can analyze files with arbitrarily long lines
+and files that end in incomplete lines. However, older versions of
+@command{patch} cannot patch such files. If you are having trouble
+applying such patches, try upgrading to a recent version of @sc{gnu}
+@command{patch}.
+
+@node Avoiding Common Mistakes
+@section Avoiding Common Mistakes
+@cindex common mistakes with patches
+@cindex patch, common mistakes
+
+When producing a patch for multiple files, apply @command{diff} to
+directories whose names do not have slashes. This reduces confusion
+when the patch consumer specifies the @option{-p@var{number}} option,
+since this option can have surprising results when the old and new
+file names have different numbers of slashes. For example, do not
+send a patch with a header that looks like this:
+
+@example
+diff -Naur v2.0.29/prog/README prog/README
+--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800
++++ prog/README 2002-03-17 20:49:32.442260588 -0800
+@end example
+
+@noindent
+because the two file names have different numbers of slashes, and
+different versions of @command{patch} interpret the file names
+differently. To avoid confusion, send output that looks like this
+instead:
+
+@example
+diff -Naur v2.0.29/prog/README v2.0.30/prog/README
+--- v2.0.29/prog/README 2002-03-10 23:30:39.942229878 -0800
++++ v2.0.30/prog/README 2002-03-17 20:49:32.442260588 -0800
+@end example
+
+Make sure you have specified the file names correctly, either in a
+context diff header or with an @samp{Index:} line. Take care to not send out
+reversed patches, since these make people wonder whether they have
+already applied the patch.
+
+Avoid sending patches that compare backup file names like
+@file{README.orig} or @file{README~}, since this might confuse
+@command{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.@: @file{old/README} and @file{new/README}.
+
+To save people from partially applying a patch before other patches that
+should have gone before it, you can make the first patch in the patch
+file update a file with a name like @file{patchlevel.h} or
+@file{version.c}, which contains a patch level or version number. If
+the input file contains the wrong version number, @command{patch} will
+complain immediately.
+
+An even clearer way to prevent this problem is to put a @samp{Prereq:}
+line before the patch. If the leading text in the patch file contains a
+line that starts with @samp{Prereq:}, @command{patch} takes the next word
+from that line (normally a version number) and checks whether the next
+input file contains that word, preceded and followed by either
+white space or a newline. If not, @command{patch} prompts you for
+confirmation before proceeding. This makes it difficult to accidentally
+apply patches in the wrong order.
+
+@node Generating Smaller Patches
+@section Generating Smaller Patches
+@cindex patches, shrinking
+
+The simplest way to generate a patch is to use @samp{diff -Naur}
+(@pxref{Tips for Patch Producers}), but you might be able to reduce
+the size of the patch by renaming or removing some files before making
+the patch. If the older version of the package contains any files
+that the newer version does not, or if any files have been renamed
+between the two versions, make a list of @command{rm} and @command{mv}
+commands for the user to execute in the old version directory before
+applying the patch. Then run those commands yourself in the scratch
+directory.
+
+If there are any files that you don't need to include in the patch
+because they can easily be rebuilt from other files (for example,
+@file{TAGS} and output from @command{yacc} and @command{makeinfo}),
+exclude them from the patch by giving @command{diff} the @option{-x
+@var{pattern}} option (@pxref{Comparing Directories}). If you want
+your patch to modify a derived file because your recipients lack tools
+to build it, make sure that the patch for the derived file follows any
+patches for files that it depends on, so that the recipients' time
+stamps will not confuse @command{make}.
+
+Now you can create the patch using @samp{diff -Naur}. Make sure to
+specify the scratch directory first and the newer directory second.
+
+Add to the top of the patch a note telling the user any @command{rm} and
+@command{mv} commands to run before applying the patch. Then you can
+remove the scratch directory.
+
+You can also shrink the patch size by using fewer lines of context,
+but bear in mind that @command{patch} typically needs at least two
+lines for proper operation when patches do not exactly match the input
+files.
+
+@node Invoking cmp
+@chapter Invoking @command{cmp}
+@cindex invoking @command{cmp}
+@cindex @command{cmp} invocation
+
+The @command{cmp} command compares two files, and if they differ,
+tells the first byte and line number where they differ. Bytes and
+lines are numbered starting with 1. The arguments of @command{cmp}
+are as follows:
+
+@example
+cmp @var{options}@dots{} @var{from-file} @r{[}@var{to-file} @r{[}@var{from-skip} @r{[}@var{to-skip}@r{]}@r{]}@r{]}
+@end example
+
+The file name @file{-} is always the standard input. @command{cmp}
+also uses the standard input if one file name is omitted. The
+@var{from-skip} and @var{to-skip} operands specify how many bytes to
+ignore at the start of each file; they are equivalent to the
+@option{--ignore-initial=@var{from-skip}:@var{to-skip}} option.
+
+An exit status of 0 means no differences were found, 1 means some
+differences were found, and 2 means trouble.
+
+@menu
+* cmp Options:: Summary of options to @command{cmp}.
+@end menu
+
+@node cmp Options
+@section Options to @command{cmp}
+@cindex @command{cmp} options
+@cindex options for @command{cmp}
+
+Below is a summary of all of the options that @sc{gnu} @command{cmp} accepts.
+Most options have two equivalent names, one of which is a single letter
+preceded by @samp{-}, and the other of which is a long name preceded by
+@samp{--}. Multiple single letter options (unless they take an
+argument) can be combined into a single command line word: @option{-bl} is
+equivalent to @option{-b -l}.
+
+@table @option
+@item -b
+@itemx --print-bytes
+Print the differing bytes. Display control bytes as a
+@samp{^} followed by a letter of the alphabet and precede bytes
+that have the high bit set with @samp{M-} (which stands for ``meta'').
+
+@item --help
+Output a summary of usage and then exit.
+
+@item -i @var{skip}
+@itemx --ignore-initial=@var{skip}
+Ignore any differences in the first @var{skip} bytes of the input
+files. Treat files with fewer than @var{skip} bytes as if they are
+empty. If @var{skip} is of the form
+@option{@var{from-skip}:@var{to-skip}}, skip the first @var{from-skip}
+bytes of the first input file and the first @var{to-skip} bytes of the
+second.
+
+@item -l
+@itemx --verbose
+Print the (decimal) byte numbers and (octal) values of all differing bytes.
+
+@item -n @var{count}
+@itemx --bytes=@var{count}
+Compare at most @var{count} input bytes.
+
+@item -s
+@itemx --quiet
+@itemx --silent
+Do not print anything; only return an exit status indicating whether
+the files differ.
+
+@item -v
+@itemx --version
+Output version information and then exit.
+@end table
+
+In the above table, operands that are byte counts are normally
+decimal, but may be preceded by @samp{0} for octal and @samp{0x} for
+hexadecimal.
+
+A byte count can be followed by a suffix to specify a multiple of that
+count; in this case an omitted integer is understood to be 1. A bare
+size letter, or one followed by @samp{iB}, specifies a multiple using
+powers of 1024. A size letter followed by @samp{B} specifies powers
+of 1000 instead. For example, @option{-n 4M} and @option{-n 4MiB} are
+equivalent to @option{-n 4194304}, whereas @option{-n 4MB} is
+equivalent to @option{-n 4000000}. This notation is upward compatible
+with the @uref{http://www.bipm.fr/enus/3_SI/si-prefixes.html, SI
+prefixes} for decimal multiples and with the
+@uref{http://physics.nist.gov/cuu/Units/binary.html, IEC 60027-2
+prefixes for binary multiples}.
+
+The following suffixes are defined. Large sizes like @code{1Y} may be
+rejected by your computer due to limitations of its arithmetic.
+
+@table @samp
+@item kB
+@cindex kilobyte, definition of
+kilobyte: @math{10^3 = 1000}.
+@item k
+@itemx K
+@itemx KiB
+@cindex kibibyte, definition of
+kibibyte: @math{2^10 = 1024}. @samp{K} is special: the SI prefix is
+@samp{k} and the IEC 60027-2 prefix is @samp{Ki}, but tradition and
+@sc{posix} use @samp{k} to mean @samp{KiB}.
+@item MB
+@cindex megabyte, definition of
+megabyte: @math{10^6 = 1,000,000}.
+@item M
+@itemx MiB
+@cindex mebibyte, definition of
+mebibyte: @math{2^20 = 1,048,576}.
+@item GB
+@cindex gigabyte, definition of
+gigabyte: @math{10^9 = 1,000,000,000}.
+@item G
+@itemx GiB
+@cindex gibibyte, definition of
+gibibyte: @math{2^30 = 1,073,741,824}.
+@item TB
+@cindex terabyte, definition of
+terabyte: @math{10^12 = 1,000,000,000,000}.
+@item T
+@itemx TiB
+@cindex tebibyte, definition of
+tebibyte: @math{2^40 = 1,099,511,627,776}.
+@item PB
+@cindex petabyte, definition of
+petabyte: @math{10^15 = 1,000,000,000,000,000}.
+@item P
+@itemx PiB
+@cindex pebibyte, definition of
+pebibyte: @math{2^50 = 1,125,899,906,842,624}.
+@item EB
+@cindex exabyte, definition of
+exabyte: @math{10^18 = 1,000,000,000,000,000,000}.
+@item E
+@itemx EiB
+@cindex exbibyte, definition of
+exbibyte: @math{2^60 = 1,152,921,504,606,846,976}.
+@item ZB
+@cindex zettabyte, definition of
+zettabyte: @math{10^21 = 1,000,000,000,000,000,000,000}
+@item Z
+@itemx ZiB
+@math{2^70 = 1,180,591,620,717,411,303,424}.
+(@samp{Zi} is a GNU extension to IEC 60027-2.)
+@item YB
+@cindex yottabyte, definition of
+yottabyte: @math{10^24 = 1,000,000,000,000,000,000,000,000}.
+@item Y
+@itemx YiB
+@math{2^80 = 1,208,925,819,614,629,174,706,176}.
+(@samp{Yi} is a GNU extension to IEC 60027-2.)
+@end table
+
+@node Invoking diff
+@chapter Invoking @command{diff}
+@cindex invoking @command{diff}
+@cindex @command{diff} invocation
+
+The format for running the @command{diff} command is:
+
+@example
+diff @var{options}@dots{} @var{files}@dots{}
+@end example
+
+In the simplest case, two file names @var{from-file} and
+@var{to-file} are given, and @command{diff} compares the contents of
+@var{from-file} and @var{to-file}. A file name of @file{-} stands for
+text read from the standard input. As a special case, @samp{diff - -}
+compares a copy of standard input to itself.
+
+If one file is a directory and the other is not, @command{diff} compares
+the file in the directory whose name is that of the non-directory.
+The non-directory file must not be @file{-}.
+
+If two file names are given and both are directories,
+@command{diff} compares corresponding files in both directories, in
+alphabetical order; this comparison is not recursive unless the
+@option{-r} or @option{--recursive} option is given. @command{diff} never
+compares the actual contents of a directory as if it were a file. The
+file that is fully specified may not be standard input, because standard
+input is nameless and the notion of ``file with the same name'' does not
+apply.
+
+If the @option{--from-file=@var{file}} option is given, the number of
+file names is arbitrary, and @var{file} is compared to each named file.
+Similarly, if the @option{--to-file=@var{file}} option is given, each
+named file is compared to @var{file}.
+
+@command{diff} options begin with @samp{-}, so normally file names
+may not begin with @samp{-}. However, @option{--} as an
+argument by itself treats the remaining arguments as file names even if
+they begin with @samp{-}.
+
+An exit status of 0 means no differences were found, 1 means some
+differences were found, and 2 means trouble.
+
+@menu
+* diff Options:: Summary of options to @command{diff}.
+@end menu
+
+@node diff Options
+@section Options to @command{diff}
+@cindex @command{diff} options
+@cindex options for @command{diff}
+
+Below is a summary of all of the options that @sc{gnu} @command{diff} accepts.
+Most options have two equivalent names, one of which is a single letter
+preceded by @samp{-}, and the other of which is a long name preceded by
+@samp{--}. Multiple single letter options (unless they take an
+argument) can be combined into a single command line word: @option{-ac} is
+equivalent to @option{-a -c}. Long named options can be abbreviated to
+any unique prefix of their name. Brackets ([ and ]) indicate that an
+option takes an optional argument.
+
+@table @option
+@item -a
+@itemx --text
+Treat all files as text and compare them line-by-line, even if they
+do not seem to be text. @xref{Binary}.
+
+@item -b
+@itemx --ignore-space-change
+Ignore changes in amount of white space. @xref{White Space}.
+
+@item -B
+@itemx --ignore-blank-lines
+Ignore changes that just insert or delete blank lines. @xref{Blank
+Lines}.
+
+@item --binary
+Read and write data in binary mode. @xref{Binary}.
+
+@item -c
+Use the context output format, showing three lines of context.
+@xref{Context Format}.
+
+@item -C @var{lines}
+@itemx --context@r{[}=@var{lines}@r{]}
+Use the context output format, showing @var{lines} (an integer) lines of
+context, or three if @var{lines} is not given. @xref{Context Format}.
+For proper operation, @command{patch} typically needs at least two lines of
+context.
+
+On older systems, @command{diff} supports an obsolete option
+@option{-@var{lines}} that has effect when combined with @option{-c}
+or @option{-p}. @sc{posix} 1003.1-2001 (@pxref{Standards
+conformance}) does not allow this; use @option{-C @var{lines}}
+instead.
+
+@item --changed-group-format=@var{format}
+Use @var{format} to output a line group containing differing lines from
+both files in if-then-else format. @xref{Line Group Formats}.
+
+@item -d
+@itemx --minimal
+Change the algorithm perhaps find a smaller set of changes. This makes
+@command{diff} slower (sometimes much slower). @xref{diff Performance}.
+
+@item -D @var{name}
+@itemx --ifdef=@var{name}
+Make merged @samp{#ifdef} format output, conditional on the preprocessor
+macro @var{name}. @xref{If-then-else}.
+
+@item -e
+@itemx --ed
+Make output that is a valid @command{ed} script. @xref{ed Scripts}.
+
+@item -E
+@itemx --ignore-tab-expansion
+Ignore changes due to tab expansion.
+@xref{White Space}.
+
+@item -f
+@itemx --forward-ed
+Make output that looks vaguely like an @command{ed} script but has changes
+in the order they appear in the file. @xref{Forward ed}.
+
+@item -F @var{regexp}
+@itemx --show-function-line=@var{regexp}
+In context and unified format, for each hunk of differences, show some
+of the last preceding line that matches @var{regexp}. @xref{Specified
+Headings}.
+
+@item --from-file=@var{file}
+Compare @var{file} to each operand; @var{file} may be a directory.
+
+@item --help
+Output a summary of usage and then exit.
+
+@item --horizon-lines=@var{lines}
+Do not discard the last @var{lines} lines of the common prefix
+and the first @var{lines} lines of the common suffix.
+@xref{diff Performance}.
+
+@item -i
+@itemx --ignore-case
+Ignore changes in case; consider upper- and lower-case letters
+equivalent. @xref{Case Folding}.
+
+@item -I @var{regexp}
+@itemx --ignore-matching-lines=@var{regexp}
+Ignore changes that just insert or delete lines that match @var{regexp}.
+@xref{Specified Folding}.
+
+@item --ignore-file-name-case
+Ignore case when comparing file names during recursive comparison.
+@xref{Comparing Directories}.
+
+@item -l
+@itemx --paginate
+Pass the output through @command{pr} to paginate it. @xref{Pagination}.
+
+@item --label=@var{label}
+Use @var{label} instead of the file name in the context format
+(@pxref{Context Format}) and unified format (@pxref{Unified Format})
+headers. @xref{RCS}.
+
+@item --left-column
+Print only the left column of two common lines in side by side format.
+@xref{Side by Side Format}.
+
+@item --line-format=@var{format}
+Use @var{format} to output all input lines in if-then-else format.
+@xref{Line Formats}.
+
+@item -n
+@itemx --rcs
+Output @sc{rcs}-format diffs; like @option{-f} except that each command
+specifies the number of lines affected. @xref{RCS}.
+
+@item -N
+@itemx --new-file
+In directory comparison, if a file is found in only one directory,
+treat it as present but empty in the other directory. @xref{Comparing
+Directories}.
+
+@item --new-group-format=@var{format}
+Use @var{format} to output a group of lines taken from just the second
+file in if-then-else format. @xref{Line Group Formats}.
+
+@item --new-line-format=@var{format}
+Use @var{format} to output a line taken from just the second file in
+if-then-else format. @xref{Line Formats}.
+
+@item --old-group-format=@var{format}
+Use @var{format} to output a group of lines taken from just the first
+file in if-then-else format. @xref{Line Group Formats}.
+
+@item --old-line-format=@var{format}
+Use @var{format} to output a line taken from just the first file in
+if-then-else format. @xref{Line Formats}.
+
+@item -p
+@itemx --show-c-function
+Show which C function each change is in. @xref{C Function Headings}.
+
+@item -q
+@itemx --brief
+Report only whether the files differ, not the details of the
+differences. @xref{Brief}.
+
+@item -r
+@itemx --recursive
+When comparing directories, recursively compare any subdirectories
+found. @xref{Comparing Directories}.
+
+@item -s
+@itemx --report-identical-files
+Report when two files are the same. @xref{Comparing Directories}.
+
+@item -S @var{file}
+@itemx --starting-file=@var{file}
+When comparing directories, start with the file @var{file}. This is
+used for resuming an aborted comparison. @xref{Comparing Directories}.
+
+@item --speed-large-files
+Use heuristics to speed handling of large files that have numerous
+scattered small changes. @xref{diff Performance}.
+
+@item --strip-trailing-cr
+Strip any trailing carriage return at the end of an input line.
+@xref{Binary}.
+
+@item --suppress-common-lines
+Do not print common lines in side by side format.
+@xref{Side by Side Format}.
+
+@item -t
+@itemx --expand-tabs
+Expand tabs to spaces in the output, to preserve the alignment of tabs
+in the input files. @xref{Tabs}.
+
+@item -T
+@itemx --initial-tab
+Output a tab rather than a space before the text of a line in normal or
+context format. This causes the alignment of tabs in the line to look
+normal. @xref{Tabs}.
+
+@item --to-file=@var{file}
+Compare each operand to @var{file}; @var{file} may be a directory.
+
+@item -u
+Use the unified output format, showing three lines of context.
+@xref{Unified Format}.
+
+@item --unchanged-group-format=@var{format}
+Use @var{format} to output a group of common lines taken from both files
+in if-then-else format. @xref{Line Group Formats}.
+
+@item --unchanged-line-format=@var{format}
+Use @var{format} to output a line common to both files in if-then-else
+format. @xref{Line Formats}.
+
+@item --unidirectional-new-file
+When comparing directories, if a file appears only in the second
+directory of the two, treat it as present but empty in the other.
+@xref{Comparing Directories}.
+
+@item -U @var{lines}
+@itemx --unified@r{[}=@var{lines}@r{]}
+Use the unified output format, showing @var{lines} (an integer) lines of
+context, or three if @var{lines} is not given. @xref{Unified Format}.
+For proper operation, @command{patch} typically needs at least two lines of
+context.
+
+On older systems, @command{diff} supports an obsolete option
+@option{-@var{lines}} that has effect when combined with @option{-u}.
+@sc{posix} 1003.1-2001 (@pxref{Standards conformance}) does not allow
+this; use @option{-U @var{lines}} instead.
+
+@item -v
+@itemx --version
+Output version information and then exit.
+
+@item -w
+@itemx --ignore-all-space
+Ignore white space when comparing lines. @xref{White Space}.
+
+@item -W @var{columns}
+@itemx --width=@var{columns}
+Output at most @var{columns} (default 130) print columns per line in
+side by side format. @xref{Side by Side Format}.
+
+@item -x @var{pattern}
+@itemx --exclude=@var{pattern}
+When comparing directories, ignore files and subdirectories whose basenames
+match @var{pattern}. @xref{Comparing Directories}.
+
+@item -X @var{file}
+@itemx --exclude-from=@var{file}
+When comparing directories, ignore files and subdirectories whose basenames
+match any pattern contained in @var{file}. @xref{Comparing Directories}.
+
+@item -y
+@itemx --side-by-side
+Use the side by side output format. @xref{Side by Side Format}.
+@end table
+
+@node Invoking diff3
+@chapter Invoking @command{diff3}
+@cindex invoking @command{diff3}
+@cindex @command{diff3} invocation
+
+The @command{diff3} command compares three files and outputs descriptions
+of their differences. Its arguments are as follows:
+
+@example
+diff3 @var{options}@dots{} @var{mine} @var{older} @var{yours}
+@end example
+
+The files to compare are @var{mine}, @var{older}, and @var{yours}.
+At most one of these three file names may be @file{-},
+which tells @command{diff3} to read the standard input for that file.
+
+An exit status of 0 means @command{diff3} was successful, 1 means some
+conflicts were found, and 2 means trouble.
+
+@menu
+* diff3 Options:: Summary of options to @command{diff3}.
+@end menu
+
+@node diff3 Options
+@section Options to @command{diff3}
+@cindex @command{diff3} options
+@cindex options for @command{diff3}
+
+Below is a summary of all of the options that @sc{gnu} @command{diff3}
+accepts. Multiple single letter options (unless they take an argument)
+can be combined into a single command line argument.
+
+@table @option
+@item -a
+@itemx --text
+Treat all files as text and compare them line-by-line, even if they
+do not appear to be text. @xref{Binary}.
+
+@item -A
+@itemx --show-all
+Incorporate all unmerged changes from @var{older} to @var{yours} into
+@var{mine}, surrounding conflicts with bracket lines.
+@xref{Marking Conflicts}.
+
+@item --diff-program=@var{program}
+Use the compatible comparison program @var{program} to compare files
+instead of @command{diff}.
+
+@item -e
+@itemx --ed
+Generate an @command{ed} script that incorporates all the changes from
+@var{older} to @var{yours} into @var{mine}. @xref{Which Changes}.
+
+@item -E
+@itemx --show-overlap
+Like @option{-e}, except bracket lines from overlapping changes' first
+and third files.
+@xref{Marking Conflicts}.
+With @option{-E}, an overlapping change looks like this:
+
+@example
+<<<<<<< @var{mine}
+@r{lines from @var{mine}}
+=======
+@r{lines from @var{yours}}
+>>>>>>> @var{yours}
+@end example
+
+@item --help
+Output a summary of usage and then exit.
+
+@item -i
+Generate @samp{w} and @samp{q} commands at the end of the @command{ed}
+script for System V compatibility. This option must be combined with
+one of the @option{-AeExX3} options, and may not be combined with @option{-m}.
+@xref{Saving the Changed File}.
+
+@item -L @var{label}
+@itemx --label=@var{label}
+Use the label @var{label} for the brackets output by the @option{-A},
+@option{-E} and @option{-X} options. This option may be given up to three
+times, one for each input file. The default labels are the names of
+the input files. Thus @samp{diff3 -L X -L Y -L Z -m A B C} acts like
+@samp{diff3 -m A B C}, except that the output looks like it came from
+files named @samp{X}, @samp{Y} and @samp{Z} rather than from files
+named @samp{A}, @samp{B} and @samp{C}. @xref{Marking Conflicts}.
+
+@item -m
+@itemx --merge
+Apply the edit script to the first file and send the result to standard
+output. Unlike piping the output from @command{diff3} to @command{ed}, this
+works even for binary files and incomplete lines. @option{-A} is assumed
+if no edit script option is specified. @xref{Bypassing ed}.
+
+@item -T
+@itemx --initial-tab
+Output a tab rather than two spaces before the text of a line in normal format.
+This causes the alignment of tabs in the line to look normal. @xref{Tabs}.
+
+@item -v
+@itemx --version
+Output version information and then exit.
+
+@item -x
+@itemx --overlap-only
+Like @option{-e}, except output only the overlapping changes.
+@xref{Which Changes}.
+
+@item -X
+Like @option{-E}, except output only the overlapping changes.
+In other words, like @option{-x}, except bracket changes as in @option{-E}.
+@xref{Marking Conflicts}.
+
+@item -3
+@itemx --easy-only
+Like @option{-e}, except output only the nonoverlapping changes.
+@xref{Which Changes}.
+@end table
+
+@node Invoking patch
+@chapter Invoking @command{patch}
+@cindex invoking @command{patch}
+@cindex @command{patch} invocation
+
+Normally @command{patch} is invoked like this:
+
+@example
+patch <@var{patchfile}
+@end example
+
+The full format for invoking @command{patch} is:
+
+@example
+patch @var{options}@dots{} @r{[}@var{origfile} @r{[}@var{patchfile}@r{]}@r{]}
+@end example
+
+You can also specify where to read the patch from with the @option{-i
+@var{patchfile}} or @option{--input=@var{patchfile}} option.
+If you do not specify @var{patchfile}, or if @var{patchfile} is
+@file{-}, @command{patch} reads the patch (that is, the @command{diff} output)
+from the standard input.
+
+If you do not specify an input file on the command line, @command{patch}
+tries to intuit from the @dfn{leading text} (any text in the patch
+that comes before the @command{diff} output) which file to edit.
+@xref{Multiple Patches}.
+
+By default, @command{patch} replaces the original input file with the
+patched version, possibly after renaming the original file into a
+backup file (@pxref{Backup Names}, for a description of how
+@command{patch} names backup files). You can also specify where to
+put the output with the @option{-o @var{file}} or
+@option{--output=@var{file}} option; however, do not use this option
+if @var{file} is one of the input files.
+
+@menu
+* patch Options:: Summary table of options to @command{patch}.
+@end menu
+
+@node patch Options
+@section Options to @command{patch}
+@cindex @command{patch} options
+@cindex options for @command{patch}
+
+Here is a summary of all of the options that @sc{gnu} @command{patch}
+accepts. @xref{patch and Tradition}, for which of these options are
+safe to use in older versions of @command{patch}.
+
+Multiple single-letter options that do not take an argument can be
+combined into a single command line argument with only one dash.
+
+@table @option
+@item -b
+@itemx --backup
+Back up the original contents of each file, even if backups would
+normally not be made. @xref{Backups}.
+
+@item -B @var{prefix}
+@itemx --prefix=@var{prefix}
+Prepend @var{prefix} to backup file names. @xref{Backup Names}.
+
+@item --backup-if-mismatch
+Back up the original contents of each file if the patch does not
+exactly match the file. This is the default behavior when not
+conforming to @sc{posix}. @xref{Backups}.
+
+@item --binary
+Read and write all files in binary mode, except for standard output
+and @file{/dev/tty}. This option has no effect on
+@sc{posix}-conforming systems like @sc{gnu}/Linux. On systems where
+this option makes a difference, the patch should be generated by
+@samp{diff -a --binary}. @xref{Binary}.
+
+@item -c
+@itemx --context
+Interpret the patch file as a context diff. @xref{patch Input}.
+
+@item -d @var{directory}
+@itemx --directory=@var{directory}
+Make directory @var{directory} the current directory for interpreting
+both file names in the patch file, and file names given as arguments to
+other options. @xref{patch Directories}.
+
+@item -D @var{name}
+@itemx --ifdef=@var{name}
+Make merged if-then-else output using @var{name}. @xref{If-then-else}.
+
+@item --dry-run
+Print the results of applying the patches without actually changing
+any files. @xref{Dry Runs}.
+
+@item -e
+@itemx --ed
+Interpret the patch file as an @command{ed} script. @xref{patch Input}.
+
+@item -E
+@itemx --remove-empty-files
+Remove output files that are empty after the patches have been applied.
+@xref{Creating and Removing}.
+
+@item -f
+@itemx --force
+Assume that the user knows exactly what he or she is doing, and do not
+ask any questions. @xref{patch Messages}.
+
+@item -F @var{lines}
+@itemx --fuzz=@var{lines}
+Set the maximum fuzz factor to @var{lines}. @xref{Inexact}.
+
+@item -g @var{num}
+@itemx --get=@var{num}
+If @var{num} is positive, get input files from a revision control
+system as necessary; if zero, do not get the files; if negative, ask
+the user whether to get the files. @xref{Revision Control}.
+
+@item --help
+Output a summary of usage and then exit.
+
+@item -i @var{patchfile}
+@itemx --input=@var{patchfile}
+Read the patch from @var{patchfile} rather than from standard input.
+@xref{patch Options}.
+
+@item -l
+@itemx --ignore-white-space
+Let any sequence of blanks (spaces or tabs) in the patch file match
+any sequence of blanks in the input file. @xref{Changed White Space}.
+
+@item -n
+@itemx --normal
+Interpret the patch file as a normal diff. @xref{patch Input}.
+
+@item -N
+@itemx --forward
+Ignore patches that @command{patch} thinks are reversed or already applied.
+See also @option{-R}. @xref{Reversed Patches}.
+
+@item --no-backup-if-mismatch
+Do not back up the original contents of files. This is the default
+behavior when conforming to @sc{posix}. @xref{Backups}.
+
+@item -o @var{file}
+@itemx --output=@var{file}
+Use @var{file} as the output file name. @xref{patch Options}.
+
+@item -p@var{number}
+@itemx --strip=@var{number}
+Set the file name strip count to @var{number}. @xref{patch Directories}.
+
+@item --posix
+Conform to @sc{posix}, as if the @env{POSIXLY_CORRECT} environment
+variable had been set. @xref{patch and POSIX}.
+
+@item --quoting-style=@var{word}
+Use style @var{word} to quote names in diagnostics, as if the
+@env{QUOTING_STYLE} environment variable had been set to @var{word}.
+@xref{patch Quoting Style}.
+
+@item -r @var{reject-file}
+@itemx --reject-file=@var{reject-file}
+Use @var{reject-file} as the reject file name. @xref{Reject Names}.
+
+@item -R
+@itemx --reverse
+Assume that this patch was created with the old and new files swapped.
+@xref{Reversed Patches}.
+
+@item -s
+@itemx --quiet
+@itemx --silent
+Work silently unless an error occurs. @xref{patch Messages}.
+
+@item -t
+@itemx --batch
+Do not ask any questions. @xref{patch Messages}.
+
+@item -T
+@itemx --set-time
+Set the modification and access times of patched files from time
+stamps given in context diff headers, assuming that the context diff
+headers use local time. @xref{Patching Time Stamps}.
+
+@item -u
+@itemx --unified
+Interpret the patch file as a unified diff. @xref{patch Input}.
+
+@item -v
+@itemx --version
+Output version information and then exit.
+
+@item -V @var{backup-style}
+@itemx --version=control=@var{backup-style}
+Select the naming convention for backup file names. @xref{Backup Names}.
+
+@item --verbose
+Print more diagnostics than usual. @xref{patch Messages}.
+
+@item -x @var{number}
+@itemx --debug=@var{number}
+Set internal debugging flags. Of interest only to @command{patch}
+patchers.
+
+@item -Y @var{prefix}
+@itemx --basename-prefix=@var{prefix}
+Prepend @var{prefix} to base names of backup files. @xref{Backup Names}.
+
+@item -z @var{suffix}
+@itemx --suffix=@var{suffix}
+Use @var{suffix} as the backup extension instead of @samp{.orig} or
+@samp{~}. @xref{Backup Names}.
+
+@item -Z
+@itemx --set-utc
+Set the modification and access times of patched files from time
+stamps given in context diff headers, assuming that the context diff
+headers use @sc{utc}. @xref{Patching Time Stamps}.
+
+@end table
+
+@node Invoking sdiff
+@chapter Invoking @command{sdiff}
+@cindex invoking @command{sdiff}
+@cindex @command{sdiff} invocation
+
+The @command{sdiff} command merges two files and interactively outputs the
+results. Its arguments are as follows:
+
+@example
+sdiff -o @var{outfile} @var{options}@dots{} @var{from-file} @var{to-file}
+@end example
+
+This merges @var{from-file} with @var{to-file}, with output to @var{outfile}.
+If @var{from-file} is a directory and @var{to-file} is not, @command{sdiff}
+compares the file in @var{from-file} whose file name is that of @var{to-file},
+and vice versa. @var{from-file} and @var{to-file} may not both be
+directories.
+
+@command{sdiff} options begin with @samp{-}, so normally @var{from-file}
+and @var{to-file} may not begin with @samp{-}. However, @option{--} as an
+argument by itself treats the remaining arguments as file names even if
+they begin with @samp{-}. You may not use @file{-} as an input file.
+
+@command{sdiff} without @option{-o} (or @option{--output}) produces a
+side-by-side difference. This usage is obsolete; use the @option{-y}
+or @option{--side-by-side} option of @command{diff} instead.
+
+An exit status of 0 means no differences were found, 1 means some
+differences were found, and 2 means trouble.
+
+@menu
+* sdiff Options:: Summary of options to @command{diff}.
+@end menu
+
+@node sdiff Options
+@section Options to @command{sdiff}
+@cindex @command{sdiff} options
+@cindex options for @command{sdiff}
+
+Below is a summary of all of the options that @sc{gnu} @command{sdiff} accepts.
+Each option has two equivalent names, one of which is a single
+letter preceded by @samp{-}, and the other of which is a long name
+preceded by @samp{--}. Multiple single letter options (unless they take
+an argument) can be combined into a single command line argument. Long
+named options can be abbreviated to any unique prefix of their name.
+
+@table @option
+@item -a
+@itemx --text
+Treat all files as text and compare them line-by-line, even if they
+do not appear to be text. @xref{Binary}.
+
+@item -b
+@itemx --ignore-space-change
+Ignore changes in amount of white space. @xref{White Space}.
+
+@item -B
+@itemx --ignore-blank-lines
+Ignore changes that just insert or delete blank lines. @xref{Blank
+Lines}.
+
+@item -d
+@itemx --minimal
+Change the algorithm to perhaps find a smaller set of changes. This
+makes @command{sdiff} slower (sometimes much slower). @xref{diff
+Performance}.
+
+@item --diff-program=@var{program}
+Use the compatible comparison program @var{program} to compare files
+instead of @command{diff}.
+
+@item -E
+@itemx --ignore-tab-expansion
+Ignore changes due to tab expansion.
+@xref{White Space}.
+
+@item --help
+Output a summary of usage and then exit.
+
+@item -i
+@itemx --ignore-case
+Ignore changes in case; consider upper- and lower-case to be the same.
+@xref{Case Folding}.
+
+@item -I @var{regexp}
+@itemx --ignore-matching-lines=@var{regexp}
+Ignore changes that just insert or delete lines that match @var{regexp}.
+@xref{Specified Folding}.
+
+@item -l
+@itemx --left-column
+Print only the left column of two common lines.
+@xref{Side by Side Format}.
+
+@item -o @var{file}
+@itemx --output=@var{file}
+Put merged output into @var{file}. This option is required for merging.
+
+@item -s
+@itemx --suppress-common-lines
+Do not print common lines. @xref{Side by Side Format}.
+
+@item --speed-large-files
+Use heuristics to speed handling of large files that have numerous
+scattered small changes. @xref{diff Performance}.
+
+@item --strip-trailing-cr
+Strip any trailing carriage return at the end of an input line.
+@xref{Binary}.
+
+@item -t
+@itemx --expand-tabs
+Expand tabs to spaces in the output, to preserve the alignment of tabs
+in the input files. @xref{Tabs}.
+
+@item -v
+@itemx --version
+Output version information and then exit.
+
+@item -w @var{columns}
+@itemx --width=@var{columns}
+Output at most @var{columns} (default 130) print columns per line.
+@xref{Side by Side Format}. Note that for historical reasons, this
+option is @option{-W} in @command{diff}, @option{-w} in @command{sdiff}.
+
+@item -W
+@itemx --ignore-all-space
+Ignore white space when comparing lines. @xref{White Space}.
+Note that for historical reasons, this option is @option{-w} in @command{diff},
+@option{-W} in @command{sdiff}.
+@end table
+
+@node Standards conformance
+@chapter Standards conformance
+@cindex @sc{posix}
+
+@vindex POSIXLY_CORRECT
+In a few cases, the @sc{gnu} utilities' default behavior is
+incompatible with the @sc{posix} standard. To suppress these
+incompatibilities, define the @env{POSIXLY_CORRECT} environment
+variable. Unless you are checking for @sc{posix} conformance, you
+probably do not need to define @env{POSIXLY_CORRECT}.
+
+Normally options and operands can appear in any order, and programs act
+as if all the options appear before any operands. For example,
+@samp{diff lao tzu -C 2} acts like @samp{diff -C 2 lao tzu}, since
+@samp{2} is an option-argument of @option{-C}. However, if the
+@env{POSIXLY_CORRECT} environment variable is set, options must appear
+before operands, unless otherwise specified for a particular command.
+
+Newer versions of @sc{posix} are occasionally incompatible with older
+versions. For example, older versions of @sc{posix} allowed the
+command @samp{diff -c -10} to have the same meaning as @samp{diff -C
+10}, but @sc{posix} 1003.1-2001 @samp{diff} no longer allows
+digit-string options like @option{-10}.
+
+@vindex _POSIX2_VERSION
+The @sc{gnu} utilities normally conform to the version of @sc{posix}
+that is standard for your system. To cause them to conform to a
+different version of @sc{posix}, define the @env{_POSIX2_VERSION}
+environment variable to a value of the form @var{yyyymm} specifying
+the year and month the standard was adopted. Two values are currently
+supported for @env{_POSIX2_VERSION}: @samp{199209} stands for
+@sc{posix} 1003.2-1992, and @samp{200112} stands for @sc{posix}
+1003.1-2001. For example, if you are running older software that
+assumes an older version of @sc{posix} and uses @samp{diff -c -10},
+you can work around the compatibility problems by setting
+@samp{_POSIX2_VERSION=199209} in your environment.
+
+@node Projects
+@chapter Future Projects
+
+Here are some ideas for improving @sc{gnu} @command{diff} and
+@command{patch}. The @sc{gnu} project has identified some
+improvements as potential programming projects for volunteers. You
+can also help by reporting any bugs that you find.
+
+If you are a programmer and would like to contribute something to the
+@sc{gnu} project, please consider volunteering for one of these
+projects. If you are seriously contemplating work, please write to
+@email{gnu@@gnu.org} to coordinate with other volunteers.
+
+@menu
+* Shortcomings:: Suggested projects for improvements.
+* Bugs:: Reporting bugs.
+@end menu
+
+@node Shortcomings
+@section Suggested Projects for Improving @sc{gnu} @command{diff} and @command{patch}
+@cindex projects for directories
+
+One should be able to use @sc{gnu} @command{diff} to generate a patch from any
+pair of directory trees, and given the patch and a copy of one such
+tree, use @command{patch} to generate a faithful copy of the other.
+Unfortunately, some changes to directory trees cannot be expressed using
+current patch formats; also, @command{patch} does not handle some of the
+existing formats. These shortcomings motivate the following suggested
+projects.
+
+@menu
+* Internationalization:: Handling multibyte and varying-width characters.
+* Changing Structure:: Handling changes to the directory structure.
+* Special Files:: Handling symbolic links, device special files, etc.
+* Unusual File Names:: Handling file names that contain unusual characters.
+* Time Stamp Order:: Outputting diffs in time stamp order.
+* Ignoring Changes:: Ignoring certain changes while showing others.
+* Speedups:: Improving performance.
+@end menu
+
+@node Internationalization
+@subsection Handling Multibyte and Varying-Width Characters
+@cindex multibyte characters
+@cindex varying-width characters
+
+@command{diff}, @command{diff3} and @command{sdiff} treat each line of
+input as a string of unibyte characters. This can mishandle multibyte
+characters in some cases. For example, when asked to ignore spaces,
+@command{diff} does not properly ignore a multibyte space character.
+
+Also, @command{diff} currently assumes that each byte is one column
+wide, and this assumption is incorrect in some locales, e.g., locales
+that use UTF-8 encoding. This causes problems with the @option{-y} or
+@option{--side-by-side} option of @command{diff}.
+
+These problems need to be fixed without unduly affecting the
+performance of the utilities in unibyte environments.
+
+The IBM GNU/Linux Technology Center Internationalization Team has
+proposed some patches to support internationalized @command{diff}
+@uref{http://oss.software.ibm.com/developer/opensource/linux/patches/i18n/diffutils-2.7.2-i18n-0.1.patch.gz}.
+Unfortunately, these patches are incomplete and are to an older
+version of @command{diff}, so more work needs to be done in this area.
+
+@node Changing Structure
+@subsection Handling Changes to the Directory Structure
+@cindex directory structure changes
+
+@command{diff} and @command{patch} do not handle some changes to directory
+structure. For example, suppose one directory tree contains a directory
+named @samp{D} with some subsidiary files, and another contains a file
+with the same name @samp{D}. @samp{diff -r} does not output enough
+information for @command{patch} to transform the directory subtree into
+the file.
+
+There should be a way to specify that a file has been removed without
+having to include its entire contents in the patch file. There should
+also be a way to tell @command{patch} that a file was renamed, even if
+there is no way for @command{diff} to generate such information.
+There should be a way to tell @command{patch} that a file's time stamp
+has changed, even if its contents have not changed.
+
+These problems can be fixed by extending the @command{diff} output format
+to represent changes in directory structure, and extending @command{patch}
+to understand these extensions.
+
+@node Special Files
+@subsection Files that are Neither Directories Nor Regular Files
+@cindex special files
+
+Some files are neither directories nor regular files: they are unusual
+files like symbolic links, device special files, named pipes, and
+sockets. Currently, @command{diff} treats symbolic links like regular files;
+it treats other special files like regular files if they are specified
+at the top level, but simply reports their presence when comparing
+directories. This means that @command{patch} cannot represent changes
+to such files. For example, if you change which file a symbolic link
+points to, @command{diff} outputs the difference between the two files,
+instead of the change to the symbolic link.
+
+@c This might not be a good idea; is it wise for root to install devices
+@c this way?
+@command{diff} should optionally report changes to special files specially,
+and @command{patch} should be extended to understand these extensions.
+
+@node Unusual File Names
+@subsection File Names that Contain Unusual Characters
+@cindex file names with unusual characters
+
+When a file name contains an unusual character like a newline or
+white space, @samp{diff -r} generates a patch that @command{patch} cannot
+parse. The problem is with format of @command{diff} output, not just with
+@command{patch}, because with odd enough file names one can cause
+@command{diff} to generate a patch that is syntactically correct but
+patches the wrong files. The format of @command{diff} output should be
+extended to handle all possible file names.
+
+@node Time Stamp Order
+@subsection Outputting Diffs in Time Stamp Order
+
+Applying @command{patch} to a multiple-file diff can result in files
+whose time stamps are out of order. @sc{gnu} @command{patch} has
+options to restore the time stamps of the updated files
+(@pxref{Patching Time Stamps}), but sometimes it is useful to generate
+a patch that works even if the recipient does not have @sc{gnu} patch,
+or does not use these options. One way to do this would be to
+implement a @command{diff} option to output diffs in time stamp order.
+
+@node Ignoring Changes
+@subsection Ignoring Certain Changes
+
+It would be nice to have a feature for specifying two strings, one in
+@var{from-file} and one in @var{to-file}, which should be considered to
+match. Thus, if the two strings are @samp{foo} and @samp{bar}, then if
+two lines differ only in that @samp{foo} in file 1 corresponds to
+@samp{bar} in file 2, the lines are treated as identical.
+
+It is not clear how general this feature can or should be, or
+what syntax should be used for it.
+
+A partial substitute is to filter one or both files before comparing,
+e.g.:
+
+@example
+sed 's/foo/bar/g' file1 | diff - file2
+@end example
+
+However, this outputs the filtered text, not the original.
+
+@node Speedups
+@subsection Improving Performance
+
+When comparing two large directory structures, one of which was
+originally copied from the other with time stamps preserved (e.g.,
+with @samp{cp -pR}), it would greatly improve performance if an option
+told @command{diff} to assume that two files with the same size and
+time stamps have the same content. @xref{diff Performance}.
+
+@node Bugs
+@section Reporting Bugs
+@cindex bug reports
+@cindex reporting bugs
+
+If you think you have found a bug in @sc{gnu} @command{cmp},
+@command{diff}, @command{diff3}, or @command{sdiff}, please report it
+by electronic mail to the
+@uref{http://mail.gnu.org/mailman/listinfo/bug-gnu-utils,GNU utilities
+bug report mailing list} @email{bug-gnu-utils@@gnu.org}. Please send
+bug reports for @sc{gnu} @command{patch} to
+@email{bug-patch@@gnu.org}. Send as precise a description of the
+problem as you can, including the output of the @option{--version}
+option and sample input files that produce the bug, if applicable. If
+you have a nontrivial fix for the bug, please send it as well. If you
+have a patch, please send it too. It may simplify the maintainer's
+job if the patch is relative to a recent test release, which you can
+find in the directory @uref{ftp://alpha.gnu.org/gnu/diffutils/}.
+
+@node Copying This Manual
+@appendix Copying This Manual
+
+@menu
+* GNU Free Documentation License:: License for copying this manual.
+@end menu
+
+@include fdl.texi
+
+@node Index
+@appendix Index
+
+@printindex cp
+
+@bye
diff --git a/external/gpl2/diffutils/dist/doc/fdl.texi b/external/gpl2/diffutils/dist/doc/fdl.texi
new file mode 100644
index 00000000000..0c30df24036
--- /dev/null
+++ b/external/gpl2/diffutils/dist/doc/fdl.texi
@@ -0,0 +1,404 @@
+
+@c $NetBSD: fdl.texi,v 1.1.1.1 2016/01/13 03:15:29 christos Exp $
+@node GNU Free Documentation License
+@appendixsec GNU Free Documentation License
+
+@cindex FDL, GNU Free Documentation License
+@center Version 1.1, March 2000
+
+@display
+Copyright @copyright{} 2000 Free Software Foundation, Inc.
+59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+@end display
+
+@enumerate 0
+@item
+PREAMBLE
+
+The purpose of this License is to make a manual, textbook, or other
+written document @dfn{free} in the sense of freedom: to assure everyone
+the effective freedom to copy and redistribute it, with or without
+modifying it, either commercially or noncommercially. Secondarily,
+this License preserves for the author and publisher a way to get
+credit for their work, while not being considered responsible for
+modifications made by others.
+
+This License is a kind of ``copyleft'', which means that derivative
+works of the document must themselves be free in the same sense. It
+complements the GNU General Public License, which is a copyleft
+license designed for free software.
+
+We have designed this License in order to use it for manuals for free
+software, because free software needs free documentation: a free
+program should come with manuals providing the same freedoms that the
+software does. But this License is not limited to software manuals;
+it can be used for any textual work, regardless of subject matter or
+whether it is published as a printed book. We recommend this License
+principally for works whose purpose is instruction or reference.
+
+@item
+APPLICABILITY AND DEFINITIONS
+
+This License applies to any manual or other work that contains a
+notice placed by the copyright holder saying it can be distributed
+under the terms of this License. The ``Document'', below, refers to any
+such manual or work. Any member of the public is a licensee, and is
+addressed as ``you''.
+
+A ``Modified Version'' of the Document means any work containing the
+Document or a portion of it, either copied verbatim, or with
+modifications and/or translated into another language.
+
+A ``Secondary Section'' is a named appendix or a front-matter section of
+the Document that deals exclusively with the relationship of the
+publishers or authors of the Document to the Document's overall subject
+(or to related matters) and contains nothing that could fall directly
+within that overall subject. (For example, if the Document is in part a
+textbook of mathematics, a Secondary Section may not explain any
+mathematics.) The relationship could be a matter of historical
+connection with the subject or with related matters, or of legal,
+commercial, philosophical, ethical or political position regarding
+them.
+
+The ``Invariant Sections'' are certain Secondary Sections whose titles
+are designated, as being those of Invariant Sections, in the notice
+that says that the Document is released under this License.
+
+The ``Cover Texts'' are certain short passages of text that are listed,
+as Front-Cover Texts or Back-Cover Texts, in the notice that says that
+the Document is released under this License.
+
+A ``Transparent'' copy of the Document means a machine-readable copy,
+represented in a format whose specification is available to the
+general public, whose contents can be viewed and edited directly and
+straightforwardly with generic text editors or (for images composed of
+pixels) generic paint programs or (for drawings) some widely available
+drawing editor, and that is suitable for input to text formatters or
+for automatic translation to a variety of formats suitable for input
+to text formatters. A copy made in an otherwise Transparent file
+format whose markup has been designed to thwart or discourage
+subsequent modification by readers is not Transparent. A copy that is
+not ``Transparent'' is called ``Opaque''.
+
+Examples of suitable formats for Transparent copies include plain
+@sc{ascii} without markup, Texinfo input format, La@TeX{} input format,
+@acronym{SGML} or @acronym{XML} using a publicly available
+@acronym{DTD}, and standard-conforming simple @acronym{HTML} designed
+for human modification. Opaque formats include PostScript,
+@acronym{PDF}, proprietary formats that can be read and edited only by
+proprietary word processors, @acronym{SGML} or @acronym{XML} for which
+the @acronym{DTD} and/or processing tools are not generally available,
+and the machine-generated @acronym{HTML} produced by some word
+processors for output purposes only.
+
+The ``Title Page'' means, for a printed book, the title page itself,
+plus such following pages as are needed to hold, legibly, the material
+this License requires to appear in the title page. For works in
+formats which do not have any title page as such, ``Title Page'' means
+the text near the most prominent appearance of the work's title,
+preceding the beginning of the body of the text.
+
+@item
+VERBATIM COPYING
+
+You may copy and distribute the Document in any medium, either
+commercially or noncommercially, provided that this License, the
+copyright notices, and the license notice saying this License applies
+to the Document are reproduced in all copies, and that you add no other
+conditions whatsoever to those of this License. You may not use
+technical measures to obstruct or control the reading or further
+copying of the copies you make or distribute. However, you may accept
+compensation in exchange for copies. If you distribute a large enough
+number of copies you must also follow the conditions in section 3.
+
+You may also lend copies, under the same conditions stated above, and
+you may publicly display copies.
+
+@item
+COPYING IN QUANTITY
+
+If you publish printed copies of the Document numbering more than 100,
+and the Document's license notice requires Cover Texts, you must enclose
+the copies in covers that carry, clearly and legibly, all these Cover
+Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on
+the back cover. Both covers must also clearly and legibly identify
+you as the publisher of these copies. The front cover must present
+the full title with all words of the title equally prominent and
+visible. You may add other material on the covers in addition.
+Copying with changes limited to the covers, as long as they preserve
+the title of the Document and satisfy these conditions, can be treated
+as verbatim copying in other respects.
+
+If the required texts for either cover are too voluminous to fit
+legibly, you should put the first ones listed (as many as fit
+reasonably) on the actual cover, and continue the rest onto adjacent
+pages.
+
+If you publish or distribute Opaque copies of the Document numbering
+more than 100, you must either include a machine-readable Transparent
+copy along with each Opaque copy, or state in or with each Opaque copy
+a publicly-accessible computer-network location containing a complete
+Transparent copy of the Document, free of added material, which the
+general network-using public has access to download anonymously at no
+charge using public-standard network protocols. If you use the latter
+option, you must take reasonably prudent steps, when you begin
+distribution of Opaque copies in quantity, to ensure that this
+Transparent copy will remain thus accessible at the stated location
+until at least one year after the last time you distribute an Opaque
+copy (directly or through your agents or retailers) of that edition to
+the public.
+
+It is requested, but not required, that you contact the authors of the
+Document well before redistributing any large number of copies, to give
+them a chance to provide you with an updated version of the Document.
+
+@item
+MODIFICATIONS
+
+You may copy and distribute a Modified Version of the Document under
+the conditions of sections 2 and 3 above, provided that you release
+the Modified Version under precisely this License, with the Modified
+Version filling the role of the Document, thus licensing distribution
+and modification of the Modified Version to whoever possesses a copy
+of it. In addition, you must do these things in the Modified Version:
+
+@enumerate A
+@item
+Use in the Title Page (and on the covers, if any) a title distinct
+from that of the Document, and from those of previous versions
+(which should, if there were any, be listed in the History section
+of the Document). You may use the same title as a previous version
+if the original publisher of that version gives permission.
+
+@item
+List on the Title Page, as authors, one or more persons or entities
+responsible for authorship of the modifications in the Modified
+Version, together with at least five of the principal authors of the
+Document (all of its principal authors, if it has less than five).
+
+@item
+State on the Title page the name of the publisher of the
+Modified Version, as the publisher.
+
+@item
+Preserve all the copyright notices of the Document.
+
+@item
+Add an appropriate copyright notice for your modifications
+adjacent to the other copyright notices.
+
+@item
+Include, immediately after the copyright notices, a license notice
+giving the public permission to use the Modified Version under the
+terms of this License, in the form shown in the Addendum below.
+
+@item
+Preserve in that license notice the full lists of Invariant Sections
+and required Cover Texts given in the Document's license notice.
+
+@item
+Include an unaltered copy of this License.
+
+@item
+Preserve the section entitled ``History'', and its title, and add to
+it an item stating at least the title, year, new authors, and
+publisher of the Modified Version as given on the Title Page. If
+there is no section entitled ``History'' in the Document, create one
+stating the title, year, authors, and publisher of the Document as
+given on its Title Page, then add an item describing the Modified
+Version as stated in the previous sentence.
+
+@item
+Preserve the network location, if any, given in the Document for
+public access to a Transparent copy of the Document, and likewise
+the network locations given in the Document for previous versions
+it was based on. These may be placed in the ``History'' section.
+You may omit a network location for a work that was published at
+least four years before the Document itself, or if the original
+publisher of the version it refers to gives permission.
+
+@item
+In any section entitled ``Acknowledgments'' or ``Dedications'',
+preserve the section's title, and preserve in the section all the
+substance and tone of each of the contributor acknowledgments
+and/or dedications given therein.
+
+@item
+Preserve all the Invariant Sections of the Document,
+unaltered in their text and in their titles. Section numbers
+or the equivalent are not considered part of the section titles.
+
+@item
+Delete any section entitled ``Endorsements''. Such a section
+may not be included in the Modified Version.
+
+@item
+Do not retitle any existing section as ``Endorsements''
+or to conflict in title with any Invariant Section.
+@end enumerate
+
+If the Modified Version includes new front-matter sections or
+appendices that qualify as Secondary Sections and contain no material
+copied from the Document, you may at your option designate some or all
+of these sections as invariant. To do this, add their titles to the
+list of Invariant Sections in the Modified Version's license notice.
+These titles must be distinct from any other section titles.
+
+You may add a section entitled ``Endorsements'', provided it contains
+nothing but endorsements of your Modified Version by various
+parties---for example, statements of peer review or that the text has
+been approved by an organization as the authoritative definition of a
+standard.
+
+You may add a passage of up to five words as a Front-Cover Text, and a
+passage of up to 25 words as a Back-Cover Text, to the end of the list
+of Cover Texts in the Modified Version. Only one passage of
+Front-Cover Text and one of Back-Cover Text may be added by (or
+through arrangements made by) any one entity. If the Document already
+includes a cover text for the same cover, previously added by you or
+by arrangement made by the same entity you are acting on behalf of,
+you may not add another; but you may replace the old one, on explicit
+permission from the previous publisher that added the old one.
+
+The author(s) and publisher(s) of the Document do not by this License
+give permission to use their names for publicity for or to assert or
+imply endorsement of any Modified Version.
+
+@item
+COMBINING DOCUMENTS
+
+You may combine the Document with other documents released under this
+License, under the terms defined in section 4 above for modified
+versions, provided that you include in the combination all of the
+Invariant Sections of all of the original documents, unmodified, and
+list them all as Invariant Sections of your combined work in its
+license notice.
+
+The combined work need only contain one copy of this License, and
+multiple identical Invariant Sections may be replaced with a single
+copy. If there are multiple Invariant Sections with the same name but
+different contents, make the title of each such section unique by
+adding at the end of it, in parentheses, the name of the original
+author or publisher of that section if known, or else a unique number.
+Make the same adjustment to the section titles in the list of
+Invariant Sections in the license notice of the combined work.
+
+In the combination, you must combine any sections entitled ``History''
+in the various original documents, forming one section entitled
+``History''; likewise combine any sections entitled ``Acknowledgments'',
+and any sections entitled ``Dedications''. You must delete all sections
+entitled ``Endorsements.''
+
+@item
+COLLECTIONS OF DOCUMENTS
+
+You may make a collection consisting of the Document and other documents
+released under this License, and replace the individual copies of this
+License in the various documents with a single copy that is included in
+the collection, provided that you follow the rules of this License for
+verbatim copying of each of the documents in all other respects.
+
+You may extract a single document from such a collection, and distribute
+it individually under this License, provided you insert a copy of this
+License into the extracted document, and follow this License in all
+other respects regarding verbatim copying of that document.
+
+@item
+AGGREGATION WITH INDEPENDENT WORKS
+
+A compilation of the Document or its derivatives with other separate
+and independent documents or works, in or on a volume of a storage or
+distribution medium, does not as a whole count as a Modified Version
+of the Document, provided no compilation copyright is claimed for the
+compilation. Such a compilation is called an ``aggregate'', and this
+License does not apply to the other self-contained works thus compiled
+with the Document, on account of their being thus compiled, if they
+are not themselves derivative works of the Document.
+
+If the Cover Text requirement of section 3 is applicable to these
+copies of the Document, then if the Document is less than one quarter
+of the entire aggregate, the Document's Cover Texts may be placed on
+covers that surround only the Document within the aggregate.
+Otherwise they must appear on covers around the whole aggregate.
+
+@item
+TRANSLATION
+
+Translation is considered a kind of modification, so you may
+distribute translations of the Document under the terms of section 4.
+Replacing Invariant Sections with translations requires special
+permission from their copyright holders, but you may include
+translations of some or all Invariant Sections in addition to the
+original versions of these Invariant Sections. You may include a
+translation of this License provided that you also include the
+original English version of this License. In case of a disagreement
+between the translation and the original English version of this
+License, the original English version will prevail.
+
+@item
+TERMINATION
+
+You may not copy, modify, sublicense, or distribute the Document except
+as expressly provided for under this License. Any other attempt to
+copy, modify, sublicense or distribute the Document is void, and will
+automatically terminate your rights under this License. However,
+parties who have received copies, or rights, from you under this
+License will not have their licenses terminated so long as such
+parties remain in full compliance.
+
+@item
+FUTURE REVISIONS OF THIS LICENSE
+
+The Free Software Foundation may publish new, revised versions
+of the GNU Free Documentation License from time to time. Such new
+versions will be similar in spirit to the present version, but may
+differ in detail to address new problems or concerns. See
+@uref{http://www.gnu.org/copyleft/}.
+
+Each version of the License is given a distinguishing version number.
+If the Document specifies that a particular numbered version of this
+License ``or any later version'' applies to it, you have the option of
+following the terms and conditions either of that specified version or
+of any later version that has been published (not as a draft) by the
+Free Software Foundation. If the Document does not specify a version
+number of this License, you may choose any version ever published (not
+as a draft) by the Free Software Foundation.
+@end enumerate
+
+@page
+@appendixsubsec ADDENDUM: How to use this License for your documents
+
+To use this License in a document you have written, include a copy of
+the License in the document and put the following copyright and
+license notices just after the title page:
+
+@smallexample
+@group
+ Copyright (C) @var{year} @var{your name}.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.1
+ or any later version published by the Free Software Foundation;
+ with the Invariant Sections being @var{list their titles}, with the
+ Front-Cover Texts being @var{list}, and with the Back-Cover Texts being @var{list}.
+ A copy of the license is included in the section entitled ``GNU
+ Free Documentation License''.
+@end group
+@end smallexample
+
+If you have no Invariant Sections, write ``with no Invariant Sections''
+instead of saying which ones are invariant. If you have no
+Front-Cover Texts, write ``no Front-Cover Texts'' instead of
+``Front-Cover Texts being @var{list}''; likewise for Back-Cover Texts.
+
+If your document contains nontrivial examples of program code, we
+recommend releasing these examples in parallel under your choice of
+free software license, such as the GNU General Public License,
+to permit their use in free software.
+
+@c Local Variables:
+@c ispell-local-pdict: "ispell-dict"
+@c End:
+
diff --git a/external/gpl2/diffutils/dist/doc/stamp-vti b/external/gpl2/diffutils/dist/doc/stamp-vti
new file mode 100644
index 00000000000..5e7a10cf720
--- /dev/null
+++ b/external/gpl2/diffutils/dist/doc/stamp-vti
@@ -0,0 +1,4 @@
+@set UPDATED 5 April 2002
+@set UPDATED-MONTH April 2002
+@set EDITION 2.8.1
+@set VERSION 2.8.1
diff --git a/external/gpl2/diffutils/dist/doc/version.texi b/external/gpl2/diffutils/dist/doc/version.texi
new file mode 100644
index 00000000000..430bceb5ba7
--- /dev/null
+++ b/external/gpl2/diffutils/dist/doc/version.texi
@@ -0,0 +1,5 @@
+@set UPDATED 5 April 2002
+@c $NetBSD: version.texi,v 1.1.1.1 2016/01/13 03:15:29 christos Exp $
+@set UPDATED-MONTH April 2002
+@set EDITION 2.8.1
+@set VERSION 2.8.1