Robert Laganière

Subversive Programming.

Using Subversion in few simple steps

Her is a very short introduction to Subversion, the tool you need for your versions control. Simple to use, open-source and multi-platform, check the Subversion website for complete information and installation instructions.

General principle: with Subversion, you have access to a repository inside which you can insert your projects’ files. Subversion keeps track of all the changes you make to your files; all the different versions of the files you submit correspond to revisions. You usually access the most recent revision, use it, make change to it and then submit a new version. You can also obtain files in the state they were at any past revisions. The Subversion’s repository can be located on your local machine or on a network server where multiple can access it.

Directories in your Repository

Within the Subversion repository, you create a directory tree of all your projects and files, the same way you do on your own local disk. At anytime, you can then decide to work on any subdirectory. You then create an image of this one on your machine, eventually update it and resubmit it to the repository. You structure your directory tree the way you want; there is no constraint. However, it is suggested that you define three particular directories below each of your projects (or group of projects); but this is just a pattern of work, you are free to use your own structure. The next paragraphs briefly describe this suggested directory structure. Since these are optional, you can skip the rest of this section and go to the next immediately.

The current version of your software project, on which your team is currently working is usually located under a directory called trunk. As the project evolves, the developer updates that version fix bugs, add new features) and submit his changes under that directory.

At any given point in time, you may want to ‘freeze’ a version and capture a snapshot of the software as it is at this stage of the development. This generally corresponds to the official versions of your software, for example, the ones you will deliver to your clients. These snapshots are located under the tags directory of your project. 

Finally, it is often useful to create, at some point, a new line of development for your software. This happens, for example, when you wish to test an alternative implementation in which you have to modify your software but you do not want to submit these changes to the main project until you decide if you adopt the new solution. The main team can then continue to work on the project while other developer work on the prototype. You would put these new lines of development of the project under a directory call branches.

One way to use this directory structure is as follow. The software product is developed under the trunk. When the software is ready for an official release, you copy it to a branch (e.g. version 1.0) and to a tag (version 1.00). This is the tagged version that your clients will use. While the development team continue to develop the new features on the main project (under the trunk), the quality assurance team maintain the version in the branch in order to fix the small bugs. When enough bugs have been corrected, you are ready to generate a new tag (version 1.01,…). In parallel, new release of the software will generate new branches (version 2.0, 3.0,…).

The Three Basic Steps

Let’s now assume that you have installed Subversion on your machine and that you have access to a Subversion repository on some server, here designated as: svn://www.server.ca:5555/. This address designates the root of your tree. The svn commands are launched from your console. The first command you should use is the one that list the content of the repository:      

  > svn list svn://www.server.ca:5555/

This is for the root, but you can also list the content of any existing directrory, i.e.:

  > svn list svn://www.server.ca:5555/test/

STEP 0. Creating a new directory.

Creating a new directory: this is something you will do only when you start a new project. You want to submit the content of a directory (e.g. called myproject) to a new directory. We want to put everything under the existing test directory of the repository and we are located in the directory that contains the myproject directory.

  > svn import myproject svn://www.server.ca:5555/test/projectX –m "Initial submission"

You have then created a new directory called projectX that contains the content of your local directory projectX. The last part of the command is a message that is used to specify what the submission is about; you have to include such messages every time you submit something to the repository.

If you follow the directory structure described in the previous section, then myproject should have contained the trunk, branches and tags directories; projectX in the repository will then also contain these directories.

STEP 1. Checking out a directory.

You wish to start working on your ProjectX. You are located in your work directory; you will then obtain the latest revision of the project from the subversion repository:

 > svn checkout svn://www.server.ca:5555/test/projectX/trunk mycurrentproject

This command will create a local copy of the project files in a new directory called mycurrentproject corresponding to the content of the trunk directory of the remote repository.

If you now go inside the newly created directory (here mycurrentproject ) you will notice that a new directory called .svn has been created; this one will be used by Subversion to keep track of your changes. Other .svn directories also exist in all subdirectories that have been checked out. The subsequent Subversion commands can then be applied to any directory that contains a .svn subdirectory. You have to locate yourself into this directory and issue a command which will then affect the files in this directory as well as all its subdirectories.

STEP 2. Editing.

At this point, you can start editing the files of your projects using your favorite editor. When you will submit your changes to Subversion, it will automatically update the files you have modified. However, you should never change the tree structure without letting know Subversion, that is when you add, delete, copy or move files or directories, you have to use Subversion commands.

> svn delete aFile.txt

> svn add aFile.txt

> svn copy aFile.txt thisDir/anotherFile.txt

