C. Daniel Chase

I need to clarify one thing from my earlier post. I demonstrated how to create a subversion repository on your local computer. Note, this was for demonstration purposes only. To get maximum advantage from using a subversion repository, it needs to be located on a networked server that all site developers can access. OK, you are thinking, “I’m only one person, why do I need to do it this way?” Easy answer: Backup! Not to mention the advantages of using the entire concept of source code management to develop your site.

So, if your repository is on a different server, how do you work with it on a daily basis? That’s what I’m going to describe today. Keep the two locations in mind as the remote server Repository, and the local Working Copy.

Last time when we parted, we had just checked out a local copy from the repository. (Just imagine that repository was remote rather than local to your computer.) Let’s pretend you quit at that point for the day. This is the point you want to be at whenever you quit working–synchronized with the repository. You should never quit working without doing an UPDATE & COMMIT of all of your work. We’ll cover those details momentarily. By doing this, you will always have a backup of your work, as well as have it stored remotely in case you edit from multiple computers and/or locations. For example, I might do some work at my office, and then come home and feel like doing a little more… or end up wanting to work from home the next day. Having the files in the repository allows me access to the current files from wherever I choose. Just connect from the alternate location, and UPDATE.

Update

OK, what exactly is UPDATE? With the UPDATE function subversion compares the files you currently have locally, with the remote copy on the server and downloads files from the server, if they are newer. Note, this is one-way updating. If you have edited any of your files and want to upload them, you do a COMMIT–we’ll cover that in a minute. During an UPDATE there are a few possibilities:

• No changes–your local files are already up-to-date with the server
• Newer files on server–none of your copies of the files have been edited locally
• Newer files on server–some of the same changed files have been edited locally also, but in unrelated ways
• Newer files on server–changes in files are in the same area as changes made locally

No Changes

While this may seem an obvious answer, it is important to recognize you are at this state. Especially if you are in a multi-developer environment. In this case, no changes will be made either on the server or locally, and the current Revision Number will be displayed.

Newer Files in Repository, No Working Copy Files Changed

In this case, the newer files on the server will be copied to your local working copy. You will see a list of the files that have been updated, as well as what the status of each file is–note each of these possibilities we are covering occur on an individual file basis, so what happens per file might be different. The current Revision number will be updated.

Newer Files in Repository, Unrelated Working Copy Changes

The important thing to ask in this case is, what is an ‘unrelated change’? The key here is that you may have edited a file in one area, say lines #5-10. But, the changes in the repository file–compared to a common base–are in an entirely unrelated area of the file, say lines #50-55. You can probably see that as long as each individual change is in entirely separate areas of the file, with no overlapping, that it is possible to merge the changes without much thought. Note, even if lines are inserted in one location or the other, the context of the surrounding lines identifies where they are in relationship to the base file.

It is important to note that this merging of changes can only be done with text-based files. And while binary files, such as images, can be maintained in subversion, they cannot be merged.

In the no conflict case such as this, subversion will automatically merge the files for you, updating your local copy. In the list of files with changes you receive at the end of the update, you will see a code G next to them indicating a successful automated merge.

Newer Files in Repository, Conflicting Working Copy Changes

As you may have guessed, in this case subversion can’t automate the change. But, it helps! You will be advised of the Conflict, and several copies of the file in question will be put in your local working copy. Your original file will be renamed: filename.mine, there will be two other files with a Revision number appended: filename.r<old rev #> and filename.r<new rev #>. The old rev number is the one you had before you started making changes, the new on is from the server copy. The original file will contain special marks in the file showing both revisions to enable you to compare and figure out which changes should be used, or if you can manually merge the two changes. There are several convenient tools available to ease the process of this editing.

Once you have edited the original filename to contain the changes you really want, you should do an UPDATE (to make sure no more changes showed up while you were working on it!) and then a RESOLVE in order to let the repository know the conflict has been resolved and which changes to keep. Then COMMIT your changes as usual–see below.

Commit

Commit is simply the process of uploading your changes to the repository. Remember, as mentioned above, if you have been working for any significant period of time since your last commit and your are in a multi-user environment, do an Update as described above first before doing a Commit. It will also be easier to merge changes if you do an Update on a regular basis to get new changes from the repository even if you are not ready to commit your changes.

When a commit is done, all changed files are updated in one batch. So, best practice is to keep related changes together. If you have to modify a form to be displayed and update it’s related processing code in a separate file, make the changes and commit them together. Every commit will require a Log message, so it makes it easy to describe the related changes and see them together when looking at historical changes.

Summary

To wrap things up at this point, I want to point out a couple of resources you can use for the details I have not include here, but will in future installments. The easiest, and free, resource is the online version of the Subversion Book. Several versions are available, including a download PDF. If you are like me, you may like to have a paper reference of it, and the authors would appreciate the purchase of it as well, it is published by O’Reilly Media and is available from Amazon: Version Control with Subversion.

Another good book is the one I use personally, and is part of the Pragmatic Starter Kit Series: Pragmatic Version Control: Using Subversion (The Pragmatic Starter Kit Series)(2nd Edition). This book is a little over 200 pages, and I was able to read it cover-to-cover in a little over a week in my spare moments. Many great ‘pragmatic concepts’ to be learned and applied in the future.

Well, that about wraps it up today. Next time, I will get into explicit demonstrations of these steps. I’ll give you the command line techniques and demonstrations, as well as snapshots of doing the same in TortoiseSVN. Stay tuned!

