SVN How to

The following describes how to setup a personal SVN account at MSDL. There are two types of SVN accounts in our lab, a central, project-related one and another for each lab member, if they want one. I strongly urge you to use SVN. It makes life a whole lot easier and I know people who SVN their entire computer!!! It also makes synchronizing work and home computer data much easier. And when you make a mistake, a simple revert command takes you back to your correct version! Imagine working on a conference paper and having to email your LaTeX files to yourself every time you change locations. It's pretty sad if you're emailing yourself in the first place...but I shouldn't talk, we've all done it in the past! Please talk to Professor Hans, our MSDL supervisor, about project-related SVN access.

So, you can actually do the following anywhere, even at home, assuming you have SVN installed. You can get the SVN package from your favourite Linux package repository or for Windoze from the SVN website, under downloads. For Windoze, I also suggest TortoiseSVN as a nice GUI front-end. I have never used it because I am mostly on my Ubuntu but I have heard it is pretty nice. Note that for home use, you won't be able to access your repository from the WWW unless you have integrated SVN with SSH or Apache (click here for some not-so-helpful info, but a google search for "svn ssh" or "svn apache" is much better). Even without WWW access, it is still pretty nice to have a local SVN repository because you can, on your very own computer, have version control. Though it might not make sense because you will always be on your computer, but imagine this: you have a working piece of code, you modify it a gazillion times and now it doesn't work. You want to go back to revision a gazillion - 1, but you don't even remember what you modified. So even at home, this is very helpful.

Now, at MSDL, we use https:// to access all our project-related repositories and svn+ssh:// to access our personal repositories from the WWW. If you are on the machine that holds your SVN repository, then you just have to use file://. In the following, these are all interchangeable depending on your location. Here are the steps to get started on your personal repository:

• Read this IMPORTANT how-to if you plan to use svn+ssh.
  
  
• Log/SSH into an MSDL machine (you must have an MSDL account, not a local machine account for WWW access).
  
  
• Issue the following command (you can create the repository directory anywhere, but it is preferable to be under your $HOME directory, because when you SSH, this is where you land):
  
  svnadmin create /path/to/.myrepo

• Now, if you already have a clean directory structure (for example, all your projects are under a folder called "myProjects"), then all you have to do is import the entire "myProjects" folder and all your projects within that folder will be SVNed. But, like any other human being, you probably don't have that and rather have a folder for each course you are taking and under that you have a folder called "courseProject" that only contains the course's project. This means that on your computer, you have projects that you want SVNed neatly scattered all over the place. I will assume this is the case. So, what you have to do is import each project separately. First, let's import your first project "myProj" into the repository as follows (assuming you are in myProj's parent directory):
  
  svn import myProj file:///home/user/userName/path/to/.myrepo/projects/myProj/ -m "Initial import"
  
  Notice that I never explicitly created the "projects" folder in my repository! It will automatically get created with the above command, and so will "myProj". The "-m" option is for a message. When you look at the SVN log, these messages show up and should be meaningful to differentiate between revisions. Also, don't forget the trailing slash before "-m", otherwise the directory structure messes up.
  
  
• Now, just to make sure, check if the project was imported:
  
  svn list file:///home/user/userName/path/to/.myrepo/projects/myProj
  
  If there is a listing of your project file(s), SUCCESS and move on. If not, try again!
  
  
• Delete your local version of the project. Don't be scared. There is an SVN version of the project. You now need to check out the project from the SVN repository so that your computer knows that this project is under SVN. If you feel uneasy about deleting the project, compress it and keep it as a back up for now.
  
  
• Make a new, empty folder called "myProj", go into that folder and issue the following command:
  
  svn co file:///home/user/userName/path/to/.myrepo/project/myProj .
  
  Notice the "." at the end of the command. "co" stands for checkout, meaning you want to get your first copy of the project.
  
  
• Now, if you ls -a in the new local myProj folder, there should be a new folder called ".svn" along with all your project file(s). SUCCESS, the project is under SVN.
  
  
• Keep doing this for every project you want under SVN, creating a new folder for each project under the "projects" folder in the repository.

• Make some modifications to project files.
  
  
• Once you have done some modifications, let's check in our changes with the following command (you must be in myProj's directory):
  
  svn ci -m "some meaningful message"
  
  If you are in the myProj directory, all changes in myProj and contents under it will be checked in. If myProj has a subfolder and you are in that subfolder and you issue the above command, only the modifications in that subfolder and under it will be checked in. Basically, the checkin command starts at the current directory and anything below it. So be careful and make sure you checkin everything at the end of the day! Also, a rule of thumb, only checkin working code if you are working with a team. No one wants to look at buggy code that isn't even theirs. If you are the only one on the repository, then do as you wish.
  
  
