diff options
Diffstat (limited to 'Tools/scripts/README.patchtool')
| -rw-r--r-- | Tools/scripts/README.patchtool | 136 |
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 +[...] |