Using SVN for PhpGedView

PhpGedView for the more advanced

Most of us use stable versions of PhpGedView, notified and released through the main PGV pages on SourceForge. But there are always developments in the pipeline. These take two forms—patches (and you will find "fixes" there from time to time) and unproven scripts—often referred to as "subversions" (SVN for short). You will find references to "revision control", which is the same concept.

SVN is for everyone involved in developing and testing open source software. The hub of SVN is the repository, where all the current subversions are stored. There are writers/scripters/progammers/etc who are working on changes, which are committed to the repository. Then there are the users/testers/leading edgers, who draw down from the repository to their workspace. This document will hopefully help you begin using the Subversion repository code on your PhpGedView web site.

Subversion

SVN is a version control system; it allows users to keep track of changes made over time to any type of electronic data. Typical uses are versioning source code, web pages or design documents.

Open source software like PhpGedView has many contributors. As revisions are written, the developer(s) “commit” the changed files into a repository. This repository is the core "filing cabinet" for the SVN system. Other developers and users can draw these files from the repository, but with many hundreds of files involved, sharing changes could be quite complicated without SVN control software.

Using version control software, you can create parallel versions of the repository on your computer. The software then allows you to keep the two locations synchronized, so you always have a copy of the latest revisions. From there, you can work on the source files, or upload the revisions to your server, either local or remote, to test and comment on.

Installing a Client (for Windows Users)

There are some good Windows tools available that will give you the means to build a replica of the files in the repository on your computer. Tortoise is one such piece of software, and will be used in this wiki to guide you along. Tortoise is free and can be downloaded from http://tortoisesvn.tigris.org/.

Note: There are other clients available: SmartSVN is a more full-featured client and it too is free.

Installation is quite straight-forward. This is the welcome setup screen for the Tortoise version used to prepare this document. Click on "Next" to start the process. There is little to gain, or lose, by choosing options on the next screen, so simply click "Next" again. When the process is complete, restart your computer.

Installing a Client (other)

