Subversion

Becoming a User of Subversion

To become a user of the subversion repository at AG Softech, you have to first create an encrypted password. This can be done in several ways:

• Using crypt: Issue the command

  perl -e 'print crypt("PASSWORT","SALT");'
  

  where PASSWORT is replaced by your desired password, and SALT is a two- character parameter that is used in the encryption process. Of course, you must not provide the latter with password requests from the subversion server.
• Using htpasswd: If you have htpasswd installed on your system (it comes with apache), you can issue the command

  htpasswd -m -n username
  

  This will print a line, which is suitable for inclusion into a htpasswd file. The flag -m tells htpasswd to use MD5 encryption which is a better encryption standard. If you omit the flag, the standard crypt encryption algorithm will be used.

Send the password created by crypt together with your desired username or the contents of the htpasswd-generated file to Kathrin Geilmann.

Repository Access and Client Requirements

The subversion repository can be accessed via SSL by using the WebDAV? protocol. The subversion server is at version 1.0.0. There seem to be some incompatibilities with older clients, e.g. client version 0.27.0 complains about some XML incompatibilities. So please make sure that your svn client is at version 1.0.0 (you can get the information with svn --version).

It is required that the subversion client supports the HTTPS access scheme. This can be verified by entering svn --version. The output should contain the following information:

* ra_dav : Module for accessing a repository via WebDAV (DeltaV) protocol.
- handles 'https' schema

Usually, some other schemes are listed as well (e. g. http, file, svn). These are not used, though. If the client does not offer https-support, it can be compiled with the option -- with-ssl.

Access Paths

Each repository is usually separated into three paths: /trunk, /branches and /tags. The /trunk path contains the main development strand of a repository. It is required that it is always functional, i.e. compilable, translatable, etc. In order to be able to exchange and to backup recent developments, branches are used (see below). They are stored in the /branches path. Each branch has its own directory by which it can be identified. The /tags path contains tags (see below).

To check out the trunk of a repository, the checkout command is used:

svn checkout https://softech.informatik.uni-kl.de:2443/svn/myproject/trunk
localdirname

This checks out the main trunk of the project myproject. The result is a local directory localdirname that contains all files of the project.

Basic SVN Commands

Here is a short overview of the most important subversion commands. More information is available by entering svn --help or svn command --help, where command is replaced by the command that you want information about.

• checkout: This is used to initially checkout a project from the repository (see above).
• add: Schedules a file or directory for addition on the server. The next commit operation will add it to the server.
• status: Shows the status of the working copy, i.e. the files that are changed wrt. the repository.
• info: Lists information regarding the working copy, e.g. the current revision number and the URL of the subversion server (here one can especially see whether the working copy mirrors the trunk or a branch, see below).
• log: Shows the log history of a file or directory. It is useful to use the -v flag (verbose) which gives more information on each log entry. Unfortunately, the log entries are output newest-first. Therefore, if the project is quite old, there is a lot of uninteresting output. It is helpful to restrict the output by using -rX:Y where X and Y specify the range of revisions whose logs are to be displayed. It is quite common to use HEAD as the upper revision number.
• revert: reverts a file of the working copy back to the last version that is on the SVN server (or to any older version if the revision number is given).
• update: updates the current working copy with any new files that have been sent to the server by others. Also allows to step through the development process by passing a revision number: this will update the working copy to the given revision. Caution: This operation may introduce conflicts, no matter whether the working directory is updated to the newest revision or to an older one.
• resolved: If an update produced a local conflict in a file, then a conflict flag is set for this file which prevents the file from being added to the server. Once the user has resolved the conflict by editing the file, the svn resolved command clears the conflict flag and allows the file to be submitted to the server again. Note: This command does not solve the conflict! That has to be done by you, the user. It only clears the conflict flag.

• copy: Copies a file or directory in the working copy and schedules the new file for addition. The next commit operation will add it to the repository. This command is especially used to create a branch (see below). It is also very helpful to restore files that were accidentally removed from a revision. Copy is able to copy these files back to the working copy together with their history. Usage: svn copy --revision 1234 https://svnurl  targetlocation.

• delete: Schedules a file or directory for deletion on the server. The next commit operation will remove it from the repository. This command is also used to delete branches or tags (see below).

• move: Moves or renames a file or directory in the working copy. The next commit operation will send the change to the server. This is equivalent to copy and delete.

• commit: This command sends modified files and directories to the server.

• switch: This command can either change the repository path from which a (part of a) working copy is derived (i.e. it can transform a working copy from a trunk working copy to a branch working copy and vice versa), or it can change the server from which the working copy is retrieved (in case the svn repository is moved to a different server). When trying this command, I had some problems; I will try this more in-depth and extend the documentation afterwards.

How to Go Back to a Previous Version of a File

One of the most common uses of svn is to revert to a previous version of a file. This can be done by copying the old version from the repository to the working directory.

If you want to go back to revision X of file myfile, you can achieve this with

svn copy -r X https://softech.informatik.uni-kl.de:2443/myproject/trunk/.../myfile ./myfile -m "Comment"

After this, you need to submit myfile to the repository.

A detailed description is available in the Subversion Book.

If there are multiple files to be reverted, you can as well check out an older version of the whole directory to a temporary directory and copy the files manually within the file system.

Branches

Creating a Branch

Creating a branch means nothing else than copying the files on the SVN server. This is done in an intelligent, lazy way to minimize harddisk usage.

The easiest way to create a branch is via the copy command (everything must appear in a single line):

svn copy https://softech.informatik.uni-kl.de:2443/myproject/trunk
https://softech.informatik.uni-kl.de:2443/myproject/branches/branchname
-m "Comment"