> svn move aFile.txt thisDir/anotherFile.txt

When you apply these commands, you, in fact, schedule the corresponding tree changes to be made the next time you will submit your changes to the repository. If you never submit these changes, then they will never be applied to the projects on the repository.

Note also that when you work in team, you should always make sure that you are not making changes that conflict with the changes of another teammate; this is a question of proper project management. Although Subversion can help you to reconcile the conflicting files, this is a situation should be avoided. 

STEP 3. Committing your changes.

Once you are done with your project work, you are ready to submit the changes you have made to the repository and thus create a new revision of the project.

> svn commit –m "Feature Y added"

Again, the message is there to inform about the nature of the changes made to the files in this revision. The modified files will be uploaded to the server and a new revision will be created that other users can, in turn, check out. In principle, this is as simple as this: you checkout! you edit! and you commit!

Three Additional Commands

Before committing your changes to Subversion, you should examine them to make sure everything is as expected.

STEP 2’. Reviewing your changes.

You can review your changes by using the status command:

> svn status

You will then obtain a list of all the files that have changed. In front of each file in that list, there will be a letter describing the nature of the change, the most common ones being: ‘M’ for a file that has been modified; ‘A’ for a file that has been added and; ‘D’ for a file that has been deleted. These are all normal status for files and directories as long as they correspond to changes you made.

You must however pay attention to some special characters. You can obtain a ‘!’ if a file that has disappeared; this means that you probably deleted a file on your local disk without telling Subversion: you should or declare it as deleted using svn delete or restore it using svn revert. You can also obtain a ‘?’ Which means that a file is not under version control, i.e. you have added it without telling Subversion using svn add; it is still time to do it.

Another useful command is:

> svn diff filename

This command will describe the difference between a file on your local disk and the corresponding file on the repository. So, in doubt, you can always double-check what changes have been made before committing them. Note that you can also use svn diff to show the difference between two revisions of the project (here between revision 312 and revision 325):

> svn diff –r 312:325 svn://www.server.ca:5555/test/projectX/trunk

ALTERNATIVE STEP 1. or STEP 2’’. Updating your project files.

When you start working on your project, you generally start by checking out a fresh copy of the project on your local machine. However, if you already have a copy of the project on your machine it is possible to simply update it with the latest revision. This way you will avoid downloading the full set of project files if only few of them need to be updated. 

> svn update

Another situation where you need to update your project files is just before committing your changes. When you work in team, it is important to always update your local project files in order to verify if your changes are still compatible with the changes made and committed by the other developers since your last check out. A svn update always give you a list of all files that have been updated. Like in the case of svn status, a letter in front of the filename will indicate how the file has been updated: the letter ‘U’ means that the local file has been updated with a new version (i.e., you have not touch this file, but a new version was available in the repository); the letter ‘G’ indicates that your changes has been merged with the changes made by your colleagues to produce a new version of the file. These two situations are normal and of no concern. The letter ‘C’ is however more problematic; it indicates the occurrence of a conflict. In this case, you will have to meet with your team and find a way to resolve the conflicting changes.

Branches and Tags

You create a branch when you want to work on a copy of a project and make changes without affecting the main project files (the trunk). You can then work independently on this new line of development while the rest of the team works on the main project. The branch is, in fact, just a copy of the main files, so you create it by copying the files onto a new directory.

> svn copy trunk branches/myProjectX

> svn commit –m  "Creation of a new branch of ProjectX"

Suppose now that you have worked on your branch for a while. The team has also continued the work on the trunk and they made some improvements to the lib directory of ProjectX that you wish to use. However, you also made some changes to these files. The solution is to merge the two sets of files using the command svn merge. This command proceed by considering two directories (or files) of the repository and merge them together into the local working copy. Now, if you want to merge your branch with the trunk and have the merge result apply to your branch, you need to have a copy of your branch on your local machine and be located under this directory when you issue the command.

> svn merge svn://www.server.ca:5555/test/projectX/trunk \

        svn://www.server.ca:5555/test/projectX/branches/myProjectX .

You can then run svn status to see what changes have been made.

A tag is a snapshot of your project that should not be changed after. To create a tag, you just need to create a copy of your project. This is done the same way as you do for branches. Note that there is a shortcut command that directly copy a directory to another one in the repository without having to use a local copy.

> svn copy svn://www.server.ca:5555/test/projectX/trunk \

        svn://www.server.ca:5555/test/projectX/tags/release2.03

Conclusion

You can do much more than that using Subversion. You are invited to read the Subversion manual for more details. However the basic steps presented here should be sufficient for you to start working with Subversion and perform proper version control of your projects.