Wiggle 0.6 - first release

ANNOUNCE

@@ -0,0 +1,95 @@
+ANNOUNCE: wiggle - a tools for applying patches with conflicts
+
+I am pleased to announce the first public release of 'wiggle'.
+
+Wiggle is a program for applying patches that 'patch' cannot
+apply due to conflicting changes in the original.
+
+Wiggle will always apply all changes in the patch to the original.
+If it cannot find a way to cleanly apply a patch, it inserts it
+in the original in a manner similar to 'merge', and report an
+unresolvable conflict.  Such a conflict will look like:
+
+<<<<<<<
+Some text from
+the original file
+|||||||
+Some text that the patch changes
+=======
+Some text that is the result of the patch
+>>>>>>>
+
+with the meaning that the "text that the patch
+changes" was expected somewhere in the "text from the original 
+file" and should be replaced with "the result of the patch".
+
+wiggle analyses the file and the patch in terms of words rather than
+whole lines and so is able to find matches that patch is
+unable to find.  If a patch changes a word at the end of a line, and
+a word at the start of that line has been modified since the patch
+was made, then wiggle will have no trouble applying the patch.
+
+wiggle has proved very useful for back-porting patches that were
+generated for the development kernel, onto the stable kernel.
+Sometimes it does exactly the right thing with the patch.  When it doesn't
+it reports a conflict which is easy to resolve with an understanding of
+what the code and the patch were trying to achieve.
+
+Wiggle is available under the GPL and can be fetched from:
+
+   http://www.cse.unsw.edu.au/~neilb/source/wiggle/
+
+The name 'wiggle' was inspired by Andrew Morton's comment:
+
+   The problem I find is that I often want to take
+     (file1+patch) -> file2,
+   when I don't have file1.  But merge tools want to take
+     (file1|file2) -> file3.
+   I haven't seen a graphical tool which helps you to wiggle a patch
+   into a file.
+
+which google can find for you:
+ http://www.google.com/search?q=graphical+tool+which+helps+you+to+wiggle+a+patch
+
+It isn't a graphical tool, but it is a good first step.
+
+NOTES:
+
+This release contains a 'tests' directory with a number of test cases
+that have proved invaluable in developing the program and my
+understanding of the subtleties of some of the issues involved.  If you
+find a case where wiggle behaves sub-optimally (e.g. dumps core),
+please consider sending me a test case to add to the tests directory.
+
+This release also contains a script 'p' and accompanying 'p.help'.
+This is a script that I use for patch management for my kernel patches
+and it makes use of wiggle to allow me to apply patches that
+'patch' cannot manage.  It is included both as an example of
+how wiggle can be used, and as a tool that some might find useful.
+
+One shortcoming I find with wiggle is that I would like to be able
+to 'see' what it has done.  I would love it if someone were to write
+a program that allowed the results of wiggle to be visualised.
+The closest that I have come to imagining a workable UI is to
+have two side-by-side windows, one of which shows the original patch,
+and the other shows a "diff -u" of before and after wiggle has done it's
+thing, and to have these windows automatically aligned so that when
+a change is shown in one, the corresponding change appears in the other.
+Maybe something like tkdiff, but that knows about patches and knows
+about word-based diffs....
+
+Wiggle is also able to perform a function similar to 'diff' and show the 
+differences and similarities between two files.  It can show these differences
+and similarities at a word-by-word level.  The output format is not machine
+readable as the character sequences used to delimit inserted and deleted
+words are not quoted in the output.  Hence this format will probably change
+at some stage and should not be depended upon.
+
+If you read the source, beware of comments: they were probably written 
+while I was still trying to understand the issues myself, and so are 
+probably wrong and out-of-date.  I would like to review all the code and
+comments, but if I wait until I do that before releasing it, it'll never
+get released!
+
+NeilBrown
+The University of New South Wales

INSTALL

@@ -0,0 +1,11 @@
+
+To build and install wiggle, simply type:
+
+   make install
+
+This will install /usr/bin/wiggle and /usr/share/man/man1/wiggle.1
+
+You might like to inspect the Makefile and change
+   OptDbg=-ggdb
+to something that will compile faster code on your compter, such as
+   OptDbg=-O3 -march=pentium2

Makefile

