1WIGGLE(1) General Commands Manual WIGGLE(1)
2
6 wiggle - apply rejected patches and perform word-wise diffs
7
9 wiggle [function] [options] file [files]
10
12 The main function of wiggle is to apply a patch to a file in a similar
13 manner to the patch(1) program.
14 The distinctive difference of wiggle is that it will attempt to apply a
16 patch even if the "before" part of the patch doesn't match the target
17 file perfectly. This is achieved by breaking the file and patch into
18 words and finding the best alignment of words in the file with words in
19 the patch. Once this alignment has been found, any differences (word-
20 wise) in the patch are applied to the file as best as possible.
21 Also, wiggle will (in some cases) detect changes that have already been
23 applied, and will ignore them.
24 wiggle ensures that every change in the patch is applied to the target
26 file somehow. If a particular change cannot be made in the file, the
27 file is annotated to show where the change should be made in a similar
28 way to the merge(1) program with the -A option. Each annotation con‐
29 tains 3 components: a portion of the original file where the change
30 should be applied, a portion of the patch that couldn't be matched pre‐
31 cisely in the file, and the text that should replace that portion of
32 the patch. These are separated by lines containing precisely 7 identi‐
33 cal characters, either '<', '|', '=', or '>', possibly followed by a
34 descriptive word. So
35 <<<<<<< found
36 Some portion of the original file
37 ||||||| expected
38 text to replace
39 =======
40 text to replace it with
41 >>>>>>> replacement
42 indicates that "text to replace" should be replaced by "text to replace
43 it with" somewhere in the portion of the original file. However wiggle
44 was not able to find a place to make this change.
45 wiggle can also produce conflict reports showing only the words that
47 are involved rather than showing whole lines. In this case the output
48 looks like:
49 <<<---original|||old===new--->>>
50 One possible usage of wiggle is to run patch to apply some patch, and
52 to collect a list of rejects by monitoring the error messages from
53 patch. Then for each file for which a reject was found, run
54 wiggle --replace originalfile originalfile.rej
55 Finally each file must be examined to resolve any unresolved conflicts,
57 and to make sure the applied patch is semantically correct.
58 Alternately, the original patch file can be fed to the browse mode as
60 wiggle -B < patchfile
61 This will allow the changes and conflicts to be inspected and, to some
63 extent, modified; and then the results can be saved.
64 OPTIONS
66 The following options are understood by wiggle. Some of these are
67 explained in more detail in the following sections on MERGE, DIFF,
68 EXTRACT, and BROWSE.
69 -m, --merge
71 Select the "merge" function. This is the default function.
72 -d, --diff
74 Select the "diff" function. This displays the differences
75 between files. This can be given after --browse (see below) in
76 which case a patch or diff of two files can be viewed without
77 the originals.
78 -x, --extract
80 Select the "extract" function. This extracts one branch of a
81 patch or merge file.
82 -B, --browse
84 Select the "browse" function. This is similar to "merge" (or
85 "diff") only with a different presentation. Instead of the
86 result simply being sent to standard output, it is presented
87 using an ncurses-based GUI so that each hunk of the patch can be
88 examined to understand what conflicts where involved and what
89 needed to be ignored in order of the patch to be wiggled in to
90 place.
91 -w, --words
93 Request that all operations and display be word based. This is
94 the default for the "diff" function.
95 -l, --lines
97 Request that all operations and display be line based.
98 -b, --ignore-blanks
100 De-emphasise white space (space, tab, and newline) is determin‐
101 ing differences and changes.
102 Normally white space is treated like a word which can be matched
104 or changed by a patch. When this flag is in force, white space
105 serves only as a separator between other words and is not
106 matched itself. The effect of this is that changes in the
107 amount of white space are not treated as significant.
108 To be precise, any white space is combined with the preceding
110 word or, in the case of leading space on a line, with the fol‐
111 lowing word. However it is not involved in any comparisons of
112 that word. If a patch deletes a word, the attached white space
113 is deleted as well. If a patch adds a word, the attached white
114 space is added as well.
115 An empty line, or one that contains only blanks, will be treated
117 as a single word that will match any other blank line, no matter
118 how many spaces it has.
119 -b has no effect in --line mode.
121 -p, --patch
123 Treat the last named file as a patch instead of a file (with
124 --diff) or a merge (--extract). In merge or browse mode, -p
125 requires there be exactly one file which is a patch and which
126 can contain patches to multiple files. The patches are merged
127 into each file. When used in merge mode, this usage requires
128 the --replace option as writing lots of merged files to stan‐
129 dard-out is impractical.
130 When processing a multi-file patch, -p can be followed by a
132 numeric argument indicating how many file name components should
133 be stripped from files named in the patch file. If no numeric
134 argument is given, wiggle will deduce an appropriate number
135 based what files are present in the filesystem.
136 -r, --replace
138 Normally the merged output is written to standard-output. With
139 --replace, the original file is replaced with the merge output.
140 In browse mode, this instructs wiggle to always save the result‐
141 ing merge when exiting.
142 --no-backup
144 Normally when an original file is replaced with the merged
145 result, that file is renamed to have a ".porig" extension, so
146 that it is preserved. If you don't want to keep the original,
147 use this option to suppress the backup.
148 -o, --output=
150 Rather than writing the result to stdout or to replace the orig‐
151 inal file, this requests that the output be written to the given
152 file. This is only meaningful with --merge or --browse when
153 given a single merge to browse.
154 This option overrides -r.
156 -R, --reverse
158 When used with the diff function, swap the files before calcu‐
159 lating the differences. When used with the merge or browse
160 functions, wiggle attempts to revert changes rather than apply
161 them.
162 -i, --no-ignore
164 Normally wiggle will ignore changes in the patch which appear to
165 already have been applied in the original. With this flag those
166 changes are reported as conflicts rather than being ignored.
167 -W, --show-wiggles
169 When used with --merge, conflicts that can be wiggled into place
170 are reported as conflicts with an extra stanza which shows what
171 the result would be if this flag had not been used. The extra
172 stanza is introduce with a line containing 7 ampersand (&) char‐
173 acters thus:
174 <<<<<<< found
175 Some portion of the original file
176 ||||||| expected
177 text to replace
178 =======
179 text to replace it with
180 &&&&&&& resolution
181 Text that would result from a successful wiggle
182 >>>>>>> replacement
183 --report-wiggles
185 If a merge is successful in applying all changes, it will nor‐
186 mally exit with a success status (0), only reporting failure (1)
187 if a conflict occurred and was annotated. With --report-wiggles
188 wiggle will also report failure if any changes had to be wiggled
189 in. This can be useful when wiggle is used for automatic merges
190 as with git. If any wiggles happen, git will report the fail‐
191 ure, and the results can be examined to confirm they are accept‐
192 able.
193 -h, --help
195 Print a simple help message. If given after one of the function
196 selectors (--merge, --diff, --extract, --browse) help specific
197 to that function is displayed.
198 -V, --version
200 Display the version number of wiggle.
201 -v, --verbose
203 Enable verbose mode. Currently this makes no difference.
204 -q, --quiet
206 Enable quiet mode. This suppresses the message from the merge
207 function when there are unresolvable conflicts.
208 WORDS
210 wiggle can divide a text into lines or words when performing it's
211 tasks. A line is simply a string of characters terminated by a new‐
212 line. A word is either a maximal contiguous string of alphanumerics
213 (including underscore), a maximal contiguous string of space or tab
214 characters, or any other single character.
215 MERGE
217 The merge function modifies a given text by finding all changes between
218 two other texts and imposing those changes on the given text.
219 Normally wiggle focuses on which words have changed so as to maximise
221 the possibility of finding a good match in the given text for the con‐
222 text of a given change. However it can consider only whole lines
223 instead.
224 wiggle extracts the three texts that it needs from files listed on the
226 command line. Either 1, 2, or 3 files may be listed, and any one of
227 them may be a lone hyphen signifying standard-input.
228 If one file is given and the -p option is not present, the file is
230 treated as a merge file, i.e. the output of "merge -A" or "wiggle".
231 Such a file implicitly contains three streams and these are extracted
232 and compared.
233 If two files are given, then the first simply contains the primary
235 text, and the second is treated as a patch file (the output of
236 "diff -u" or "diff -c", or a ".rej" file from patch) and the two other
237 texts are extracted from that.
238 If one file is given together with the -p option, the file is treated
240 as a patch file containing the names of the files that it patches. In
241 this case multiple merge operations can happen and each takes one
242 stream from a file named in the patch, and the other two from the patch
243 itself. The --replace option is required and the results are written
244 back to the target files.
245 Finally if three files are listed, they are taken to contain the given
247 text and the two other texts, in order.
248 Normally the result of the merge is written to standard-output. If the
250 -r flag is given, the output is written to a file which replaces the
251 original given file. In this case the original file will normally be
252 renamed to have a .porig suffix (for "patched original" which makes
253 sense if you first use patch to apply a patch, and then use wiggle to
254 wiggle the rejects in). This can be suppressed with the --no-backup
255 uption.
256 Further if the -o option is given with a file name, the output will be
258 written to that file. In this case no backup is created.
259 If no errors occur (such as file access errors) wiggle will exit with a
261 status of 0 if all changes were successfully merged, and with an exit
262 status of 1 and a brief message if any changes could not be fully
263 merged and were instead inserted as annotations. However if either
264 --report-wiggles or --show-wiggles options were given, wiggle will also
265 exist with status of 1 if any changes had to be wiggled in even though
266 this was successful.
267 The merge function can operate in three different modes with respect to
269 lines or words.
270 With the --lines option, whole lines are compared and any conflicts are
272 reported as whole lines that need to be replaced.
273 With the --words option, individual words are compared and any con‐
275 flicts are reported just covering the words affected. This uses the
276 <<<|||===>>> conflict format.
277 Without either of these options, a hybrid approach is taken. Individ‐
279 ual words are compared and merged, but when a conflict is found the
280 whole surrounding line is reported as being in conflict.
281 wiggle will ensure that every change between the two other texts is
283 reflected in the result of the merge somehow. There are four different
284 ways that a change can be reflected.
285 1 If a change converts A to B and A is found at a suitable place
287 in the original file, it is replaced with B. This includes the
288 possibility that B is empty, but not that A is empty.
289 2 If a change is found which simply adds B and the text immedi‐
291 ately preceding and following the insertion are found adjacent
292 in the original file in a suitable place, then B is inserted
293 between those adjacent texts.
294 3 If a change is found which changes A to B and this appears
296 (based on context) to align with B in the original, then it is
297 assumed that this change has already been applied, and the
298 change is ignored. When this happens, a message reflecting the
299 number of ignored changes is printed by wiggle. This optimisa‐
300 tion can be suppressed with the -i flag.
301 4 If a change is found that does not fit any of the above possi‐
303 bilities, then a conflict is reported as described earlier.
304 DIFF
306 The diff function is provided primarily to allow inspection of the
307 alignments that wiggle calculated between texts and that it uses for
308 performing a merge.
309 The output of the diff function is similar to the unified output of
311 diff. However while diff does not output long stretches of common
312 text, wiggle's diff mode outputs everything.
313 When calculating a word-based alignment (the default), wiggle may need
315 to show these word-based differences. This is done using an extension
316 to the unified-diff format. If a line starts with a vertical bar, then
317 it may contain sections surrounded by special multi-character brackets.
318 The brackets "<<<++" and "++>>>" surround added text while "<<<--" and
319 "-->>>" surround removed text.
320 wiggle can be given the two texts to compare in one of three ways.
322 If only one file is given, then it is treated as a patch and the two
324 branches of that patch are compared. This effectively allows a patch
325 to be refined from a line-based patch to a word-based patch.
326 If two files are given, then they are normally assumed to be simple
328 texts to be compared.
329 If two files are given along with the --patch option, then the second
331 file is assumed to be a patch and either the first (with -1) or the
332 second (with -2) branch is extracted and compared with text found in
333 the first file.
334 This last option causes wiggle to apply a "best-fit" algorithm for
336 aligning patch hunks with the file before computing the differences.
337 This algorithm is used when merging a patch with a file, and its value
338 can be seen by comparing the difference produced this way with the dif‐
339 ference produced by first extracting one branch of a patch into a file,
340 and then computing the difference of that file with the main file.
341 EXTRACT
343 The extract function of wiggle simply exposes the internal functional‐
344 ity for extracting one branch of a patch or a merge file.
345 Precisely one file should be given, and it will be assumed to be a
347 merge file unless --patch is given, in which case a patch is assumed.
348 The choice of branch in made by providing one of -1, -2, or -3 with
350 obvious meanings.
351 BROWSE
353 The browse function of wiggle presents the result of a merge or (with
354 -d) a diff in a text-based GUI that can be navigated using keystrokes
355 similar to vi(1) or emacs(1).
356 The browser allows each of the two or three streams to be viewed indi‐
358 vidually with colours used to highlight different sorts of text - green
359 for added text, red for deleted text etc. It can also show the patch
360 by itself, the full result of the merge, or the merge and the patch
361 side-by-side.
362 The browser provides a number of context-sensitive help pages which can
364 be accessed by typing '?'
365 The top right of the GUI will report the type of text under the cursor,
367 which is also indicated by the colour of the text. Options are
368 Unchanged, Changed, Unmatched, Extraneous, AlreadyApplied and Conflict.
369 If the meanings of these are clear a little experimentations should
370 help.
371 A limited amount of editing is permitted while in browse mode. Cur‐
373 rently text that is unwanted can be discarded with x. This will con‐
374 vert a Conflict or Change to Unchanged, and an Unmatched to Changed
375 (which effectively changes it to the empty string). Similarly a text
376 can be marked as wanted with c. This will convert a Conflict or Extra‐
377 neous to Changed. Using the same key again will revert the change.
378 Finally, the uppercase X will revert all changes on the current line.
380 To make more sweeping changes you can use v which runs an editor, pre‐
382 ferring $VISUAL or $EDITOR if they are set in the environment.
383 If you make any changes, then wiggle will ask you if you want to save
385 the changes, even if --replace was not given.
386
388 Caution should always be exercised when applying a rejected patch with
389 wiggle. When patch rejects a patch, it does so for a good reason.
390 Even though wiggle may be able to find a believable place to apply each
391 textual change, there is no guarantee that the result is correct in any
392 semantic sense. The result should always be inspected to make sure it
393 is correct.
394
396 wiggle --replace file file.rej
397 This is the normal usage of wiggle and will take any changes in
398 file.rej that patch could not apply, and merge them into file.
399 wiggle -dp1 file file.rej
401 This will perform a word-wise comparison between the file and the
402 before branch of the diff in file.rej and display the differences.
403 This allows you to see where a given patch would apply.
404 wiggle --merge --help
406 Get help about the merge function of wiggle.
407 wiggle --browse --patch update.patch
409 Parse the update.patch file for patches and present a list of patched
410 files which can be browsed to examine each patch in detail.
411 wiggle can be integrated with git so that it is used as the default
413 merge tool and diff tool. This can be achieved by adding the following
414 lines to .gitconfig in the user's home directory.
415 [merge "wiggle"]
416 name = "Wiggle flexible merging"
417 driver = wiggle -o %A %A %O %B
418 recursive = binary
419 [merge]
420 tool = wiggle
421 [mergetool "wiggle"]
422 cmd = wiggle -B -o $MERGED $LOCAL $BASE $REMOTE
423 [difftool "wiggle"]
424 cmd = wiggle -Bd $LOCAL $REMOTE
425 This will make git mergetool and git difftool use wiggle.
426 If you want git to always use wiggle for merges (which may be danger‐
428 ous), you can add
429 * merge=wiggle
430 to an appropriate gitattributes file such as $HOME/.con‐
431 fig/git/attributes.
432
434 The name of wiggle was inspired by the following quote.
435 The problem I find is that I often want to take
437 (file1+patch) -> file2,
438 when I don't have file1. But merge tools want to take
439 (file1|file2) -> file3.
440 I haven't seen a graphical tool which helps you to wiggle a patch
441 into a file.
442 -- Andrew Morton - 2002
443
445 - wiggle cannot read the extended unified-diff output that it pro‐
446 duces for --diff --words.
447 - wiggle cannot read the word-based merge format that it produces
449 for --merge --words.
450 - wiggle does not understand unicode and so will treat all non-
452 ASCII characters much the same as it treats punctuation - it
453 will treat each one as a separate word. The browser will not
454 display non-ASCII characters properly.
455
457 Neil Brown at Computer Science and Engineering at The University of New
458 South Wales, Sydney, Australia; and later at SUSE, still in Sydney,
459 Australia.
460
462 patch(1), diff(1), merge(1), wdiff(1), diff3(1), git-config(1), gitat‐
463 tributes(5).
464v1.2 WIGGLE(1)