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>
6 .\" Copyright (C) 2018-2020 Neil Brown <neil@brown.name>
9 .\" This program is free software; you can redistribute it and/or modify
10 .\" it under the terms of the GNU General Public License as published by
11 .\" the Free Software Foundation; either version 2 of the License, or
12 .\" (at your option) any later version.
14 .\" This program is distributed in the hope that it will be useful,
15 .\" but WITHOUT ANY WARRANTY; without even the implied warranty of
16 .\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
17 .\" GNU General Public License for more details.
19 .\" You should have received a copy of the GNU General Public License
20 .\" along with this program.
22 .\" Author: Neil Brown
23 .\" Email: <neil@brown.name>
27 wiggle \- apply rejected patches and perform word-wise diffs
29 .BI wiggle " [function] [options] file [files]"
33 is to apply a patch to a file in a similar manner to the
37 The distinctive difference of
39 is that it will attempt to apply a patch even if the "before" part of
40 the patch doesn't match the target file perfectly.
41 This is achieved by breaking the file and patch into words and finding
42 the best alignment of words in the file with words in the patch.
43 Once this alignment has been found, any differences (word-wise) in the
44 patch are applied to the file as best as possible.
48 will (in some cases) detect changes that have already been applied,
52 ensures that every change in the patch is applied to the target
53 file somehow. If a particular change cannot be made in the file, the
54 file is annotated to show where the change should be made in a similar
60 Each annotation contains 3 components: a portion of the original file
61 where the change should be applied, a portion of the patch that
62 couldn't be matched precisely in the file, and the text that should
63 replace that portion of the patch. These are separated by lines
64 containing precisely 7 identical characters, either '<', '|', '=',
65 or '>', possibly followed by a descriptive word. So
70 Some portion of the original file
74 text to replace it with
79 indicates that "text to replace" should be replaced by "text to
80 replace it with" somewhere in the portion of the original file.
83 was not able to find a place to make this change.
86 can also produce conflict reports showing only the words that are
87 involved rather than showing whole lines.
88 In this case the output looks like:
91 <<<---original|||old===new--->>>
98 to apply some patch, and to collect a list of rejects by monitoring
99 the error messages from patch. Then for each file for which a
100 reject was found, run
102 wiggle \-\-replace originalfile originalfile.rej
104 Finally each file must be examined to resolve any unresolved
105 conflicts, and to make sure the applied patch is semantically correct.
107 Alternately, the original patch file can be fed to the
111 wiggle \-B < patchfile
113 This will allow the changes and conflicts to be inspected and, to some
114 extent, modified; and then the results can be saved.
116 The following options are understood by
118 Some of these are explained in more detail in the following sections
119 on MERGE, DIFF, EXTRACT, and BROWSE.
121 .BR \-m ", " \-\-merge
122 Select the "merge" function. This is the default function.
124 .BR \-d ", " \-\-diff
125 Select the "diff" function. This displays the differences between
126 files. This can be given after
128 (see below) in which case a patch or diff of two files can be viewed
129 without the originals.
131 .BR \-x ", " \-\-extract
132 Select the "extract" function. This extracts one branch of a patch or
135 .BR \-B ", " \-\-browse
136 Select the "browse" function. This is similar to "merge" (or "diff")
137 only with a different presentation. Instead of the result simply
138 being sent to standard output, it is presented using an ncurses-based
139 GUI so that each hunk of the patch can be examined to understand what
140 conflicts where involved and what needed to be ignored in order of the
141 patch to be wiggled in to place.
143 .BR \-w ", " \-\-words
144 Request that all operations and display be word based. This is the
145 default for the "diff" function.
148 Request that words be defined as sequences of non-white-space. Without
149 this flag words are sequences of alphanumerics or single non-white-space
150 characters. This flag is enabled by automatically enabled if
152 needs to compare two files which both have more than 50,000 words.
154 .BR \-l ", " \-\-lines
155 Request that all operations and display be line based.
157 .BR \-b ", " \-\-ignore\-blanks
158 De-emphasise white space (space, tab, and newline) is determining
159 differences and changes.
162 Normally white space is treated like a word which can be matched or
163 changed by a patch. When this flag is in force, white space serves
164 only as a separator between other words and is not matched itself.
165 The effect of this is that changes in the amount of white space are
166 not treated as significant.
168 To be precise, any white space is combined with the preceding word
169 or, in the case of leading space on a line, with the following word.
170 However it is not involved in any comparisons of that word. If a patch
171 deletes a word, the attached white space is deleted as well. If a
172 patch adds a word, the attached white space is added as well.
174 An empty line, or one that contains only blanks, will be treated as a
175 single word that will match any other blank line, no matter how many
184 .BR \-p ", " \-\-patch
185 Treat the last named file as a patch instead of a file (with \-\-diff)
186 or a merge (\-\-extract).
193 requires there be exactly one file which is a patch and which can
194 contain patches to multiple files. The patches are merged into each
197 mode, this usage requires the
199 option as writing lots of merged files to standard-out is impractical.
202 When processing a multi-file patch,
204 can be followed by a numeric argument indicating how many file name
205 components should be stripped from files named in the patch file. If no
206 numeric argument is given,
208 will deduce an appropriate number based what files are present in the
212 .BR \-r ", " \-\-replace
213 Normally the merged output is written to standard-output. With
215 the original file is replaced with the merge output.
220 to always save the resulting merge when exiting.
223 Normally when an original file is replaced with the merged result, that
224 file is renamed to have a ".porig" extension, so that it is preserved.
225 If you don't want to keep the original, use this option to suppress
228 .BR \-o ", " \-\-output=
229 Rather than writing the result to stdout or to replace the original
230 file, this requests that the output be written to the given file.
231 This is only meaningful with
235 when given a single merge to browse.
238 This option overrides
242 .BR \-R ", " \-\-reverse
245 function, swap the files before calculating
253 attempts to revert changes rather than apply them.
256 If the files being compared are large, it can take a long time to
257 isolate the differences. Normally
259 will give up on perfection if a step take more than 20msec. To over-ride
260 this and always find the shortest edit-distance between two files, use the
264 .BR \-i ", " \-\-no\-ignore
265 Normally wiggle will ignore changes in the patch which appear to
266 already have been applied in the original. With this flag those
267 changes are reported as conflicts rather than being ignored.
269 .BR \-W ", " \-\-show\-wiggles
272 conflicts that can be wiggled into place are reported as conflicts
273 with an extra stanza which shows what the result would be if this flag
274 had not been used. The extra stanza is introduce with a line
275 containing 7 ampersand
282 Some portion of the original file
286 text to replace it with
288 Text that would result from a successful wiggle
294 .B \-\-report\-wiggles
295 If a merge is successful in applying all changes, it will normally exit
296 with a success status (0), only reporting failure (1) if a conflict
297 occurred and was annotated. With
298 .B \-\-report\-wiggles
300 will also report failure if any changes had to be wiggled in. This
303 is used for automatic merges as with
305 If any wiggles happen,
307 will report the failure, and the results can be examined to confirm
310 .BR \-h ", " \-\-help
311 Print a simple help message. If given after one of the function
317 help specific to that function is displayed.
319 .BR \-V ", " \-\-version
320 Display the version number of
323 .BR \-v ", " \-\-verbose
324 Enable verbose mode. Currently this makes no difference.
326 .BR \-q ", " \-\-quiet
327 Enable quiet mode. This suppresses the message from the merge
328 function when there are unresolvable conflicts.
331 can divide a text into lines or words when performing it's tasks.
332 A line is simply a string of characters terminated by a newline.
333 A word is either a maximal contiguous string of alphanumerics
334 (including underscore), a maximal contiguous string of space or tab
335 characters, or any other single character.
337 The merge function modifies a given text by finding all changes between
338 two other texts and imposing those changes on the given text.
342 focuses on which words have changed so as to maximise the possibility
343 of finding a good match in the given text for the context of a given
344 change. However it can consider only whole lines instead.
347 extracts the three texts that it needs from files listed on the
348 command line. Either 1, 2, or 3 files may be listed, and any one of
349 them may be a lone hyphen signifying standard-input.
351 If one file is given and the
353 option is not present, the file is treated as a
355 file, i.e. the output of "merge \-A" or "wiggle". Such a file
356 implicitly contains three streams and these are extracted and
359 If two files are given, then the first simply contains the primary
360 text, and the second is treated as a patch file (the output of "diff\ \-u"
361 or "diff\ \-c", or a ".rej" file from
363 and the two other texts
364 are extracted from that.
366 If one file is given together with the
368 option, the file is treated as a patch file containing the names of
369 the files that it patches. In this case multiple merge operations can
370 happen and each takes one stream from a file named in the patch, and
371 the other two from the patch itself. The
373 option is required and the results are written back to the
376 Finally if three files are listed, they are taken to contain the given
377 text and the two other texts, in order.
379 Normally the result of the merge is written to standard-output.
382 flag is given, the output is written to a file
383 which replaces the original given file. In this case the original file
384 will normally be renamed to have a
386 suffix (for "patched original" which makes sense if you first use
388 to apply a patch, and then use
390 to wiggle the rejects in). This can be suppressed with the
396 option is given with a file name, the output will be written to that
397 file. In this case no backup is created.
399 If no errors occur (such as file access errors)
401 will exit with a status of 0 if all changes were successfully merged,
402 and with an exit status of 1 and a brief message if any changes could
403 not be fully merged and were instead inserted as annotations.
405 .B \-\-report\-wiggles
410 will also exist with status of 1 if any changes had to be wiggled in
411 even though this was successful.
413 The merge function can operate in three different modes with respect
418 option, whole lines are compared and any conflicts
419 are reported as whole lines that need to be replaced.
423 option, individual words are compared and any
424 conflicts are reported just covering the words affected. This uses
425 the \f(CW <<<|||===>>> \fP conflict format.
427 Without either of these options, a hybrid approach is taken.
428 Individual words are compared and merged, but when a conflict is found
429 the whole surrounding line is reported as being in conflict.
432 will ensure that every change between the two other texts is reflected
433 in the result of the merge somehow. There are four different ways
434 that a change can be reflected.
442 is found at a suitable place in the original file, it is
445 This includes the possibility that
452 If a change is found which simply adds
454 and the text immediately preceding and following the insertion are
455 found adjacent in the original file in a suitable place, then
457 is inserted between those adjacent texts.
459 If a change is found which changes
463 and this appears (based on context) to align with
465 in the original, then it is assumed that this change has already been
466 applied, and the change is ignored. When this happens, a message
467 reflecting the number of ignored changes is printed by
469 This optimisation can be suppressed with the
473 If a change is found that does not fit any of the above possibilities,
474 then a conflict is reported as described earlier.
476 The diff function is provided primarily to allow inspection of the
479 calculated between texts and that it uses for performing a merge.
481 The output of the diff function is similar to the unified output of
482 diff. However while diff does not output long stretches of common text,
484 diff mode outputs everything.
486 When calculating a word-based alignment (the default),
488 may need to show these word-based differences. This is done using an
489 extension to the unified-diff format. If a line starts with a
490 vertical bar, then it may contain sections surrounded by special
491 multi-character brackets. The brackets "<<<++" and "++>>>" surround
492 added text while "<<<--" and "-->>>" surround removed text.
495 can be given the two texts to compare in one of three ways.
497 If only one file is given, then it is treated as a patch and the two
498 branches of that patch are compared. This effectively allows a patch
499 to be refined from a line-based patch to a word-based patch.
501 If two files are given, then they are normally assumed to be simple
502 texts to be compared.
504 If two files are given along with the \-\-patch option, then the second
505 file is assumed to be a patch and either the first (with \-1) or the
506 second (with \-2) branch is extracted and compared with text found in
509 This last option causes
511 to apply a "best-fit" algorithm for aligning patch hunks with the
512 file before computing the differences. This algorithm is used when
513 merging a patch with a file, and its value can be seen by comparing
514 the difference produced this way with the difference produced by first
515 extracting one branch of a patch into a file, and then computing the
516 difference of that file with the main file.
518 The extract function of
520 simply exposes the internal functionality for extracting one branch of
521 a patch or a merge file.
523 Precisely one file should be given, and it will be assumed to be a
526 is given, in which case a patch is assumed.
528 The choice of branch in made by providing one of
533 with obvious meanings.
535 The browse function of
537 presents the result of a merge or (with
539 a diff in a text-based GUI that can be
540 navigated using keystrokes similar to
545 The browser allows each of the two or three streams to be viewed individually
546 with colours used to highlight different sorts of text - green for
547 added text, red for deleted text etc. It can also show the patch by
548 itself, the full result of the merge, or the merge and the patch
551 The browser provides a number of context-sensitive help pages which
552 can be accessed by typing '?'
554 The top right of the GUI will report the type of text under the
555 cursor, which is also indicated by the colour of the text. Options
556 are Unchanged, Changed, Unmatched, Extraneous, AlreadyApplied and
557 Conflict. If the meanings of these are clear a little
558 experimentations should help.
560 A limited amount of editing is permitted while in
562 mode. Currently text that is unwanted can be discarded with
564 This will convert a Conflict or Change to Unchanged, and an Unmatched
565 to Changed (which effectively changes it to the empty string).
566 Similarly a text can be marked as wanted with
568 This will convert a Conflict or Extraneous to Changed. Using the same
569 key again will revert the change.
571 Finally, the uppercase
573 will revert all changes on the current line.
575 To make more sweeping changes you can use
577 which runs an editor, preferring
581 if they are set in the environment.
583 If you make any changes, then wiggle will ask you if you want
584 to save the changes, even if
588 Caution should always be exercised when applying a rejected patch with
592 rejects a patch, it does so for a good reason. Even though
594 may be able to find a believable place to apply each textual change,
595 there is no guarantee that the result is correct in any semantic
596 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.
643 name = "Wiggle flexible merging"
644 driver = wiggle \-o %A %A %O %B
649 cmd = wiggle \-B \-o $MERGED $LOCAL $BASE $REMOTE
651 cmd = wiggle \-Bd $LOCAL $REMOTE
665 for merges (which may be dangerous), you can add
672 .BR $HOME/.config/git/attributes .
676 was inspired by the following quote.
679 The problem I find is that I often want to take
680 (file1+patch) -> file2,
681 when I don't have file1. But merge tools want to take
682 (file1|file2) -> file3.
683 I haven't seen a graphical tool which helps you to wiggle a patch
686 \-\- Andrew Morton - 2002
691 cannot read the extended unified-diff output that it produces for
695 cannot read the word-based merge format that it produces for \-\-merge
699 does not understand unicode and so will treat all non-ASCII characters
700 much the same as it treats punctuation - it will treat each one
701 as a separate word. The browser will not display non-ASCII characters
704 Neil Brown at Computer Science and Engineering at
705 The University of New South Wales, Sydney, Australia;
706 and later at SUSE, still in Sydney, Australia.
714 .IR gitattributes (5).
git / wiggle.git / blob