As I have previously mentioned, I am a big fan of managing code changes with Subversion. Here I’m going to describe the process of creating your own local repository for managing changes. Think of Subversion as you own personal time machine for your content.

My basic setup will be to have the repository (where subversion stores all of your changes) on a secondary partition on my laptop’s hard drive. While I had considered having it remotely on my server, I want to have it local so I can manage my content when I am off-line traveling. I will also use backup routines to have copies on external drives. While I prefer to work in Linux, I also work in windows, so I will describe the setup from a windows point-of-view. However, the files for the repository are on a shared partition of my hard drive so I can access the repository not matter which OS I’m using at the moment.

The basics steps are these:

1. Install Subversion & optionally, TortoiseSVN for windows
2. Create directory to store repository
3. Create repository with svnadmin
4. Import web project
5. Checkout working copy of web project

Install Subversion & optionally, TortoiseSVN for windows

Subversion & TortoiseSVN are available from the Open Source projects at Tigris.org:

• Subversion
• TortoiseSVN

Follow the link to the individual download pages and download the current version for your OS. Install in the usual manner! Note, TorotoiseSVN requires a reboot since it integrates with windows explorer.

Create directory to store repository

Hopefully, if you know dos, this will be familiar. Or maybe it won’t if you have never used the command line under WinXP. Since subversion itself is a command line program, creating the repository will be at the command line. so let’s start by using the command line to create the needed new directory. Click Start -> Run… (or Windows-R from keyboard) and type cmdand press Enter. A new window with white text on a black background will open with a prompt showing your current directory. Decide where on your drive, or drives, you would like to locate the repository. Then create the directory with md:

C:> md e:svn-repo

Substitute your own drive letter instead of e: and path of your choice instead of svn-repo.

Create repository with svnadmin

Now that you have a directory to use, we use svnadmin to turn it into a repository for use by subversion.

C:>svnadmin create e:svn-repo

Let’s see what it created for you:

Directory of e:svn-repo

04/01/2007  05:53 PM    <DIR>          .
04/01/2007  05:53 PM    <DIR>          ..
04/01/2007  06:20 PM    <DIR>          dav
04/01/2007  06:20 PM    <DIR>          locks
04/01/2007  06:20 PM    <DIR>          hooks
04/01/2007  06:20 PM    <DIR>          conf
04/01/2007  06:20 PM               234 README.txt
04/01/2007  06:20 PM    <DIR>          db
04/01/2007  06:20 PM                 2 format

Don’t worry anything about the details now, but I just wanted to show you that subversion is doing a lot of work for you behind the scenes.

Import web project

Next step is to import that web site you have been working so hard on! Since we have been working at the command line, I will continue here with that technique. Then I will show you the easy way with TortoiseSVN–a graphical tool to access the power of subversion from windows explorer.

First, locate the directory where you current web site files exist on your drive. If you have multiple sites, I will suggest that you import them as separate ‘projects’ in subversion. cd to the top-level directory you want to import–all subdirectories will be imported also. You should clean them up before importing, removing any test or temporary files you do not want in the repository.

C:>cd htmlcdchase-blog

C:htmlcdChase-blog>

Next, you will use svn import to pull in all of the content to the repository. Last chance to clean up the directory and sub-folders before importing! Notice the use of -m “Importing blog.cdchase.com project” to supply a log comment. All changes to a subversion repository require a comment describing the change.

C:htmlcdChase-blog>svn import -m "Importing blog.cdchase.com project" .  
                              file:///e:/svn-repo/cdchase-blog/trunk

You will see all of your files scroll by as they are imported. Eventually, you will get to the last line:

Committed revision 1.

Congratulations! You now have your first project in the subversion repository!

Before we move on, let me point out two items in the import command above. First, the ‘.’ (dot or period): it is how you refer to the current directory as a shortcut. If you were not already in the directory you wanted to import, you could explicitly provide it instead of using the dot. Secondly, the format of the destination: file:///e:/svn-repo/cdchase-blog/trunk. This is the URL format for referencing a local file location. The file:/// replaces the use of http://hostname/ as in a web browser. The remainder is the path to the repository, including the desired project name, cdchase-blog, in my case; and the branch you want to import it to, trunk. More on the use of ‘trunk’ in a future post. The ” at the end of the first line is just to indicated that this line is continued on the next line–don’t type this in windows! The entire command should be one line, without the ”. (Linux users may recognize this as the standard continuation character.)

Importing with TortoiseSVN

As promised, doing the same import function with TortoiseSVN is as simple as right-clicking on the folder you wish to import, and selecting TortoiseSVN -> Import…

(image no longer available)

and supplying the destination path and log message:

(image no longer available)

Once you click ‘OK’ your files will be submitted as in the command line version.

Checkout working copy of web project

Finally, in order to actually use the files from the repository, you must ‘check out’ the files. This must be done to a new directory, so if you want to use the same directory name you imported from, rename that directory first.

C:html>rename cdchase-blog cdchase-blog-old

To do the ‘checkout’ or co:

C:html>svn co file:///e:/svn-repo/cdchase-blog/trunk cdchase-blog

When it is complete, you will see:

Checked out revision 1.

Congratulations! Your files are now under version control!

Tomorrow, we will go deeper into how you use Subversion on a daily use basis.