Dealing with changes/custom modifications to plugins

Frequently, developers will make customisations to plugins. This usually creates a problem – maintaining those customisations across updates; or even knowing that any customisations exist. WordShell eases the pain.

WordShell’s change management features, which include rollback/restore functions, provide you with a full backup and versioning system.

To use WordShell’s features for detecting and working with changes, you will need to have “diff” and “patch” programs installed. On Linux and many similar systems, these are provided by the GNU Diffutils package. Run “wordshell –checkrequirements” to see if you have them already.

How does WordShell know what an unmodified version is?

WordShell keeps a cache of plugin versions, and can obtain plugins from the WordPress plugins directory. It therefore knows about all plugins that can be obtained from there, plus all plugins that it has previously installed (whether from there, or third-party).

If WordShell cannot find a plugin version online or in its local cache, then it cannot know if the version you have installed on a site is modified or not. It will advise you in this case.

If you have an unmodified zip of a plugin and you wish WordShell to know about it, then simply copy it into the directory “customimports.plugin” in your WordShell working directory – by default, ~/.wordshell/customimports.plugin.

Note that for WordShel;, a modification means modified content, and not simply a changed date or changed whitespace. (In particular, WordShell calls out to diff using these flags: -BbuNr).

Detecting modified versions

You can audit your sites for modifications using the –checkmodifications switch. (One use of this would be to automate it using cron for security checks).

e.g.

wordshell mysite cart66-lite --checkmodifications

If the plugin has been modified, then you will see output like this:

mysite : Cart66 Lite        Installed: 1.4.8 (modified)

If there is no output, then there were no modifications. If you wish to list even unmodified plugins, then use –checkmodifications=showall, e.g.:

wordshell mysite all --checkmodifications=showall

Example output:

mysite : Cart66 Lite                Installed: 1.4.7 (modified) 
mysite : Cimy User Extra Fields     Installed: 2.3.7 (unmodified) 
mysite : Akismet                    Installed: 2.5.6 (unmodified) 
mysite : WP Super FAQ               Installed: 0.5.6 (unmodified)

Displaying modifications

To display the content of modifications, use –checkmodifications=view. The diff command used to produce the output will be shown, using more or less. (By default WordShell uses “more” for short output, and “less” for longer output). If you wish, you can then save that output by going into vi (press v when in more/less).

wordshell mysite cart66-lite --checkmodifications=view

Example output:

mysite : Cart66 Lite                      Installed: 1.4.7 (modified)
Press any key to view the modifications...
diff -BbuNr ./cart66.php ../../../current/mysite/plugins/cart66-lite/cart66.php
--- ./cart66.php        2012-05-03 01:22:50.0 +0300
+++ ../../../current/mysite/plugins/cart66-lite/cart66.php      2012-05-03 11:19:52.00 +0300
@@ -10,6 +10,7 @@
Domain Path: /languages/

------------------------------------------------------------------------
+This is an example change I made
Cart66 WordPress Ecommerce Plugin
Copyright 2011  Reality 66

If you wish to also view all the unmodified plugins then you can specify both “showall” and “view” by separating them by comma, i.e. –checkmodifications=showall,view

Upgrading plugins that have been modified

When WordShell is requested to update a plugin, it will detect if the existing (i.e. installed) plugin has been modified.

If a modification is detected, then you will be told. Note that sometimes plugin authors release new, different versions without changing the version number (they do this sometimes for tiny changes). So, do not be surprised if WordShell tells you about a modification if you were not aware of changing the plugin – it does not necessarily mean that someone has been tampering with your site!

When a change is found during an update operation, you will then be asked what to do, with the following question:

Choose an action: a=abort, v=view differences (less), p=apply patch to new version, c=continue with new version as is:

  • If you press a (abort), then WordShell will immediately exit.
  • If you press v (view differences), then WordShell will show you the changes from the pristine (unmodified) plugin to your installed (modified) version. You will then be asked the question again after seeing those changes.
  • If you press p (patch), then WordShell will create a patch of your changes, and attempt to apply them to the new version. If this does not work, then WordShell will instead create a patch of the changes between the pristine old version and pristine new version of the plugin, and try to apply those changes to your existing (modified) plugin. If that also fails, then you will be asked again what to do (you will be given the option to make manual changes). You can automatically choose the option by specifying –autopatch on the command-line; that switch is useful only if you know that your changes were small and likely to be easily transferred to the new version (e.g. if you update the same plugin on many sites and you know that the patch operation will work because you tested it once manually).
  • If you press c (continue), then WordShell will simply install the new version without making any modifications to it. Your changes will be discarded. This is useful if those changes are not needed (e.g. you were fixing a bug that is now fixed in the new version of the plugin). Sometimes also you did not modify the plugin, but the plugin author released a new version without changing the version number (plugin authors sometimes do this if they make trivial changes, e.g. changing a language string).

If you want to see more of what WordShell is doing internally, then you can add –debug to your command line. You can also add –dryrun to simply show what would have been done, but not touch your live WordPress installation. (Patches are still created, but not used).

Example run:

wordshell mysite cart66-lite --update --autopatch --latest

Output:

mysite : Cart66 Lite                 Installed: 1.4.7 (modified)
WARNING: mysite: cart66-lite: The plugin has apparently been modified from its original state.
New plugin version: 1.4.8
Testing applying patch from the pristine to installed version against the new version: OK
INFO: The patch applied successfully
Moving new plugin in: Done

Showing changes before updating

The above sections of this page have all been about modifications already made to plugins in your installed, live website. This next section is about something different: about showing what changes will be made when you update. i.e. About changes from your live website to the new plugin version.

This is a simple operation; simply add –showchanges to your update line.

e.g.

wordshell mysite myplugin --latest --showchanges

Example output:

mysite : My Plugin                      Installed: 1.0.8 (unmodified)
diff -BbduNr current/mysite/plugins/myplugin/myplugin.php tmp/./NEW-myplugin.ncVcy/myplugin/myplugin.php
--- current/mysite/plugins/myplugin/myplugin.php       2012-05-03 12:07:41.000000000 +0300
+++ tmp/./NEW-myplugin.ncVcy/myplugin/myplugin.php  2012-05-03 01:22:50.000000000 +0300
@@ -10,7 +10,6 @@

-Version: 1.0.8
+Version: 1.0.9

If you wish to have a chance to stop the update (or rollback, or restore) after viewing the changes, then add –confirm, and you will then be asked this question before the update proceeds:

Do you want to go ahead with the update operation? (c to continue, any other to abort):

Read next:

Leave a Reply

Site Map