The TortoiseSVN downloads section can be found at this link. At the time of writing, this was the latest version. Download the appropriate (probably 32-bit) file and install. There should be nothing exceptional in the installer, just put follow the normal steps. If you're at university, they already have TortoiseSVN installed it seems, so you can skip this step.
In essence: at university, as a student, you cannot directly connect to an external SVN repository. You must use the proxy in that case. However, if you are using the new CS Projects repository, you do not need to worry about this, because you will be accessing repositories internally. So for CS Projects, skip this step (go to step 2)! Right-click in the file view in Windows anywhere, and go to the TortoiseSVN sub-menu then Settings. Click on Network on the left-hand side of the window. You should see this view:
Tick the Enable Proxy Server button at the top of the window, then fill in the follow fields:
Finally, select Ok to save these changes.
The first step is to checkout the project. A check-out is a Subversion term for taking a copy of the project to a new location ready to work on. This is not the same as grabbing the latest changes to an existing checked-out version, which is covered in the Update section later on. You should only need to check each project out once on any machine, but it is the first step.
First, create a new empty directory for JCSP to be checked out into. In the following screenshots, I have created one called JCSP on drive Q:. Right click in the folder, and you will see the SVN Checkout... option on the menu - click on it:
Once you have clicked on this, a new window will appear that looks like this:
The top field should be filled in with the repository address. You will want to fill in something like https://projects.cs.kent.ac.uk/projects/csprojects/svn/ (for CS Projects, use the Subversion link associated with your project). You do not need to alter the other fields. The second textbox should already be filled in with the name of your new empty directory (where you right-clicked originally). The two tick boxes can be ignored. The bottom part of the window would allow you to choose an old revision to check out. We want the latest revision (also known in subversion terms as the HEAD revision) so we leave that selected.
The next box that will appear will ask for a username and password. This is not your Kent username/password; rather, it is the repository username/password (in the case of CS Projects, this will be your CS Projects login). Every time you access the repository you will be asked for this username/password, so in the long-term you may well want TortoiseSVN to remember them for you.
Finally, a window will come up displaying the progress, showing the names of all the files it is checking out:
The OK box on the above progress window will be greyed-out until the checkout is completed. When it has finished, click the OK button, and the window will disappear. You will see that you now have a checked out version of JCSP in your chosen directory.
You should now see (you may have to press F5 to refresh the view) that small icons have appeared on your file icons:
The .svn directory is an internal subversion directory that can be ignored. You will see that the other files now have green ticks on them. More information on the icons can be found in the TortoiseSVN manual but you are only likely to run into four of them:
A green tick: indicates that the file has not been changed from the last time you took it out of the repository.
A red exclamation mark: indicates that you have changed the file since you took it out of the repository
A yellow exclamation mark: indicates conflicts (see much later on).
A blue plus: indicates that the file has been marked as to-be-added (see the Add section) by you, and will be added next time you commit it.The icons are recursive; if a directory contains a modified file anywhere within it, its icon will be a red exclamation mark. If you open this directory, you can see which files/subdirectories have changes, and thus you should be able to easily see what files you have changed.
So you now have a new directory with the latest (HEAD) version of JCSP from the repository. You also have your changes somewhere else. One option would be to simply copy your changed files into the appropriate directories - but this could be slightly problematic - consider the following scenario:
rc7 version:
class Dummy
{
private int an_rc7_field;
private int another_rc7_field;
}
Repository version (another_rc7_field removed):
class Dummy
{
private int an_rc7_field;
}
Your version (new field added):
class Dummy
{
private int an_rc7_field;
private int petersNewField;
private int another_rc7_field;
}
If you clobber the repository version with your version (e.g. by copying your changed sources over the top of the checked out sources), you will effectively be re-adding the another_rc7_field field. You can either do the merging by hand, to be sure and/or you can make use of diff (see next section).
Often you will want to know not just what files have been changed, but what parts of them have been changed. Let's imagine that you had changed BlackHoleChannel to add a message whenever the channel was poisoned. You will see in your file view the icon indicating that the file has been changed (look for BlackHoleChannel below):
If you right click on the file and go into the TortoiseSVN menu, you will see the Diff option:
When you click on this Diff option, a window will pop up:
The left-hand side is the unchanged repository (server) copy. The right-hand side is your local, changed copy. You'll see that white-space is visualised as dots in case it is important.
On the very left of the window there are three thin columns. This is like an index to the file. Ignoring the middle column, the left-column corresponds to the left window, and the right-column to the right window. The blue portion indicates where your view of the files is. You will see lower down on the columns there are coloured portions, which are the changes. It is perhaps best experienced for yourself, if you scroll up and down the file and see for yourself what is happening. The black line in the left-hand window merely indicates which line is currently selected -- it does not indicate a change.
If we scroll down we find our change:
You can see the yellow line we've added on the right, marked with a plus next to it. The location where it has been added is marked by a grey line on the left-hand side. So we can see that we have added one line to the file.
Be warned that changing white-space counts as a change to the file. So if you change any indentation, that will be marked up as a change even though the code is the same.
Here is an example of a slightly more complex change. Imagine you wanted to deprecate an old channel create method, and also change its implementation to use the new creation methods instead of a factory (note: I'm only changing one method here, just for illustration):
So you can see that we have removed the crossed-out line on the left, and added a few on the right.
So now you might be happy with the changes you have made, and want to actually send them to the server to record. This is known as committing your change [to the repository] in Subversion. You can:
When you do click commit, you will get the commit dialog:
The top text box will be blank, and it is where you should write a message describing what change you have made. You can see that I've added a simple message. The bottom part of the window shows what files you are committing (which may be existing files you've modified, or new files you've added). Once you press ok, the changes are sent off to the server.
You will probably want to add new files to the repository at some point. New files have no symbol next to them in the file view - Subversion ignores them until you tell it otherwise. To add a new file, right-click on it, go into the TortoiseSVN sub-menu and click Add... (simply click Ok on the window that appears). This doesn't actually send any changes to the server, but it means that you can now commit this file (see previous section). In the mean-time, the file will be tagged with a blue plus (meaning to-be-added on next commit)
In future you will want to get any changes from the server (that I or Kevin might have committed, for example) before doing any work, to remove any possibility of conflicts. To do this, you right-click and select SVN Update. Just as with commit, you can do this by selecting one file, multiple files, or directories (to be updated recursively). The easiest way to update the whole repository is to select the JCSP directory you originally checked out into (in my case, Q:\JCSP) and update that. You will be informed of any conflicts (see Conflicts section). A successful update changes your local files -- you will likely need to recompile. You should also get a list of changes that have been made.
You may encounter situations where you want to scrub all the changes to your local copy and revert to the server (repository) version. This may be because you accidentally changed something, or because an idea for changing the code did not pan out. This can be done by right-clicking on the appropriate file/files/directories and selecting the TortoiseSVN sub-menu and then Revert.... This will bring up a list of all the files you have changed, and offer to revert them. For example, when reverting the example changes I made earlier:
I simply click OK to remove my changes and revert those files back to their unchanged versions.
You may even want to delete some files from the repository some times. Note that deleting a file is just like another change -- it does not remove the file's history from the repository, it just removes it in the latest version so that it's no longer visible.
If you simply delete the file locally, this is not enough. The repository on the server needs to know about this deletion. To delete a file, you right-click and in the TortoiseSVN sub-menu you select Delete.
Conflicts were touched upon briefly earlier, in the Integrating Existing Source Changes section. Hopefully you won't have to deal with any conflicts -- accordingly, I have not included instructions here on resolving them. If this is a problem in future, I'll add some words about it.