| blob | 18591c7e9ae7ddf4d07517555757c3027d7c126e |
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.9
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 Alternately, the original patch file can be feed to the
111 .B browse
112 mode as
113 .ti +5
114 wiggle -B < patchfile
116 This will allow the changes and conflicts to be inspected and, to some
117 extent, modified; and then the results can be save.
119 .SS OPTIONS
120 The following options are understood by
121 .IR wiggle .
122 Some of these are explained in more detail in the following sections
123 on MERGE, DIFF, EXTRACT, and BROWSE.
125 .TP
126 .BR \-m ", " \-\-merge
127 Select the "merge" function. This is the default function.
129 .TP
130 .BR \-d ", " \-\-diff
131 Select the "diff" function. This displays the differences between files.
133 .TP
134 .BR \-x ", " \-\-extract
135 Select the "extract" function. This extracts one branch of a patch or
136 merge file.
138 .TP
139 .BR \-B ", " \-\-browse
140 Select the "browse" function. This is similar to "merge" only with a
141 different presentation. Instead of the result simply being sent to
142 standard output, it is presented using an ncurses-based GUI so that
143 each hunk of the patch can be examined to understand what conflicts
144 where involved and what needed to be ignored in order of the patch to
145 be wiggled in to place.
147 .TP
148 .BR \-w ", " \-\-words
149 Request that all operations and display be word based. This is the
150 default for the "diff" function.
152 .TP
153 .BR \-l ", " \-\-lines
154 Request that all operations and display be line based.
156 .TP
157 .BR \-b ", " \-\-ignore\-blanks
158 De-emphasise white space (space, tab, and newline) is determining
159 differences and changes.
161 Normally white space is treated like a word which can be matched or
162 changed by a patch. When this flag is in force, white space serves
163 only as a separator between other words and is not matched itself.
164 The effect of this is that changes in the amount of white space are
165 not treated as significant.
167 To be precise, any white space is combined with the preceeding word
168 or, in the case of leading space on a line, with the following word.
169 However it is not involved in any comparisons of that word. If a patch
170 deletes a word, the attached white space is deleted as well. If a
171 patch adds a word, the attached white space is added as well.
173 An empty line, or one that contains only blanks, will be treated as a
174 single word that will match any other blank line, no matter how many
175 spaces it has.
177 .B \-b
178 has no effect in
179 .B \-\-line
180 mode.
182 .TP
183 .BR -p ", " \-\-patch
184 Treat the last named file as a patch instead of a file (with \-\-diff)
185 or a merge (\-\-extract).
186 In
187 .I merge
188 or
189 .B browse
190 mode,
191 .B -p
192 requires there be exactly one file which is a patch and which can
193 contain patches to multiple files. The patches are merged into each
194 file. When used in
195 .I merge
196 mode, this usage requires the
197 .B \-\-replace
198 option as writing lots of merged files to standard-out is impractical.
200 When processing a multi-file patch,
201 .B \-p
202 can be followed by a numeric argument indicating how many file name
203 components should be stripped from files named in the patch file. If no
204 numeric argument is given,
205 .I wiggle
206 will deduce an appropriate number based what files are present in the
207 filesystem.
209 .TP
210 .BR -r ", " \-\-replace
211 Normally the merged output is written to standard-output. With
212 \-\-replace, the original file is replaced with the merge output.
213 In
214 .B browse
215 mode, this instructs
216 .I wiggle
217 to always save the resulting merge when exiting.
219 .TP
220 .BR -R ", " \-\-reverse
221 When used with the
222 .B diff
223 function, swap the files before calculating
224 the differences.
225 When used with the
226 .B merge
227 or
228 .B browse
229 functions,
230 .I wiggle
231 attempts to revert changes rather than apply them.
233 .TP
234 .BR -i ", " \-\-no\-ignore
235 Normally wiggle will ignore changes in the patch which appear to
236 already have been applied in the original. With this flag those
237 changes are reported as conflicts rather than being ignored.
239 .TP
240 .BR -W ", " \-\-show\-wiggle
241 When used with
242 .IR \-\-merge ,
243 conflicts that can be wiggled into place are reported as conflicts
244 with an extra stanza which shows what the result would be if this flag
245 had not been used. The extra stanza is introduce with a line
246 containing 7 ampersand
247 .RB ( & )
248 characters thus:
249 .in +5
250 .nf
251 .ft CW
252 <<<<<<<
253 Some portion of the original file
254 |||||||
255 text to replace
256 =======
257 text to replace it with
258 &&&&&&&
259 Text that would result from a successful wiggle
260 >>>>>>>
261 .ft
262 .fi
263 .in -5
265 .TP
266 .BR -h ", " \-\-help
267 Print a simple help message. If given after one of the function
268 selectors
269 .RB ( \-\-merge ,
270 .BR \-\-diff ,
271 .BR \-\-extract ,
272 .BR \-\-browse )
273 help specific to that function is displayed.
275 .TP
276 .BR -V ", " \-\-version
277 Display the version number of
278 .IR wiggle .
280 .TP
281 .BR -v ", " \-\-verbose
282 Enable verbose mode. Currently this makes no difference.
284 .TP
285 .BR -q ", " \-\-quiet
286 Enable quiet mode. This suppresses the message from the merge
287 function when there are unresolvable conflicts.
289 .SS WORDS
290 .I wiggle
291 can divide a text into lines or words when performing it's tasks.
292 A line is simply a string of characters terminated by a newline.
293 A word is either a maximal contiguous string of alphanumerics
294 (including underscore), a maximal contiguous string of space or tab
295 characters, or any other single character.
297 .SS MERGE
298 The merge function modifies a given text by finding all changes between
299 two other texts and imposing those changes on the given text.
301 Normally
302 .I wiggle
303 focuses on which words have changed so as to maximise the possibility
304 of finding a good match in the given text for the context of a given
305 change. However it can consider only whole lines instead.
307 .I wiggle
308 extracts the three texts that it needs from files listed on the
309 command line. Either 1, 2, or 3 files may be listed, and any one of
310 them may be a lone hyphen signifying standard-input.
312 If one file is given and the
313 .B \-p
314 option is not present, the file is treated as a
315 .B merge
316 file, i.e. the output of "merge \-A" or "wiggle". Such a file
317 implicitly contains three streams and these are extracted and
318 compared.
320 If two files are given, then the first simply contains the primary
321 text, and the second is treated as a patch file (the output of "diff\ \-u"
322 or "diff\ \-c", or a ".rej" file from
323 .IR patch )
324 and the two other texts
325 are extracted from that.
327 If one file is given together with the
328 .B \-p
329 option, the file is treated as a patch file containing the names of
330 the files that it patches. In this case multiple merge operations can
331 happen and each takes one stream from a file named in the patch, and
332 the other two from the patch itself. The
333 .B \-\-replace
334 option is required and the results are written back to the
335 target files.
337 Finally if three files are listed, they are taken to contain the given
338 text and the two other texts, in order.
340 Normally the result of the merge is written to standard-output.
341 However if the
342 .B \-r
343 flag is given, the output is written to a file
344 which replaces the original given file. In this case the original file
345 is renamed to have a
346 .B .porig
347 suffix (for "patched original" which makes sense if you first use
348 .I patch
349 to apply a patch, and then use
350 .I wiggle
351 to wiggle the rejects in).
353 If no errors occur (such as file access errors)
354 .I wiggle
355 will exit with a status of 0 if all changes were successfully merged,
356 and with an exit status of 1 and a brief message if any changes could
357 not be fully merged and were instead inserted as annotations.
359 The merge function can operate in three different modes with respect
360 to lines or words.
362 With the
363 .B \-\-lines
364 option, whole lines are compared and any conflicts
365 are reported as whole lines that need to be replaced.
367 With the
368 .B \-\-words
369 option, individual words are compared and any
370 conflicts are reported just covering the words affected. This uses
371 the \f(CW <<<|||===>>> \fP conflict format.
373 Without either of these options, a hybrid approach is taken.
374 Individual words are compared and merged, but when a conflict is found
375 the whole surrounding line is reported as being in conflict.
377 .I wiggle
378 will ensure that every change between the two other texts is reflected
379 in the result of the merge somehow. There are four different ways
380 that a change can be reflected.
381 .IP 1
382 If a change converts
383 .B A
384 to
385 .B B
386 and
387 .B A
388 is found at a suitable place in the original file, it is
389 replaced with
390 .BR B .
391 This includes the possibility that
392 .B B
393 is empty, but
394 not that
395 .B A
396 is empty.
398 .IP 2
399 If a change is found which simply adds
400 .B B
401 and the text immediately preceding and following the insertion are
402 found adjacent in the original file in a suitable place, then
403 .B B
404 is inserted between those adjacent texts.
406 .IP 3
407 If a change is found which changes
408 .B A
409 to
410 .B B
411 and this appears (based on context) to align with
412 .B B
413 in the original, then it is assumed that this change has already been
414 applied, and the change is ignored. When this happens, a message
415 reflecting the number of ignored changes is printed by
416 .IR wiggle .
417 This optimisation can be suppressed with the
418 .B \-i
419 flag.
421 .IP 4
422 If a change is found that does not fit any of the above possibilities,
423 then a conflict is reported as described earlier.
425 .SS DIFF
427 The diff function is provided primarily to allow inspection of the
428 alignments that
429 .I wiggle
430 calculated between texts and that it uses for performing a merge.
432 The output of the diff function is similar to the unified output of
433 diff. However while diff does not output long stretches of common text,
434 .IR wiggle 's
435 diff mode outputs everything.
437 When calculating a word-based alignment (the default),
438 .I wiggle
439 may need to show these word-based differences. This is done using an
440 extension to the unified-diff format. If a line starts with a
441 vertical bar, then it may contain sections surrounded by special
442 multi-character brackets. The brackets "<<<++" and "++>>>" surround
443 added text while "<<<--" and "-->>>" surround removed text.
445 .I wiggle
446 can be given the two texts to compare in one of three ways.
448 If only one file is given, then it is treated as a patch and the two
449 branches of that diff are compared. This effectively allows a patch
450 to be refined from a line-based patch to a word-based patch.
452 If two files are given, then they are normally assumed to be simple
453 texts to be compared.
455 If two files are given along with the \-\-patch option, then the second
456 file is assumed to be a patch and either the first (with \-1) or the
457 second (with \-2) branch is extracted and compared with text found in
458 the first file.
460 This last option causes
461 .I wiggle
462 to apply a "best-fit" algorithm for aligning patch hunks with the
463 file before computing the differences. This algorithm is used when
464 merging a patch with a file, and its value can be seen by comparing
465 the difference produced this way with the difference produced by first
466 extracting one branch of a patch into a file, and then computing the
467 difference of that file with the main file.
470 .SS EXTRACT
472 The extract function of
473 .I wiggle
474 simply exposes the internal functionality for extracting one branch of
475 a patch or a merge file.
477 Precisely one file should be given, and it will be assumed to be a
478 merge file unless
479 .B \-\-patch
480 is given, in which case a patch is assumed.
482 The choice of branch in made by providing one of
483 .BR -1 ,
484 .BR -2 ,
485 or
486 .B -3
487 with obvious meanings.
489 .SS BROWSE
491 The browse function of
492 .I wiggle
493 presents the result of a merge in a text-based GUI that can be
494 navigated using keystrokes similar to vi(1) or emacs(1).
496 The browser allows each of the three streams to be viewed individually
497 with colours used to highlight different sorts of text - green for
498 added text, red for deleted text etc. It can also show the patch by
499 itself, the full result of the merge, or the merge and the patch
500 side-by-side.
502 The browser provides a number of context-sensitive help pages which
503 can be accessed by typing '?'
505 A limited amount of editing is permitted while in
506 .B browse
507 mode. Currently any Conflict or Changed section can be marked as
508 "ignored" by using the
509 .B x
510 key (lower case), or all the Conflict and Changes sections in a line
511 can be ignored by using
512 .B X
513 (upper case). The effect can be toggled by pressing
514 .B x
515 or
516 .B X
517 again. If you make any changes, then wiggle will ask you if you want
518 to save the changes, even if
519 .B \-\-replace
520 was not given.
522 .SH WARNING
524 Caution should always be exercised when applying a rejected patch with
525 .IR wiggle .
526 When
527 .I patch
528 rejects a patch, it does so for a good reason. Even though
529 .I wiggle
530 may be able to find a believable place to apply each textual change,
531 there is no guarantee that the result is correct in any semantic
532 sense. The result should always be inspected to make sure it is
533 correct.
535 .SH EXAMPLES
537 .B " wiggle \-\-replace file file.rej"
538 .br
539 This is the normal usage of
540 .I wiggle
541 and will take any changes in
542 .B file.rej
543 that
544 .I patch
545 could not apply, and merge them into
546 .BR file .
548 .B " wiggle -dp1 file file.rej"
549 .br
550 This will perform a word-wise comparison between the
551 .B file
552 and the
553 .I before
554 branch of the diff in
555 .B file.rej
556 and display the differences. This allows you to see where a given
557 patch would apply.
559 .B " wiggle \-\-merge \-\-help"
560 .br
561 Get help about the merge function of
562 .IR wiggle .
564 .B " wiggle --browse --patch update.patch"
565 .br
566 Parse the
567 .B update.patch
568 file for patches and present a list of patched files which can be
569 browsed to examine each patch in detail.
571 .SH QUOTE
572 The name of
573 .I wiggle
574 was inspired by the following quote. However
575 .I wiggle
576 does not yet
577 .B help
578 you to wiggle a patch into place. It either does the wiggle itself,
579 or leave it for you to finish off.
581 .nf
582 The problem I find is that I often want to take
583 (file1+patch) -> file2,
584 when I don't have file1. But merge tools want to take
585 (file1|file2) -> file3.
586 I haven't seen a graphical tool which helps you to wiggle a patch
587 into a file.
589 \-\- Andrew Morton - 2002
590 .fi
592 .SH SHORTCOMINGS
593 .IP -
594 .I wiggle
595 cannot read the extended unified-diff output that it produces for
596 \-\-diff \-\-words.
598 .IP -
599 .I wiggle
600 cannot read the word-based merge format that it produces for \-\-merge
601 \-\-words.
603 .SH AUTHOR
605 Neil Brown at Computer Science and Engineering at
606 The University of New South Wales, Sydney, Australia;
607 and later and SUSE, still in Sydney, Australia.
609 .SH SEE ALSO
610 .IR patch (1),
611 .IR diff (1),
612 .IR merge (1),
613 .IR wdiff (1),
614 .IR diff3 (1).