Subversion Tutorial
What is Subversion?
Subversion is a tool that allows a team of people to work on a project together. Subversion remembers all the changes that are made to a project and allows multiple changes to be merged together. The code is stored in a repository (we provide that for you) and you can import and export files from it. The repository is stored on a server through a URL, which makes it easy to work on the project from anywhere. You can check out a copy of a file and Subversion will keep track of all the changes made to that file. You then commit the file back into the repository and all the changes that you made are copied into the repository.
For this course you will save the programs you write in your subversion repository. This will allow the TA's access to those files so that they can pass off your projects. You will need to submit all your files to the repository to pass off labs for this class.
Using subversion will familiarize you with some of the tools that are used in industry. Subversion is extremely applicable in the professional world and so it is good practice to successfully use it now.
Your Subversion Repository
Your repository is located at:
svn+ssh://(csid)@schizo.cs.byu.edu/users/groups/cs235(csid)/cs235/
schizo is the name of the server where your repository is stored.
Cs235 is the location of your repository on the server.
"(csid)" is you CS username
Starting a Project
Suppose you want to get started on project one. Use this command to create a folder in your repository for lab1:
svn mkdir -m "starting lab1" svn+ssh://(csid)@schizo.cs.byu.edu/users/groups/cs235(csid)/cs235/lab1
Svn runs the subversion client.
Mkdir is the action that makes a directory in the repository.
The '-m "starting lab1"' gives a message that subversion will record
in its log.
Lab1 is the folder where lab1 will be stored in your repository.
It is important that you store all project 1 files in the 'lab1'
folder, project 2 in 'lab2', and so on.
If the folder isn't named correctly your lab submission will not work.
Subversion will ask for your username and password. Use your CS (not Route-Y) username and password. If the prompt shows the wrong username, just hit enter.
Checkout a Working Copy
Create a folder named 'cs235' where you will store the local working copies of all your projects.
mkdir cs235
Because we use packaging, the name of the folder to which you save your projects must match the package declaration at the top of each file in your project. For example: A file with the package declaration "package cs235.java;" at the top must be saved in a folder named "java," which, in turn is inside a folder named "cs235."
Navigate into the 'cs235' folder.
cd cs235
Checkout the 'lab1' folder from your repository:
svn checkout svn+ssh://(csid)@schizo.cs.byu.edu/users/groups/cs235(csid)/cs235/lab1 java
This makes 'java' your working directory for lab 1.
Add The Project Files
An empty directory isn't much good, so now you need to get the files and place them in your working folder, java. Download the files from the class website and put them in the folder. To add these files to the repository, go into the 'java' folder and add them using these commands:
cd java
svn add *.java
The files are then marked as under subversion control, and they will be sent to the repository the next time that you commit your files to the repository.
Commit The Changes
Commit your changes to the repository with this command:
svn commit -m "add provided files"
Committing is when you are updating the repository with changes that you have made. In order to commit something to the repository, it needs to be in a folder that is controlled by subversion. That is why you did the checkout step earlier. If you hadn't done this step, it would be impossible to commit things to the repository. Nothing can be checked in unless it is in a working folder and is being kept track of by subversion.
You can now make changes to the files in your working copy. When you are ready to put the changes into your repository you simply repeat the commit command (with an appropriate log message). If you create any new files in the working copy don't forget to use an add command to add them to the repository.
Working From Another Location
Now let's say that you are working from a different computer and don't have your files with you. As long as you have subversion, you can access those files. You can check out the entire folder to a new location (thus creating a new working directory) using the checkout command again:
svn checkout svn+ssh://(csid)@schizo.cs.byu.edu/users/groups/cs235(csid)/cs235/lab1 java
This will allow you to get the files, make changes and then re-submit. Now suppose you are back on the first machine and you need to get your updated files. Since you already have them checked out, you won't use the checkout commmand again. You will use update. From the 'java' folder, use this command:
svn update
This gets the files from the repository and overwrites your local files with them. This command will tell you what files have been updated. It won't list anything if no changes are made.
Other Subversion Commands
In general, the steps we have covered are the only steps that you will need to be able to use subversion. There are many other svn commands that you may want to use. If you google any command (for example svn update) the top page should be an entry from the online book on subversion. The beginning of the web address is svnbook.red-bean.com. Here's a short summary of some of the other commands.
Delete
Suppose that you placed code in the repository already, but you want to start over and get rid of that code. This is how you would delete all the code for lab 1:
svn delete svn+ssh://(csid)@schizo.cs.byu.edu/users/groups/cs235(csid)/cs235/lab1 -m "starting over on lab 1"
Move
Suppose that you want to move a file, either within your working copy or in the repository. You can use the svn move command. One use of this might be renaming a java class. You might forget that a class has to have the same name as the file it is in, and name a class PairImpl but place it in a file name Bob.java. You get a compile error locally and want to change the name. If you just create a new file and copy the contents, that file wouldn't be under version control, but the old, broken one still would be. Instead of having multiple commands to worry about, just use the move command. From the folder where Bob.java is, you'd do this:
svn move Bob.java PairImpl.java
Copy
The 'copy' command can be used to create a duplicate of a file from one directory and add it to another within the repository.
svn copy svn+ssh://(csid)@schizo.cs.byu.edu/users/groups/cs235(csid)/cs235/hello.java lab1 -m "description"
List
If you have forgotten which files you copied to the repository in your lab1 folder, you can check by using list:
svn list svn+ssh://(csid)@schizo.cs.byu.edu/users/groups/cs235(csid)/cs235/lab1
Log
You may want to remember what the difference was between the various versions of lab 1. If you have been telling svn what changes you were making as you made them (that's the part where you say -m "description of the changes") it has stored your messages for you to review. You can go to your working copy of lab 1 and type:
svn log
It will then tell you the revision number (i.e. r5 for revision 5), the user that changed it, the date, how many lines were changed, and the comment associated with it. This can help you go back if you made and committed changes that you no longer think are a good idea.
Status
To review all of the changes you've made and the status of your code, enter:
svn status
For more detailed information, you can enter the status command with -v to get in depth feedback.
Export
Export copies code from the repository to your local machine but doesn't place that code under version control. You would probably only rarely want to use this command, since you will want to sync your code with the repository. Example:
svn export svn+ssh://(csid)@schizo.cs.byu.edu/users/groups/cs235(csid)/cs235/lab0 bob
A folder named 'bob' is created by the export command and put inside the folder you are currently in. If you already have a folder named 'bob' in your current folder it won't work.
Help
If you ever need further help with Subversion commands, simply enter
svn help [command]
For example, if you have any questions about the commit command, you would type
svn help commit
and Subversion will give you details about running that particular command, and its functions and other options.
Windows Subversion Client
If you are using windows you may want to download the TortoiseSVN client.