WIGGLE(1)WIGGLE(1)NAMEwiggle - apply rejected patches and perform word-wise diffs
SYNOPSISwiggle [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 con‐
tains 3 components: a portion of the original file where the change
should be applied, a portion of the patch that couldn't be matched pre‐
cisely in the file, and the text that should replace that portion of
the patch. These are separated by lines containing precisely 7 identi‐
cal characters, either '<', '|', '=', or '>', possibly followed by a
descriptive word. So
<<<<<<< found
Some portion of the original file
||||||| expected
text to replace
=======
text to replace it with
>>>>>>> replacement
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--->>>
One possible 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.
Alternately, the original patch file can be fed to the browse mode as
wiggle-B < patchfile
This will allow the changes and conflicts to be inspected and, to some
extent, modified; and then the results can be saved.
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. This can be given after --browse (see below) in
which case a patch or diff of two files can be viewed without
the originals.
-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" (or
"diff") 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.
-b, --ignore-blanks
De-emphasise white space (space, tab, and newline) is determin‐
ing differences and changes.
Normally white space is treated like a word which can be matched
or changed by a patch. When this flag is in force, white space
serves only as a separator between other words and is not
matched itself. The effect of this is that changes in the
amount of white space are not treated as significant.
To be precise, any white space is combined with the preceeding
word or, in the case of leading space on a line, with the fol‐
lowing word. However it is not involved in any comparisons of
that word. If a patch deletes a word, the attached white space
is deleted as well. If a patch adds a word, the attached white
space is added as well.
An empty line, or one that contains only blanks, will be treated
as a single word that will match any other blank line, no matter
how many spaces it has.
-b has no effect in --line mode.
-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 files. 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 stan‐
dard-out is impractical.
When processing a multi-file patch, -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 present in the filesystem.
-r, --replace
Normally the merged output is written to standard-output. With
--replace, the original file is replaced with the merge output.
In browse mode, this instructs wiggle to always save the result‐
ing merge when exiting.
-o, --output=
Rather than writing the result to stdout or to replace the orig‐
inal file, this requests that the output be written to the given
file. This is only meaningful with --merge or --browse when
given a single merge to browse.
This option overrides -r.
-R, --reverse
When used with the diff function, swap the files before calcu‐
lating the differences. When used with the merge or browse
functions, 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-wiggles
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 (&) char‐
acters thus:
<<<<<<< found
Some portion of the original file
||||||| expected
text to replace
=======
text to replace it with
&&&&&&& resolution
Text that would result from a successful wiggle
>>>>>>> replacement
--report-wiggles
If a merge is successful in applying all changes, it will nor‐
mally exit with a success status (0), only reporting failure (1)
if a conflict occurred and was annotated. With --report-wiggles
wiggle will also report failure if any changes had to be wiggled
in. This can be useful when wiggle is used for automatic merges
as with git. If any wiggles happen, git will report the fail‐
ure, and the results can be examined to confirm they are accept‐
able.
-h, --help
Print a simple help message. If given after one of the function
selectors (--merge, --diff, --extract, --browse) 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 new‐
line. 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 con‐
text 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 two 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. 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).
Further if the -o option is given with a file name, the output will be
written to that file. In this case no backup is created.
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. However if either
--report-wiggles or --show-wiggles options were given, wiggle will also
exist with status of 1 if any changes had to be wiggled in even though
this was successful.
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 con‐
flicts are reported just covering the words affected. This uses the
<<<|||===>>> conflict format.
Without either of these options, a hybrid approach is taken. Individ‐
ual 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 immedi‐
ately 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 reflecting the
number of ignored changes is printed by wiggle. This optimisa‐
tion can be suppressed with the -i flag.
4 If a change is found that does not fit any of the above possi‐
bilities, 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 patch 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 dif‐
ference 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 functional‐
ity 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 or (with
-d) a diff in a text-based GUI that can be navigated using keystrokes
similar to vi(1) or emacs(1).
The browser allows each of the two or three streams to be viewed indi‐
vidually 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 '?'
The top right of the GUI will report the type of text under the cursor,
which is also indicated by the colour of the text. Options are
Unchanged, Changed, Unmatched, Extraneous, AlreadyApplied and Conflict.
If the meanings of these are clear a little experimentations should
help.
A limited amount of editing is permitted while in browse mode. Cur‐
rently text that is unwanted can be discarded with x. This will con‐
vert a Conflict or Change to Unchanged, and an Unmatched to Changed
(which effectively changes it to the empty string). Similarly a text
can be marked as wanted with c. This will convert a Conflict or Extra‐
neous to Changed. Using the same key again will revert the change.
Finally, the uppercase X will revert all changes on the current line.
To make more sweeping changes you can use v which runs an editor, pre‐
ferring $VISUAL or $EDITOR if they are set in the environment.
If you make any changes, then wiggle will ask you if you want to save
the changes, even if --replace was not given.
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.
EXAMPLESwiggle--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.
wiggle can be integrated with git so that it is used as the default
merge tool and diff tool. This can be achieved by adding the following
lines to .gitconfig in the user's home directory.
[merge "wiggle"]
name = "Wiggle flexible merging"
driver = wiggle-o %A %A %O %B
recursive = binary
[merge]
tool = wiggle
[mergetool "wiggle"]
cmd = wiggle-B -o $MERGED $LOCAL $BASE $REMOTE
[difftool "wiggle"]
cmd = wiggle-Bd $LOCAL $REMOTE
This will make git mergetool and git difftool use wiggle.
If you want git to always use wiggle for merges (which may be danger‐
ous), you can add
* merge=wiggle
to an appropriate gitattributes file such as $HOME/.con‐
fig/git/attributes.
QUOTE
The name of wiggle was inspired by the following quote.
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 pro‐
duces for --diff --words.
- wiggle cannot read the word-based merge format that it produces
for --merge --words.
- wiggle does not understand unicode and so will treat all non-
ASCII characters much the same as it treats punctuation - it
will treat each one as a separate word. The browser will not
display non-ASCII characters properly.
AUTHOR
Neil Brown at Computer Science and Engineering at The University of New
South Wales, Sydney, Australia; and later at SUSE, still in Sydney,
Australia.
SEE ALSOpatch(1), diff(1), merge(1), wdiff(1), diff3(1), git-config(1), gitat‐
tributes(5).
v1.0WIGGLE(1)
