This tutorial is intended for PLU students who wish to use Subversion to help manage their code/documents for their capstone project. It describes the basics of using Subversion on PLU's servers, and common workflow practices.
Subversion (SVN) is a free/open source version control system. It manages a tree of files and directories over time, keeping track of changes to all files under its control. It is a valuable tool for developing large scale projects with a group or individually. A tree of files is placed in a repository. Subversion remembers every change ever made to your files and directories. This allows you to recover older versions of your data, or examine the history of how your data changed.
Other features:
To create your SVN repository log on to shemp with your regular username and password via ssh, and execute the following commands:
To use SVN to work on your project, the first thing you need to do is create initial versions of your files (you don't need to create all of the files yet, just a few to get started). You could even start with an empty directory, but that might be somewhat confusing.
For this example, I have created three files for my project: Foo.java, Bar.java, and README. They are located in a folder called MyProject. Everything in this folder will be imported into my SVN repository.
Right click in some blank area in the folder, and choose "Import..." (see screenshot below).
After choosing this option, you will be presented with the following screen:
Notice the URL field. This example uses a shemp username username, a project account sps, and a SVN project name MyProject. You will need to replace all of these in the URL with names appropriate for your situation. In general, you will use something like this:
svn+ssh://username@shemp.cs.plu.edu/home/project/projectAccountName/svnrep/ProjectName/trunk
Where all words in italics are replaced with appropriate values for you.
Important note: don't add any files to the repository that can be generated from other files in the repository. For example, don't add object (.obj) files, bytecode (.class) files, or the Debug directory (created by Visual C++).
Once you have filled in the information and clicked OK (and after you enter your shemp password multiple times), Tortoise SVN has imported all of the files in your directory into the trunk of your new project. The reason that we use a directory called trunk is that it allows you to make "branches" off of the main trunk of your code base. (For more information on branches, see the Subversion book referenced below.)
You can now delete the MyProject folder (or just re-name it to be safe).
Now that we have imported our data in the subversion repository, we need to "check out" a working copy of our repository. Right click in the parent folder and choose "Checkout..":
The following dialog will appear:
Here you will use the same URL that we used in the import step above. In addition, you should choose the destination folder for your working copy. In this example, all files contained in the "trunk" will be placed in the destination folder.
After entering your password (twice) you should see the following:
The "Add" indicates that the file is "Added" to your local working copy. After clicking Ok, navigate to the MyProject folder. You should see something like the following:
The green check marks indicate two things: (1) the file is under subversion "control", and (2) that the file is equivalent to the most recently checked out version of the file (called the BASE).
Now that you have a SVN controlled working copy, you can start coding away. It is important to remember that if you make any changes to the file name, file location, add files, or delete files you need to let subversion know about it. In this example, I add a file, and modify a few files. In general, you might have changes that involve file name changes or file location changes. In those situations, you must "tell" subversion about those changes using one of the options in the TortoiseSVN menu like "Relocate.." or "Delete". You should have subversion make these kinds of changes rather than doing them yourself.
For example, suppose that during the course of my work, I have made changes to the files Foo.java and README. Also, I have created a new file to add to my project called Car.java. Then my working copy would look like this:
The exclamation marks in the red circles mean that the files have been changed since they were checked out. The file Car.java does not have any symbol on it because SVN does not know about it yet. To add it to my SVN project, I right click on the file and choose TortoiseSVN -> Add.
Once that is done, the file is marked for addition. There is no change to the image of the file, because it has not been "officially" added to the server's repository. The file is not truly added to the repository until you commit your changes to the repository by doing a "Commit." The commit operation sends all local changes (file adds, file changes, deletes, moves, renames etc.) to the server. Generally, you will execute a commit when you are done working for the day.
When you have finished your coding for the day, it is time to commit your changes to the repository. However, before you do so, it is a good idea to make sure that you have merged any changes that might have been made to the repository after you checked out your working copy. To do so right click in your working copy and choose Update. If there were any changes to the repository since your last checkout, SVN will try to merge those changes with your working copy. If there are conflicting changes, SVN will notify you and you may need to manually resolve those conflicts. For more information on this, please see the links below.
Now that you have updated your working copy, you are ready to commit your work to the repository. To commit your changes (and add the files marked to be added) don't highlight any files, just right click in the blank space and choose Commit. You should see a screen like the following:
Every time you commit, you will be asked to write a comment. This is a very useful way of keeping a record of the changes you make to your project. Every time you do a commit, write a brief, but detailed description of the changes you made in the text area.
Click Ok, and your changes will be committed to the repository. When you are done for the day, and after you have committed your changes, you can safely delete the local copy of your module. In fact, it is a good idea to do so. The reason for this is that the next time you sit down to work on your project you will check out a new copy of the module, along with any changes that may have been made by your group partners in the meantime. The other option is rather than deleting your working copy you can just make sure that you do an "Update" before you start working.
For best results, you should use the following steps as a guideline when working with SVN. On a given day when you want to work on your project,
Of course, there are many other features to SVN that I have not covered here. For more information on SVN check out the following:
Written by David Wolff, last updated 1/11/05