For Linux/*BSD/Unix the command line SVN client can be installed through your distribution's package manager.

• For Debian/Ubuntu

sudo apt-get install subversion

For MacOS X users see WikiHow for several options and additional links.

Using the SVN Client

Checkout

When your computer has rebooted, right-click anywhere on the screen. You will get a list with a couple of new entries: "SVN Checkout" and "TortoiseSVN". The next part of the process is to get a copy from the repository to your computer—a checkout. Select "SVN Checkout". Tortoise will suggest a target/checkout directory, which you can adjust to suit your needs. Note: It is preferable to keep the path simple. C:\Checkout is a simple suggestion.

For the command-line client (CLI) use:

svn co https://phpgedview.svn.sourceforge.net/svnroot/phpgedview/trunk/phpGedView phpgedview

PGV repository on the SourceForge server

In the "URL of repository" field enter either https://phpgedview.svn.sourceforge.net/svnroot/phpgedview/trunk/phpGedView or https://phpgedview.svn.sourceforge.net/svnroot/phpgedview/branches/phpGedView-4.2 if you want the development version.

Things get busy now. A long list of files will scroll through the window as they download to your computer. At this time, Tortoise will download about 12,600 files, consuming a bit over 100 MB of disk space (the actual files total about 70MB, the rest is slack space). When the download has finished, open Windows Explorer and browse to the C:\Checkout directory.

Update

The "update" function of Subversion will only update those files that are newer in the SVN repository. You don't need to do this immediately after a checkout because you already have the latest files.

1. Open your file directory, and right-click on the SVN folder.
2. Left-click on "SVN Update". The Tortoise system will check all your current files against the repository, and download any repository files that are more recent.

For Linux/BSD/other:

cd /path/to/svn/tree
svn update

The .svn directory

These folders are both a blessing and a curse. The blessing is that they hold all the version information for the other files in the mother folder. When you do an update, Tortoise will compare the information about the files you hold with the information about the files at SourceForge. If the information is identical, there is no need for a download because you have the latest. If the SourceForge file is newer than yours, then it has to be downloaded and the .svn files updated to show this. This has many advantages, including:

• the ability to reverse-out an update if you find a problem with it
• comparing the update with the previous change
• merging the changes to any manual alterations to the files you have done for your own purposes, etc.

They are a curse because if you are working with your files on a remote server, you don’t want to upload all this extra baggage. The .svn directory about doubles the gross disk space used by PGV.

Preparing to Upload

Whether to a local or remote location, the next step will be to copy the files from your computer to that server. But first, it would be wise to do some housekeeping. The .svn directoriess are not wanted or needed in the final location, so they need to be cleaned out. To do this is quite easy.

This process will make a fresh copy of C:\Checkout, but without all the .svn directories. Note: this process does not currently work with Microsoft Vista.

Using the Tortoise "Export" command:

1. Find the C:\Checkout directory in Windows Explorer and right-click on it. The side menu that opens has an item "TortoiseSVN", which leads to "Export…", select this.
2. Select where you want to create the exported copy and click on "Make New Folder", then select "OK".

Using Windows:

1. Copy all the files to a new directory, call it "xxxxx" for this example.
2. Open a command line window by clicking the "Start" bar, then “Run” and finally type "cmd" in the text box and push "OK".
3. In the newly opened command line type in this line and press "Enter"

for /r c:\xxxxx %f in (.svn) do rd /s /q "%f"

That will clean all the .svn sub-directories from "xxxxx" for you.

The Linux/BSD/other user may do this in preparation for uploading their updated svn tree:

cp -a /path/to/svn/tree /tmp/pgv
find /tmp/pgv -type d -name '.svn' -exec rm -rf {} \;

Why follow this longhand path? It is useful when you plan to delete anything you don’t want or require, e.g., modules you don’t plan to use, flags, themes, language files, etc. However unless you are really short of server space leave them in place. Uploading them intact can be useful because it simplifies later updates.

When this has been finished, you are ready to upload the files in "xxxxx" to your server. You can now go ahead and configure and populate the SVN version of PGV.

Synchronize step 1

Synchronize

Synchronize step 2

Synchronize step 3

Synchronize step 4

Now you need a FTP client to synchronize your files with the server files. Unless you followed the procedures above your files have all the .svn directories and it is essential that you can set some conditions within the FTP client to prevent them being uploaded as well.

One useful client is called WinSCP and can be downloaded here: http://winscp.net/eng/index.php. After installing and starting the program setup the conditions for it to connect to your server site.

1. Go to the menu bar and select "Commands / Synchronize…"
2. Select "Remote" as your target directory, and tick the "Existing files only" box. This ensures that the only files uploaded are a match for the files already on the server. However, there will be times when new files are added to the repository. In that case, because they won’t have yet been uploaded to your server, this system won’t copy them or new issues of them
3. In this case click on "Transfer settings" and on the next screen, work your way to "Transfer/Presets" and finally click the "Add" button
4. Give this “Preset” of conditions a name—“Mine” or “Mask_1” to suit
5. Next, down in the lower left, in the "Exclude" box, copy from below and then click the "OK" button. That will look recursively through all directories for .svn files and exclude them from the upload

*/;.svn; 

You may exclude other sections if you want. For example, SVN also inserts .htaccess files in various directories. Except for the Index directory these are not required. So, upload .htaccess to the Index directory the first time you do an upload, but after that, make the exclude mask:

*/;.svn;.htaccess

OR

.svn;.htaccess 

Add any others to suit your needs, e.g., the Images directory, with a comma or semi-colon between the parameters.

Linux/BSD/other users can use the CLI scp or any FTP client such as lftp or ncftp.

An example scp command might look like:

scp -r /tmp/pgv user@host:/hosting/site/phpgedview/