Subversion - A Quick Tutorial

Subversion is a version control system that is widely used by many Open Source projects such as Apache and GCC. Subversion started as a project to implement features missing in CVS. Some of these features are:

  • Subversion tracks structure of folders. CVS doesn't have the concept of folders.
  • Subversion has a global revision number for the whole repository. CVS tracks each file individually. A commit that represents one logical change to the project code may change a group of files; in Subversion, this commit will have one revision number instead of separate revision numbers for every changed file in CVS.
  • Subversion commits are atomic.
  • Subversion retains the revision history of moved or copied files.

Subversion commands are very similar to CVS. It's very easy to switch for CVS users. Most of the time it's a matter of replacing cvs with svn. The following is a tutorial and cheat-sheet to help you get up and running in Subversion quickly.

Installation

The first step for using Subversion is installing it. This depends on your system. In Ubuntu and Debian, it a matter of running the following command:

$ sudo apt-get install subversion

Subversion has packages for many systems, Linux (Gentoo, Debian, Fedora, ...), Mac OS X, FreeBSD, Windows, ...

Creating the Repository

The first Subversion tool we will use is svnadmin. This tool is for administration tasks, like creating repositories, making backup dumps, and the like. To create a repository, open the command line, change the current directory to where you want to create it, and run svnadmin:

$ cd /home/ayman
$ svnadmin create svn

(I created my repository under my home directory: /home/ayman)

I called my repository svn. You can call it whatever you like. Subversion uses this directory to store information about your projects, like file revisions. You won't need to directly deal with this directory, so I suggest keeping it in a safe place and not tinkering with its contents unless you know what you're doing.

Importing Projects

Now that we have a repository, we will use the svn tool to import and manage projects. To import a project, first create a directory for it in your repository. To do so run svn mkdir:

$ svn mkdir file:///home/ayman/svn/myproj

(Replace /home/ayman/svn/myproj with the actual path to your repository and the new project name)

Subversion will open your default text editor and ask you to enter a log message. Enter an explanation of what you're doing, save, and exit the editor.

Next, it's time to import project files. Change the current directory to the project's directory, and run svn import:

$ cd /home/ayman/[...]/myproj
$ svn import file:///home/ayman/svn/myproj

(This will import all files under /home/ayman/[...]/myproj to the newly-created myproj directory in your repository)

Check out, Modify, Commit

As I said, the repository is stored in the svn directory which you won't deal with. To work on your files, first you need to check a working copy out of the repository. To do so, use svn checkout:

$ svn checkout file:///home/ayman/svn

A new directory named myproj will be created containing your project files. You can work and modify them. Once you're done and you want to store the new revision in your repository, run svn commit in the checked-out myproj directory:

$ svn commit

Subversion will open your default editor asking for a log message. Again, enter an explanation, save, and exit.

Working with Revisions

Now let's make real use of Subversion. While working with revisions, you can:

Check Status

$ svn status <filename>

Compare different Revisions

$ svn compare -r R1:R2 <filename>

(Replace R1 and R2 with actual revision numbers you want to compare)

Revert Local Edits

$ svn revert <filename>

Revert to Previous Revisions

$ svn update -r R

(Replace R with an actual revision number)

<filename> is optional; you can run the previous commands on the current directory if you omit it.

Final Word

This is a very quick start for using Subversion to control local projects. For extended help on commands, you can always use svn help <command> to get a help message on <command>, for example:

svn help import

This will give a detailed explanation on svn import.

In addition, check out "Version Control with Subversion" for more information.

Good luck, and happy subversion'ing!

Comments

JVA
JVA's gravatar

Version Control, is an essential tool in software engineering, so good for you to switch into this organized programming world, no lost versions anymore, no overwritten version either. I use CVS, i've heard that SVN is better, but CVS is more popular "as far as i know", and i started with CVS first. I do basic management of my source, no branches and stuff, so i'll stick to CVS. Anyway, nice tutorial.


Posted at 4:23 p.m. on January 13, 2006

nart
nart's gravatar

btw, its also nice to use Trac (http://www.edgewall.com/trac/) with svn for collaborative projects.


Posted at 1:39 p.m. on February 14, 2006

Dandor
Dandor's gravatar

It's a nice little tutorial. Just one remark. I think it's a better idea to create repositories on per project basis, this way you will have separate numbering for different projects. Anyway it's a very useful summary.


Posted at 2:56 a.m. on March 16, 2006

Ayman Hourieh
Ayman Hourieh's gravatar

Fixed. Thanks. I installed a new filter that broke this article.


Posted at 2:56 p.m. on August 20, 2006

prasad iyer
prasad iyer's gravatar

Very well written. I am setting up my repository now. Thanks for the help


Posted at 9:04 p.m. on August 30, 2008

Pelle
Pelle's gravatar

Dear all,

I'm only just getting started with version control and I chose subversion with TortoiseSVN for my needs. I had thought about doing repositories per project, too, but somehow I feel like this is not intended. Does anyone know where to start reading about repository-layout and whether it's a good or bad idea to do this on a per-project approach or rather do repositories for a single group of developers or whatever?

Any help on this would be greatly appreciated!

Thanks, Pelle.


Posted at 12:05 p.m. on September 12, 2008

Aamod
Aamod's gravatar

Very neatly written and useful for lazy people like me. Using svn after just reading this single page.

Thanks ;-)


