Getting Started

To begin you'll need two things. First of all, you obviously require NuSphere PhpED to be installed and working. Secondly, you need a cvsdude.com account. You can register on their site here, just click 'sign-up' under the 'Free' column, or if you know you're going to be using their services extensively, plump for one of the paid services. You won't regret it.

Once your activation email arrives you're good to go.

Importing an existing project into CVSDude

You most likely have a copy of your web site files on a local or network drive. When you need to update the code, you fire-up NuSphere, edit away and then upload the changes. This is a set-up most developers are familiar with.

When it comes to CVS you need to extend this process a little. You need to think of CVSDude as being the 'server' on which all of your source controlled files and projects live. They hold the 'master copy' so to speak. All you really do is download a copy of the project to your local PC, work on it, and then save your changes back up to the master server again. The process of doing this creates new versions of your files, allowing you to then 'step back' and compare previous versions, should you realise you didn't really want to delete that function after all and need to restore it.

Your working environment

For the sake of argument, we will assume that your web sites all exist on your local drive in a folder called C:\WebProjects - and inside this folder you have another folder for each project.

When you work in PhpED your Workspace and Project settings all point to these C:\WebProjects sub-folders. Your FTP software (or PhpED) also most likely syncs these files up to the server.

You need to change this method of working slightly though. Here is how I handle this:

Let's assume we've got a web site called 'GuestBook' that current lives in C:\WebProjects\GuestBook. We want to put all of this into CVS.

1. Start by creating a new folder: C:\CVSProjects\GuestBook.

2. Within PhpED create a new Workspace. Then create a new Project.

3. The 'Root directory' of the project should be: C:\WebProjects\GuestBook.

4. Change 'Source Control' to CVS and then click on the CVS tab that appears at the top.

5. The settings entered here should come from the email you received from CVSDude.com. Namely:

5.1 Host: This is given in the CVSDude email as the 'CVS Server'. For my account this was 'cvs6.cvsdude.com'. The Host should literally just be the domain name they gave you, do not incude :pserver: at the front, or the Repository (/cvs/stdx/) at the end.

5.2 Repository: This is given in the CVSDude email as the 'server dir'. For my account it was /cvs/stdx

5.3 Module: PhpED will fill this in with the directory name selected as the Root Directory. So in this case it'll be 'GuestBook'. You can however change this to whatever you want - it is the name of the project within CVS.

5.4 Authentication. Fill in your CVSDude Username and Password in the boxes given.

The end result should look something like this:

6. Click OK and save your Project. It will now appear as usual in the Workspace window in PhpED. To transfer it to CVSDude you need to right-click on the Project itself and from the CVS sub-menu pick 'CVS Import'. A new window will appear asking for a Vendor tag, a Release tag and a Log message.

You need to enter a Vendor tag and Release tag. Do not include any spaces or non A-Z, 0-9 characters in the tags or it will complain at you, you can however use a hyphen. For this project I entered 'CorePHP' as the Vendor tag. The Vendor in CVS terminology is the company, team or developers name. I put 'v1' as the Release tag. The 'Log message' was left blank, but you could fill it in with a reminder of what you did, for example 'Initial import'. You should end-up with something like this:

7. Click OK and a 'Please wait - Waiting for CVS' window will appear. Depending on the size of your project and your network connection depends on how long this part will take. When it finishes the PhpED Log window will appear with the CVS Import results. Here is a screen grab showing the results of importing my Easy Reflections web site into CVS. As you can see, each file is listed and I've even imported my graphics files, so they too are under source control (allowing me to revert back to a previous image should I accidentally delete or overwrite it locally).

8. Now you have successfully imported your project you can login to your CVSDude account to verify it appears on the Modules list. Just login using the credentials they sent you and the Welcome page should show your list of Modules, including the one just created:

9. Now we have got a fully source controlled version of our web site up on the CVSDude.com servers. It can be checked-out onto any machine, worked on, and updated again without ever loosing any of the changes that take place.

Working on your Project in PhpED

With your web site safely in the capable hands of CVSDude you can now work on it with PhpED. Close down the Project and Workspace you had open from the Import, as you won't need them again.

Earlier on in this guide we created a new folder called CVSProjects\GuestBook. The aim of doing this was that it would serve as the location where all the files are saved when we download them from CVSDude (via a CVS Checkout).

1. From within PhpED you need to create a new Workspace and then a new Project. For the project you should set the Root directory to be the CVSProjects\GuestBook location, and as in the Import step, set Source control to CVS and fill in all of the details in the CVS tab exactly as you did above for the Import. The important part is to get the Module name exactly the same as the one you imported.

2. When you have finished click OK and save your project. You'll be left with your new Workspace with a single project that has no files under it. Right-click the project title, pick the CVS sub-menu and then CVS Checkout. The CVS sticky options will appear. As you've not created any branches you are safe to use the default option of 'Use the same version as it was last checked out (default)' and click OK.

3. The 'Waiting for CVS' window will appear and all of the files will download to your local PC. Again this will take however long is needed for the size of the project. At the end of it your project within PhpED will now have all of the files from your web site visible.

4. You'll notice that each file has a padlock icon next to it. This means it is locked and cannot be modified. If you want to work on a file, right-click it and from the CVS menu pick 'CVS Edit'. The padlock will disappear and you can then open the file, modify it and save your changes.

5. It is worth mentioning that when you save the file it is not automatically sent back to the CVS server. When you are ready and have made all the modifications you wish, you should right-click the file and pick 'CVS Commit'. Once you've made a commit, the file is sent back from your local PC to the server. A side effect is that it's also locked again from PhpED, so you need to them 'CVS Edit' once more to carry on modifying it. This is a bit of a pain, but weight up the costs a moment here. This quote from the O'Reilly book 'Essential CVS, 2nd Edition' by Jennifer Vesperman really sums it up well:

"If your changes will not affect anyone else, commit frequently. Commit every time you'd hate to have to redo your work. Frequent commits keep your work in a single place for backup. If you are working in a team, frequent commits and updates reduce the chance of having to do a major, difficult merge."

6. You can assign keyboard short-cuts to the CVS functions. Click on Tools - Settings and then in the Settings window pick 'Integration' under the Tools menu on the left. The CVS commands appear, pick the ones you'll use most frequently (edit, commit, update) and then edit each one. The very top option is 'Shortcut', click the 'Value' box and press the keyboard combination you wish to use. You can then use that in future rather than right-clicking the file and using the sub-menu nav.

There is a lot more to CVS than just this, and the O'Reilly book I mentioned will answer most questions you may have on the subject. But I hope this guide shows that it's not too intimidating getting a project managed under source control from PhpED.