| blob | f883f8b5ea0059ece5fb6d2e5c2d29c7699f2e90 |
1 .\" -*- nroff -*-
2 .\" wiggle - apply rejected patches
3 .\"
4 .\" Copyright (C) 2003 Neil Brown <neilb@cse.unsw.edu.au>
5 .\" Copyright (C) 2010 Neil Brown <neilb@suse.de>
6 .\"
7 .\"
8 .\" This program is free software; you can redistribute it and/or modify
9 .\" it under the terms of the GNU General Public License as published by
10 .\" the Free Software Foundation; either version 2 of the License, or
11 .\" (at your option) any later version.
12 .\"
13 .\" This program is distributed in the hope that it will be useful,
14 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
15 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
16 .\" GNU General Public License for more details.
17 .\"
18 .\" You should have received a copy of the GNU General Public License
19 .\" along with this program; if not, write to the Free Software
20 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
21 .\"
22 .\" Author: Neil Brown
23 .\" Email: <neilb@suse.de>
24 .\"
25 .TH WIGGLE 1 "" v0.8
26 .SH NAME
27 wiggle \- apply rejected patches and perform word-wise diffs
29 .SH SYNOPSIS
31 .BI wiggle " [function] [options] file [files]"
33 .SH DESCRIPTION
34 The main function of
35 .I wiggle
36 is to apply a patch to a file in a similar manner to the
37 .BR patch (1)
38 program.
40 The distinctive difference of
41 .I wiggle
42 is that it will attempt to apply a patch even if the "before" part of
43 the patch doesn't match the target file perfectly.
44 This is achieved by breaking the file and patch into words and finding
45 the best alignment of words in the file with words in the patch.
46 Once this alignment has been found, any differences (word-wise) in the
47 patch are applied to the file as best as possible.
49 Also,
50 .I wiggle
51 will (in some cases) detect changes that have already been applied,
52 and will ignore them.
54 .I wiggle
55 ensures that every change in the patch is applied to the target
56 file somehow. If a particular change cannot be made in the file, the
57 file is annotated to show where the change should be made in a similar
58 way to the
59 .BR merge (1)
60 program with the
61 .B \-A
62 option.
63 Each annotation contains 3 components: a portion of the original file
64 where the change should be applied, a portion of the patch that
65 couldn't be matched precisely in the file, and the text that should
66 replace that portion of the patch. These are separated by lines
67 containing precisely 7 identical characters, either '<', '|', '=', or '>', so
68 .in +5
69 .nf
70 .ft CW
71 <<<<<<<
72 Some portion of the original file
73 |||||||
74 text to replace
75 =======
76 text to replace it with
77 >>>>>>>
78 .ft
79 .fi
80 .in -5
82 indicates that "text to replace" should be replaced by "text to
83 replace it with" somewhere in the portion of the original file.
84 However
85 .I wiggle
86 was not able to find a place to make this change.
88 .I wiggle
89 can also produce conflict reports showing only the words that are
90 involved rather than showing whole lines.
91 In this case the output looks like:
92 .ft CW
93 .ti +5
94 <<<---original|||old===new--->>>
95 .ft
97 A typical usage of
98 .I wiggle
99 is to run
100 .I patch
101 to apply some patch, and to collect a list of rejects by monitoring
102 the error messages from patch. Then for each file for which a
103 reject was found, run
104 .ti +5
105 wiggle \-\-replace originalfile originalfile.rej
107 Finally each file must be examined to resolve any unresolved
108 conflicts, and to make sure the applied patch is semantically correct.
110 .SS OPTIONS
111 The following options are understood by
112 .IR wiggle .
113 Some of these are explained in more detail in the following sections
114 on MERGE, DIFF, EXTRACT, and BROWSE.
116 .TP
117 .BR \-m ", " \-\-merge
118 Select the "merge" function. This is the default function.
120 .TP
121 .BR \-d ", " \-\-diff
122 Select the "diff" function. This displays the differences between files.
124 .TP
125 .BR \-x ", " \-\-extract
126 Select the "extract" function. This extracts one branch of a patch or
127 merge file.
129 .TP
130 .BR \-B ", " \-\-browse
131 Select the "browse" function. This is similar to "merge" only with a
132 different presentation. Instead of the result simply being sent to
133 standard output, it is presented using an ncurses-based GUI so that
134 each hunk of the patch can be examined to understand what conflicts
135 where involved and what needed to be ignored in order of the patch to
136 be wiggled in to place.
138 .TP
139 .BR -w ", " \-\-words
140 Request that all operations and display be word based. This is the
141 default for the "diff" function.
143 .TP
144 .BR -l ", " \-\-lines
145 Request that all operations and display be line based.
147 .TP
148 .BR -p ", " \-\-patch
149 Treat the last named file as a patch instead of a file (with \-\-diff)
150 or a merge (\-\-extract).
151 In
152 .I merge
153 or
154 .B browse
155 mode,
156 .B -p
157 requires there be exactly one file which is a patch and which can
158 contain patches to multiple file. The patches are merged into each
159 file. When used in
160 .I merge
161 mode, this usage requires the
162 .B \-\-replace
163 option as writing lots of merged files to standard-out is impractical.
165 When processing a multi-file patch,
166 B -p
167 can be followed by a numeric argument indicating how many file name
168 components should be stripped from files named in the patch file. If no
169 numeric argument is given,
170 .I wiggle
171 will deduce an appropriate number based what files are visible.
173 .TP
174 .BR -r ", " \-\-replace
175 Normally the merged output is written to standard-output. With
176 \-\-replace, the original file is replaced with the merge output.
178 .TP
179 .BR -R ", " \-\-reverse
180 When used with the "diff" function, swap the files before calculating
181 the differences.
182 When used with the "merge" function,
183 .I wiggle
184 attempts to revert changes rather than apply them.
186 .TP
187 .BR -i ", " \-\-no\-ignore
188 Normally wiggle will ignore changes in the patch which appear to
189 already have been applied in the original. With this flag those
190 changes are reported as conflicts rather than being ignored.
192 .TP
193 .BR -W ", " \-\-show\-wiggle
194 When used with
195 .IR \-\-merge ,
196 conflicts that can be wiggled into place are reported as conflicts
197 with an extra stanza which shows what the result would be if this flag
198 had not been used. The extra stanza is introduce with a line
199 containing 7 ampersand
200 .RB ( & )
201 characters thus:
202 .in +5
203 .nf
204 .ft CW
205 <<<<<<<
206 Some portion of the original file
207 |||||||
208 text to replace
209 =======
210 text to replace it with
211 &&&&&&&
212 Text that would result from a successful wiggle
213 >>>>>>>
214 .ft
215 .fi
216 .in -5
218 .TP
219 .BR -h ", " \-\-help
220 Print a simple help message. If given after one of the function
221 selectors (\-\-merge, \-\-diff, \-\-extract) help specific to that function
222 is displayed.
224 .TP
225 .BR -V ", " \-\-version
226 Display the version number of
227 .IR wiggle .
229 .TP
230 .BR -v ", " \-\-verbose
231 Enable verbose mode. Currently this makes no difference.
233 .TP
234 .BR -q ", " \-\-quiet
235 Enable quiet mode. This suppresses the message from the merge
236 function when there are unresolvable conflicts.
238 .SS WORDS
239 .I wiggle
240 can divide a text into lines or words when performing it's tasks.
241 A line is simply a string of characters terminated by a newline.
242 A word is either a maximal contiguous string of alphanumerics
243 (including underscore), a maximal contiguous string of space or tab
244 characters, or any other single character.
246 .SS MERGE
247 The merge function modifies a given text by finding all changes between
248 two other texts and imposing those changes on the given text.
250 Normally
251 .I wiggle
252 focuses on which words have changed so as to maximise the possibility
253 of finding a good match in the given text for the context of a given
254 change. However it can consider only whole lines instead.
256 .I wiggle
257 extracts the three texts that it needs from files listed on the
258 command line. Either 1, 2, or 3 files may be listed, and any one of
259 them may be a lone hyphen signifying standard-input.
261 If one file is given and the
262 .B \-p
263 option is not present, the file is treated as a
264 .B merge
265 file, i.e. the output of "merge \-A" or "wiggle". Such a file
266 implicitly contains three streams and these are extracted and
267 compared.
269 If two files are given, then the first simply contains the primary
270 text, and the second is treated as a patch file (the output of "diff\ \-u"
271 or "diff\ \-c", or a ".rej" file from
272 .IR patch )
273 and the two other texts
274 are extracted from that.
276 If one file is given together with the
277 .B \-p
278 option, the file is treated as a patch file containing the names of
279 the files that it patches. In this case multiple merge operations can
280 happen and each takes one stream from a file named in the patch, and
281 the other to from the patch itself. The
282 .B \-\-replace
283 option is required and the results are written back to the
284 target files.
286 Finally if three files are listed, they are taken to contain the given
287 text and the two other texts, in order.
289 Normally the result of the merge is written to standard-output.
290 However if the "\-r" flag is given, the output is written to a file
291 which replaces the original given file. In this case the original file
292 is renamed to have a
293 .B .porig
294 suffix (for "patched original" which makes sense if you first use
295 .I patch
296 to apply a patch, and then use
297 .I wiggle
298 to wiggle the rejects in).
300 If no errors occur (such as file access errors)
301 .I wiggle
302 will exit with a status of 0 if all changes were successfully merged,
303 and with an exit status of 1 and a brief message if any changes could
304 not be fully merged and were instead inserted as annotations.
306 The merge function can operate in three different modes with respect
307 to lines or words.
309 With the
310 .B \-\-lines
311 option, whole lines are compared and any conflicts
312 are reported as whole lines that need to be replaced.
314 With the
315 .B \-\-words
316 option, individual words are compared and any
317 conflicts are reported just covering the words affected. This uses
318 the \f(CW <<<|||===>>> \fP conflict format.
320 Without either of these options, a hybrid approach is taken.
321 Individual words are compared and merged, but when a conflict is found
322 the whole surrounding line is reported as being in conflict.
324 .I wiggle
325 will ensure that every change between the two other texts is reflected
326 in the result of the merge somehow. There are four different ways
327 that a change can be reflected.
328 .IP 1
329 If a change converts
330 .B A
331 to
332 .B B
333 and
334 .B A
335 is found at a suitable place in the original file, it is
336 replaced with
337 .BR B .
338 This includes the possibility that
339 .B B
340 is empty, but
341 not that
342 .B A
343 is empty.
345 .IP 2
346 If a change is found which simply adds
347 .B B
348 and the text immediately preceding and following the insertion are
349 found adjacent in the original file in a suitable place, then
350 .B B
351 is inserted between those adjacent texts.
353 .IP 3
354 If a change is found which changes
355 .B A
356 to
357 .B B
358 and this appears (based on context) to align with
359 .B B
360 in the original, then it is assumed that this change has already been
361 applied, and the change is ignored. When this happens, a message
362 reflected the number of ignored changes is printed by
363 .IR wiggle .
364 This optimisation can be suppressed with the
365 .B \-i
366 flag.
368 .IP 4
369 If a change is found that does not fit any of the above possibilities,
370 then a conflict is reported as described earlier.
372 .SS DIFF
374 The diff function is provided primarily to allow inspection of the
375 alignments that
376 .I wiggle
377 calculated between texts and that it uses for performing a merge.
379 The output of the diff function is similar to the unified output of
380 diff. However while diff does not output long stretches of common text,
381 .IR wiggle 's
382 diff mode outputs everything.
384 When calculating a word-based alignment (the default),
385 .I wiggle
386 may need to show these word-based differences. This is done using an
387 extension to the unified-diff format. If a line starts with a
388 vertical bar, then it may contain sections surrounded by special
389 multi-character brackets. The brackets "<<<++" and "++>>>" surround
390 added text while "<<<--" and "-->>>" surround removed text.
392 .I wiggle
393 can be given the two texts to compare in one of three ways.
395 If only one file is given, then it is treated as a patch and the two
396 branches of that diff are compared. This effectively allows a patch
397 to be refined from a line-based patch to a word-based patch.
399 If two files are given, then they are normally assumed to be simple
400 texts to be compared.
402 If two files are given along with the \-\-patch option, then the second
403 file is assumed to be a patch and either the first (with \-1) or the
404 second (with \-2) branch is extracted and compared with text found in
405 the first file.
407 This last option causes
408 .I wiggle
409 to apply a "best-fit" algorithm for aligning patch hunks with the
410 file before computing the differences. This algorithm is used when
411 merging a patch with a file, and its value can be seen by comparing
412 the difference produced this way with the difference produced by first
413 extracting one branch of a patch into a file, and then computing the
414 difference of that file with the main file.
417 .SS EXTRACT
419 The extract function of
420 .I wiggle
421 simply exposes the internal functionality for extracting one branch of
422 a patch or a merge file.
424 Precisely one file should be given, and it will be assumed to be a
425 merge file unless
426 .B \-\-patch
427 is given, in which case a patch is assumed.
429 The choice of branch in made by providing one of
430 .BR -1 ,
431 .BR -2 ,
432 or
433 .B -3
434 with obvious meanings.
436 .SS BROWSE
438 The browse function of
439 .I wiggle
440 presents the result of a merge in a text-based GUI that can be
441 navigated using keystrokes similar to vi(1) or emacs(1).
443 The browser allow each of the three streams to be viewed individually
444 with colours used to highlight different sorts of text - green for
445 added text, red for deleted text etc. It can also show the patch by
446 itself, the full result of the merge, or the merge and the patch
447 side-by-side.
449 The browser provides a number of context-sensitive help pages which
450 can be accessed by typing '?'
452 .SH WARNING
454 Caution should always be exercised when applying a rejected patch with
455 .IR wiggle .
456 When
457 .I patch
458 rejects a patch, it does so for a good reason. Even though
459 .I wiggle
460 may be able to find a believable place to apply each textual change,
461 there is no guarantee that the result is correct in any semantic
462 sense. The result should always be inspected to make sure it is
463 correct.
465 .SH EXAMPLES
467 .B " wiggle \-\-replace file file.rej"
468 .br
469 This is the normal usage of
470 .I wiggle
471 and will take any changes in
472 .B file.rej
473 that
474 .I patch
475 could not apply, and merge them into
476 .BR file .
478 .B " wiggle -dp1 file file.rej"
479 .br
480 This will perform a word-wise comparison between the
481 .B file
482 and the
483 .I before
484 branch of the diff in
485 .B file.rej
486 and display the differences. This allows you to see where a given
487 patch would apply.
489 .B " wiggle \-\-merge \-\-help"
490 .br
491 Get help about the merge function of
492 .IR wiggle .
494 .B " wiggle --browse --patch update.patch"
495 .br
496 Parse the
497 .B update.patch
498 file for patches and present a list of patched files which can be
499 browsed to examine each patch in detail.
501 .SH QUOTE
502 The name of
503 .I wiggle
504 was inspired by the following quote. However
505 .I wiggle
506 does not yet
507 .B help
508 you to wiggle a patch into place. It either does the wiggle itself,
509 or leave it for you to finish off.
511 .nf
512 The problem I find is that I often want to take
513 (file1+patch) -> file2,
514 when I don't have file1. But merge tools want to take
515 (file1|file2) -> file3.
516 I haven't seen a graphical tool which helps you to wiggle a patch
517 into a file.
519 \-\- Andrew Morton - 2002
520 .fi
522 .SH SHORTCOMINGS
523 .IP -
524 .I wiggle
525 cannot read the extended unified-diff output that it produces for
526 \-\-diff \-\-words.
528 .IP -
529 .I wiggle
530 cannot read the word-based merge format that it produces for \-\-merge
531 \-\-words.
533 .SH AUTHOR
535 Neil Brown at Computer Science and Engineering at
536 The University of New South Wales, Sydney, Australia;
537 and later and SUSE, still in Sydney, Australia.
539 .SH SEE ALSO
540 .IR patch (1),
541 .IR diff (1),
542 .IR merge (1),
543 .IR wdiff (1),
544 .IR diff3 (1).