2 .\" wiggle - apply rejected patches
4 .\" Copyright (C) 2003 Neil Brown <neilb@cse.unsw.edu.au>
5 .\" Copyright (C) 2010-2013 Neil Brown <neilb@suse.de>
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.
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.
18 .\" You should have received a copy of the GNU General Public License
19 .\" along with this program.
21 .\" Author: Neil Brown
22 .\" Email: <neilb@suse.de>
26 wiggle \- apply rejected patches and perform word-wise diffs
30 .BI wiggle " [function] [options] file [files]"
35 is to apply a patch to a file in a similar manner to the
39 The distinctive difference of
41 is that it will attempt to apply a patch even if the "before" part of
42 the patch doesn't match the target file perfectly.
43 This is achieved by breaking the file and patch into words and finding
44 the best alignment of words in the file with words in the patch.
45 Once this alignment has been found, any differences (word-wise) in the
46 patch are applied to the file as best as possible.
50 will (in some cases) detect changes that have already been applied,
54 ensures that every change in the patch is applied to the target
55 file somehow. If a particular change cannot be made in the file, the
56 file is annotated to show where the change should be made in a similar
62 Each annotation contains 3 components: a portion of the original file
63 where the change should be applied, a portion of the patch that
64 couldn't be matched precisely in the file, and the text that should
65 replace that portion of the patch. These are separated by lines
66 containing precisely 7 identical characters, either '<', '|', '=', or '>', so
71 Some portion of the original file
75 text to replace it with
81 indicates that "text to replace" should be replaced by "text to
82 replace it with" somewhere in the portion of the original file.
85 was not able to find a place to make this change.
88 can also produce conflict reports showing only the words that are
89 involved rather than showing whole lines.
90 In this case the output looks like:
93 <<<---original|||old===new--->>>
100 to apply some patch, and to collect a list of rejects by monitoring
101 the error messages from patch. Then for each file for which a
102 reject was found, run
104 wiggle \-\-replace originalfile originalfile.rej
106 Finally each file must be examined to resolve any unresolved
107 conflicts, and to make sure the applied patch is semantically correct.
109 Alternately, the original patch file can be feed to the
113 wiggle \-B < patchfile
115 This will allow the changes and conflicts to be inspected and, to some
116 extent, modified; and then the results can be save.
119 The following options are understood by
121 Some of these are explained in more detail in the following sections
122 on MERGE, DIFF, EXTRACT, and BROWSE.
125 .BR \-m ", " \-\-merge
126 Select the "merge" function. This is the default function.
129 .BR \-d ", " \-\-diff
130 Select the "diff" function. This displays the differences between
131 files. This can be given after
133 (see below) in which case a patch or diff of two files can be viewed
134 without the originals.
138 .BR \-x ", " \-\-extract
139 Select the "extract" function. This extracts one branch of a patch or
143 .BR \-B ", " \-\-browse
144 Select the "browse" function. This is similar to "merge" (or "diff")
145 only with a different presentation. Instead of the result simply
146 being sent to standard output, it is presented using an ncurses-based
147 GUI so that each hunk of the patch can be examined to understand what
148 conflicts where involved and what needed to be ignored in order of the
149 patch to be wiggled in to place.
152 .BR \-w ", " \-\-words
153 Request that all operations and display be word based. This is the
154 default for the "diff" function.
157 .BR \-l ", " \-\-lines
158 Request that all operations and display be line based.
161 .BR \-b ", " \-\-ignore\-blanks
162 De-emphasise white space (space, tab, and newline) is determining
163 differences and changes.
165 Normally white space is treated like a word which can be matched or
166 changed by a patch. When this flag is in force, white space serves
167 only as a separator between other words and is not matched itself.
168 The effect of this is that changes in the amount of white space are
169 not treated as significant.
171 To be precise, any white space is combined with the preceeding word
172 or, in the case of leading space on a line, with the following word.
173 However it is not involved in any comparisons of that word. If a patch
174 deletes a word, the attached white space is deleted as well. If a
175 patch adds a word, the attached white space is added as well.
177 An empty line, or one that contains only blanks, will be treated as a
178 single word that will match any other blank line, no matter how many
187 .BR \-p ", " \-\-patch
188 Treat the last named file as a patch instead of a file (with \-\-diff)
189 or a merge (\-\-extract).
196 requires there be exactly one file which is a patch and which can
197 contain patches to multiple files. The patches are merged into each
200 mode, this usage requires the
202 option as writing lots of merged files to standard-out is impractical.
204 When processing a multi-file patch,
206 can be followed by a numeric argument indicating how many file name
207 components should be stripped from files named in the patch file. If no
208 numeric argument is given,
210 will deduce an appropriate number based what files are present in the
214 .BR \-r ", " \-\-replace
215 Normally the merged output is written to standard-output. With
216 \-\-replace, the original file is replaced with the merge output.
221 to always save the resulting merge when exiting.
224 .BR \-o ", " \-\-output=
225 Rather than writing the result to stdout or to replace the original
226 file, this requests that the output be written to the given file.
227 This is only meaningful with
231 when given a single merge to browse.
233 This option overrides
237 .BR \-R ", " \-\-reverse
240 function, swap the files before calculating
248 attempts to revert changes rather than apply them.
251 .BR \-i ", " \-\-no\-ignore
252 Normally wiggle will ignore changes in the patch which appear to
253 already have been applied in the original. With this flag those
254 changes are reported as conflicts rather than being ignored.
257 .BR \-W ", " \-\-show\-wiggles
260 conflicts that can be wiggled into place are reported as conflicts
261 with an extra stanza which shows what the result would be if this flag
262 had not been used. The extra stanza is introduce with a line
263 containing 7 ampersand
270 Some portion of the original file
274 text to replace it with
276 Text that would result from a successful wiggle
283 .B \-\-report\-wiggles
284 If a merge is successful in applying all changes, it will normally exit
285 with a success status (0), only reporting failure (1) if a conflict
286 occurred and was annotated. With
287 .B \-\-report\-wiggles
289 will also report failure if any changes had to be wiggled in. This
292 is used for automatic merges as with
294 If any wiggles happen,
296 will report the failure, and the results can be examined to confirm
300 .BR \-h ", " \-\-help
301 Print a simple help message. If given after one of the function
307 help specific to that function is displayed.
310 .BR \-V ", " \-\-version
311 Display the version number of
315 .BR \-v ", " \-\-verbose
316 Enable verbose mode. Currently this makes no difference.
319 .BR \-q ", " \-\-quiet
320 Enable quiet mode. This suppresses the message from the merge
321 function when there are unresolvable conflicts.
325 can divide a text into lines or words when performing it's tasks.
326 A line is simply a string of characters terminated by a newline.
327 A word is either a maximal contiguous string of alphanumerics
328 (including underscore), a maximal contiguous string of space or tab
329 characters, or any other single character.
332 The merge function modifies a given text by finding all changes between
333 two other texts and imposing those changes on the given text.
337 focuses on which words have changed so as to maximise the possibility
338 of finding a good match in the given text for the context of a given
339 change. However it can consider only whole lines instead.
342 extracts the three texts that it needs from files listed on the
343 command line. Either 1, 2, or 3 files may be listed, and any one of
344 them may be a lone hyphen signifying standard-input.
346 If one file is given and the
348 option is not present, the file is treated as a
350 file, i.e. the output of "merge \-A" or "wiggle". Such a file
351 implicitly contains three streams and these are extracted and
354 If two files are given, then the first simply contains the primary
355 text, and the second is treated as a patch file (the output of "diff\ \-u"
356 or "diff\ \-c", or a ".rej" file from
358 and the two other texts
359 are extracted from that.
361 If one file is given together with the
363 option, the file is treated as a patch file containing the names of
364 the files that it patches. In this case multiple merge operations can
365 happen and each takes one stream from a file named in the patch, and
366 the other two from the patch itself. The
368 option is required and the results are written back to the
371 Finally if three files are listed, they are taken to contain the given
372 text and the two other texts, in order.
374 Normally the result of the merge is written to standard-output.
377 flag is given, the output is written to a file
378 which replaces the original given file. In this case the original file
381 suffix (for "patched original" which makes sense if you first use
383 to apply a patch, and then use
385 to wiggle the rejects in).
387 If no errors occur (such as file access errors)
389 will exit with a status of 0 if all changes were successfully merged,
390 and with an exit status of 1 and a brief message if any changes could
391 not be fully merged and were instead inserted as annotations.
393 .B \-\-report\-wiggles
398 will also exist with status of 1 if any changes had to be wiggled in
399 even though this was successful.
401 The merge function can operate in three different modes with respect
406 option, whole lines are compared and any conflicts
407 are reported as whole lines that need to be replaced.
411 option, individual words are compared and any
412 conflicts are reported just covering the words affected. This uses
413 the \f(CW <<<|||===>>> \fP conflict format.
415 Without either of these options, a hybrid approach is taken.
416 Individual words are compared and merged, but when a conflict is found
417 the whole surrounding line is reported as being in conflict.
420 will ensure that every change between the two other texts is reflected
421 in the result of the merge somehow. There are four different ways
422 that a change can be reflected.
430 is found at a suitable place in the original file, it is
433 This includes the possibility that
441 If a change is found which simply adds
443 and the text immediately preceding and following the insertion are
444 found adjacent in the original file in a suitable place, then
446 is inserted between those adjacent texts.
449 If a change is found which changes
453 and this appears (based on context) to align with
455 in the original, then it is assumed that this change has already been
456 applied, and the change is ignored. When this happens, a message
457 reflecting the number of ignored changes is printed by
459 This optimisation can be suppressed with the
464 If a change is found that does not fit any of the above possibilities,
465 then a conflict is reported as described earlier.
469 The diff function is provided primarily to allow inspection of the
472 calculated between texts and that it uses for performing a merge.
474 The output of the diff function is similar to the unified output of
475 diff. However while diff does not output long stretches of common text,
477 diff mode outputs everything.
479 When calculating a word-based alignment (the default),
481 may need to show these word-based differences. This is done using an
482 extension to the unified-diff format. If a line starts with a
483 vertical bar, then it may contain sections surrounded by special
484 multi-character brackets. The brackets "<<<++" and "++>>>" surround
485 added text while "<<<--" and "-->>>" surround removed text.
488 can be given the two texts to compare in one of three ways.
490 If only one file is given, then it is treated as a patch and the two
491 branches of that diff are compared. This effectively allows a patch
492 to be refined from a line-based patch to a word-based patch.
494 If two files are given, then they are normally assumed to be simple
495 texts to be compared.
497 If two files are given along with the \-\-patch option, then the second
498 file is assumed to be a patch and either the first (with \-1) or the
499 second (with \-2) branch is extracted and compared with text found in
502 This last option causes
504 to apply a "best-fit" algorithm for aligning patch hunks with the
505 file before computing the differences. This algorithm is used when
506 merging a patch with a file, and its value can be seen by comparing
507 the difference produced this way with the difference produced by first
508 extracting one branch of a patch into a file, and then computing the
509 difference of that file with the main file.
514 The extract function of
516 simply exposes the internal functionality for extracting one branch of
517 a patch or a merge file.
519 Precisely one file should be given, and it will be assumed to be a
522 is given, in which case a patch is assumed.
524 The choice of branch in made by providing one of
529 with obvious meanings.
533 The browse function of
535 presents the result of a merge or (with
537 a diff) in a text-based GUI that can be
538 navigated using keystrokes similar to vi(1) or emacs(1).
540 The browser allows each of the two or three streams to be viewed individually
541 with colours used to highlight different sorts of text - green for
542 added text, red for deleted text etc. It can also show the patch by
543 itself, the full result of the merge, or the merge and the patch
546 The browser provides a number of context-sensitive help pages which
547 can be accessed by typing '?'
549 A limited amount of editing is permitted while in
551 mode. Currently any Conflict or Changed section can be converted to
552 Unchanged by using the
554 key (lower case), or all the Conflict and Changes sections in a line
555 can be converted to Unchanged.
557 (upper case). The effect can be toggled by pressing
563 A Conflict section can also be converted to Change (so the result is
564 accepted even though there wasn't a proper match) with the (lower
571 If you make any changes, then wiggle will ask you if you want
572 to save the changes, even if
576 To make more sweeping changes you can use
578 which runs an editor, preferring
582 if they are set in the environment.
586 Caution should always be exercised when applying a rejected patch with
590 rejects a patch, it does so for a good reason. Even though
592 may be able to find a believable place to apply each textual change,
593 there is no guarantee that the result is correct in any semantic
594 sense. The result should always be inspected to make sure it is
599 .B " wiggle \-\-replace file file.rej"
601 This is the normal usage of
603 and will take any changes in
607 could not apply, and merge them into
610 .B " wiggle \-dp1 file file.rej"
612 This will perform a word-wise comparison between the
616 branch of the diff in
618 and display the differences. This allows you to see where a given
621 .B " wiggle \-\-merge \-\-help"
623 Get help about the merge function of
626 .B " wiggle \-\-browse \-\-patch update.patch"
630 file for patches and present a list of patched files which can be
631 browsed to examine each patch in detail.
634 can be integrated with
636 so that it is used as the default merge tool and diff tool.
637 This can be achieved by adding the following lines to
639 in the user's home directory.
644 name = "Wiggle flexible merging"
645 driver = wiggle \-o %A %A %O %B
650 cmd = wiggle \-B \-o $MERGED $LOCAL $BASE $REMOTE
652 cmd = wiggle \-Bd $LOCAL $REMOTE
667 for merges (which may be dangerous), you can add
674 .BR $HOME/.config/git/attributes .
681 was inspired by the following quote. However
685 you to wiggle a patch into place. It either does the wiggle itself,
686 or leave it for you to finish off.
689 The problem I find is that I often want to take
690 (file1+patch) -> file2,
691 when I don't have file1. But merge tools want to take
692 (file1|file2) -> file3.
693 I haven't seen a graphical tool which helps you to wiggle a patch
696 \-\- Andrew Morton - 2002
702 cannot read the extended unified-diff output that it produces for
707 cannot read the word-based merge format that it produces for \-\-merge
712 does not understand unicode and so will treat all non-ASCII characters
713 much the same as it treats punctuation - it will treat each one
714 as a separate word. The browser will not display non-ASCII characters
719 Neil Brown at Computer Science and Engineering at
720 The University of New South Wales, Sydney, Australia;
721 and later and SUSE, still in Sydney, Australia.
730 .IR gitattributes (5).
git / wiggle.git / blob