Subversion Tutorial

From NLPWiki

Contents 1 Introduction 2 Concepts 2.1 Help 2.2 Repositories and URLs 2.2.1 Access Protocols 2.2.1.1 svn+ssh 2.2.1.2 http 2.2.1.3 svn 2.2.1.4 file 3 Clustering 4 MultiSite 4.1 Working Copy 4.2 Transactions 5 Basic Commands 5.1 Check Out 5.2 Update 5.3 Status 5.4 Diff 5.5 Check In 6 Advanced Commands 6.1 Branch 6.2 Merge 6.3 Revert 6.4 Switch 6.5 Administrative 7 Notes About Branching/Merging

Introduction

If you already know what subversion is, please skip to the next section.

Subversion is set to become a replacement for CVS (a fine product with unfortunate deficiencies). Unlike CVS, subversion stores its repository in a non-file system accessible database (sleepycat DB). Some interesting features of subversion are atomic commits (transactions), symbolic link versioning, directory versioning (including directory moves), file renames, and repository-wide revision number.

Subversion uses transactions to ensure that the files of revisions (change sets) are commited to the repository as one: Either all of the files in the revision are commited, or none of them are. Thus, no operation on a subversion repository can possibly leave the repository in an unstable condition. In contrast, CVS does not use transactions at all. A commit on a CVS repository can fail half-way through, leaving the repository in an unstable condition as far as the project is concerned. For example, consider a change to two files, one of which has a dependency on the other for successfully being compiled. If the commit of these changes fails, and the file with the dependency is commited, but the other file is not, the code will not build. Subversion elliminates this problem.

Each repository has a single repository-wide revision number (change set number). This implies that multiple projects under a single repository will share the same revision number: A commit to one project will also affect the revision number of the other project. If this behavior is undersirable, use separate repositories for each project.

Now that some of these features have been outlined, it's time to take a practical look at subversion. Keep in mind that an excellent and more complete resource is available at http://svnbook.red-bean.com/. This book, The Subversion Book, covers these topics and more much more accurately and in greater detail.

Concepts

This section outlines the concepts one needs to understand about subversion to use if effectively.

Help

Each subversion command (svn, svnadmin, svnlook, and more) can ouput help information. Each command will print help information when the word help is passed as the first argument. For example

svn help

will cause help information about the svn command to be printed on the console.

Repositories and URLs

Subversion uses a cenral repository to store the revisions (change sets). A repository may be used for one project or many. To create a repository, see the svnadmin commands below. Subversion uses DB (from sleepycat) as a persistence/storage mechanism for each repository. As such, the actually directories and files you put in your repository will not be visible on the file system when you are looking at the repository files. Instead, you need to access the repository and create a working copy (see below). All repositories are available through any of four different access protocols.

Subversion uses a URL to reference a repository. In the next section, Access Protocols, these URL's are outlined in greater detail.

Access Protocols

You can access subversion a few different ways, each with advantages and disadvantages. Let's start w

svn+ssh

http

svn

file

Clustering

You can cluster Subversion with WANdisco's Subversion Clustering technology. With Subversion Clustering, a central Subversion server is no longer a performance bottleneck.

MultiSite

Subversion MultiSite synchronizes work from globally distributed development teams in real-time. Now, all of your development teams can work as one, regardless of where they're located.

Working Copy

A working copy is essentially a copy of the repository on your local system that is separate from the repository and any other working copies you or others may have created. Any changes you make to a working copy are not automatically made to the repository (see commiting below). A working copy is not the only way to make changes to a repository, but it is the most useful.

When creating a new repository, you most likely want to add new files to it. To do this, you need a working copy. Use a check-out command to obtain a working copy of the repository. With this copy, you can add files, makes changes, etc. When you are convinced that your changes are good, commit them using the commit command.

Transactions

Basic Commands

Check Out

Update

Status

Diff

Check In

Advanced Commands

Branch

Merge

Revert

Switch

Administrative

Notes About Branching/Merging

If you're doing work on a branch, you MUST be very careful about merges. Let's consider an example to illustrate why.

Let's say that we create a branch called branches/mybranch from trunk. Here's how you'd do it: svn cp http://entropy.cs.byu.edu/subversion/Clustering/trunk http://entropy.cs.byu.edu/subversion/Clustering/branches/mybranch

(This is essentially a copy--branches are actually just copies of another directory in subversion.)

Okay, now we have the branch. So, we make changes on our branch, mybranch. At the same time, someone else makes changes on trunk. So, trunk and branches/mybranch have forked, essentially. We need to merge at some point.

Let's say that Dan makes changes on the trunk that we want on branches/mybranch. We merge the trunk onto branches/mybranch--however we just created a significant problem. We have to be very careful if we ever want to merge the changes we make on branches/mybranch onto the trunk, because we have brought changes from the trunk to our branch. We do not want to merge the trunk to itself, which would happen if we included the revision that has the merge from the trunk onto the branch as part of the merge from the branch to trunk. Therefore, we must specify precise revision ranges and actually execute two merges--one ranging from the creation of the branch up to but excluding the merge from trunk onto mybranch and one range from the begining of changes after the merge from trunk to mybranch to the end of our changes. This can be a frustrating and difficult process. DO NOT DO THIS UNLESS ABSOLUTELY NECESSARY.

Instead, create a new branch from trunk, merge your old branch onto the new branch, and begin making more changes on the new branch, making sure to delete the old branch. When you're ready to merge to the trunk, we only have to do one merge.

Furthermore, it is time consuming and difficult to merge from a branch to somewhere else multiple times. An excellent practice is to merge from a branch to somewhere else, then delete the branch and recreate it. Believe me, this is much easier and less time consuming. So, after a merge from a branch back to the trunk, ALWAYS DELETE THE BRANCH AND RECREATE IT if you want to continue work on that branch. Merges are not documented automatically in the logs for subversion, so unless you document merges in the logs, you will have no idea which revisions were merges and which were not--worse, you won't even know what a merge included.

Good luck!