@@ -0,0 +1,50 @@
+
+# Note on my Mobile Pentium II, -march=pentium2 delivers twice the performance of i386
+#OptDbg=-O3
+#OptDbg=-O3 -march=pentium2
+OptDbg=-ggdb
+CFLAGS=$(OptDbg) -Wall -Werror
+
+# STRIP = -s
+INSTALL = /usr/bin/install
+DESTDIR = 
+BINDIR  = /usr/bin
+MANDIR  = /usr/share/man
+MAN1DIR = $(MANDIR)/man1
+MAN5DIR = $(MANDIR)/man5
+
+all: wiggle wiggle.man test
+
+
+wiggle : wiggle.o load.o split.o extract.o diff.o bestmatch.o ReadMe.o merge.o
+wiggle.o load.o split.o extract.o diff.o bestmatch.o ReadMe.o merge.o : wiggle.h
+
+test: wiggle dotest
+	sh dotest
+
+wiggle.man : wiggle.1
+	nroff -man wiggle.1 > wiggle.man
+
+clean:
+	rm -f *.o *.man wiggle .version* version
+	find . -name core -o -name '*.tmp*' -o -name .tmp | xargs rm -f
+
+install : wiggle wiggle.1
+	$(INSTALL) -D $(STRIP) -m 755 wiggle $(DESTDIR)$(BINDIR)/wiggle
+	$(INSTALL) -D -m 644 wiggle.1 $(DESTDIR)$(MAN1DIR)/wiggle.1
+
+version : ReadMe.c wiggle.1
+	@rm -f version
+	@sed -n -e 's/.*wiggle - v\([0-9.]*\) - .*/\1/p' ReadMe.c > .version-readme
+	@sed -n -e 's/.*WIGGLE 1 "" v\([0-9.]*\)$$/\1/p' wiggle.1 > .version-man
+	@cmp -s .version-readme .version-man && cat .version-man > version || { echo Inconsistant versions.; exit 1;}
+
+dist : test clean version
+	mkdir -p DIST
+	rm -f DIST/wiggle-`cat version`
+	ln -s .. DIST/wiggle-`cat version`
+	tar czvf DIST/wiggle-`cat version`.tar.gz -h -C DIST --exclude RCS --exclude DIST wiggle-`cat version`
+	rm -f DIST/wiggle-`cat version`
+
+v : version
+	cat version

ReadMe.c

