Manage Your Documents with Subversion

[ Saturday, 2 September 2006, michuk ]


Version control systems are commonly used by programmers. They allow for easy team work and version management. However their benefits can easily be exploited by regular users as well. This article’s purpose is to help you take advantage of Subversion at home to improve control over your own set of documents

Author: Borys Musielak
Translation: Szymon Bakowski
Correction: Mariusz Czyz, Michał Rutkowski

What is Subversion?

Subversion is a version control system, so let us explain what a version control system is, in the first place. According to Wikipedia:

Version control (also known as revision control or source control) is the management of multiple revisions of the same unit of information. It is most commonly used in engineering and software development to manage ongoing development of digital documents like application source code, art resources such as blueprints or electronic models and other critical information that may be worked on by a team of people. Changes to these documents are identified by incrementing an associated number or letter code, termed the “revision number”, “revision level”, or simply “revision” and associated historically with the person making the change.

In simple words, Subversion provides you with:

Subversion vs CVS
Subversion has been created in order to overcome vulnerabilities existing in obsolete but still very popular CVS. Subversion is more secure (security provided by ssl_mod module of Apache2 server) and bared a few annoying errors of CVS. Just to mention a few like lack of control over directory and metadata versioning, lack of transactional operations (either all the files are checked in or none of them). If you are interested, read more about the differences between Subversion and other version control systems.

  • better control over important documents,
  • secure access to your files from any place you can imagine,
  • means to easily edit your documents independently from any location without the need to worry about synchronization.

If you found the above features appealing, please read on about the technical details of using Subversion. Below we explain how to set up your own installation of Subversion and how to use it daily.

Why is Subversion useful?

How many times it happened that you accidentally deleted some important file or even worse, lost a phone number to a distant relative? How many times it happened that you wanted to access some important file but you forgot to copy it to your USB stick? Subversion is the right solution to these problems.

So how does it work? Well, it stores all your documents in a special repository. Every time you change a document which is in control of Subversion, it is marked as a new version. Subversion stores the log of changes (differences between versions) so that you can easily compare the document with its previous versions and get them back if needed.

What is more, with Subversion you can access and modify your important files from any place (e.g. Internet cafe, your work, or your friend’s house). You can work on them as if they were local. No more constantly checking if you work on the most recent version (did I copy the document to my USB drive after making that change?) because the current version of your file is always in the repository!

If you want, you can even share your selected files with friends or co-workers, letting them edit the files or just read their content. Actually, Subversion gets even more useful when multiple people need to work on one file since it allows for easy merging of the changes. This is why it has got so popular among programmers. But obviously its usefulness is not limited just to the IT industry.

Installation of Subversion

If you use a GNU/Linux distribution which provides good package management, you can safely assume that a Subversion package is available in the default repository. Note that in order to successfully run Subversion you will also need ((*)) Apache2 web server which provides authentication and a web interface.

Let’s take Debian or Ubuntu as an example (in other GNU/Linux distros the command will look slightly different but similar). Issuing the following command:

apt-get install apache2 subversion libapache2-svn \\
subversion-tools

should provide us with all the necessary software for setting up our home Subversion repository.

