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. :-)

Terminology

  • 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.

Installation

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.

Commands

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.

Worked Example

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.

When some filenames are in the list, pmedit <pattern> will load all the files from the list matching the pattern into your editor. So, pmedit *.js will load all the Javascript files in your working files set. Having edited the files and saved them, to get a diff to submit for review, execute pmdiff. It will produce a diff of only the files in the file list (handy if you are working on several things in the same directory). Use pmview to have a look at it.

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.

Original URL: http://www.gerv.net/software/patch-maker/quickstart.html