This creates the branch branchname. The logs of all files in the branch will get the comment that is added to the command. It is also possible to create a branch that only contains a part of the repository. This has to be specified in the first URL, by adding the desired directory after the /trunk directory.

Checking out a Branch

Checking out a branch works in the same way as checking out the trunk:

svn checkout https://softech.informatik.uni-kl.de:2443/myproject/branches/
branchname localdirname

Merging a Branch with the Main Trunk

When working on a branch, it is important not to let the branch drift too far away from the main trunk because the chance of conflicts increases. Therefore it is important to merge the changes on a regular basis.

There are two possibilities for merging: Changes that have been performed on the main trunk can be merged into the branch, or changes in the branch can be incorporated into the main trunk. The latter is of course only recommendable if the work that has been performed in the branch is completed and tested.

The basic principle of merging works as follows: Take two different revisions of a single repository strand (either the trunk or a branch). Subversion will create a diff of these two revisions and apply it to a working directory (which should belong to a different repository strand).

Take the following example:

The repository for the project myproject has been created (starting at revision number 1). Directly after this, the branch mybranch has been created (this produces revision number 2). Afterwards, some changes have been performed to the trunk and the branch in turn. The trunk and the branch are in the same SVN repository, therefore the revision numbers increase for both strands with each change to one of them. This is indicated in the graphics by the dashed boxes where the solid boxes represent changes to one of the strands.

Suppose that somebody performed a change to the trunk, producing revision 3, that you want to incorporate into your branch (which is at the level of revision 2).

The easiest way is to change into the root directory (!) of the working copy of your branch. Then issue the svn command:

svn merge -r1:3 https://softech.informatik.uni-kl.de:2443/svn/myproject/trunk

This takes the changes that have been performed between revisions 1 and 3 in the strand /svn/myproject/trunk and applies them as local changes to the current working directory (which belongs to the branch). Now you can review the merging process, adapt it if necessary, compile and test the result and finally commit it to the repository (this produces revision 4 in the example above).

Some remarks on this:

• You can also apply the merging to a part of your working copy by specifying it in the trunk URL, but the specified location must exactly match your position in the working copy.

• You need not actually move into the working copy: you can also specify the path to the working copy after the trunk URL. If it is omitted, the current path (".") is assumed as argument.

• You cannot perform a merge operation on a working copy that is not up-to-date with regard to the repository. But this does not pose a problem because you are working in your private branch anyways, so you can always commit the current working copy status without disrupting anybody else.

Once you finished working on the branch, you want to merge your branch changes into the trunk (which has last been changed in revision 7 in the current example). This is done by the same operation (now you have to change into the trunk's working copy or specify its path):

svn merge -r2:7 https://softech.informatik.uni-kl.de:2443/svn/myproject/branches/
mybranch

Some remarks on this:

• Instead of explicitly specifying the revision 7, you can also use the name HEAD which represents the most recent revision.

• To find out at which revision a branch was created, you can use the command

  svn log -v --stop-on-copy .
  

  which lists all logs of the current directory (which must be located within the working copy of the branch) until it reaches a log entry that indicates that a branch was created. You can then read the revision number and use it in your command.

SVN does not (yet) keep track of merging processes. Therefore, you (the user) have to do this yourself. The easiest way to do this is to add explicit comments to the logs, detailing which revisions have been merged (e.g. "Merged revisions 17:25 of branch mybranch into trunk").

After the merging process, the branch can still be used for further development (as indicated by the dashed arrow in the example above). On subsequent merges of the branch into the trunk, one has to take care that changes are not merged twice. Therefore it is important to specify as starting revision the lowest revision after the last merge (revision 9 in the example above).

If a branch is not meant to be used any more, it can be removed from the repository by the svn delete command.

If a merging operation does not produce the desired result (e.g. because the wrong revision numbers have been used), this is no problem: svn revert undoes the changes performed by the merging operation, and you can try to merge the strands once again.

Tags

Simply speaking, tags are branches that are not meant to be further developed.

Subversion's revisions describe the whole repository, not only single files. This makes it very easy to step through the repository "in time" by going back to a certain revision number. To make this even more comfortable, tags can be used which are supposed to be stored in /tags. With tags, one need not remember revision numbers.

How to Make Subversion Ignore Generated Files

svn status displays all files that are not checked into the repository. This can be annoying if there are many files that are generated by e.g. a compiler because it clutters the output. This can be changed in three ways:

• per computer in the file /etc/subversion/config by enabling and extending the line global-ignores in the [miscellany] section (this refers to the computer on which the working directory is located!)

• per user in the file ~/.subversion/config in the same way as described above

• per directory by setting the property svn:ignore. This command works on a single directory and is non- recursive. It takes a file that contains each of the files to be ignored, one per line. Wildcards are allowed. Those who have worked with CVS before know this syntax: it is the syntax of the .cvsignore file. Therefore, it is very easy to use an existing .cvsignore file to perform the same in subversion. The command is:

  svn propset svn:ignore -F .cvsignore .
  

  This will store the ignore-rules given in .cvsignore in the current directory. The .cvsignore file can be deleted afterwards because it is not used by subversion.

Browsing Repositories

You can browse the subversion repositories by entering the repository URL in your web browser. This will (after authentication) give you access to all files of the repository in the most recent revision. This is especially nice to get a quick overview of existing tags and branches.

Further Links

The Subversion Book is a must-read for subversion users and the source of answers to many subversion-related questions. Available as HTML and PDF. Soon available as O'Reilly book.

The Subversion home page gives a brief overview of the project as a whole.