A store implementation using plain text files for all versions of a topic

An implementation of a Foswiki store using nothing more sophisticated than files.

  • Uses simple files - no shell commands used
  • Incorporates script for moving between store implementations

The usual store implementations (RcsLite and RcsWrap) use a version control tool - RCS. There are some issues with these implementations:
  • RcsWrap invokes external programs. These are reasonably fast, but cause major performance problems when used with a web server accelerator, such as fcgi or mod_perl. Most sites therefor use:
  • RcsLite, which is a pure-perl implementation of RCS. This doesn't use any external programs but is very inefficient with topics that have large numbers of versions.

The PlainFileStoreContrib implements topic and attachment histories by keeping a complete file for each version of the topic/attachment. This means it is less efficient in terms of disk space than RCS - at least, it is less efficient for text files; binary files, such as images, are equal. For many sites this is an acceptable tradeoff, as disk space is relatively cheap, and Foswiki doesn't use much even with this store.

  • Webs map to directories, like in the RCS stores
  • Topics are stored in web/topic.txt, like in the RCS stores
  • Topic histories are in web/topic,pfv/
  • Attachments are in web/topic/attachment, like in the RCS stores
  • Attachment histories are in web/topic/attachment,pfv/
  • Histories consist of files numbered for the revision they store
The latest rev also has a history file (note: this means that everything is stored at least twice; same as in the RCS stores)

There is currently no way to move from an RCS-based store to a PlainFile store, so this extension has to be regarded as experimental at this stage. If there is sufficient interest, I will develop tools to support migration to and from RCS histories.

Developers note: this contrib is tested using the standard store unit tests.

Moving between store implementations

The =tools/change_store = script included in this module allows you to move between different store implementations. The script uses internal, unpublished store APIs.

To support source and destination store implementations that both use files on disc pointed at by {DataDir} and {PubDir}, the the script supports redirecting the output of the conversion to a different directory.

Run the script without parameters to get instructions:

$ tools/ -I lib

Developer Notes

Testing is performed using the standard system tests. Because some of these tests are written assuming a broken store (the RCS based stores have problems with "inconsistent topics") they are known to fail with the PlainFileStore. The tests that are relevant to this store are:
  • HierarchicalWebsTests
  • StoreImplementationTests
  • StoreTests
A subset of the VC* store tests may also be run as a sanity check, but expect failures as this store maintains a correct version history, unlike the RCS stores.


You do not need to install anything in the browser to use this extension. The following instructions are for the administrator who installs the extension on the server.

Open configure, and open the "Extensions" section. Use "Find More Extensions" to get a list of available extensions. Select "Install".

If you have any problems, or if the extension isn't available in configure, then you can still install manually from the command-line. See for more help.


Many thanks to the following sponsors for supporting this work

Author: CrawfordCurrie
Copyright © 2012-2013 Crawford Currie
License: GPL (GNU General Public License)
Version: 1.2.1
Change History:  
1.2.1 (28 Feb 2013) Foswiki:Tasks/Item12395: fix taint problems
1.2.0 (21 Jun 2012) Added script; Corrected TOPICNFO handling
1.1.0 (30 Mar 2012) Removed dependency on VC
1.0.0 (23 Mar 2012) Initial version

Topic revision: r2 - 15 Jun 2015, GeorgeClark

The copyright of the content on this website is held by the contributing authors, except where stated elsewhere. see CopyrightStatement. Creative Commons License