svn Tutorial

By Xah Lee. Date: . Last updated: .
subversion logo new

This page is a tutorial of using Subversion (SVN), a version control system.

Check Out, Commit

What commands are available?

Type svn help.

How to checkout a project?

cd to a directory where you want the files to be. Examples:

svn checkout svn:// --username john
svn checkout svn:// --username john
svn checkout ergoemacs --username john

How to commit a change?

Once you checked out, made your modifications, then you can check back in (commit your changes). To commit, cd to the working dir, then do:

# commiting all files in current dir
svn commit . -m "one-line summary of what you changed"
# commit one file
svn commit -m "one-line summary of what you changed"

How to add a file or dir?

If you created new files in your working copy and committed it, that won't work. After you created a file, you need to run a svn command to add the file, then commit. Same for directories.

To add a file or dir, use the add command:

svn add filename
svn add dirname

Once you are done adding, then you need to do a commit.

How to delete a file or dir?

If you simply delete the file/dir on your disk then commit, it won't work. Use the svn “delete” instead.

To remove a file or dir, use the “delete” command, like this:

svn delete filename
svn delete dirname

svn will delete the file or dir for you. You should not delete the file/dir yourself.

How to update your working dir?

cd to your working dir and use the svn update command. Changes made by others will now show in your working copy.

svn update .

Updating won't erase changes you made. When there's a conflict, svn will tell you.

How to erase your local edits?

If you made some changes (and have not committed yet), and decided it's all bad, you want a clean copy from the repository. You can do revert:

svn revert .

This means all your changes will be gone.

Getting Info (info, diff, log, status)

How to find out what's the revision number of a file?

Use the “info” command.

svn info init.el

Here's a sample output:

c:\Users\xah\ErgoEmacs_Source\ergoemacs\ergoemacs>svn info init.el
svn info init.el
Path: init.el
Name: init.el
Repository Root:
Repository UUID: f1309a34-a24b-11de-ba4d-5dbaeb624ccf
Revision: 425
Node Kind: file
Schedule: normal
Last Changed Author: john
Last Changed Rev: 392
Last Changed Date: 2010-06-03 05:57:19 -0700 (Thu, 03 Jun 2010)
Text Last Updated: 2010-06-03 05:56:21 -0700 (Thu, 03 Jun 2010)
Checksum: 4216c9db9c13ca60fa12415bbf0c3ae8

How to see what's the diff between your local version and repository version?

svn diff filename
svn diff dirname

How view the change log of a file or dir?

To get all change log of a file or dir, do:

svn log dirPath -l 50
svn log filePath -l 50

The -l 50 limits printing to a max of 50 entries.

To view the log of a particular revision number, do:

svn log -r 420 -v

The -v prints the files changed for that revision.

Here's a example of printing all change log of a dir, with a date range.

svn log . -r '{2011-05-28}:{2011-07-30}'

How to find which files changed on your disk?

svn status .

That will tell you whiche files are different in your dir compared to the ones in repository. If the output is empty, that means they are identical.

For explanation of the output, see: svn help status.

Reverting to a Previous Version

How to revert to a previous version?

If you want to revert a version to a previous version, here's what to do. Note that there's a “revert” command, but that's not what you want. The “revert” command simply erase your local edits. What you want is actually the “merge” command. (yes, it is very unintuitive)

Suppose you have this file xyz.txt, and the current version is 161, you want the version 107. These are the commands you need to run:

svn merge -r161:107 xyz.txt
svn commit -m "Reverted to revision 107." xyz.txt

The “merge” command will change that file on your machine to revision 107. The “commit” actually makes that change back to the central repository.

svn Date Format and Date Range

Many svn commands has a -r option. This option accept a revision number, or a date. Here's some example of using date.


svn checkout -r '{2006-02-17}'
svn checkout -r '{15:30}'
svn checkout -r '{15:30:00.200000}'
svn checkout -r '{"2006-02-17 15:30"}'
svn checkout -r '{"2006-02-17 15:30 +0230"}'
svn checkout -r '{2006-02-17T15:30}'
svn checkout -r '{2006-02-17T15:30Z}'
svn checkout -r '{2006-02-17T15:30-04:00}'
svn checkout -r '{20060217T1530}'
svn checkout -r '{20060217T1530Z}'
svn checkout -r '{20060217T1530-0500}'

Date Range

Example of a date range.

svn log . -r '{2011-05-28}:{2011-07-30}'

Creating Projects

Here are some tips for svn admins.

How to create a project?

First, create the svn root dir using this command:

sudo svnadmin create /usr/local/svn_rooty

You need do the above. It is not merely creating a dir with “mkdir”.

The /usr/local/svn_rooty is the dir you want svn to hold the repository.

To import a project, do:

sudo svn import /Users/john/mysourcecode file:///usr/local/svn_rooty -m "Initial import of project X"

The path /Users/john/mysourcecode is the path of your source code folder, the file:///usr/local/svn_rooty is a path for the svn root path, in a URL format. The -m is a comment.

Then, modify the file


To contain for example these lines:


The left side is user's login name, the right side is password. This is for running svn as a stand-alone server.

modify the file /usr/local/svn_rooty/conf/svnserve.conf to contain these lines:

anon-access = read
auth-access = write
password-db = passwd
realm = transvections

What should be the file permissions?

The following dir needs to be owned by “svn” user.


How to start the stand-alone server?

First, change to svn user.

sudo su svn

Then, run the following command to launch it, while you are “svn” user.

svnserve --daemon --listen-port=3091 --root=/usr/local/svn_rooty

The --daemon is for stand-alone, the --root= specifies root, so that in the checkout command it doesn't need to specify the full path. The --listen-port=3091 can be omitted. The default port for svn is 3690.

Once you did this, a client can checkout with these commands:

svn checkout svn://
svn checkout svn://

# if using default port
svn checkout svn://

Importing Your Source Code Into Google Code

If you host your project at Google Code, they have svn built-in. Here's instruction on how to import your source code dir into google code. (we assume that your source code dir is brand new, and is not already under a svn.)

By default, a svn repository is created for you as soon as you filled out the form for a google code project.

Now, you need to do a svn checkout, even though there's nothing to check out. The purpose to checkout is to create those svn internal files on youl local disk.

To checkout, first create a dir on your local disk where you want the local mirror to be. Then, cd to the dir, then do:

svn checkout xyz --username john

Once you have checked out, you'll see that your current dir has a dir named .svn. That's svn's internal files.

Stay in the dir. Now, you can use the “import” command to actually create stuff in your svn repository at google code.

Suppose your source code dir is at c:/Users/xah/xyz. You want to import this dir to google code's svn. Type the following in your command line:

svn import "c:/Users/xah/xyz" -m"first import of the project."
svn import "c:/Users/xah/xyz" -m"first import of the project."