Apache2 vs Svnserve
You don’t need Apache in order to run Subversion. There is also a possibility to run Subversion as a standalone, autonomous server called svnserve. It runs as an inetd`s super-server or as a daemon with very simple authentication (it is possible to use SSH tunnel for that purpose as well). We are not going to get into details of that kind of installation in this article, but you can read more about svnserve in the SVN book.

Subversion configuration

At the beginning, we have to create a directory where we are going to store our SVN repositories. For example /home/subversion/public

That is only an example. You can set the Subversion root folder to any location, according to your preferences (e.g. /var/lib or directly in the root of your file system).

Next step involves setting up a new repository. Since we are planning to use it to store a whole bunch of scripts, commands, and many tips & tricks we have learned while using Linux, it will be called ‘faq’ (of course you can choose a different name). Shell command is as follows:

svnadmin create faq

Now the Subversion server is configured. The next step is to configure Apache2 so that you can access it securely from a remote location.

Apache2 configuration

Now, you are going to configure a web server – in your case – Apache2. You’ll generate a new SSL certificate, modify a few configuration files, and at the end, create Subversion users.


 Sample command-line session in Subversion

Pic 1. Sample command-line session in Subversion

Generating SSL certificate

Subversion uses SSL authentication provided by Apache2 (to be more precise by mod_ssl module of Apache2). In order to use that functionality you have to generate a SSL certificate by issuing the following command:

apache2-ssl-certificate -days 365

You are going to be asked a few simple questions: country code, city name and the name of the organization issuing the certificate (it can be i.e. your name or company). You also have to provide a server name (in our case: funky_seal). The generated certificate in most cases is saved to /etc/apache2/ssl/Apache2.pem file. If this is not the case, you should write down the full path of the generated file, as we are going to need it later on.

The -days option stands for the length of the certificate. The default is one month.

Notice that if may happen that the certificate script is not available in your distribution. In this case, you can use openssl command direclty. A sample command could look like this:

openssl req -new -newkey rsa:2048 -keyout key.pem -x509 \\
-set_serial 1000 -days 365 -out cert.pem
cat key.pem cert.pem >/etc/apache2/ssl/Apache2.pem

But you are encouraged to read the openssl manual before.

SSL support in Apache2

In order to activate SSL support in Apache2, you have to modify a line with Listen directive in /etc/apache2/ports.conf so that it looks like this:

Listen 443

.

That will make the server start listening on port 443 (which is the default SSL port).

Next step involves creating symbolic links to ssl.conf and ssl.load files (located in mods-available) in mods-enabled directory. These two commands will do:

ln -s /etc/apache2/mods-available/ssl.load \\
/etc/apache2/mods-enabled/
ln -s /etc/apache2/mods-available/ssl.conf \\
/etc/apache2/mods-enabled/

This step ensures that the modules responsible for SSL support will be read during the Apache2 start-up (only the files in mods_enabled folder are read during the Apache2 start-up).

Subversion support in Apache2

Activating Subversion support in Apache2 is similar to enabling SSL support. We have to create a link from /etc/apache2/mods-enabled/ to dav_svn.load which is located in /etc/apache2/mods-available:

ln -s /etc/apache2/mods-available/dav_svn.load \\
/etc/apache2/mods-enabled/

Modules responsible for Subversion support will be loaded during Apache’s start-up (together with other Apache2 modules). In our case, we are not going to additionally configure the dav_svn module (standard configuration is enough for our needs) and that is why the dav_svn.conf file doesn’t have to be linked against mods-enabled directory. Still, it can be linked if there is such need.

Virtual host configuration

This step involves creating a file named (for example) subversion in /etc/apache2/sites-available directory. As an example virtual host configuration file with short description of each directive is presented below:

<VirtualHost funky_seal:443>
# IP address and port – most commonly it is an IP address \\
and port 443 (SSL) of the hosting computer
# In our case, IP address belongs to our internal network \\
and available from outside world through port 443
# redirection on hardware firewall
# SVN administrator
ServerAdmin michuk@polishlinux.org
# Server name (e.g. host name)
ServerName funky_seal
# SSL activation
SSLEngine On
# SSL certificate file location SSLCertificateFile \\
/etc/apache2/ssl/Apache2.pem
# Set up public repository directory
# Directory privileges – access from everywhere \\
Order allow,deny
Allow from all
#Activation of svn_dav module instead of standard webdav \\
module DAV svn
# SVNParentPath to the directory with repositories
# (used in case of having more than one repository)
SVNParentPath /home/subversion/public
# Path to configuration path for access privileges for users \\
and user groups
AuthzSVNAccessFile \\
/etc/apache2/auth-files/public-svn-authzfile
# Use of HTTP Basic Authentication - ”Satisfy Any” manes \\
that svn is going
# to accept any authentication requirements that we will \\
impose
Satisfy Any
Require valid-user
AuthType Basic
# Authentication welcome banner
AuthName "polishlinux.org Subversion Repository"
# Location of hashed file containing users` passwords
AuthUserFile /home/subversion/.dav_svn.passwd
# Log level and error log file location
ErrorLog /var/log/Apache2/error.log
LogLevel warn
CustomLog /var/log/Apache2/access.log combined
</VirtualHost>

