Subversion Tutorial

Subversion (SVN) is a version control system designed specifically to be a modern replacement for CVS. This article briefly overviews the essentials of SVN, as well as using SVN on Linux and on Windows (through TortoiseSVN).

Essentials

Introduction

The best analogy for SVN's model is a library. The library maintains the "master" copies of all the source code. To obtain the source code, you "check out" a copy. You can then make revisions to your copy. When you're ready to return your changes to the master copy, it is called a "commit."

SVN source code repositories can separated into "modules," which are simply sub-directories of the repository. Each module can have directories or files (both text and binary).

Access to SVN repositories is generally based on three methods:

• Local filesystem or network filesystem, accessed by client directly (via file://)
• WebDAV/DeltaV (over HTTP or HTTPS) using the mod_dav_svn module for Apache 2
• Custom "svn" protocol using svnserve, either plain text (svn://) or over SSH (svn+ssh://)

Basic Commands

These are the four essential SVN operations:

• co (or checkout) - Retrieves the current copy of the source tree.
• update - Updates your local copy to sync any changes from the master.
• add - Adds a file or directory to the local source tree.
• commit - Commits any local changes to the master (including adds).

Checkouts

Normally, you only need to checkout code once. After this, you can simply update your code to acquire any changes. A clean checkout often helps remove stale files.

Updates

In practice, you should always update your local source copy before editing. This is to prevent merge problems, where two developers edit the same file and try to commit it at the same time.

Some people prefer to keep two copies of the source locally. The first copy is used only for committing changes and updating, and the second copy is only used for editing. This essentially keeps a local master and a local volatile copy.

Adds/Removals

SVN adds are also complemented by removals (the command is remove or delete). Both are considered changes to the source tree, and thus, they do not take effect until committed.

Commits

SVN commits are always atomic and transactional. That means if you commit a set of changes while your copy is older than the master, or otherwise unsynced, that file cannot be committed (and you may have to manually merge changes in). Furthermore, when committing a set of files, if one fails, the entire commit should fail.

When commits do fail, it is important to review why. Otherwise, you could risk reverting changes from another author.

Differences From CVS

While SVN is fairly similar to CVS, there are some important differences that should be noted.

Revisions

In CVS, revisions are on a per-file basis. In Subversion, the repository looks like a single filesystem. Thus, each commit results in an entirely new filesystem tree and each tree is given a revision number. When someone speaks of revision 25, they are referring to the way the SVN repository looked after the 25th commit. In short, revision numbers refer to a particular state of the repository.

Directories

In CVS, directories are merely containers for other files or directories. But in SVN, directories are versioned in the same way files are. If a new commit only contains directory changes then a new revision number will be assigned to that commit. This means that the remove or delete commands work on directories.

Branches and Tags

SVN does not distinguish between filesystem space and “branch” space. Branches and tags are regular directories within the repository filesystem.

In general, the root directory of a repository might contain three directories: trunk, tags, and branches. The trunk can be compared to a CVS repository's "head" or it could be considered as the main branch of a project. The tags and branches directories are self-explanatory.

Creating a tag or branch simply involves using SVN's copy command to copy the trunk or a specfic revision into the tags or branches directory.

TortoiseSVN

Introduction

TortoiseSVN is a Windows Explorer/Shell SVN integration tool. Most users like it for its inherent simplicity and the quick ability to checkout source from within any Windows directory.

TortoiseSVN can be downloaded from: http://tortoisesvn.sourceforge.net/downloads

Once installed, you should either kill and restart all explorer.exe instances, or simply reboot. Once installed, read below.

Basic Usage

To start, create an empty folder anywhere on your computer. Open it and right click somewhere inside. You should see a "SVN Checkout" option similar to below. Click it.

Empty TortoiseSVN Menu

The dialog box will say "Checkout." This is where you enter the information about the SVN server.

• URL of repository: - This is where you enter the server's path to the SVN repository. You must know this in advance.
• Checkout directory: - This is where the working copy of the repository will be stored. This is usually automatically filled.

For example, SVN connections to alliedmods.net generally look like:

If you have an account on the server, and you know you have SSH based access to the repository, then svn+ssh:// should be at the beginning of the URL, followed by your account user name and a @. This is shown in the example image. However, if you wish to anonymously check out a repository or do not have an actual account on the server, then svn:// must be at the beginning, followed by the path to repository with no user name specified. For example, it might look like this:

svn://alliedmods.net/svnroot/sourcemm/trunk

If the repository you are checking out has the tag/branch/trunk directory structure, you should be certain to check out the trunk or a specific branch or tag. Otherwise you may end up downloading every tag and branch along with the trunk.

Once all the files are downloaded, you will see them in the folder. You can then perform general SVN operations, such as committing, by right clicking in the empty spaces.

To operate on a specific file, you can simply right click on the file. TortoiseSVN addd overlays to the file icons based on their status. A green checkmark means "unmodified locally," a red exclamation point means "modified locally," and an orange exclamation point means "merge conflict." Files not in the repository do not have any overlay icons.

To commit changes, simply right click and choose "Commit." You can either commit all changes to the local scope or one single file. When you commit, you are allowed to attach a text comment to your revision. This is a good way to let people watching or reading the SVN repository to see an overview of your changes.

Adding/Removing Files and Directories

Right click on the new file and then choose "Add". Click OK on the dialog box. You will need to commit.

To add a directory and all its files, right click on the directory and click "Add." You will get a dialog box similar to below. It is important to uncheck files that might accidentally get merged in, such as password text files, binaries, et cetera.

Likewise, to remove a file, simply right click it and use "Remove." Directories are removable as well.

Linux/Command Line SVN

Introduction

Command line SVN requires the SVN binary to be installed and ideally accessible from your PATH environment variable.

Before you begin, you should also know whether or not the repository you are trying to checkout will be accessed via SSH or not. If you have an account on the server containing the repository, then it is likely you will be using SSH via the svn+ssh:// protocol when you enter the URL to the repository. If you wish to anonymously checkout a repository or do not have an account on the server then you will be using the svn://.

Basic Usage

The checkout example from TortoiseSVN would look like:

svn co svn+ssh://[email protected]/svnroot/sourcemm/trunk sourcemm

This will create a new directory called "source" which will contain all the downloaded files from the master's trunk.

To then update this copy, you simply need to type "svn update" while inside the directory.

Similarly, "svn commit" will attempt to commit the files in the current directory. It will bring up an editor (defined in the SVN_EDITOR or EDITOR environment variables) so you can type your comment -- simply save and exit the editor once done.

You can "svn add <file>" or "svn remove <file>" as well.

Creating Repositories/Modules

If your SVN is local, you can create a new repository like this:

svnadmin create mysvn

This will create a directory in the current location named mysvn which will contain the new repository.

To create a new module, create an empty directory somewhere. Then use "svn import" as shown. Note that if you use this with a directory that contains files, the files will be added as the initial import. This is a good idea if you already have the source code structure in place.

mkdir trunk
svn import -m "Initial import" trunk file:///home/users/damagedsoul/mysvn

The URL to the file can also use svn+ssh:// or svn:// if you so desire.

SSH Authentication

If you are accessing your repository via SSH using the svn+ssh protocol, you may have noticed that you must enter your password more than once on certain occasions. When checking out a repository, you may have to enter your password three or four times. Operations such as adding, removing, or committing usually only ask for your password once. But other commands may also require it more than once.

However, there is way around this through the use of a private-public key pair. See SSH Keys for more details.

External Links

• Subversion Home Page
• TortoiseSVN Home Page
• Version Control with Subversion - free online book about Subversion with lots of helpful information
• Subversion Wikipedia article