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

%TOC%

*Foswiki 2.0 and later only*

This is the modern implementation of the classic Foswiki RCS based store. It has been moved into a contrib as other store implementations have emerged, and the RCS store's status as "the one and only" store implementation has been eroded.

---++ Managing Topics
The =Trash= web should be be cleared periodically, by archiving (saving) the text and RCS files if required (recommended), then deleting them from the =pub/Trash= and =data/Trash= directories.

<div class="foswikiHelp">%X% This can only be done from on the server, not through the browser. %T% Be sure to recreate the empty !TrashAttachments after you remove it.

%T% Since simple FTP access to the ==Trash== directory is all that is required for maintenance, it is possible to grant =Trash= admin privileges to multiple users, while strictly limiting server access.</div>

---++ Performance

The RCS Store can be quite resource intensive, especially for topics with large numbers of revisions, or for large binary files, where rcs is unable to caluculate a difference for the change.
The RCSStoreContrib implements two versions of RCS based stores:
   $ =RcsWrap=: A Perl wrapper for the system "rcs" tools. It uses "fork" to run the system =rcs= commands under the control of Foswiki. It is generally not recommended
   on systems running with mod_perl, and is unavailable on Windows.
   $ =RcsLite=: A pure Perl implementation of RCS. It avoids the "fork" overhead and is preferred in a "Persistent Perl" environment like mod_perl.
   It works well when working with small revision histories. However very large histories, such as created with large binary attachments, or topics like !WebStatistics which can have a high volume of changes can be extremely
   slow due to RCSLite loading the revision history into memory.

Each of the RCS implementations have their own strengths, but neither is ideal. Foswiki 2.0 now ships with a new PlainFileStoreContrib. This is the default
for new Foswiki sites, and comes with migration tools to convert away from RCS based stores.

---+++ !RcsLite

There is a configuration option embedded in the RCSLite module that can significantly improve performance, It is not enabled by default because it
will disable the capability of storing a revision comment with each save. The developers do not believe that Foswiki uses this feature, but as it might be used by
non-default extensions, it has not been disabled.

To improve performance, (and disable storage of save comments) apply the following patch. Paste it into a file named ="patchrcs"= in your Foswiki installation directory,
and then apply the patch by running =patch -p0 < patchrcs=. You can also just edit the file directly and change the =0;= to =1;=, around line 105.

<verbatim>
diff lib/Foswiki/Store/Rcs/RcsLiteHandler.pm lib/Foswiki/Store/Rcs/RcsLiteHandler.pm
--- lib/Foswiki/Store/Rcs/RcsLiteHandler.pm
+++ lib/Foswiki/Store/Rcs/RcsLiteHandler.pm
@@ -102,7 +102,7 @@ use Foswiki::Sandbox ();
 # doesn't actually use that part of the info record for anything much. We could rework the store API to
 # separate the log info, but it would be a lot of work. Using this constant you can ignore the log info in
 # getInfo calls. The tests will fail, but the core will run a lot faster.
-use constant CAN_IGNORE_COMMENT => 0;    # 1
+use constant CAN_IGNORE_COMMENT => 1;    # 1

 #
 # As well as the field inherited from Rcs::Handler, the object for each file
</verbatim>

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


---++ 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.23 (17 Nov 2023): | Foswikitask:Item15228: better error reporting in RCS store |
|  1.22 (31 Mar 2022): | Foswikitask:Item15076: RCS store does not properly encode topic information |
|  1.21 (30 Sep 2021): | Foswikitask:Item15045: getRevisionInfo of an attachment always returned the revision info of the first attachment of a topic |
|  1.20 (24 Jan 2021): | Foswikitask:Item15010: accept rcs versions &gt; 5.10 |
|  1.10 (5 Jan 2018): | Foswikitask:Item14591: Fixed loading old revisions |
|  1.06 (4 Apr 2017): | Foswikitask:Item14368: Failure to handle edge cases leads to obscure bug. |
|  1.05 (26 Nov 2016): | Released wth Foswiki 2.1.3<br>\
                         Foswikitask:Item14066: performance issue sorting topic list based on NFKD. |
|  1.04 (06 Mar 2016): | Foswikitask:Iem14008: Error if !FoswikiAttachPubFiles is enabled with a non-RCS store. |
|  1.03 (03 Feb 2016): | Released with Foswiki 2.1, Foswikitask:Item13405 - NFC Normalize all UNICODE strings.<br/>\
                         Foswikitask:Item12569: Use NFKD normalization when sorting names.<br/>\
                         Foswikitask:Item13894: Fix double-encoding of attachment comments.<br/>\
                         Foswikitask:Item13870: Foswikitask:Item13927: Fixes to configure checkers |
|  1.01 (11 Sep 2015): | Foswikitask:Item13697: Reject unsupported characters from web/topic and attachment filenames.<br/>\
                         Foswikitask:Item13728: Rename fails for symlinked attachments. |
|  1.00 (10 May 2013): | Initial version, abstracted from core |

%META:FORM{name="PackageForm"}%
%META:FIELD{name="Author" title="Author" value="ProjectContributor"}%
%META:FIELD{name="Copyright" title="Copyright" value="&copy; 2015-2023 Foswiki Contributors, All Rights Reserved"}%
%META:FIELD{name="Description" title="Description" value="A wiki topic and attachment store using the RCS revision control system"}%
%META:FIELD{name="Home" title="Home" value="http://foswiki.org/Extensions/RCSStoreContrib"}%
%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/RCSStoreContrib"}%
%META:FIELD{name="Version" title="Version" value="1.23"}%
