diff options
| author | christos <christos@NetBSD.org> | 2016-01-13 03:41:44 +0000 |
|---|---|---|
| committer | christos <christos@NetBSD.org> | 2016-01-13 03:41:44 +0000 |
| commit | beeb86fbf335bbe73b0ecee826d3435e55f61cf9 (patch) | |
| tree | 1fd7af3dffec9798776995b398b381a8a4fc71a8 /gnu/dist/diffutils/doc | |
| parent | e24eccea776de5d0b3032898b8329fd07f09d4ce (diff) | |
diffutils has moved
Diffstat (limited to 'gnu/dist/diffutils/doc')
| -rw-r--r-- | gnu/dist/diffutils/doc/Makefile.am | 24 | ||||
| -rw-r--r-- | gnu/dist/diffutils/doc/Makefile.in | 359 | ||||
| -rw-r--r-- | gnu/dist/diffutils/doc/diagmeet.note | 71 | ||||
| -rw-r--r-- | gnu/dist/diffutils/doc/diff.info | 5084 | ||||
| -rw-r--r-- | gnu/dist/diffutils/doc/diff.texi | 4557 | ||||
| -rw-r--r-- | gnu/dist/diffutils/doc/fdl.texi | 404 | ||||
| -rw-r--r-- | gnu/dist/diffutils/doc/stamp-vti | 4 | ||||
| -rw-r--r-- | gnu/dist/diffutils/doc/version.texi | 5 |
8 files changed, 0 insertions, 10508 deletions
diff --git a/gnu/dist/diffutils/doc/Makefile.am b/gnu/dist/diffutils/doc/Makefile.am deleted file mode 100644 index 574fdab8705..00000000000 --- a/gnu/dist/diffutils/doc/Makefile.am +++ /dev/null @@ -1,24 +0,0 @@ -# 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/gnu/dist/diffutils/doc/Makefile.in b/gnu/dist/diffutils/doc/Makefile.in deleted file mode 100644 index 408013d8e2b..00000000000 --- a/gnu/dist/diffutils/doc/Makefile.in +++ /dev/null @@ -1,359 +0,0 @@ -# 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/gnu/dist/diffutils/doc/diagmeet.note b/gnu/dist/diffutils/doc/diagmeet.note deleted file mode 100644 index 8f7242c7356..00000000000 --- a/gnu/dist/diffutils/doc/diagmeet.note +++ /dev/null @@ -1,71 +0,0 @@ -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/gnu/dist/diffutils/doc/diff.info b/gnu/dist/diffutils/doc/diff.info deleted file mode 100644 index d58accf7ea9..00000000000 --- a/gnu/dist/diffutils/doc/diff.info +++ /dev/null @@ -1,5084 +0,0 @@ -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/gnu/dist/diffutils/doc/diff.texi b/gnu/dist/diffutils/doc/diff.texi deleted file mode 100644 index d4e952a4923..00000000000 --- a/gnu/dist/diffutils/doc/diff.texi +++ /dev/null @@ -1,4557 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c $NetBSD: diff.texi,v 1.2 2003/01/26 00:48:01 wiz Exp $ -@comment $Id: diff.texi,v 1.2 2003/01/26 00:48:01 wiz Exp $ -@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/gnu/dist/diffutils/doc/fdl.texi b/gnu/dist/diffutils/doc/fdl.texi deleted file mode 100644 index d61c8e3c421..00000000000 --- a/gnu/dist/diffutils/doc/fdl.texi +++ /dev/null @@ -1,404 +0,0 @@ - -@c $NetBSD: fdl.texi,v 1.1.1.1 2003/01/26 00:43:12 wiz 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/gnu/dist/diffutils/doc/stamp-vti b/gnu/dist/diffutils/doc/stamp-vti deleted file mode 100644 index 5e7a10cf720..00000000000 --- a/gnu/dist/diffutils/doc/stamp-vti +++ /dev/null @@ -1,4 +0,0 @@ -@set UPDATED 5 April 2002 -@set UPDATED-MONTH April 2002 -@set EDITION 2.8.1 -@set VERSION 2.8.1 diff --git a/gnu/dist/diffutils/doc/version.texi b/gnu/dist/diffutils/doc/version.texi deleted file mode 100644 index 932d050a976..00000000000 --- a/gnu/dist/diffutils/doc/version.texi +++ /dev/null @@ -1,5 +0,0 @@ -@set UPDATED 5 April 2002 -@c $NetBSD: version.texi,v 1.1.1.1 2003/01/26 00:43:12 wiz Exp $ -@set UPDATED-MONTH April 2002 -@set EDITION 2.8.1 -@set VERSION 2.8.1 |