Posted at 3:44 p.m. on October 24, 2008

Ahmed El Gamil
Ahmed El Gamil's gravatar

Thanks Ayman for this simple yet powerful tutorial


Posted at 8:17 p.m. on November 17, 2008

DJ
DJ's gravatar

Thanks for the simple version of setting this up.


Posted at 12:28 a.m. on February 11, 2009

Abdullah
Abdullah 's gravatar

Well written totorial. Thanks


Posted at 1:22 p.m. on February 16, 2009

al
al's gravatar

i have installed Subversion in Ubuntu but how do i access it from WinXp.


Posted at 12:31 p.m. on March 3, 2009

Matthew Frazier
Matthew Frazier's gravatar

Thanks for putting this together. A very clean, concise guide to setting up a simple versioning system. I was up and running in under 15 minutes.


Posted at 4:54 p.m. on March 20, 2009

Anonymous
Anonymous's gravatar

Don't know why anyone would want to use a command prompt and not the context menu (assuming you're using windows) to do all this above. Same with using Visual SVN Server. Command prompt is sooo tedious.


Posted at 3:18 a.m. on April 21, 2009

GeekyGrad
GeekyGrad's gravatar

This is a great piece of work - I linked to it in my article on using Subversion for LaTeX files.


Posted at 8:25 p.m. on April 30, 2009

Igor Grinkin
Igor Grinkin's gravatar

I'm using:

Subversion command-line client, version 1.4.6

svn compare -r R1:R2 [filename]

