Documentation

Subversion

What is Subversion?

Subversion is a free/open-source version control system. That is, Subversion manages files and directories over time. A tree of files is placed into a central repository. The repository is much like an ordinary file server, except that it remembers every change ever made to your files and directories. This allows you to recover older versions of your data, or examine the history of how your data changed.

In this regard, many people think of a version control system as a sort of "time machine". If you're new to the entire concept of version control or to the "copy-modify-merge" model used by both CVS and Subversion, then you should read Chapter 2, Basic Concepts in the SVNbook before going any further.

What do I need to use Subversion?

The easiest way to get Subversion is to download a [http:// subversion.tigris.org/project_packages.html binary package] built for your operating system. Subversion's website (http://subversion.apache.org) often has these packages available for download, posted by volunteers. The site usually contains graphical installer packages for users of Microsoft operating systems. If you run a Unix-like operating system, you can use your system's native package distribution system (RPMs, DEBs, the ports tree, etc.) to get Subversion.

How can I get a repository on ULYSSIS?

If you want a repository you can go to the ULYSSIS User Control panel and make one. http://ucc.ulyssis.org/ (this is of course free of charge).

Repositories will reside here:

I have an empty repository now, how do I put my files into it?

This is only useful if you already have a tree of files on your local disk, that you would like to import, otherwise skip to "How do I use a repository?".

You use svn import to import a new project into a Subversion repository. While this is most likely the very first thing you will do when you set up your Subversion server, it's not something that happens very often. For a detailed description of import, see the section called "svn import" in the svnbook.

The svn import command is a quick way to copy an unversioned tree of files into a repository, creating intermediate directories as necessary.

   $ svn import mytree https://svn.ulyssis.org/repos/somerepo
   Adding         mytree/foo.c
   Adding         mytree/bar.c
   Adding         mytree/subdir
   Adding         mytree/subdir/quux.h
   Committed revision 1.

Make sure you don't add files to the SVN directory in your repository. (https://svn.ulyssis.org/repos/somerepo/SVN). Only the access file should be there, nothing else. If you ever put something there anyway, you'll have to contact us to get it removed. (Removing from the SVN directory has been disabled to prevent you from accidentally removing the access file, which would revoke your commit rights).

Is there any limit on the size of a repository?

No, there are no forced limits on the size of repositories. As long as the volume stays within certain arbitrary reasonable limits, you wont hear any complaints from us. Just refrain from committing big binary files like audio or video.

How do I use a repository?

Most of the time, you will start using a Subversion repository by doing a checkout of your project. Checking out a repository creates a copy of it on your local machine. This copy contains the HEAD (latest revision) of the Subversion repository that you specify on the command line.

For more info, Read The Fine Manual at http://svnbook.red-bean.com.


   $ svn checkout https://svn.ulyssis.org/repos/annika
   A annika/SVN
   A annika/SVN/access
   A annika/readme.txt
   A annika/testdir
   A annika/testdir/testfile.txt
   Checked out revision 10.

Subversion has numerous features, options, bells and whistles, but on a day-to-day basis, odds are that you will only use a few of them. We'll run through some common things that you might find yourself doing with Subversion in the course of a day's work.

The typical work cycle looks like this:

  • Update your working copy
    • o svn update
  • Make changes
    • o svn add
    • o svn delete
    • o svn copy
    • o svn move
  • Examine your changes
    • o svn status
    • o svn diff
    • o svn revert
  • Merge others' changes
    • o svn merge
    • o svn resolved
  • Commit your changes
    • o svn commit

Update Your Working Copy

When working on a project with a team, you'll want to update your working copy to receive any changes made since your last update by other developers on the project. Use svn update to bring your working copy into sync with the latest revision in the repository.

   $ svn update
   U readme.txt
   Updated to revision 11.

In this case, someone else checked in modifications to readme.txt since the last time you updated, and Subversion has updated your working copy to include those changes.

Make Changes

Read more about add, delete, copy, move, status, diff, revert, merge, resolved and commit in the svnbook.

   $ vim readme.txt 
   [...edit&save...]

Commit Your Changes

Finally! Your edits are finished and you're ready to commit your changes to the repository. The svn commit command sends all of your changes to the repository.

When you commit a change, you need to supply a log message, describing your change. Your log message will be attached to the new revision you create. If your log message is brief, you may wish to supply it on the command line using the --message (or -m) option:

   $svn commit -m "Corrected spelling errors"
   Sending readme.txt
   Transmitting <a href="http://www.php.net/file">file</a> data .
   Committed revision 12.

Can I give other people access to my repository?

  • all ULYSSIS members with an svn account are allowed full access to subversion
  • all non-ULYSSIS KUL students are allowed full access
  • people external to KUL are allowed readonly access


This doesn't mean all these people will have access to your repository. By default, only the repository owner will have (full) access. Anyone other then the owner won't have any access at all (not even readonly access).

Of course, it's possible for the owner to allow/disallow certain svn users to access the repository. It's even possible to control access to directories within the repository.

Every user you want to give access to needs to be registered with us. This means:

  • Every ULYSSIS-member has to request a svn account in the ULYSSIS Control Center.
  • You can invite a kul-member in your ULYSSIS Control Center. Just go to the 'subversion' module, enter the correct data, and she will receive an email with the login information.
  • External people can only use the "guest:guest" "user:password") account.


When we create a repository for a user/organization, it isn't completely empty, as one would expect from a newly created repo. Inside you will find a directory "SVN/" containing a file "access", which we put there. This versioned file controls the access rights to your repo.

At first it will look something like this:

   $ cat SVN/access
   # Put your configuration here
   ########### WARNING !!!DO NOT EDIT BEYOND THIS POINT !!!!! ##########
   [/]
   annika = rw
   [/SVN]
   * =
   annika = rw

This default access file ensures the owner (annika in this case) has full access to the root (/) of the repo, and full access to /SVN. '* = ' means that any other user has no access to /SVN. Location names like [/] and [/SVN] are inherited by branches deeper in the file tree, unless overridden by more specific names.

Access file example 1

    [/project_a] 
    guest=r     # guest's default is read only access 
    steven.opdebeeck=r  # Steven's default is read only access
    remko.troncon=rw   # Remko's default is full access 
     
    [/project_a/docs]
    steven.opdebeeck=rw   # Steven does have full access to the docs dir
    remko.troncon=r   # Remko however has only read access 
     
    [/project_b]
    remko.troncon=rw   # only Remko has (full) access to project_b

Access file example 2: with groups

   [groups]
   a_developers=remko.troncon,steven.opdebeeck
   b_developers=jane.doe,john.doe 
    
   [/project_a]
   anonymous=r
   @a_developers=rw
    
   [/project_b]
   @b_developers=rw


You can adjust the access file to match your needs, and commit it to propagate the changes into the subversion system. But be careful not to include any syntactically incorrect entries, or you will lose complete access to the repository and will be forced to contact the admins to fix the problem -- we are still working on a way to protect the user from doing this. Read more on this in the svnbook.

Can I convert an existing CVS repository to Subversion?

Yes, a tool exists that does just that, convert complete or partial cvs repositories to subversion. It's called cvs2svn. cvs2svn is a Python script that converts a CVS repository to a Subversion repository. It is designed for one-time conversions, not for repeated synchronizations between CVS and Subversion.

Dump your CVS repository to a SVN dumpfile using cvs2svn , place it online and mail us the location of the dumpfile. We will do the rest.

You can download cvs2svn from the projects webpage. Or grab the most recent development version from the subversion trunk (user 'guest, password 'guest').

References