Add patchtool - a tool to automate generation/updating of patchfiles. This

tool has something in common with update-patches shell script, but has more
features and is more intelligent. See README.patchtool or source code for
details.

1 files changed, 136 insertions, 0 deletions

diff --git a/Tools/scripts/README.patchtool b/Tools/scripts/README.patchtool
new file mode 100644
index 000000000000..20388c2fde23
--- /dev/null
+++ b/Tools/scripts/README.patchtool
@@ -0,0 +1,136 @@
+INTRODUCTION
+------------
+Patchtool is a tool aimed to simplify common operations with patchfiles. It
+was designed using real world's experience with the subject and expected to be
+very handy for an active porter.
+
+
+MODES OF OPERATION
+------------------
+The tool has the following two basic modes of operation:
+o generation/update of patchfiles. In this mode user provides list of working
+  files for which patchfiles are to be generated and the tool generates or
+  updates corresponding patches automatically guessing if there is an original
+  version (.orig file, rcs(1)) or it is a completely new file;
+
+o automatic update of the existing patchfiles. In this mode user provides a
+  list of patchfiles or directories containing patchfiles and the tool
+  re-generates specified patches. In this mode the tool tries hard to guess
+  whether the patchfile in question is already up to date or not and updates
+  only those patchfiles, which are found to be outdated.
+
+The following options are supported:
+  -a -- automatically save resulting diff into a patchfile;
+  -f -- don't ask any question if target patchfile already exists and is to be
+        replaced;
+  -u -- run tool in the "update" mode (see above);
+  -i -- perform requiested operation (generate or update) even if the
+	patchfile seems to be up-to-date based on last modification time of
+	all files involved.
+
+The tool supports dozen environment variables that can be used to override
+default settings. You can find complete list at the top of patchtool.py,
+following are the most useful ones:
+PT_CVS_ID	-- CVS id to be added at the top of each patchfile generated
+		   ("FreeBSD");
+PT_DIFF_ARGS	-- diff(1) args used to generate patchfile ("-du");
+PT_DIFF_SUFX	-- suffix used to save original version of the file (".orig");
+
+
+KNOWN BUGS AND LIMITATIONS
+--------------------------
+o It is assumed that each patchfile contains exactly one diff, so the tool
+  may remove useful diffs when there are several diffs merged into one
+  patchfile. Actually I don't think that it is a bug, because Porter's
+  Handbook clearly demands to follow a "one diff - one patchfile" rule.
+  Perhaps portlint(1) should be extended to warn about such abuses;
+
+o only '+++' supported as the prefix for the name of target file in the
+  patchfile. Neither '***' nor 'Index:' are not recognised/supported yet;
+
+o please keep in mind that when you are trying to do automatic update and
+  some of the patches are for auto-generated/mangled files (e.g. configure
+  script in the situation when USE_LIBTOOL is used) then you would end up
+  with some of patchfiles containing bogus hunks;
+
+o by default the tool tries to recognise saved original version on the file
+  first by probing file with '.orig' suffix added and if it fails then by
+  probing file with ',v' suffix added. If you use other suffix to save
+  original version, for example '~', then set PT_DIFF_SUFX environment
+  variable to match your settings, otherwise the tool will not function
+  properly.
+
+
+REPORTING BUGS AND PROPOSING ENHANCEMENTS
+-----------------------------------------
+The author of the tool is Maxim Sobolev <sobomax@FreeBSD.org>. Any bug
+reports, patches, proposals or suggestions are encouraged. You can do it
+either contacting author directly at the e-mail above or submitting a FreeBSD
+problem report.
+
+
+EXAMPLES
+--------
+Following are several sample sessions which show common usage patterns for
+this tool.
+
+1. Generation mode (usefull when creating new port).
+$ cd /somewhere/foo ; make
+[compilation blows with error in src/bar/baz.c]
+$ cd work/foo-1.0/src/bar
+[digged here and there and finally have found a solution]
+$ vi baz.c
+[fixing it]
+$ patchtool baz.c
+[reading diff]
+$ patchtool -a baz.c
+Generating patchfile: patch-src_bar_baz.c...ok
+$ cd ../../../../
+$ make
+[works as expected, wow!]
+$ make install clean
+$ send-pr
+[...]
+
+2. Generation mode when target patchfile already exists (Minor port update).
+$ cd /somewhere/foo ; make
+[...]
+1 out of 4 hunks failed--saving rejects to Makefile.rej
+>> Patch patch-aa failed to apply cleanly.
+*** Error code 1
+$ cd work/foo-1.0
+[examining Makefile.rej]
+$ vi Makefile
+[merging changes by hand]
+$ patchtool Makefile
+[reading diff]
+$ patchtool -a Makefile
+Target patchfile "patch-aa" already exists, do you want to  replace it? [y/N]: y
+Generating patchfile: patch-aa...ok
+$ cd ../../
+$ make clean
+$ make install clean
+$ send-pr
+[...]
+
+3. "Gross" update mode (Major update, when several existing patches do not apply
+   cleanly).
+$ cd /somewhere/foo
+$ vi Makefile
+[increase PORTVERSION]
+$ make fetch makesum patch
+[several patches are failing to apply cleanly]
+$ cd work/foo-1.0
+[doing merging work, finally all changes are merged] 
+$ cd ../../ ; make all install
+[compile and works like a charm]
+$ pwd
+/somewhere/foo
+$ patchtool -u ./
+Updating patchfile: patch-aa
+Updating patchfile: patch-as
+Updating patchfile: patch-foo.c
+Updating patchfile: patch-foo_bar.c
+$ make clean
+$ send-pr
+[...]