WIGGLE(1)						      General Commands Manual							 WIGGLE(1)

NAME

       wiggle - apply rejected patches and perform word-wise diffs

SYNOPSIS

       wiggle [function] [options] file [files]

DESCRIPTION

       The main function of wiggle is to apply a patch to a file in a similar manner to the patch(1) program.

       The distinctive difference of wiggle is that it will attempt to apply a patch even if the "before" part of the patch doesn't match the tar-
       get file perfectly.  This is achieved by breaking the file and patch into words and finding the best alignment of words in  the	file  with
       words in the patch.  Once this alignment has been found, any differences (word-wise) in the patch are applied to the file as best as possi-
       ble.

       Also, wiggle will (in some cases) detect changes that have already been applied, and will ignore them.

       wiggle ensures that every change in the patch is applied to the target file somehow.  If a particular change cannot be made  in	the  file,
       the  file is annotated to show where the change should be made is a similar way to the merge(1) program.  Each annotation contains 3 compo-
       nents: a portion of the original file where the change should be applied, a portion of the patch that couldn't be matched precisely in  the
       file,  and  the	text that should replace that portion of the patch.  These are separated by lines containing precisely 7 identical charac-
       ters, either '<', '|', '=', or '>', so
	    <<<<<<<
	    Some portion of the original file
	    |||||||
	    text to replace
	    =======
	    text to replace it with
	    >>>>>>>

       indicates that "text to replace" should be replaced by "text to replace it with" somewhere in the portion of the  original  file.   However
       wiggle was not able to find a place to make this change.

       wiggle can also produce conflict reports showing only the words that are involved rather than showing whole lines.  In this case the output
       looks like:
	    <<<---original|||old===new--->>>

       A typical usage of wiggle is to run patch to apply some patch, and to collect a list of rejects	by  monitoring	the  error  messages  from
       patch.  Then for each file for which a reject was found, run
	    wiggle --replace originalfile originalfile.rej

       Finally each file must be examined to resolve any unresolved conflicts, and to make sure the applied patch is semantically correct.

   OPTIONS
       The  following  options are understood by wiggle.  Some of these are explained in more detail in the following sections on MERGE, DIFF, and
       EXTRACT.

       -m, --merge
	      Select the "merge" function.  This is the default function.

       -d, --diff
	      Select the "diff" function.  This displays the differences between files.

       -x, --extract
	      Select the "extract" function.  This extracts one branch of a patch or merge file.

       -w, --words
	      Request that all operations and display be word based.  This is the default for the "diff" function.

       -l, --lines
	      Request that all operations and display be line based.

       -p, --patch
	      Treat the last named file as a patch instead of a file (with --diff) or a merge (--extract).

       -r, --replace
	      Normally the merged output is written to standard-output.  With --replace, the original file is replaced with the merge output.

       -R, --reverse
	      When used with the "diff" function, swap the files before calculating the differences.  When used with the "merge" function,  wiggle
	      attempts to revert changes rather than apply them.

       -i, --no-ignore
	      Normally	wiggle	with  ignore changes in the patch which appear to already have been applied in the original.  With this flag those
	      changes are reported as conflicts rather than being ignored.

       -h, --help
	      Print a simple help message.  If given after one of the function selectors (--merge, --diff, --extract) help specific to that  func-
	      tion is displayed.

       -V, --version
	      Display the version number of wiggle.

       -v, --verbose
	      Enable verbose mode.  Currently this makes no difference.

       -q, --quiet
	      Enable quiet mode.  This suppresses the message from the merge function when there are unresolvable conflicts.

   WORDS
       wiggle  can divide a text into lines or words when performing it's tasks.  A line is simply a string of characters terminated by a newline.
       A word is either a maximal contiguous string of alphanumerics (including underscore), a maximal contiguous string of space or  tab  charac-
       ters, or any other single character.

   MERGE
       The merge function modifies a given text by finding all changes between two other texts and imposing those changes on the given text.

       Normally wiggle considers words which have changed so as to maximise the possibility of finding a good match in the given text for the con-
       text of a given change.	However it can consider only whole lines.

       wiggle extracts the three texts that it needs from files listed on the command line.  Either 1, 2, or 3 files may be listed, and any one of
       them may be a lone hyphen signifying standard-input.

       If  one	file  is  given,  it is treated as a merge file, i.e. the output of "merge -A" or "wiggle".  Such a file implicitly contains three
       streams and these are extracted and compared.

       If two files are given, then the first simply contains the primary text, and the second is treated as a patch file (the output of "diff -u"
       or "diff -c", or a ".rej" file from patch) and the two other texts are extracted from that.

       Finally if three files are listed, they are taken to contain the given text and the two other texts, in order.

       Normally  the  result of the merge is written to standard-output.  However if the "-r" flag is given, the output is written to a file which
       replaces the original given file. In this case the original file is renamed to have a .porig suffix (for  "patched  original"  which  makes
       sense if you first use patch to apply a patch, and then use wiggle to wiggle the rejects in).

       If  no  errors  occur (such as file access errors) wiggle will exit with a status of 0 if all changes were successfully merged, and with an
       exit status of 1 and a brief message if any changes could not be fully merged and were instead inserted as annotations.

       The merge function can operate in three different modes with respect to lines or words.

       With the --lines option, whole lines are compared and any conflicts are reported as whole lines that need to be replaced.

       With the --words option, individual words are compared and any conflicts are reported just covering the	words  affected.   This  used  the
       <<<|||===>>>  conflict format.

       Without	either	of  these options, a hybrid approach is taken.	Individual words are compared and merged, but when a conflict is found the
       whole surrounding line is reported as being in conflict.

       wiggle will ensure that every change between the two other texts is reflected in the result of the merge somehow.  There are four different
       ways that a change can be reflected.

       1      If  a change converts A to B and A is found at a suitable place in the original file, it is replaced with B.  This includes the pos-
	      sibility that B is empty, but not that A is empty.

       2      If a change is found which simply adds B and the text immediately preceding and following the insertion are found  adjacent  in  the
	      original file in a suitable place, then B is inserted between those adjacent texts.

       3      If  a  change  is found which changes A to B and this appears (based on context) to align with B in the original, then it is assumed
	      that this change has already been applied, and the change is ignored.  When this happens, a message reflected the number of  ignored
	      changes is printed by wiggle.  This optimisation can be suppressed with the -i flag.

       4      If a change is found that does not fit any of the above possibilities, then a conflict is reported as described earlier.

   DIFF
       The  diff  function  is	provided primarily to allow inspection of the alignments that wiggle calculated between texts and that it uses for
       performing a merge.

       The output of the diff function is similar to the unified output of diff.  However while diff does not  output  long  stretches	of  common
       text, wiggle's diff mode outputs everything.

       When  calculating a word-based alignment (the default), wiggle may need to show these word-based differences.  This is done using an exten-
       sion to the unified-diff format.  If a line starts with a vertical bar, then it may contain sections surrounded by special  multi-character
       brackets.  The brackets "<<<++" and "++>>>" surround added text while "<<<--" and "-->>>" surround removed text.

       wiggle can be given the two texts to compare in one of three ways.

       If  only  one file is given, then it is treated as a patch and the two branches of that diff are compared.  This effectively allows a patch
       to be refined from a line-based patch to a word-based patch.

       If two files are given, then they are normally assumed to be simple texts to be compared.

       If two files are given along with the --patch option, then the second file is assumed to be a patch and either the first (with -1)  or  the
       second (with -2) branch is extracted and compared with text found in the first file.

       This  last  option  causes  wiggle to apply a "best-fit" algorithm for aligning patch hunks with the file before computing the differences.
       This algorithm is used when merging a patch with a file, and its value can be seen by comparing the difference produced this was  with  the
       difference  produced  by  first	extracting one branch of a patch into a file, and then computing the difference of that file with the main
       file.

   EXTRACT
       The extract function of wiggle simply exposes the internal functionality for extracting one branch of a patch or a merge file.

       Precisely one file should be given, and it will be assumed to be a merge file unless --patch is given, in which case a patch is assumed.

       The choice of branch in made by providing one of -1, -2, or -3 with obvious meanings.

