ANNOUNCE

   1 ANNOUNCE: wiggle - a tool for applying patches with conflicts
   2
   3 I am pleased to announce the first public release of 'wiggle'.
   4
   5 Wiggle is a program for applying patches that 'patch' cannot
   6 apply due to conflicting changes in the original.
   7
   8 Wiggle will always apply all changes in the patch to the original.
   9 If it cannot find a way to cleanly apply a patch, it inserts it
  10 in the original in a manner similar to 'merge', and reports an
  11 unresolvable conflict.  Such a conflict will look like:
  12
  13 <<<<<<<
  14 Some text from
  15 the original file
  16 |||||||
  17 Some text that the patch changes
  18 =======
  19 Some text that is the result of the patch
  20 >>>>>>>
  21
  22 with the meaning that the "text that the patch changes"
  23 was expected somewhere in the "text from the original file"
  24 and should be replaced with "the result of the patch".
  25
  26 wiggle analyses the file and the patch in terms of words rather than
  27 whole lines and so is able to find matches that patch is
  28 unable to find.  If a patch changes a word at the end of a line, and
  29 a word at the start of that line has been modified since the patch
  30 was made, then wiggle will have no trouble applying the patch.
  31
  32 wiggle has proved very useful for back-porting patches that were
  33 generated for the development kernel, onto the stable kernel.
  34 Sometimes it does exactly the right thing with the patch.  When it doesn't
  35 it reports a conflict which is easy to resolve with an understanding of
  36 what the code and the patch were trying to achieve.
  37
  38 Wiggle is available under the GPL and can be fetched from:
  39
  40    http://www.cse.unsw.edu.au/~neilb/source/wiggle/
  41
  42 The name 'wiggle' was inspired by Andrew Morton's comment:
  43
  44    The problem I find is that I often want to take
  45      (file1+patch) -> file2,
  46    when I don't have file1.  But merge tools want to take
  47      (file1|file2) -> file3.
  48    I haven't seen a graphical tool which helps you to wiggle a patch
  49    into a file.
  50
  51 which google can find for you:
  52  http://www.google.com/search?q=graphical+tool+which+helps+you+to+wiggle+a+patch
  53
  54 It isn't a graphical tool, but it is a good first step.
  55
  56 NOTES:
  57
  58 This release contains a 'tests' directory with a number of test cases
  59 that have proved invaluable in developing the program and my
  60 understanding of the subtleties of some of the issues involved.  If you
  61 find a case where wiggle behaves sub-optimally (e.g. dumps core),
  62 please consider sending me a test case to add to the tests directory.
  63
  64 This release also contains a script 'p' and accompanying 'p.help'.
  65 This is a script that I use for patch management for my kernel patches
  66 and it makes use of wiggle to allow me to apply patches that
  67 'patch' cannot manage.  It is included both as an example of
  68 how wiggle can be used, and as a tool that some might find useful.
  69
  70 One shortcoming I find with wiggle is that I would like to be able
  71 to 'see' what it has done.  I would love it if someone were to write
  72 a program that allowed the results of wiggle to be visualised.
  73 The closest that I have come to imagining a workable UI is to
  74 have two side-by-side windows, one of which shows the original patch,
  75 and the other shows a "diff -u" of before and after wiggle has done it's
  76 thing, and to have these windows automatically aligned so that when
  77 a change is shown in one, the corresponding change appears in the other.
  78 Maybe something like tkdiff, but that knows about patches and knows
  79 about word-based diffs....
  80
  81 Wiggle is also able to perform a function similar to 'diff' and show the
  82 differences and similarities between two files.  It can show these differences
  83 and similarities at a word-by-word level.  The output format is not machine
  84 readable as the character sequences used to delimit inserted and deleted
  85 words are not quoted in the output.  Hence this format will probably change
  86 at some stage and should not be depended upon.
  87
  88 If you read the source, beware of comments: they were probably written
  89 while I was still trying to understand the issues myself, and so are
  90 probably wrong and out-of-date.  I would like to review all the code and
  91 comments, but if I wait until I do that before releasing it, it'll never
  92 get released!
  93
  94 NeilBrown
  95 The University of New South Wales