@@ -0,0 +1,143 @@
+/*
+ * wiggle - apply rejected patches
+ *
+ * Copyright (C) 2003 Neil Brown <[email protected]>
+ *
+ *
+ *    This program is free software; you can redistribute it and/or modify
+ *    it under the terms of the GNU General Public License as published by
+ *    the Free Software Foundation; either version 2 of the License, or
+ *    (at your option) any later version.
+ *
+ *    This program is distributed in the hope that it will be useful,
+ *    but WITHOUT ANY WARRANTY; without even the implied warranty of
+ *    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ *    GNU General Public License for more details.
+ *
+ *    You should have received a copy of the GNU General Public License
+ *    along with this program; if not, write to the Free Software
+ *    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
+ *
+ *    Author: Neil Brown
+ *    Email: <[email protected]>
+ *    Paper: Neil Brown
+ *           School of Computer Science and Engineering
+ *           The University of New South Wales
+ *           Sydney, 2052
+ *           Australia
+ */
+
+/*
+ * Options and help text for wiggle
+ */
+
+#include "wiggle.h"
+
+char Version[] = "wiggle - v0.6 - 20 May 2003\n";
+
+char short_options[]="xdmwlrh123pVRvq";
+struct option long_options[] = {
+	{"extract",	0, 0, 'x'},
+	{"diff",	0, 0, 'd'},
+	{"merge",	0, 0, 'm'},
+	{"words",	0, 0, 'w'},
+	{"lines",	0, 0, 'l'},
+	{"patch",	0, 0, 'p'},
+	{"replace",	0, 0, 'r'},
+	{"help",	0, 0, 'h'},
+	{"version",	0, 0, 'V'},
+	{"reverse",	0, 0, 'R'},
+	{"verbose",	0, 0, 'v'},
+	{"quiet",	0, 0, 'q'},
+	{0, 0, 0, 0}
+};
+
+char Usage[] =
+"Usage: wiggle --diff|--extract|--merge --lines|--words [--replace] files...\n";
+
+char Help[] =  "\n"
+"Wiggle - apply patches that 'patch' rejects.\n"
+"\n"
+"Wiggle provides three distinct but related functions:\n"
+"merge, diff, and extract.\n"
+"To get more detailed help on a function, select the function\n"
+"before requesting help.  e.g.\n"
+"    wiggle --diff --help\n"
+"\n"
+"Options:\n"
+"   --extract   -x    : select 'extract' function.\n"
+"   --diff      -d    : select 'diff' function.\n"
+"   --merge     -m    : select 'merge' function (default).\n"
+"\n"
+"   --words     -w    : word-wise diff and merge.\n"
+"   --lines     -l    : line-wise diff and merge.\n"
+"\n"
+"   --patch     -p    : treat last file as a patch file.\n"
+"   -1  -2  -3        : select which component of patch or merge to use.\n"
+"   --reverse   -R    : swap 'before' and 'after' for diff function.\n"
+"\n"
+"   --help      -h    : get help.\n"
+"   --version   -V    : get version of wiggle.\n"
+"   --verbose   -v    : (potentially) be more verbose.\n"
+"   --quiet     -q    : don't print un-necessary messages.\n"
+"\n"
+"   --replace   -r    : replace first file with result of merger.\n"
+"\n"
+"Wiggle needs to be given 1, 2, or 3 files.  Any one of these can\n"
+"be given as '-' to signify standard input.\n"
+"\n";
+
+char HelpExtract[] = "\n"
+"wiggle --extract -[123] [--patch]  merge-or-patch\n"
+"\n"
+"The extract function allows one banch of a patch or merge file\n"
+"to be extracted.  A 'patch' is the output of 'diff -c' or 'diff -u'.\n"
+"Either the before (-1) or after (-2) branch can be extracted.\n"
+"\n"
+"A 'merge' is the output of 'diff3 -m' or 'merge -A'.  Either the\n"
+"first, second, or third branch can be extracted.\n"
+"\n"
+"A 'merge' file is assumed unless --patch is given.\n"
+"\n";
+
+char HelpDiff[] = "\n"
+"wiggle --diff [-wl] [-p12] [-R]  file-or-patch [file-or-patch]\n"
+"\n"
+"The diff function will report the differencs and similarities between\n"
+"two files in a format similar to 'diff -u'.  With --word mode\n"
+"(the default) word-wise differences are displayed on lines starting\n"
+"with a '|'.  With --line mode, only whole lines are considered\n"
+"much like normal diff.\n"
+"\n"
+"If one file is given is it assumed to be a patch, and the two\n"
+"branches of the patch are extracted and compared.  If two files\n"
+"are given they are normally assumed to be whole files and are compared.\n"
+"However if the --patch option is given with two files, then the\n"
+"second is treated as a patch and the first or (with -2) second branch\n"
+"is extracted and compared against the first file.\n"
+"\n"
+"--reverse (-R) with cause diff two swap the two files before comparing\n"
+"them.\n"
+"\n";
+
+char HelpMerge[] = "\n"
+"wiggle --merge [-wl] [--replace]  file-or-merge [file-or-patch [file]]\n"
+"\n"
+"The merge function is the primary function of wiggle and is assumed\n"
+"if no function is explicitly chosen.\n"
+"\n"
+"Normally wiggle will compare three files on a word-by-word basis and\n"
+"output unresolvable conflicts in the resulting merge by showing\n"
+"whole-line differences.\n"
+"With the --lines option, the files are compared line-wise much\n"
+"like 'merge'.  With the --words option, files are compared\n"
+"word-wise and unresolvable conflicts are reported word-wise.\n"
+"\n"
+"If --merge is given one file, it is treated as a merge (merge -A\n"
+"output) and the three needed streams are extracted from it.\n"
+"If --merge is given two files, the second is treated as a patch\n"
+"file and the first is the original file.\n"
+"If --merge is given three files, they are each treated as whole files\n"
+"and differences between the second and third are merged into the first.\n"
+"This usage is much like 'merge'.\n"
+"\n";

TODO

@@ -0,0 +1,29 @@
+
+- extract.c should be able to extract half of a word-diff
+- extract.c should work on word-merges
+- review all test output to make sure it looks right
+- document 'p' DOING
+- can find_best be optimised more?
+- --verbose flag ?? what should it do?
+- review commented code and discard some of it
+- test on raid code
+- possibly encourage "###...####" onto line by itself in diff output
+- possibly remember match information while reading patch/merge
+  to help matching.
+- is there anything useful to be done with linenumber information?
+- document diff algorithm
+- document best-match algorithm
+- document merge algorithm
+- enhance 'p'
+  - editmail?  reviewmail
+  - review wiggle failures
+
+- Application of patch-03-MdRaid5Works caused some odd matches
+
+- possible verbosity:
+     report lines at which each patch was applied.??
+- add examples to man page
+
+- Design viewer.
+   Maybe:
+    3 windows: before, patch, after