Ubuntu Manpage: wiggle - apply rejected patches and perform word-wise diffs

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 target 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 possible.

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 in a similar way to the merge(1) program with the -A option. Each
annotation contains 3 components: 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 characters, 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, EXTRACT, and BROWSE.

-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.

-B, --browse
Select the "browse" function. This is similar to "merge" only with a different
presentation. Instead of the result simply being sent to standard output, it is
presented using an ncurses-based GUI so that each hunk of the patch can be examined
to understand what conflicts where involved and what needed to be ignored in order
of the patch to be wiggled in to place.

-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). In merge or browse mode, -p requires there be exactly one file which
is a patch and which can contain patches to multiple file. The patches are merged
into each file. When used in merge mode, this usage requires the --replace option
as writing lots of merged files to standard-out is impractical.

When processing a multi-file patch, B -p can be followed by a numeric argument
indicating how many file name components should be stripped from files named in the
patch file. If no numeric argument is given, wiggle will deduce an appropriate
number based what files are visible.

-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 will 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.

-W, --show-wiggle
When used with --merge, conflicts that can be wiggled into place are reported as
conflicts with an extra stanza which shows what the result would be if this flag
had not been used. The extra stanza is introduce with a line containing 7
ampersand (&) characters thus:
<<<<<<<
Some portion of the original file
|||||||
text to replace
=======
text to replace it with
&&&&&&&
Text that would result from a successful wiggle
>>>>>>>

-h, --help
Print a simple help message. If given after one of the function selectors
(--merge, --diff, --extract) help specific to that function 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 characters, 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 focuses on which words have changed so as to maximise the possibility of
finding a good match in the given text for the context of a given change. However it can
consider only whole lines instead.

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 and the -p option is not present, the file 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.

If one file is given together with the -p option, the file is treated as a patch file
containing the names of the files that it patches. In this case multiple merge operations
can happen and each takes one stream from a file named in the patch, and the other to from
the patch itself. The --replace option is required and the results are written back to
the target files.

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 uses 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 possibility 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 extension 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 way
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.

BROWSE
The browse function of wiggle presents the result of a merge in a text-based GUI that can
be navigated using keystrokes similar to vi(1) or emacs(1).

The browser allow each of the three streams to be viewed individually with colours used to
highlight different sorts of text - green for added text, red for deleted text etc. It
can also show the patch by itself, the full result of the merge, or the merge and the
patch side-by-side.

The browser provides a number of context-sensitive help pages which can be accessed by
typing '?'

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.

          wiggle --browse --patch update.patch
       Parse the update.patch file for patches and present a list of patched files which  can  be
       browsed to examine each patch in detail.

QUOTE

       The  name of wiggle was inspired by the following quote.  However wiggle does not yet help
       you to wiggle a patch into place.  It either does the wiggle itself, or leave it  for  you
       to finish off.

       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; and later and SUSE, still in Sydney, Australia.