Inside WordShell

If you want to get deeper into the innards of WordShell, then this is your place. The information here is for experts only, and hence is more technical. This page is intended only to describe WordShell’s practice – it is not a guaranteed specification; rather, being internal, it is subject to continuous change.

Theory of operation

WordShell works with the following assumptions:

  • The user leaves it up to WordShell to backup, store and cache information as it sees best.
  • WordShell is designed to be fault-tolerant; if an operation fails, it tries to achieve the same result in a different way. In particular we try to avoid assuming that the WordPress site is not broken; we try to work as much as possible through the filesystem and not assume that any PHP can be run. Operations do not fail until they need to.

Internal information stored

WordShell stores its information by default in ~/.wordshell.

Internally, WordShell works using plugin slugs, e.g. contact-form-7.

Inside WordShell’s directory, you may find the following files and directories, which are reasonably intuitive:

  • current: contains the last mirror of each known site. Files are fetched from here for restore operations; this is also the cache used when running from the cache (which happens if the last mirror operation was recent enough). Presently, plugins (the contents of wp-content/plugins) are stored, in current/plugins.
  • customimports.plugin: contains zips of plugins that have been manually imported (i.e. not fetched from
  • fromwporg.plugin: zips of plugins downloaded from Some plugin authors appear to update their plugins but not change the version number, which can cause confusion. WordShell tries to avoid the confusion by never re-downloading known plugins. You can force a re-download by deleting from here. Note that there may be symlinks from old into this directory.
  • lftp: the LFTP_HOME environment variable points to this folder when lftp is run (see ‘man lftp’). Thus you can use the file ‘rc’ in this folder to set any exotic FTP options you need; by default it enables use of TLS where available.
  • log: a log file used by WordShell to record its operations.
  • old.plugin: when a plugin is deleted or updated, the old version is stored here. If the old version was an unmodified version of a known plugin, then it may be a symlink into fromwporg (to save disk space). The filename indicates the site, plugin slug, time of the version, and the version number.
  • rc: WordShell’s configuration file, storing both site configurations and other options.
  • tmp: Temporary directory, subject to periodic automatic cleansing.
  • wp-wordshell-controller.php: A file that is uploaded to WP sites in order to provide an interface for remote operations (e.g. plugin activation, or core upgrading). This file is fetched from the Internet when first needed and afterwards not modified. Thus you are free to hack it as you see best.

When a plugin is needed, customimports is always searched before fromwporg – this means that you can always manually over-ride.

Leave a Reply