Patch Maker Quickstart
Patch Maker is a tool which encapsulates and accelerates common software development operations when using CVS or SVN. It helps you:
- keep track of any number of patches
- switch easily between working on different patches without clashes
- keep records of your work, so you never lose anything
- know which changes belong to which patch
- search only the relevant files for a particular string
- merge and extract your changes for attaching to bugs
Believe me, it's worth the effort of reading this page - this software has the potential to save you a ridiculous amount of time if you work with many patches at once. :-)
- patchref - a short string by which a patch is identified. Bug numbers make very good patchrefs.
- file list - a list of the paths of all the files involved in the current patch
Patch Maker keeps two files relating to each patch - the file list, mentioned above, named <patchref>.files, and the latest results of the pmdiff command, named <patchref>.diff. Both files are kept in the data directory, specified in your .pmrc file.
You need a copy of CVS or SVN and a working checked-out tree of the software you are working on. Getting these things is beyond the scope of this document.
You need Perl. Move the pm script somewhere on your path. Create a .pmrc file to match your setup. This allows you to define things like your favourite editor, and where you want Patch Maker to keep its files.
Change to the directory where you put the script, and run perl pm --init. This will create symlinks or batch files as appropriate, which let you use the "short form" Patch Maker commands. If you are on Windows and using the cygwin bash shell instead of the DOS prompt, you might like to ignore the batch files and set up aliases in your .bashrc instead.
See the Command Reference for a list of Patch Maker commands.
pmlist has a handy feature if you are testing or
working on other people's patches. Save their patch as
patchref.diff in your data directory, and pmswitch to a new
patchref. Run pmlist. Patch Maker will understand you've
grabbed someone else's patch, and populate the file list with the
names of the files referenced in the patch.
Here's an example use which shows off most of the features (using the long names for all command, for clarity.) You start in the root of your CVS sandbox. You use pmswitch <patchreference> to tell Patch Maker you are working on a particular patch. Bug numbers make particularly good patch references; you shouldn't use any characters in a patch reference that aren't allowed in filenames. Once you are working on that patch, you run pmlist to see you have no files. So use pmadd <pathname> to add some.
If you need to attach the patches to a bug, you'll find them
called <patchref>.diff in the Patch Maker data
directory that you specified in the script at install time.
Trying It Out
This is a step-by-step hands-on tutorial using Mozilla as an example. It could probably be followed using other bits of software.
- This is a non-destructive test :-)
- Change to your Mozilla source directory.
- Execute pms test. Patch Maker will tell you that you are working on patch "test".
- Confirm this with pmw.
- Execute pma xpfe/browser/resources/content/navigator.xul.
- Save the file list.
- Run a pmu to make sure you have the latest version of this file.
- Execute pme. Notice that navigator.xul appears in your editor. Try pme foo to see that you have no files that match "foo".
- Make some changes to navigator.xul - search for "&mainWindow.title;" and replace that string with "MyBrowser".
- Then, execute pmd and pmv. You should now have an editor window with a unified diff showing the changes you made.
- Execute pmc to watch your new version get copied into your Mozilla install.
- Change navigator.xul again (adding a space will do) and save it.
- Run Mozilla.
- You should have a Mozilla titled "MyBrowser".
- You could attach your patch to a Bugzilla bug by fishing it out of your Patch Maker data directory.