wiggle.1

   1 .\" -*- nroff -*-
   2 .\" wiggle - apply rejected patches
   3 .\"
   4 .\" Copyright (C) 2003 Neil Brown <neilb@cse.unsw.edu.au>
   5 .\"
   6 .\"
   7 .\"    This program is free software; you can redistribute it and/or modify
   8 .\"    it under the terms of the GNU General Public License as published by
   9 .\"    the Free Software Foundation; either version 2 of the License, or
  10 .\"    (at your option) any later version.
  11 .\"
  12 .\"    This program is distributed in the hope that it will be useful,
  13 .\"    but WITHOUT ANY WARRANTY; without even the implied warranty of
  14 .\"    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  15 .\"    GNU General Public License for more details.
  16 .\"
  17 .\"    You should have received a copy of the GNU General Public License
  18 .\"    along with this program; if not, write to the Free Software
  19 .\"    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
  20 .\"
  21 .\"    Author: Neil Brown
  22 .\"    Email: <neilb@cse.unsw.edu.au>
  23 .\"    Paper: Neil Brown
  24 .\"           School of Computer Science and Engineering
  25 .\"           The University of New South Wales
  26 .\"           Sydney, 2052
  27 .\"           Australia
  28 .\"
  29 .TH WIGGLE 1 "" v0.6
  30 .SH NAME
  31 wiggle \- apply rejected patches and perform word-wise diffs
  32
  33 .SH SYNOPSIS
  34
  35 .BI wiggle " [function] [options] file [files]"
  36
  37 .SH DESCRIPTION
  38 The main function of
  39 .I wiggle
  40 is to apply a patch to a file in a similar manner to the
  41 .BR patch (1)
  42 program.
  43
  44 The distinctive difference of
  45 .I wiggle
  46 is that it will attempt to apply a patch even if the "before" part of
  47 the patch doesn't match the target file perfectly.
  48 This is achieved by breaking the file and patch into words and finding
  49 the best alignment of words in the file with words in the patch.
  50 Once this alignment has been found, any differences (word-wise) in the
  51 patch are applied to the file as best as possible.
  52
  53 Also,
  54 .I wiggle
  55 will (in some cases) detect changes that have already been applied,
  56 and will ignore them.
  57
  58 .I wiggle
  59 ensures that every change in the patch is applied to the target
  60 file somehow.  If a particular change cannot be made in the file, the
  61 file is annotated to show where the change should be made is a similar
  62 way to the
  63 .BR merge (1)
  64 program.
  65 Each annotation contains 3 components: a portion of the original file
  66 where the change should be applied, a portion of the patch that
  67 couldn't be matched precisely in the file, and the text that should
  68 replace that portion of the patch.  These are separated by lines
  69 containing precisely 7 identical characters, either '<', '|', '=', or '>', so
  70 .in +5
  71 .nf
  72 .ft CW
  73 <<<<<<<
  74 Some portion of the original file
  75 |||||||
  76 text to replace
  77 =======
  78 text to replace it with
  79 >>>>>>>
  80 .ft
  81 .fi
  82 .in -5
  83
  84 indicates that "text to replace" should be replaced by "text to
  85 replace it with" somewhere in the portion of the original file.
  86 However
  87 .I wiggle
  88 was not able to find a place to make this change.
  89
  90 .I wiggle
  91 can also produce conflict reports showing only the words that are
  92 involved rather than showing whole lines.
  93 In this case the output looks like:
  94 .ft CW
  95 .ti +5
  96 <<<---original|||old===new--->>>
  97 .ft
  98
  99 A typical usage of
 100 .I wiggle
 101 is to run
 102 .I patch
 103 to apply some patch, and to collect a list of rejects by monitoring
 104 the error messages from patch.  Then for each file for which a
 105 reject was found, run
 106 .ti +5
 107 wiggle --replace originalfile originalfile.rej
 108
 109 Finally each file must be examined to resolve any unresolved
 110 conflicts, and to make sure the applied patch is semantically correct.
 111
 112 .SS OPTIONS
 113 The following options are understood by
 114 .IR wiggle .
 115 Some of these are explained in more detail in the following sections
 116 on MERGE, DIFF, and EXTRACT.
 117
 118 .TP
 119 .BR -m ", " --merge
 120 Select the "merge" function.  This is the default function.
 121
 122 .TP
 123 .BR -d ", " --diff
 124 Select the "diff" function.  This displays the differences between files.
 125
 126 .TP
 127 .BR -x ", " --extract
 128 Select the "extract" function.  This extracts one branch of a patch or
 129 merge file.
 130
 131 .TP
 132 .BR -w ", " --words
 133 Request that all operations and display be word based.  This is the
 134 default for the "diff" function.
 135
 136 .TP
 137 .BR -l ", " --lines
 138 Request that all operations and display be line based.
 139
 140 .TP
 141 .BR -p ", " --patch
 142 Treat the last named file as a patch instead of a file (with --diff)
 143 or a merge (--extract).
 144
 145 .TP
 146 .BR -r ", " --replace
 147 Normally the merged output is written to standard-output.  With
 148 --replace, the original file is replaced with the merge output.
 149
 150 .TP
 151 .BR -R ", " --reverse
 152 When used with the "diff" function, swap the files before calculating
 153 the differences.
 154 When used with the "merge" function,
 155 .I wiggle
 156 attempts to revert changes rather than apply them.
 157
 158 .TP
 159 .BR -h ", " --help
 160 Print a simple help message.  If given after one of the function
 161 selectors (--merge, --diff, --extract) help specific to that function
 162 is displayed.
 163
 164 .TP
 165 .BR -V ", " --version
 166 Display the version number of
 167 .IR wiggle .
 168
 169 .TP
 170 .BR -v ", " --verbose
 171 Enable verbose mode.  Currently this makes no difference.
 172
 173 .TP
 174 .BR -q ", " --quiet
 175 Enable quiet mode.  This suppresses the message from the merge
 176 function when there are unresolvable conflicts.
 177
 178 .SS WORDS
 179 .I wiggle
 180 can divide a text into lines or words when performing it's tasks.
 181 A line is simply a string of characters terminated by a newline.
 182 A word is either a maximal contiguous string of alphanumerics
 183 (including underscore), a maximal contiguous string of space or tab
 184 characters, or any other single character.
 185
 186 .SS MERGE
 187 The merge function modifies a given text by finding all changes between
 188 two other texts and imposing those changes on the given text.
 189
 190 Normally
 191 .I wiggle
 192 considers words which have changed so as to maximise the possibility
 193 of finding a good match in the given text for the context of a given
 194 change.  However it can consider only whole lines.
 195
 196 .I wiggle
 197 extracts the three texts that it needs from files listed on the
 198 command line.  Either 1, 2, or 3 files may be listed, and any one of
 199 them may be a lone hyphen signifying standard-input.
 200
 201 If one file is given, it is treated as a
 202 .B merge
 203 file, i.e. the output of "merge -A" or "wiggle".  Such a file
 204 implicitly contains three streams and these are extracted and
 205 compared.
 206
 207 If two files are given, then the first simply contains the primary
 208 text, and the second is treated as a patch file (the output of "diff\ -u"
 209 or "diff\ -c", or a ".rej" file from
 210 .IR patch )
 211 and the two other texts
 212 are extracted from that.
 213
 214 Finally if three files are listed, they are taken to contain the given
 215 text and the two other texts, in order.
 216
 217 Normally the result of the merge is written to standard-output.
 218 However if the "-r" flag is given, the output is written to a file
 219 which replaces the original given file. In this case the original file
 220 is renamed to have a
 221 .B .porig
 222 suffix (for "patched original" which makes sense if you first use
 223 .I patch
 224 to apply a patch, and then use
 225 .I wiggle
 226 to wiggle the rejects in).
 227
 228 If no errors occur (such as file access errors)
 229 .I wiggle
 230 will exit with a status of 0 if all changes were successfully merged,
 231 and with an exit status of 1 and a brief message if any changes could
 232 not be fully merged and were instead inserted as annotations.
 233
 234 The merge function can operate in three different modes with respect
 235 to lines or words.
 236
 237 With the
 238 .B --lines
 239 option, whole lines are compared and any conflicts
 240 are reported as whole lines that need to be replaced.
 241
 242 With the
 243 .B --words
 244 option, individual words are compared and any
 245 conflicts are reported just covering the words affected.  This used
 246 the \f(CW <<<|||===>>> \fP conflict format.
 247
 248 Without either of these options, a hybrid approach is taken.
 249 Individual words are compared and merged, but when a conflict is found
 250 the whole surrounding line is reported as being in conflict.
 251
 252 .I wiggle
 253 will ensure that every change between the two other texts is reflected
 254 in the result of the merge somehow.  There are four different ways
 255 that a change can be reflected.
 256 .IP 1
 257 If a change converts
 258 .B A
 259 to
 260 .B B
 261 and
 262 .B A
 263 is found at a suitable place in the original file, it is
 264 replaced with
 265 .BR B .
 266 This includes the possibility that
 267 .B B
 268 is empty, but
 269 not that
 270 .B A
 271 is empty.
 272
 273 .IP 2
 274 If a change is found which simply adds
 275 .B B
 276 and the text immediately preceding and following the insertion are
 277 found adjacent in the original file in a suitable place, then
 278 .B B
 279 is inserted between those adjacent texts.
 280
 281 .IP 3
 282 If a change is found which changes
 283 .B A
 284 to
 285 .B B
 286 and this appears (based on context) to align with
 287 .B B
 288 in the original, then it is assumed that this change has already been
 289 applied, and the change is ignored.  When this happens, a message
 290 reflected the number of ignored changes is printed by
 291 .IR wiggle .
 292
 293 .IP 4
 294 If a change is found that does not fit any of the above possibilities,
 295 then a conflict is reported as described earlier.
 296
 297 .SS DIFF
 298
 299 The diff function is provided primarily to allow inspection of the
 300 alignments that
 301 .I wiggle
 302 calculated between texts and that it uses for performing a merge.
 303
 304 The output of the diff function is similar to the unified output of
 305 diff.  However while diff does not output long stretches of common text,
 306 .IR wiggle 's
 307 diff mode outputs everything.
 308
 309 When calculating a word-based alignment (the default),
 310 .I wiggle
 311 may need to show these word-based differences.  This is done using an
 312 extension to the unified-diff format.  If a line starts with a
 313 vertical bar, then it may contain sections surrounded by special
 314 multi-character brackets.  The brackets "<<<++" and "++>>>" surround
 315 added text while "<<<--" and "-->>>" surround removed text.
 316
 317 .I wiggle
 318 can be given the two texts to compare in one of three ways.
 319
 320 If only one file is given, then it is treated as a patch and the two
 321 branches of that diff are compared.  This effectively allows a patch
 322 to be refined from a line-based patch to a word-based patch.
 323
 324 If two files are given, then they are normally assumed to be simple
 325 texts to be compared.
 326
 327 If two files are given along with the --patch option, then the second
 328 file is assumed to be a patch and either the first (with -1) or the
 329 second (with -2) branch is extracted and compared with text found in
 330 the first file.
 331
 332 This last option causes
 333 .I wiggle
 334 to apply a "best-fit" algorithm for aligning patch hunks with the
 335 file before computing the differences.  This algorithm is used when
 336 merging a patch with a file, and its value can be seen by comparing
 337 the difference produced this was with the difference produced by first
 338 extracting one branch of a patch into a file, and then computing the
 339 difference of that file with the main file.
 340
 341
 342 .SS EXTRACT
 343
 344 The extract function of
 345 .I wiggle
 346 simply exposes the internal functionality for extracting one branch of
 347 a patch or a merge file.
 348
 349 Precisely one file should be given, and it will be assumed to be a
 350 merge file unless
 351 .B  --patch
 352 is given, in which case a patch is assumed.
 353
 354 The choice of branch in made by providing one of
 355 .BR -1 ,
 356 .BR  -2 ,
 357 or
 358 .B -3
 359 with obvious meanings.
 360
 361 .SH WARNING
 362
 363 Caution should always be exercised when applying a rejected patch with
 364 .IR wiggle .
 365 When
 366 .I patch
 367 rejects a patch, it does so for a good reason.  Even though
 368 .I wiggle
 369 may be able to find a believable place to apply each textual change,
 370 there is no guarantee that the result is correct in any semantic
 371 sense.  The result should always be inspected to make sure it is
 372 correct.
 373
 374 .SH EXAMPLES
 375
 376 .B "  wiggle --replace file file.rej"
 377 .br
 378 This is the normal usage of
 379 .I wiggle
 380 and will take any changes in
 381 .B file.rej
 382 that
 383 .I patch
 384 could not apply, and merge them into
 385 .BR file .
 386
 387 .B "  wiggle -dp1 file file.rej"
 388 .br
 389 This will perform a word-wise comparison between the
 390 .B file
 391 and the
 392 .I before
 393 branch of the diff in
 394 .B file.rej
 395 and display the differences.  This allows you to see where a given
 396 patch would apply.
 397
 398 .B "   wiggle --merge --help"
 399 .br
 400 Get help about the merge function of
 401 .IR wiggle .
 402
 403 .SH QUOTE
 404 The name of wiggle was inspired by the following quote, even though
 405 wiggle does not (yet) have a graphical interface.
 406
 407 .nf
 408 The problem I find is that I often want to take
 409   (file1+patch) -> file2,
 410 when I don't have file1.  But merge tools want to take
 411   (file1|file2) -> file3.
 412 I haven't seen a graphical tool which helps you to wiggle a patch
 413 into a file.
 414
 415 -- Andrew Morton - 2002
 416 .fi
 417
 418 .SH SHORTCOMINGS
 419 .IP -
 420 .I wiggle
 421 cannot read the extended unified-diff output that it produces for
 422 --diff --words.
 423
 424 .IP -
 425 .I wiggle
 426 cannot read the word-based merge format that it produces for --merge
 427 --words.
 428
 429 .SH AUTHOR
 430
 431 Neil Brown at Computer Science and Engineering at
 432 The University of New South Wales, Sydney, Australia
 433
 434 .SH SEE ALSO
 435 .IR patch (1),
 436 .IR diff (1),
 437 .IR merge (1),
 438 .IR wdiff (1),
 439 .IR diff3 (1).