• Go to sleep at some point...too much work isn't good for you :)
  
  
• Next day, you log on...hmm, let's see if your partner made any changes to "myProj". Let's update any modifications (once again, this command will update anything in the current directory and below):
  
  svn up
  
  If there is anything updated, it will print a U and the file name, meaning your partner actually did some work last night.
  
  
• Now, suppose you have a new file that wasn't part of the repository before but is part of a folder that is under SVN. You must tell SVN to include this new file as part of the project, so you can issue the following command:
  
  svn add path/to/new/file
  
  Word of advice, always make sure you have everything added to SVN. I once was working on a project and forgot to add a crucial file. When I went to school, did an "svn up" and almost had a heart attack because it didn't update the new file. So, the next command is an easy way to overcome this.
  
  
• If you ever want to see what is going on with all the files in your SVN project, here is the golden command (this command will only look at the current directory and anything below it):
  
  svn status
  
  "?" means SVN doesn't know what this file is. If you need it in the repository, add it. If not, you can do whatever. "M" means that your local copy is a modified version so you should checkin. "A" means that this is a new file to the repository that you just added, so after you checkin, it will be in the repository.
  
  
• SVN comes with the usual linux commands. If you have a file in the repository and you delete it on your computer, next time you update, SVN will put that copy back onto your computer. This is because you told your computer to delete the file, but you didn't tell SVN. So, instead of just a plain "rm", you need to "svn rm". Same for "cp", "mkdir", "mv", etc... If ever you delete a file with a plain "rm", just update and delete with "svn rm". Or you can be clever and do the following:
  
  svn rm file:///home/user/userName/.myrepo/path/to/file
  
  But this requires all the extra typing and I am way to lazy for that!

• I made my repository in my home directory but I never wanted to see it when I "ls", so it is a hidden folder.
  
  
• It is best to split your repository from the get-go, otherwise, you are going to have trouble re-organizing it later. So, at the top-level, I have folders for "projects", "publications" and "other", and each of these have numerous subfolders.
  
  
• I always keep a tmp folder in other so that if I ever want to transfer some files from work to home, I just add them to the other/tmp/ folder, retrieve them from my other location and delete them. Note that SVN is not restricted to text files. You can put PDF, DOCs, etc... under version control, though
  svn diff someFile
  
  which shows the modifications between your local copy and the repository's copy, will not work on such binary files. It might say that they differ, but it won't show you the difference! In practice, compiled code (such as a .pyc or .class file) is not put under version control. Also note that using this tmp folder will increase your global revision count by two (one for adding and one for deleting) so if you are picky about your revision count number, use the tmp folder sparingly (see below).
  
  
• You can essentially create as many SVN repositories as you want, one for each project even. One (good or bad) thing is that SVN keeps a global revision count. So, if you are working on project A at revision x and you check in project B, both project A and B will be at revision x + 1 if they are in same SVN repository. I don't mind it because when you issue the command,
  
  svn log
  
  it will layout all the proper revision numbers and messages for the project in which you issue the command, so it looks at the current folder and below! But some are just picky like that :)
  
  
• Some are also picky about having to issue the
  
  svn up
  
  command for each project (this is because all our projects were neatly scattered and we had to import each project separately, as opposed to those who have all their projects in one folder and they just go to that folder, update and everything below it will update with one command). Well, it is easy to write a little script that does all that for you, it is really only 3 lines of code!!! If you look at my customization how-to, you can create a "bin" directory that holds all your personal scripts, put that "bin" directory on your $PATH variable and then you can execute your script from anywhere (as opposed to changing to the "bin" directory and doing "./scriptName"). Here is a sample of my script:
  
  #!/bin/bash
  echo "--Checking in project 1"
  cd path/to/project1/
  svn ci -m "Daily checkin"
  
  echo "--Checking in project 2"
  cd path/to/project2
  svn ci -m "Daily checkin"
  
  I have two other identical scripts, one that updates and another that checks the status. Voila all done with one command!
  
  
• If you use the Apache method, you will have something like:
  
  svn co https://my.svn.server/path/to/.myrepo/ .
  
  If you use the SSH method, you will have something like:
  
  svn+ssh://userName@msdl.cs.mcgill.ca/home/user/userName/path/to/.myrepo/
  
  
• Here is a crash course of pretty much what I just did but for McGill's Compiler course - written by a good friend, Kacper.