wiggle.1

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