2 .\" wiggle - apply rejected patches
4 .\" Copyright (C) 2003 Neil Brown <neilb@cse.unsw.edu.au>
5 .\" Copyright (C) 2010 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; if not, write to the Free Software
20 .\" Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
22 .\" Author: Neil Brown
23 .\" Email: <neilb@cse.unsw.edu.au>
25 .\" School of Computer Science and Engineering
26 .\" The University of New South Wales
32 wiggle \- apply rejected patches and perform word-wise diffs
36 .BI wiggle " [function] [options] file [files]"
41 is to apply a patch to a file in a similar manner to the
45 The distinctive difference of
47 is that it will attempt to apply a patch even if the "before" part of
48 the patch doesn't match the target file perfectly.
49 This is achieved by breaking the file and patch into words and finding
50 the best alignment of words in the file with words in the patch.
51 Once this alignment has been found, any differences (word-wise) in the
52 patch are applied to the file as best as possible.
56 will (in some cases) detect changes that have already been applied,
60 ensures that every change in the patch is applied to the target
61 file somehow. If a particular change cannot be made in the file, the
62 file is annotated to show where the change should be made is a similar
66 Each annotation contains 3 components: a portion of the original file
67 where the change should be applied, a portion of the patch that
68 couldn't be matched precisely in the file, and the text that should
69 replace that portion of the patch. These are separated by lines
70 containing precisely 7 identical characters, either '<', '|', '=', or '>', so
75 Some portion of the original file
79 text to replace it with
85 indicates that "text to replace" should be replaced by "text to
86 replace it with" somewhere in the portion of the original file.
89 was not able to find a place to make this change.
92 can also produce conflict reports showing only the words that are
93 involved rather than showing whole lines.
94 In this case the output looks like:
97 <<<---original|||old===new--->>>
104 to apply some patch, and to collect a list of rejects by monitoring
105 the error messages from patch. Then for each file for which a
106 reject was found, run
108 wiggle \-\-replace originalfile originalfile.rej
110 Finally each file must be examined to resolve any unresolved
111 conflicts, and to make sure the applied patch is semantically correct.
114 The following options are understood by
116 Some of these are explained in more detail in the following sections
117 on MERGE, DIFF, and EXTRACT.
120 .BR -m ", " \-\-merge
121 Select the "merge" function. This is the default function.
125 Select the "diff" function. This displays the differences between files.
128 .BR -x ", " \-\-extract
129 Select the "extract" function. This extracts one branch of a patch or
133 .BR -w ", " \-\-words
134 Request that all operations and display be word based. This is the
135 default for the "diff" function.
138 .BR -l ", " \-\-lines
139 Request that all operations and display be line based.
142 .BR -p ", " \-\-patch
143 Treat the last named file as a patch instead of a file (with \-\-diff)
144 or a merge (\-\-extract).
147 .BR -r ", " \-\-replace
148 Normally the merged output is written to standard-output. With
149 \-\-replace, the original file is replaced with the merge output.
152 .BR -R ", " \-\-reverse
153 When used with the "diff" function, swap the files before calculating
155 When used with the "merge" function,
157 attempts to revert changes rather than apply them.
161 Print a simple help message. If given after one of the function
162 selectors (\-\-merge, \-\-diff, \-\-extract) help specific to that function
166 .BR -V ", " \-\-version
167 Display the version number of
171 .BR -v ", " \-\-verbose
172 Enable verbose mode. Currently this makes no difference.
175 .BR -q ", " \-\-quiet
176 Enable quiet mode. This suppresses the message from the merge
177 function when there are unresolvable conflicts.
181 can divide a text into lines or words when performing it's tasks.
182 A line is simply a string of characters terminated by a newline.
183 A word is either a maximal contiguous string of alphanumerics
184 (including underscore), a maximal contiguous string of space or tab
185 characters, or any other single character.
188 The merge function modifies a given text by finding all changes between
189 two other texts and imposing those changes on the given text.
193 considers words which have changed so as to maximise the possibility
194 of finding a good match in the given text for the context of a given
195 change. However it can consider only whole lines.
198 extracts the three texts that it needs from files listed on the
199 command line. Either 1, 2, or 3 files may be listed, and any one of
200 them may be a lone hyphen signifying standard-input.
202 If one file is given, it is treated as a
204 file, i.e. the output of "merge \-A" or "wiggle". Such a file
205 implicitly contains three streams and these are extracted and
208 If two files are given, then the first simply contains the primary
209 text, and the second is treated as a patch file (the output of "diff\ \-u"
210 or "diff\ \-c", or a ".rej" file from
212 and the two other texts
213 are extracted from that.
215 Finally if three files are listed, they are taken to contain the given
216 text and the two other texts, in order.
218 Normally the result of the merge is written to standard-output.
219 However if the "\-r" flag is given, the output is written to a file
220 which replaces the original given file. In this case the original file
223 suffix (for "patched original" which makes sense if you first use
225 to apply a patch, and then use
227 to wiggle the rejects in).
229 If no errors occur (such as file access errors)
231 will exit with a status of 0 if all changes were successfully merged,
232 and with an exit status of 1 and a brief message if any changes could
233 not be fully merged and were instead inserted as annotations.
235 The merge function can operate in three different modes with respect
240 option, whole lines are compared and any conflicts
241 are reported as whole lines that need to be replaced.
245 option, individual words are compared and any
246 conflicts are reported just covering the words affected. This used
247 the \f(CW <<<|||===>>> \fP conflict format.
249 Without either of these options, a hybrid approach is taken.
250 Individual words are compared and merged, but when a conflict is found
251 the whole surrounding line is reported as being in conflict.
254 will ensure that every change between the two other texts is reflected
255 in the result of the merge somehow. There are four different ways
256 that a change can be reflected.
264 is found at a suitable place in the original file, it is
267 This includes the possibility that
275 If a change is found which simply adds
277 and the text immediately preceding and following the insertion are
278 found adjacent in the original file in a suitable place, then
280 is inserted between those adjacent texts.
283 If a change is found which changes
287 and this appears (based on context) to align with
289 in the original, then it is assumed that this change has already been
290 applied, and the change is ignored. When this happens, a message
291 reflected the number of ignored changes is printed by
295 If a change is found that does not fit any of the above possibilities,
296 then a conflict is reported as described earlier.
300 The diff function is provided primarily to allow inspection of the
303 calculated between texts and that it uses for performing a merge.
305 The output of the diff function is similar to the unified output of
306 diff. However while diff does not output long stretches of common text,
308 diff mode outputs everything.
310 When calculating a word-based alignment (the default),
312 may need to show these word-based differences. This is done using an
313 extension to the unified-diff format. If a line starts with a
314 vertical bar, then it may contain sections surrounded by special
315 multi-character brackets. The brackets "<<<++" and "++>>>" surround
316 added text while "<<<--" and "-->>>" surround removed text.
319 can be given the two texts to compare in one of three ways.
321 If only one file is given, then it is treated as a patch and the two
322 branches of that diff are compared. This effectively allows a patch
323 to be refined from a line-based patch to a word-based patch.
325 If two files are given, then they are normally assumed to be simple
326 texts to be compared.
328 If two files are given along with the \-\-patch option, then the second
329 file is assumed to be a patch and either the first (with \-1) or the
330 second (with \-2) branch is extracted and compared with text found in
333 This last option causes
335 to apply a "best-fit" algorithm for aligning patch hunks with the
336 file before computing the differences. This algorithm is used when
337 merging a patch with a file, and its value can be seen by comparing
338 the difference produced this was with the difference produced by first
339 extracting one branch of a patch into a file, and then computing the
340 difference of that file with the main file.
345 The extract function of
347 simply exposes the internal functionality for extracting one branch of
348 a patch or a merge file.
350 Precisely one file should be given, and it will be assumed to be a
353 is given, in which case a patch is assumed.
355 The choice of branch in made by providing one of
360 with obvious meanings.
364 Caution should always be exercised when applying a rejected patch with
368 rejects a patch, it does so for a good reason. Even though
370 may be able to find a believable place to apply each textual change,
371 there is no guarantee that the result is correct in any semantic
372 sense. The result should always be inspected to make sure it is
377 .B " wiggle \-\-replace file file.rej"
379 This is the normal usage of
381 and will take any changes in
385 could not apply, and merge them into
388 .B " wiggle -dp1 file file.rej"
390 This will perform a word-wise comparison between the
394 branch of the diff in
396 and display the differences. This allows you to see where a given
399 .B " wiggle \-\-merge \-\-help"
401 Get help about the merge function of
405 The name of wiggle was inspired by the following quote, even though
406 wiggle does not (yet) have a graphical interface.
409 The problem I find is that I often want to take
410 (file1+patch) -> file2,
411 when I don't have file1. But merge tools want to take
412 (file1|file2) -> file3.
413 I haven't seen a graphical tool which helps you to wiggle a patch
416 \-\- Andrew Morton - 2002
422 cannot read the extended unified-diff output that it produces for
427 cannot read the word-based merge format that it produces for \-\-merge
432 Neil Brown at Computer Science and Engineering at
433 The University of New South Wales, Sydney, Australia
git / wiggle.git / blob