Table of Contents
You can use Subversion at several levels: you can export code from the public VuFind repository as an easy way of loading it onto a server, you can check out code from the public repository in order to see its history and (with proper permissions) contribute changes, or you can run your own local Subversion repository to manage your local changes through the vendor branching strategy.
After creating a repository on your subversion-server, you'll need to do a checkout of the (still empty) repository into a path of your choice, thus creating a working copy of your repository. Inside this working copy you can build a subdirectory-structure suitable to your project.
Subversion is a powerful and useful tool, and it's worth taking the time to learn about it if you expect to be doing complex customization of VuFind. The free Version Control with Subversion book is a great starting point.
Exporting from Subversion
When you want to get the latest files out of a Subversion repository without also loading all of the metadata about their history, you perform an export operation. This is the appropriate option when you want to deploy code to a server and do not expect to make any modifications directly on that server.
The command to export VuFind's latest code is simple:
svn export https://vufind.svn.sourceforge.net/svnroot/vufind/trunk vufind
- “vufind” is the directory where you want the code to end up.
- You can add a –force switch if you want to overwrite any existing files in the vufind directory.
You check out code from a Subversion repository when you plan on changing it and want to keep track of its history. There are several popular Subversion clients that simplify the checkout process, including Eclipse (with Subclipse), Tortoise SVN and Rapid SVN. If you don't want to use a fancy graphical tool, there's also the good ol' command line.
Command Line Checkout
Change to the directory where you want to work on your Vufind instance and then run this command:
svn co https://vufind.svn.sourceforge.net/svnroot/vufind/trunk vufind
This will check out the Vufind source into a folder named vufind.
Vendor branching is a useful strategy for merging changes to an external project (i.e. VuFind) with changes to a local project (i.e. your own VuFind-based catalog). In other words, it's a way of keeping up with external developments without having to rewrite all of your local changes. To take advantage of this, you need your own Subversion server. The general idea is that when you set up your project, you should first create a “vendor” directory and populate it with the third party code. The “trunk” directory that you do your development in should be established as a copy of the “vendor” directory. Whenever the vendor code changes, you load the latest third-party code into the “vendor” directory and then combine those changes with your customized “trunk” by using Subversion's powerful merging capabilities. The more often you merge, the easier it will be to keep your customizations intact.
It sounds complicated at first, but it makes more sense when you understand version control in general. This is highly recommended if you plan on maintaining a complex VuFind installation over the long term! For more details, see the vendor branching chapter of the very helpful Version Control with Subversion book.
Upgrading an Old Custom VuFind Version Using Subversion
The best upgrade strategy depends on the tools you are using, the scope of the changes, and which versions of VuFind are involved.
To get started, there two possible approaches:
Option A: Rely on Subversion
- 1.) Determine which version of VuFind you originally modified. Download this code into a Subversion directory called “vendor” and commit it.
- 2.) Branch “vendor” to “trunk”.
- 3.) Copy your customized version of VuFind into the trunk directory, overwriting the files that were branched there by Subversion. Commit the resulting changes.
- 4.) Download the version of VuFind you wish to upgrade to into the “vendor” directory. Commit the changes.
- 5.) Merge “vendor” into “trunk.” Resolve conflicts. Commit. You’re done!
Sample commands to upgrade VuFind 1.0 to current trunk (assumes that you start out in an appropriate SVN working directory – note that this working directory should be from YOUR OWN Subversion repository, not the public VuFind one):
# Initialize vendor directory: svn export https://vufind.svn.sourceforge.net/svnroot/vufind/releases/VuFind-1.0/ vendor svn add vendor svn commit -m"Initial load of VuFind 1.0" # Branch to trunk: svn copy vendor trunk svn commit -m"Branched vendor to trunk" # Copy your own files and update the trunk -- note that this cp command is an example # but isn't really the best way to do this (it will pull in unwanted things like the # Solr index and cache directories -- you should be more selective). cp -r /usr/local/vufind/* trunk svn add --force --depth infinity trunk svn commit -m"Local customizations" # Load the latest version of VuFind: svn export --force https://vufind.svn.sourceforge.net/svnroot/vufind/trunk/ vendor svn add --force --depth infinity vendor svn commit -m"Latest public trunk" # Merge new changes into trunk (note that if this is not a fresh repository, you may # need to replace "vendor@1" with a different revision number): svn merge vendor@1 vendor@HEAD trunk svn commit -m"Merged latest public trunk"
The problem is that step 5 may or may not be difficult, depending on how drastic your changes have been and how many versions of VuFind you are upgrading through. Also note that your trunk may end up with some unwanted files because loading a new copy of VuFind into your “vendor” directory won’t automatically delete any files that have become obsolete. It may be useful to occasionally run a tool like WinMerge (described below in Option B) to locate and eliminate these files.
Option B: Manually Reintegrate Diffs
- 1.) Determine which version of VuFind you originally modified. Download this code to a temporary folder.
- 2.) Use a comparison tool like WinMerge to recursively compare your custom VuFind code to the original code.
- 3.) Download the latest version of VuFind into a Subversion directory called “vendor” and commit it.
- 4.) Branch “vendor” to “trunk”.
- 5.) Manually reapply the changes revealed by WinMerge to your new trunk code.
- 6.) Commit trunk.
This approach is better for a small number of changes or after many VuFind releases have passed.
Regardless of which approach you take, once you are done, you are all set to begin using the Subversion vendor branching strategy to keep things up to date. If you want to stay on the cutting edge, you should get into the habit of keeping up to date with the trunk – the more often you merge, the less painful the process should be! Get involved with the vufind-tech mailing list so that you can ask questions about recent changes and be involved in discussions of major changes to the software.
Other Subversion Resources
- Securing Svnserve using SSH - If you want to allow secure access to your local SVN repository, this tutorial will help.
- If using Subclipse on Windows, you may also need this article.
- Automatically update a Subversion working copy on commit - If you want to use SVN to automatically update your code on a server, this will help (though obviously you should only do this if you know what you are doing!).