Subversion

This page is written for those who wish to obtain/commit the contents of subversion however don't wish to use eclipse to do it. There are many different ways to do this, the command line interface will be described in detail and then some other interfaces will be mentioned that may be more convenient.

Subversion Command Line (Official Client)

I would highly recommend sitting down and reading through the  SVN Book. Chapter 1 provides a good overview of the fundamental components of version control systems, so this may be worth a look if you are unfamiliar with version control systems, how they work, and what they are useful for. Chapter 2 is a more detailed, descriptive version of what this document will be. Chapter 2 provides a basic walk through regarding what a 'typical' user of svn might experience, what problems they might see, and how to solve them. The rest of the book may be useful, but I would highly recommend the first two chapters.

For quick and easy reference there is help built into the 'svn' client. For instance 

?> svn help

provides a list of commands, and for further help run 

?> svn help <command>

To get help one one of the commands listed by 'svn help'. For instance, 'svn help checkout' will provide usage details and a quick overview for using 'svn checkout'.

Obtaining the Source (Initial Checkout)

?> svn checkout svn+ssh://<username>@mary-kate.cs.rpi.edu/projects/metpetdb/svn/trunk/

'svn checkout' will checkout (retrieve the files from the server and place a copy of them in your machine) the current development code. Notice that '<username>' should be replaced by the appropriate username.

The stated command will checkout all of the current MetPetDB code, it is also possible to checkout only portions of the code. For instance, if someone was only interested in working on the design documentation, then they can checkout out only that portion by using the following command. 

?> svn checkout svn+ssh://<username>@mary-kate.cs.rpi.edu/projects/metpetdb/svn/trunk/mpdb-common/design-docs

Working with the Source

Now that we've gotten the files we wish to edit, it is time to work with the files, update some of them, and then share the work with the rest of the team. This section walks you through the commands that you're most likely to use (again, for more details on this section, see Chapter 2 in the previously mentioned svn book).

Getting the changes other's have made (Update)

As we sit down to work, the first thing we need to do is make sure that we've got the most recent, up to date, version of the files we're looking at. To do this we run: 

?> svn update

And now we have the most recent version.

Making changes yourself (Add, Delete, Copy, Move)

Now it is time for us to actually make changes to the files that we're thinking might be good to share with other people. If files need to be edited, then go ahead an edit them. If files need to be added, then create the files, put some content into them, and then use the command 

?> svn add <Filename>

To let SVN know that you want to include them. Similarly if files need to be removed the command 

?> svn delete <Filename>

Will remove it. Similarly, 'copy' and 'move' capabilities can be achieved with the following. 

?> svn copy <Filename1> <Filename2>
?> svn move <Filename1> <Filename2>

The important thing to remember throughout all of this is that just because a file is in a svn directory doesn't necessarily mean that svn is sharing it with everyone else. You need to be sure that svn is aware of it (and this can be done through use of 'svn add').

Review your modifications (Status, Diff)

We've now spent a while making some changes to various files, and we're starting to think we've reached a point where we'd like to share what we've done. First we look at the changes we've made thus far. 

-- Bring our code up to date
?> svn update
-- See what's changed (nothing, since we just updated)
?> svn status
-- Make some changes
?> echo "blahblahblah" >> input.tex
?> svn move metpetdb.dia metpetdb_diagram.dia
A         metpetdb_diagram.dia
D         metpetdb.dia
?> svn copy mpdb-client.tex client.tex
A         client.tex
?> svn delete mpdb-client.aux
D         mpdb-client.aux
?> echo "new file, yahoo!" > new_file
-- Now see what's changed
?> svn status
?      new_file
A  +   metpetdb_diagram.dia
D      mpdb-client.aux
M      input.tex
D      metpetdb.dia
A  +   client.tex

In that last status we see a list of the files that have been changed in some way, and therefore svn would share with the team. The 'A' prefix means the file was added, 'D' means that it was deleted, and 'M' means that the contents of the file were modified. The '+' you see lets you know that the corresponding file additions aren't brand new, but are in some way connected to a file that was previously tracked by svn. Notice that 'new_file' has a '?' next to it, this is because svn found it, but it hasn't been told that it should track that file. This can be remedied by either removing the file, or using 'svn add' to add it. Let's add it. 

?> svn add new_file
A         new_file
?> svn status
A  +   metpetdb_diagram.dia
A      new_file
D      mpdb-client.aux
M      input.tex
D      metpetdb.dia
A  +   client.tex

To see the specific changes made to the files (beyond just that there were changes), then you can use the command 

?> svn diff

Throw away some of your modifications (Revert)

So we have made a bunch of changes, but what if, now that we're looking back on the changes we've made, we didn't want to make one? Well, that we want to use the state that is stored by svn instead of the new version we've created. So we fall back by using 

?> svn revert <filename>

which simply removes any changes made to the file (so if we've added a file it is now removed, if we've removed a file it is added back in, etc).

Bringing your code up to date (Update, Resolved)

Now, while we've been hard at work someone else may have committed some work, so before we progress to committing anything ourselves, we update to be sure that we've got the latest and greatest. 

?> svn update

Now it may be that a change we've made conflicts with a change made by someone else. If so, then it will be marked as 'C' in 'svn status' output, and to remedy the situation simply open the file in your favorite text editor, change the file to be what the final version should be (merging our version and the version committed by someone else), and then we let subversion know that there is no more conflict by running 

?> svn resolved <filename>

(This conflict description was purposefully short, please see the SVN Book for a more full description)

Sharing your Work with the Team (Commit)

Ok, now we've checked and double checked the changes we've made and we're ready to commit and share the changes with everyone else. To do that we use the command 

?> svn commit

Which will take *all* changes listed by 'svn status' and commit them. Before it does this however it prompts you for a commit message, which is a message that will tell others what you did in the commit and why. Detailed commit messages are with your time, expressing what changed and why can help debug and trace previous decisions made.

To commit just a subset of the work listed by 'svn status' you can also use the command 

?> svn commit <file1> <file2> ...

Which will only commit the files listed.

Subversion Clients

Beyond the Official client and subclipse which we all use, your mileage may vary as far as usefulness of the other clients. But they may be useful so I wanted to provide links.