1WIGGLE(1) General Commands Manual WIGGLE(1)
2
6 wiggle - apply rejected patches and perform word-wise diffs
7
10 wiggle [function] [options] file [files]
11
14 The main function of wiggle is to apply a patch to a file in a similar
15 manner to the patch(1) program.
16 The distinctive difference of wiggle is that it will attempt to apply a
18 patch even if the "before" part of the patch doesn't match the target
19 file perfectly. This is achieved by breaking the file and patch into
20 words and finding the best alignment of words in the file with words in
21 the patch. Once this alignment has been found, any differences (word-
22 wise) in the patch are applied to the file as best as possible.
23 Also, wiggle will (in some cases) detect changes that have already been
25 applied, and will ignore them.
26 wiggle ensures that every change in the patch is applied to the target
28 file somehow. If a particular change cannot be made in the file, the
29 file is annotated to show where the change should be made is a similar
30 way to the merge(1) program. Each annotation contains 3 components: a
31 portion of the original file where the change should be applied, a por‐
32 tion of the patch that couldn't be matched precisely in the file, and
33 the text that should replace that portion of the patch. These are sep‐
34 arated by lines containing precisely 7 identical characters, either
35 '<', '|', '=', or '>', so
36 <<<<<<<
37 Some portion of the original file
38 |||||||
39 text to replace
40 =======
41 text to replace it with
42 >>>>>>>
43 indicates that "text to replace" should be replaced by "text to replace
45 it with" somewhere in the portion of the original file. However wiggle
46 was not able to find a place to make this change.
47 wiggle can also produce conflict reports showing only the words that
49 are involved rather than showing whole lines. In this case the output
50 looks like:
51 <<<---original|||old===new--->>>
52 A typical usage of wiggle is to run patch to apply some patch, and to
54 collect a list of rejects by monitoring the error messages from patch.
55 Then for each file for which a reject was found, run
56 wiggle --replace originalfile originalfile.rej
57 Finally each file must be examined to resolve any unresolved conflicts,
59 and to make sure the applied patch is semantically correct.
60 OPTIONS
63 The following options are understood by wiggle. Some of these are
64 explained in more detail in the following sections on MERGE, DIFF, and
65 EXTRACT.
66 -m, --merge
69 Select the "merge" function. This is the default function.
70 -d, --diff
73 Select the "diff" function. This displays the differences
74 between files.
75 -x, --extract
78 Select the "extract" function. This extracts one branch of a
79 patch or merge file.
80 -w, --words
83 Request that all operations and display be word based. This is
84 the default for the "diff" function.
85 -l, --lines
88 Request that all operations and display be line based.
89 -p, --patch
92 Treat the last named file as a patch instead of a file (with
93 --diff) or a merge (--extract).
94 -r, --replace
97 Normally the merged output is written to standard-output. With
98 --replace, the original file is replaced with the merge output.
99 -R, --reverse
102 When used with the "diff" function, swap the files before calcu‐
103 lating the differences. When used with the "merge" function,
104 wiggle attempts to revert changes rather than apply them.
105 -i, --no-ignore
108 Normally wiggle with ignore changes in the patch which appear to
109 already have been applied in the original. With this flag those
110 changes are reported as conflicts rather than being ignored.
111 -h, --help
114 Print a simple help message. If given after one of the function
115 selectors (--merge, --diff, --extract) help specific to that
116 function is displayed.
117 -V, --version
120 Display the version number of wiggle.
121 -v, --verbose
124 Enable verbose mode. Currently this makes no difference.
125 -q, --quiet
128 Enable quiet mode. This suppresses the message from the merge
129 function when there are unresolvable conflicts.
130 WORDS
133 wiggle can divide a text into lines or words when performing it's
134 tasks. A line is simply a string of characters terminated by a new‐
135 line. A word is either a maximal contiguous string of alphanumerics
136 (including underscore), a maximal contiguous string of space or tab
137 characters, or any other single character.
138 MERGE
141 The merge function modifies a given text by finding all changes between
142 two other texts and imposing those changes on the given text.
143 Normally wiggle considers words which have changed so as to maximise
145 the possibility of finding a good match in the given text for the con‐
146 text of a given change. However it can consider only whole lines.
147 wiggle extracts the three texts that it needs from files listed on the
149 command line. Either 1, 2, or 3 files may be listed, and any one of
150 them may be a lone hyphen signifying standard-input.
151 If one file is given, it is treated as a merge file, i.e. the output of
153 "merge -A" or "wiggle". Such a file implicitly contains three streams
154 and these are extracted and compared.
155 If two files are given, then the first simply contains the primary
157 text, and the second is treated as a patch file (the output of
158 "diff -u" or "diff -c", or a ".rej" file from patch) and the two other
159 texts are extracted from that.
160 Finally if three files are listed, they are taken to contain the given
162 text and the two other texts, in order.
163 Normally the result of the merge is written to standard-output. How‐
165 ever if the "-r" flag is given, the output is written to a file which
166 replaces the original given file. In this case the original file is
167 renamed to have a .porig suffix (for "patched original" which makes
168 sense if you first use patch to apply a patch, and then use wiggle to
169 wiggle the rejects in).
170 If no errors occur (such as file access errors) wiggle will exit with a
172 status of 0 if all changes were successfully merged, and with an exit
173 status of 1 and a brief message if any changes could not be fully
174 merged and were instead inserted as annotations.
175 The merge function can operate in three different modes with respect to
177 lines or words.
178 With the --lines option, whole lines are compared and any conflicts are
180 reported as whole lines that need to be replaced.
181 With the --words option, individual words are compared and any con‐
183 flicts are reported just covering the words affected. This used the
184 <<<|||===>>> conflict format.
185 Without either of these options, a hybrid approach is taken. Individ‐
187 ual words are compared and merged, but when a conflict is found the
188 whole surrounding line is reported as being in conflict.
189 wiggle will ensure that every change between the two other texts is
191 reflected in the result of the merge somehow. There are four different
192 ways that a change can be reflected.
193 1 If a change converts A to B and A is found at a suitable place
195 in the original file, it is replaced with B. This includes the
196 possibility that B is empty, but not that A is empty.
197 2 If a change is found which simply adds B and the text immedi‐
200 ately preceding and following the insertion are found adjacent
201 in the original file in a suitable place, then B is inserted
202 between those adjacent texts.
203 3 If a change is found which changes A to B and this appears
206 (based on context) to align with B in the original, then it is
207 assumed that this change has already been applied, and the
208 change is ignored. When this happens, a message reflected the
209 number of ignored changes is printed by wiggle. This optimisa‐
210 tion can be suppressed with the -i flag.
211 4 If a change is found that does not fit any of the above possi‐
214 bilities, then a conflict is reported as described earlier.
215 DIFF
218 The diff function is provided primarily to allow inspection of the
219 alignments that wiggle calculated between texts and that it uses for
220 performing a merge.
221 The output of the diff function is similar to the unified output of
223 diff. However while diff does not output long stretches of common
224 text, wiggle's diff mode outputs everything.
225 When calculating a word-based alignment (the default), wiggle may need
227 to show these word-based differences. This is done using an extension
228 to the unified-diff format. If a line starts with a vertical bar, then
229 it may contain sections surrounded by special multi-character brackets.
230 The brackets "<<<++" and "++>>>" surround added text while "<<<--" and
231 "-->>>" surround removed text.
232 wiggle can be given the two texts to compare in one of three ways.
234 If only one file is given, then it is treated as a patch and the two
236 branches of that diff are compared. This effectively allows a patch to
237 be refined from a line-based patch to a word-based patch.
238 If two files are given, then they are normally assumed to be simple
240 texts to be compared.
241 If two files are given along with the --patch option, then the second
243 file is assumed to be a patch and either the first (with -1) or the
244 second (with -2) branch is extracted and compared with text found in
245 the first file.
246 This last option causes wiggle to apply a "best-fit" algorithm for
248 aligning patch hunks with the file before computing the differences.
249 This algorithm is used when merging a patch with a file, and its value
250 can be seen by comparing the difference produced this was with the dif‐
251 ference produced by first extracting one branch of a patch into a file,
252 and then computing the difference of that file with the main file.
253 EXTRACT
257 The extract function of wiggle simply exposes the internal functional‐
258 ity for extracting one branch of a patch or a merge file.
259 Precisely one file should be given, and it will be assumed to be a
261 merge file unless --patch is given, in which case a patch is assumed.
262 The choice of branch in made by providing one of -1, -2, or -3 with
264 obvious meanings.
265
268 Caution should always be exercised when applying a rejected patch with
269 wiggle. When patch rejects a patch, it does so for a good reason.
270 Even though wiggle may be able to find a believable place to apply each
271 textual change, there is no guarantee that the result is correct in any
272 semantic sense. The result should always be inspected to make sure it
273 is correct.
274
277 wiggle --replace file file.rej
278 This is the normal usage of wiggle and will take any changes in
279 file.rej that patch could not apply, and merge them into file.
280 wiggle -dp1 file file.rej
282 This will perform a word-wise comparison between the file and the
283 before branch of the diff in file.rej and display the differences.
284 This allows you to see where a given patch would apply.
285 wiggle --merge --help
287 Get help about the merge function of wiggle.
288
291 The name of wiggle was inspired by the following quote, even though
292 wiggle does not (yet) have a graphical interface.
293 The problem I find is that I often want to take
295 (file1+patch) -> file2,
296 when I don't have file1. But merge tools want to take
297 (file1|file2) -> file3.
298 I haven't seen a graphical tool which helps you to wiggle a patch
299 into a file.
300 -- Andrew Morton - 2002
302
305 - wiggle cannot read the extended unified-diff output that it pro‐
306 duces for --diff --words.
307 - wiggle cannot read the word-based merge format that it produces
310 for --merge --words.
311
314 Neil Brown at Computer Science and Engineering at The University of New
315 South Wales, Sydney, Australia
316
319 patch(1), diff(1), merge(1), wdiff(1), diff3(1).
320v0.8 WIGGLE(1)