It is very important to pay your attention to these two directives:

  • AuthzSVNAccessFile /etc/apache2/auth-files/public-svn-authzfile
  • AuthUserFile /home/subversion/.dav_svn.passwd

In order to make our configuration active, we have to create the files mentioned above and then create symbolic links to them in /etc/apache2/sites-enabled directory:

ln -s /etc/apache2/sites-available/subversion \\
/etc/apache2/sites-enabled/

Repository access privileges

To be able to use SVN, we have to create users, who posses access privileges to download or modify the files in repositories. Apache’s htpasswd script will help us with it. Using htpasswd for the first time creates a password file (i.e. /home/subversion/.dav_svn.passwd) and creates the first user at the same time:

htpasswd -cm /home/subversion/.dav_svn.passwd michuk

Of course we can provide another password file location if we want. The following users should be created without the “-c” switch (which creates a new .passwd file):

htpasswd -m /home/subversion/.dav_svn.passwd claudio
htpasswd -m /home/subversion/.dav_svn.passwd didier

Now, when we have three example users, it is time to create a /etc/apache2/auth-files/public-svn-authzfile file, which holds the authorization information for each SVN user. Let`s consider a very simple example first:

# Groups configuration

[groups] 
owner = michuk 
faq-writers = michuk 
polishlinux-developers = michuk, claudio, didier

# Repositories configuration

# Main repository. Only owner (michuk) will be able to add \\
new repositories
[/] @owner = rw

# Repository`s FAQ - accessible only for users of \\
faq-writers group. No external access.
[faq:/] 
@faq-writers = rw

# polishlinux.org repository - may be modified by members \\
of polishlinux-developers group
# and all can browse it (option * = r)
[polishlinux.org:/] 
@polishlinux-developers = rw 
* = r

The access rights mentioned above are only a simple example of authorization privileges configuration. Every single user has to be added using htpasswd first in order to be able to use SVN repository (except for anonymous users allowed to browse our repository – if we decide to allow anonymous access). Note: there is a possibility to use system authentication (PAM) if we can’t live with two user directories (separate for system and for SVN). Please consult Subversion and Apache2 documentation pages for details of such configuration since we’re not going to cover it in this HOWTO.

System privileges

Finally, there is one more thing to know. In order to make the authentication work, we have to make sure that the owner of the directory containing our repositories is exactly the same user who owns the Apache2 process. In Debian it is www-data user by default. There might be a different user in different distributions (e.g. apache or apache2) so you need to check it with your distro’s manual. As the last part of our configuration we will then set up proper access rights for /home/subversion directory:

chown -R www-data:www-data /home/subversion/

If all went well, we should already be enjoying a fully configured, up and running instance of Subversion.

Restart Apache2

Please do not forget to restart Apache2 before you start reporting any errors in the article:

/etc/init.d/apache2 restart

Basic usage

Now, after getting through the pain of configuration, we can finally start using Subversion. First, we should try to add a few files to our newly created repository. To do that, we have to import the folder ~/faq to the remote repository, using a command like:

svn --username michuk import ~/faq \\
https://funky_seal/public/faq -m "First file import"

This command will import a whole content of ~/faq directory to our repository located on the SVN server, adding an appropriate comment (-m option). Comments are very useful, since they help us (in the future) find a correct file version, in which some particular changes have been made. Note that if you don’t specify the comment explicitly with the import command, you will be asked for it anyways by means of an additional confirmation screen.


 Subversion resolves conflicts in a smart way

Pic 2. Subversion resolves conflicts in a smart way

In order to check whether our files have been properly imported into our repository we have to browse to https://funky_seal/public/faq and log in. The contents of the repository will be always available through a web interface.

If we wish to download the repository content to a different machine (e.g. at work) we have to issue the checkout (in short: co) command:

svn co https://funky_seal/public/faq

Now, we can modify and commit changes to our repository in every place where the ‘faq’ repository has been downloaded (changes are being updated to our repository located in the main repository of our SVN server). In order to update all files from ‘faq’ repository in our working directory we have to issue the following command (while in faq folder):