did not work for me :(

Unknown command: 'compare'

svn diff -r 1:2 filename

worked fine.

I'd also add

svn log filename

It shows you the revision numbers

Thanks for the tutorial!


Posted at 5:30 p.m. on July 6, 2009

Anonymous
Anonymous's gravatar

I'd give you 3 thumbs up if I could...


Posted at 5:44 p.m. on August 19, 2009

Ali
Ali's gravatar

Thanks for this short and to the point article... Many thanks,


Posted at 1:10 a.m. on September 14, 2009

Binary Soldier
Binary Soldier's gravatar

Having just installed Subversion today it's great to find such a useful quick start guide.

Version checking is something new to me, and since SVN seems to be the industry standard, I thought I should get to grips with it as soon as possible.

Thanks for sharing!


Posted at 12:11 a.m. on September 25, 2009

Chris
Chris's gravatar

Just wanted to say thanks for this... I've been tearing my hair out trying to get this working and set up with my svn client; so much of the documentation/forum-responses have been useless... very nicely done.

For any other folks using this approach to set up the repo, and are looking to use Tortoise, or Versions, or some other GUI to access it, I was getting hung up on finding the right URL to direct the client to... turns out it was ssh login plus the absolute path from the server root down to the svn project directory

e.g., svn+ssh://username@testsite.com/home/domains/xyz.com/html/svn/my_proj


Posted at 5:45 a.m. on September 28, 2009

ge
ge's gravatar

Thanks for posting this article.

I'm trying to learn SVN and am having trouble connecting to a remote SVN server I've recently setup on a Windows machine.

I've created a repository on the server with the following full path: C:svntest_repository.

When I try to create a project directory in the repository using

"svn mkdir http://mySvnServer.myDomain/svn/test_repository/new_project" It returns an http "200 OK" message but no directory ever gets created on the server.

If I try to do an initial import of a project I get a similar result.

"svn import http://mysvnserver.myDomain/c$/test_repository" returns the message "svn: OPTIONS of 'http://mysvnserver.myDomain/c$/svn/test_repository': 200 OK (http://mysvnserver.myDomain) which appears to be OK, except that when I go to the server and check to see if the project directory was created, I find that it has not.


Posted at 6:05 p.m. on October 9, 2009

Darren
Darren's gravatar

Thanks so much for the tutorial, it clarified some of the conceptions I had about this neat little program.


Posted at 5:36 a.m. on January 3, 2010

kobedi
kobedi's gravatar

Thank you very much...Good summary.


Posted at 7:14 a.m. on January 6, 2010

Alexander
Alexander's gravatar

At first, a very sincere THANK YOU Ayman!one-eleven!

I got subversion up und running in a few minutes.

Al: If you want to access SVN via Studio .net (2005 and Successors) you may be interested in Ankh svn. It works very fine for me.

You may need to tune your authz and passwd files in the svn Root:

http://groups.google.de/group/Subversion-SVN/browse_thread/thread/ebd14b999b67e458


Posted at 6:47 p.m. on January 8, 2010

Yatko
Yatko's gravatar

Hi, and thanks for this tutorial. However I was unable to get It work: $ svn mkdir file:///home/ayman/svn/myproj Subversion will open your default text editor and ask you to enter a log message. Enter an explanation of what you're doing, save, and exit the editor. It saves a .tmp file and does not create any directory

svn import file:///home/.... Creates second .tmp file ()

I gave up.... I am sure it is a great toy, but ....for insiders only.

Thank you!


Posted at 2:47 a.m. on February 16, 2010

Ranga
Ranga's gravatar

Nice Tutorial. We can learn and do it in matter of 10mins. Thanks Author.


Posted at 7:56 p.m. on May 10, 2010

Nayana Adassuriya
Nayana Adassuriya's gravatar

hi all,

I'm a new user for the Visual SVN. I'm using Visual SVN free version and tortoise SVN as client in windows xp environment. I use these configuration for a PHP project. so what i do is visualSVN and xampp install in a same computer and make a make a client environment in side of the xampp root folder using tortoise SVN. now what i want is automatically update the client inside the xampp when somebody comment to the Repository

I tried lot with hook script like fallow

"C:/Program Files/VisualSVN Server/bin/svn.exe" update "H:/WEB SERVER/xampp/htdocs/WEBSERVER/" but it not succeed. and no error message.

please help me to achieve my target.

thanks all, Nayana Adassuriya


Posted at 11:35 a.m. on May 19, 2010

Tarik
Tarik's gravatar

It would make more sense to checkout the project I want to work on using: svn checkout file:///home/ayman/svn/myproj instead of svn checkout file:///home/ayman/svn which would checkout each and every project in the repository?


Posted at 10:41 a.m. on May 26, 2010

blnl
blnl's gravatar

When I import my project files into the repository "svn import myproj file:///home/ayman/svn/myproj", "myproj" is still not the working copy. How can I tell svn that I want "myproj" to be the working copy?

Currently I have to delete "myproj" and then again checkout "myproj", but I hope there is a simple way of making the original "myproj" working copy.


Posted at 2:40 p.m. on June 2, 2010

gjwilson21
gjwilson21's gravatar

Simple, yet this the kind of article that really helps people set up their first repository in no time.


Posted at 10:06 p.m. on June 17, 2010

Avi
Avi's gravatar

Thank you, your contribution goes beyond quick help. --Avi


Posted at 5:16 p.m. on December 27, 2010

Vadim
Vadim's gravatar

Thanks for good tutorial, good job.

I just have a question related to the subvertion security, how to manage user which could read and write the repository content? How to set passwords? thanks.


Posted at 6:15 p.m. on December 29, 2010

Juan Pablo
Juan Pablo's gravatar

Thanks!!! This is a great and useful tuto...


Posted at 9:25 p.m. on February 1, 2011

Tushar
Tushar 's gravatar

Thanks a lot!!! This is really quick and helpful quide..


Posted at 6:10 a.m. on February 14, 2011

Madiha
Madiha's gravatar

I I m preparing for my exam and SVN is part of course so i want a short tutorial on svn that can help to answer the exam questions. . . It really helped


Posted at 10:48 a.m. on February 26, 2011

Madiha
Madiha's gravatar

Just one thing that i still want to know is what is 'source safe' and what is the command for it?


Posted at 10:51 a.m. on February 26, 2011

Lucas Campos
Lucas Campos's gravatar

Thank you very much for the concise tutorial. It was VERY helpful.

The compare part did not work for me, but it's just use diff instead.

But I'm with Grinkin on using svn log =p


Posted at 12:19 p.m. on March 12, 2011

Michael
Michael's gravatar

Excellent tutorial. I have never tried SVN and this tutorial is good enough that let me install it and use it in my projects.


Posted at 8:03 p.m. on May 4, 2011

David
David's gravatar

I've been looking into SVN for a few hours now, this is by far the cleanest tutorial!


Posted at 3:30 p.m. on June 27, 2011

Scott
Scott's gravatar

Thank you! This was well-explained and very helpful. One clarification that might be helpful is to tell the user where the revision numbers can be found, before telling them to use them, namely, when you describe

svn compare -r R1:R2

I think the command is

svn log

but there may be a better way.

Thanks again!


Posted at 9:20 p.m. on July 13, 2011

Phil
Phil's gravatar

Awesome tutorial. One thing. I'm using eclipse for the GUI check-in/out features of subversion. I have a middleware server that'll communicate with the subversion client which then talks to the subversion server. What's the syntax to specify the URL for the subversion repository in unix? Anyone knows, please share. Much appreciated it. Thanks.


Posted at 1:58 p.m. on August 2, 2011

Jeronimo
Jeronimo's gravatar

Thanks! It was very useful!


Posted at 7:33 p.m. on August 15, 2011

alex
alex's gravatar

Saved me a lot of pain going through the 450 pages of the manual, thx mate.


Posted at 1:33 p.m. on October 26, 2011

Gigi Mathew
Gigi Mathew's gravatar

Great Tutorial explains the product to the new users.


Posted at 4:36 a.m. on December 1, 2011

Post a comment

HTML is not allowed. You can use markdown syntax to format your comment.