WARNING

       Caution should always be exercised when applying a rejected patch with wiggle.  When patch rejects a patch, it does so for a  good  reason.
       Even though wiggle may be able to find a believable place to apply each textual change, there is no guarantee that the result is correct in
       any semantic sense.  The result should always be inspected to make sure it is correct.

EXAMPLES

	 wiggle --replace file file.rej
       This is the normal usage of wiggle and will take any changes in file.rej that patch could not apply, and merge them into file.

	 wiggle -dp1 file file.rej
       This will perform a word-wise comparison between the file and the before branch of the diff in file.rej and display the differences.   This
       allows you to see where a given patch would apply.

	  wiggle --merge --help
       Get help about the merge function of wiggle.

QUOTE

       The name of wiggle was inspired by the following quote, even though wiggle does not (yet) have a graphical interface.

       The problem I find is that I often want to take
	 (file1+patch) -> file2,
       when I don't have file1.  But merge tools want to take
	 (file1|file2) -> file3.
       I haven't seen a graphical tool which helps you to wiggle a patch
       into a file.

       -- Andrew Morton - 2002

SHORTCOMINGS

       -      wiggle cannot read the extended unified-diff output that it produces for --diff --words.

       -      wiggle cannot read the word-based merge format that it produces for --merge --words.

AUTHOR

       Neil Brown at Computer Science and Engineering at The University of New South Wales, Sydney, Australia

SEE ALSO

       patch(1), diff(1), merge(1), wdiff(1), diff3(1).

v0.8																	 WIGGLE(1)