svn update

When we make any changes to some file in the working directory, we can commit them to the SVN repository (that will succeed only if we have write privileges). The magic command is:

svn commit file

Note that you should always check whether there is a new version of a file before committing your changes. It may be that you forgot to update it before. Thus, always invoke svn update before committing anything, just in case. If there is a conflict, it will be merged anyway.

Another handy option in Subversion is diff which shows a the changes that have been made locally to a specific file since the last commit/update. To see the local changes we can use:

svn diff

When we share the same file with more than one person it is very easy to accidentally overwrite someone’s changes to the file. Luckily, owing to a smart way of merging and manual acceptance of atomic changes, lose of data is virtually nonexistent in Subversion (local changes are automatically merged with changes committed by other users after using svn update command). If there is still a need to prevent others from making any changes to a particular file, we can use a feature called lock:

svn lock file

By default, a lock is active until the next check-in (svn commit). However, if –no-unlock attribute has been used either during the file creation or with the last commit action, the only way to release the lock is to issue the command:

svn unlock file

More information about Subversion (like recovery of older revisions, checking file status, file and directories copying and moving within a repository or file and directory deletion process) can be found in Subversion FAQ , which is available on the Internet or using a local context help:

svn help

on a computer with an svn client installed. It’s really worth reading if you want to get the most of your version control system.


kdesvn - sample graphical user interface for Subversion

Pic 3. kdesvn – sample graphical user interface for Subversion

Subversion graphical interfaces

After a slightly time-consuming task of setting up a repository, it is really becoming very easy and straightforward to work with SVN in a console mode. In most cases the casual work with SVN is limited to downloading a new version of the repository (or some particular files) and committing your changes.

If you don’t like the command line interface or are overwhelmed by the multiple options of Subversion or just don’t like typing, don’t worry: you can install one of the GUI clients of Subversion. Here are some of the popular choices:

  • eSVN – graphical user interface for Subversion written in Qt
  • kdesvn – another graphical user interface for Subversion, designed for the K-Desktop environment (KDE)
  • WebSVN – web interface written in PHP and accessible from any web browser
  • Rapid SVN – very popular Subversion management tool, written using wxWidgets (works on GNU/Linux and MS Windows)
  • TortoiseSVN – a simple client for MS Windows only, which tightly integrates with the Windows shell – quite handy if you have to use the Redmond OS for some reason

As you see, you can use Subversion graphical clients on any operating system, including MS Windows (i.e. at work). GUI is quite handy when you need to get an older version of some file and need to compare multiple versions in order to find the right one. Most of the GUIs include a feature of file history, when you can compare any 2 versions of the selected file with just one mouse click. I personally recommend TortoiseSVN for Windows users and eSVN for desktop Linux fans. WebSVN can be a good option as well, if you prefer web interfaces (no need for installation on the client side).

Summary

A version control system can greatly improve your work performance, especially when working with a large documents repository. It can also prevent you from many tragedies connected with data loses. After you spend the time to create your home Subversion repository, it is just pure pleasure to use later on. I really encourage everyone to give Subversion a try – you probably won’t regret it (but sorry, no money back if you will though).

Resources

The following resources have been used while writing this article:

Updated on September 12nd, 2006: Subversion 1.4.0 is now released. Howtoforge published another great howto concerning Setting up Subversion and websvn on Debian (including websvn support).

Updated on October 12nd, 2006: There is a nice comparison of different version control systems for GNU/Linux on the IBM pages. Recemmended for the undecided.

About the Author

Borys Musielak

PolishLinux.org creator and editor in chief. Professionally -- J2EE consultant in London City. Personally -- free software enthusiast and lobbyist.

New AdTaily ads!

Are you a film buff?

film buffs community, movie recommendations and reviews

RSS: Comments

You can follow the comments to this article through a special channel RSS 2.0 .

Related articles: Apps

 more »

Related articles: HOWTOs

 more »

PolishLinux Top Content


Become our fan on Facebook!

PolishLinux.org on Facebook

Follow PolishLinux on Twitter!

Follow polishlinux on Twitter

Google Ads