Subversion/Basic Usage Guide

Wikipedia has related information at Subversion (software)

Subversion (SVN) is a version control system initiated in 2000 by CollabNet Inc. It helps you to track the history of file and directory changes over time. Generally a Subversion repository is used by a community of people. A repository is a centralized data storage, and people usually perform their changes locally, and then publish ('check in' or 'commit', all are synonyms for this process) them to the repository. So, what they have on their local machines is a Working Copy - a copy of a repository subtree (or maybe the whole tree):

Mechanism

The subversion mechanism is different from the mechanism of CVS, its well-known predecessor. Let's see how successive commits are archived on the server :

First, a user imports the files and the repertories on the server. All the files and repertories are at release (or revision) 1.

First commit

Then a user commit some changes. Only files fil1 and fil3 contain modifications so only these items are committed. The both are committed at the revision 2. If we want to retrieve all the files to the last revision, we will have files to the revision 2 or the last previous revision (i.e. 1) if not exist.

Second commit

For the commit of the release 3, only the files fil3 and fil4 have changes. Note that the file fil4 has no revision 2.

Third commit

The files fil2 and fil3 are committed.

Fourth commit

One file has been added : fil5. There is no version of this file until the release 5.

Fifth commit

One repertory has been added : rep5.

Sixth commit

When a user updates her/his local files to an old release (for instance release 4), subversion will send each file or repertory at the release 4 or the last previous one if not exist.

An update to an old revision

How do we use Subversion with JavaSVN

So, there's a server-side storage of versioned data called repository, and there're clients who access that repository. And JavaSVN is:

A client-side library.
It provides APIs for both local operations that don't need a repository and concern only a Working Copy, and for direct working with a repository.
At the same time the latest version of JavaSVN provides some extra features: it can create local repositories, replicate (copy in filesystem) existing ones, etc.
It's quite flexible to configure.

Unfortunately, the Working Copy (WC) format limits users to operating only on files and directories. JavaSVN helps to workaround this limitation, it provides two different-level engines: a high-level one which is intended for operating on Working Copies (like svn.exe), and a low-level one which is a Subversion protocol implementation. Both provide corresponding APIs. The low-level engine is actually a driver used for direct working with a Subversion repository, and the high-level engine uses that low-level one when an operation really needs to access a repository.

Common Tasks

Rollback to a Previous Revision

   alias revertfile='read revertfile?"What file do you want to revert?"'
   alias revertrev='read revertrev?"What revision do you want to revert to?"'
   alias svnrevert='revertfile; revertrev; svn up $revertfile -r$revertrev; mv $revertfile foo; svn up; mv foo $revertfile;'

Low-level Engine

As said above, the low-level engine is a protocol-specific driver used for immediate working with a repository. And the high-level engine could possibly be not the only one who uses such drivers, it's just a standard scenario. For example, there may be developers who operate with abstractions much different from just files and directories. And they would also like to keep their objects under version control, but how? A standard way of using a Working Copy is not suitable here, as it's based on trees of directories and files.