blob: 59ee672a443802497eff24e326fc5a1abed5799a (
plain) (
tree)
|
|
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 requested 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 (useful when creating new port).
$ cd /somewhere/foo ; make
[compilation blows with error in src/bar/baz.c]
$ cd work/foo-1.0/src/bar
[dig here and there and finally find that the problem in baz.c]
$ cp baz.c baz.c.orig
$ 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
[...]
|
