Use subversion (SVN)

SUBVERSION

This is a simplified explanation of Subversion (SVN). The aim of these notes is to show you how to use SVN as a source for draft PhpGedView files. It does not cover any other function. If you want to know more about SVN, try http://svnbook.red-bean.com/.

SVN is a version control system. Wikipedia says “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 control software, you can create a parallel version 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.

PART 1

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 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/

There are other clients available. SmartSVN is a more full-featured client, and it too is free (you don’t need the professional version).

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 for your distribution of choice. See: http://subversion.tigris.org .

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

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 – in the parlance, do a “checkout”. So select the first of the new options.

This brings you to the only typed/copied and pasted input required.

The URL is below on one line!

Tortoise will suggest a target/checkout directory, which you can adjust to suit. It is preferable to keep the path simple.

C:\Checkout would be a practical suggestion, so amend the second input box to read that.

PGV repository on the SourceForge server

The URL is https://phpgedview.svn.sourceforge.net/svnroot/phpgedview/trunk/phpGedView (this currently is 4.1.1)

or:

https://phpgedview.svn.sourceforge.net/svnroot/phpgedview/branches/phpGedView-4.2 (this currently is the draft of 4.2)

Type your selection exactly as shown here, or cut and paste it if convenient. Then, as nothing else needs attention, click OK.

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 scroll down through your main folders. Buried in there will be the Checkout folder, with a small green dot/tick to indicate that this is a special folder.

If you open the Checkout folder, you will see some differences between this folder and a more usual one.

The small green circle/tick is repeated to tell you that this is a SVN folder, subfolder or file. And there will be subfolders labelled “.svn”

PART 2

.svn

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 your files to a remote server, you don’t want to upload all this extra baggage. To give you some idea: .svn about doubles the number and 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 folders are not wanted or needed in the final location, so they need to be cleaned out. To do this is quite easy, by and large. Here are two longhand ways and a shorthand way - if your FTP client is up to it, jump straight to Part 3.

Longhand #1: Tortoise has an Export command. Find the Checkout folder and right-click on it. The side menu that opens has an item “TortoiseSVN”, which leads to Export…” Select this.

Select where you want to create the exported copy and click on Make New Folder. Select OK.

This process will make a fresh copy of Checkout, but without all the .svn folders.

A warning: this process does not currently work with Microsoft Vista.

Longhand #2: the second longhand way is also easy. Copy all the files to a new folder – call it “xxxxx” for this example.

Open a command line window – “Run” then “cmd”

Now type in this line: for /r c:\xxxxx %f in (.svn) do rd /s /q “%f” and press Enter

That will clean all the .svn subfolders from “xxxxx” for you.

Why follow this longhand path? It is useful when you plan to delete anything you don’t want or require – eg, modules you don’t plan to use, flags, themes, language files. But, 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.

PART 3

The whole point of SVN is that, as files are amended, you can download copies to your computer, and then upload them to your server.

Update

Open your file directory, and right-click on the SVN folder.

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.

Synchronize

Now you need an FTP client with the ability to synchronize your files with the server files. And, as your files have all the .svn folders, it is essential that you can set some conditions to prevent them being uploaded as well.

One useful client is at http://winscp.net/eng/index.php. Get a copy and install it. Arrange the conditions for it to connect to your server site. Connect to test your handiwork.

At this stage, go to the menu bar and select Commands / Synchronize…

Now you can control the upload to your server. 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.

So, instead, click on Transfer settings, and on the next screen, work your way to Transfer/Presets, then click the Add button.

Give this “Preset” of conditions a name – “Mine” or “Mask_1” to suit.

Down the lower left, in the Exclude box, type

• /;.svn;

And then click the OK button. That will look in every folder and subfolder for .svn files, and exclude them from the upload.

You may exclude other sections if you want. For example, SVN also inserts .htaccess files in various folders. Except for the Index folder, these are not required. So, upload .htaccess to the Index folder 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 (eg, the Images folder) with a comma or semi-colon between the parameters.