%META:TOPICINFO{author="ProjectContributor" date="1765968854" format="1.1" version="1"}%
---+!! PlainFileStoreContrib
%FORMFIELD{"Description"}%

%TOC%

<img src="http://upload.wikimedia.org/wikipedia/commons/f/f3/Open_cardboard_box_husky.png" class="foswikiRight" height="200" />

This is a full implementation of a Foswiki store that uses nothing more sophisticated than plain files and directories In the Foswiki spirit these files are organised in a simple and clear structure using intention-revealing file names.

Advantages:
   * Uses simple files - no shell commands used
   * Incorporates script for moving between store implementations

The traditional store implementations (!RcsLite and !RcsWrap) use a version control methodology called. RCS uses something called "deltas" to represent the differences between successive versions of topics. This has the advantage that the store is kept reasonably small, but there are some issues with these implementations:
   * !RcsWrap invokes external programs. These are reasonably fast, but can cause major performance problems when used with a web server accelerator, such as =fcgi= or =mod_perl=. Most sites using accelerators therefore 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 =data/web/topic.txt=, like in the RCS stores
   * Topic histories are in =data/web/topic,pfv/=
   * Attachments are in =pub/web/topic/attachment=, like in the RCS stores
   * Attachment histories are in =pub/web/topic/attachment,pfv/=
   * Meta-data is stored in a separate file =data/web/topic.m= or =pub/web/topic/attachment.m=
   * Histories consist of files numbered for the revision they store (each with a corresponding metafile)
The latest rev also has a history file (note: this means that
everything is stored at least twice; same as in the RCS stores)

%X%
   * Automatic attachment of files placed in pub directories is not supported
     for performance reasons.
   * Mapping the 'TWiki' web to the Foswiki 'System' web (as required for
     the !TWikiCompatibilityPlugin) is *not* supported. If you require
     TWiki compatibility, use one of the !RCSStoreContrib stores.

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

---++ Moving between store implementations

---+++ Foswiki &lt; 2.0

The =tools/bulk_copy.pl= script (part of the Foswiki 2.0 release package, or available from [[https://raw.githubusercontent.com/foswiki/distro/master/core/tools/bulk_copy.pl][github]] or ) allows you to move between different store implementations. *Do not* share data areas between different store implementations.

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

---++ Installation
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. "Extensions Operation and Maintenance" Tab -&gt; "Install, Update or Remove extensions" Tab.  Click the "Search for Extensions" button.  
Enter part of the extension name or description and press search.   Select the desired extension(s) and click install. If an extension is already installed, it will *not* show up in the
search results.

You can also install from the shell by running the extension installer as the web server user: (Be sure to run as the webserver user, not as root!)
<verbatim>
cd /path/to/foswiki
perl tools/extension_installer <NameOfExtension> install
</verbatim>

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 https://foswiki.org/Support/ManuallyInstallingExtensions for more help.


---++ Info

Many thanks to the following sponsors for supporting this work
   * [[http://c-dot.co.uk][C-Dot Consulting]]
   * [[http://www.taxonomy.org.au][TRIN]], The Taxonomy Research & Information Network

---++ Dependencies
<table border="1" class="foswikiTable"><tr><th>Name</th><th>Version</th><th>Description</th></tr><tr><td align="left">File::Copy::Recursive</td><td align="left">&gt;0</td><td align="left">Required</td></tr></table>

---++ Change History
%TABLE{columnwidths="7em" tablewidth="100%"}%
   1.48   (17 Dec 2025) | Foswikitask:Item15591: added flag to ignore oob changes |
|  1.47   (06 Aug 2023) | Foswikitask:Item15151: add warnings and strictness |
|  1.46   (08 Dec 2017) | Foswikitask:Item14554: remove link to unused wikiring.com domain. |
|  1.45   (06 Mar 2016) | Foswikitask:Item14008: Warn if <nop>FoswikiAttachPubFiles is enabled with the PlainFile store. |
|  1.44   (03 Feb 2016) | Released with Foswiki 2.1. Release notes, Copyright updates. |
|  1.43   (10 Dec 2015) | Foswikitask:Item13405 - NFC Normalize all UNICODE strings.<br/>\
                          Foswikitask:Item12569: Use NFKD normalization when sorting names. |
|  1.42   (08 Sep 2015) | Released with Foswiki 2.0.2. Foswikitask:Item13598 - Rename of symlinked web fails<br />\
                          Foswikitask:Item13697: Reject unsuported characters from web/topic and attachment filenames |
|  1.41   (27 Jul 2015) | Released with Foswiki 2.0.1<br/>\
                          Foswikitask:Item13516: Correct issues with attachment transfer, and when source store is Foswiki 2.0<br />\
                          Foswikitask:Item13541: Don't return directory names when listing attachments<br />\
                          Foswikitask:Item13547: Crash when copying an attachment without history |
|  1.40   (14 Jun 2015) | Released with Foswiki 2.0  Foswikitask:Item13405: Foswikitask:Item13378: utf-8 support<br />\
                          Foswikitask:Item13455: Don't encode filenames read from directories<br />\
                          Foswikitask:Item13432: Character encoding<br />\
                          Foswikitask:Item13423: Perl 5.22 deprecations<br /> |
| 1.2.1 (28 Feb 2013) | Foswiki:Tasks/Item12395: fix taint problems |
| 1.2.0 (21 Jun 2012) | Added change_store.pl script; Corrected TOPICNFO handling |
| 1.1.0 (30 Mar 2012) | Removed dependency on VC |
| 1.0.0 (23 Mar 2012) | Initial version |

%META:FORM{name="PackageForm"}%
%META:FIELD{name="Author" title="Author" value="CrawfordCurrie http://c-dot.co.uk"}%
%META:FIELD{name="Copyright" title="Copyright" value="&copy; 2012-2025 Crawford Currie, Foswiki Contributors"}%
%META:FIELD{name="Description" title="Description" value="Store Foswiki data using plain text files"}%
%META:FIELD{name="Home" title="Home" value="http://foswiki.org/Extensions/PlainFileStoreContrib"}%
%META:FIELD{name="License" title="License" value="GPL ([[http://www.gnu.org/copyleft/gpl.html][GNU General Public License]])"}%
%META:FIELD{name="Release" title="Release" value="15 Mar 2026"}%
%META:FIELD{name="Repository" title="Repository" value="https://github.com/foswiki/distro"}%
%META:FIELD{name="Support" title="Support" value="http://foswiki.org/Support/PlainFileStoreContrib"}%
%META:FIELD{name="Version" title="Version" value="1.48"}%
