Revision Control Systems (RCS, CVS, SVN, Git)

THIS PAGE IS OUTDATED. Please read the articles on Subversion or use our GitLab-Server.

For almost all projects, no matter whether pure software development or the creation of a document, it is very reasonable to use some kind of revision control. Commonly used revision control systems are RCS (revision control system), CVS (concurrent versions system), and SVN ("Subversion"). This is not the place to discuss these in detail. Use books, manual pages, or online tutorials on the Web to learn more about them.

These three tools are installed on all common IBR Linux systems, usually as parts of installed Debian GNU/Linux packages.

To give a short advice on which one is the best for your task: Maybe, RCS for single files. Maybe, SVN for "projects". Maybe, CVS if SVN cannot be used for obscure technical reasons.

How to use RCS

There is not much to say about RCS. Its two most important tools ci and co can be used as usual. Note that RCS follows a "pessimistic" approach, which means only one person can have a lock on a file and is able to edit it, while other approaches to edit it are denied. So you should release your locks immediately after your changes. There are manual pages available on all RCS tools.

How to use CVS

CVS is used for many projects. It support multiple methods to access a repository. Note that at IBR we do not support the "pserver" method on a central CVS server, since there have been many security problems with this protocol in the past and there are better choices these days. However, if you prefer to use CVS, you can setup your own repository in your home directory (and make it also accessible to other users, if you wish). You can also use SSH and the ":ext:" access method to access it from remote sites. It's all documented in the CVS info pages.

How to use SVN (Subversion)

Subversion is in some way the successor of CVS. It uses the HTTP (and HTTPS) protocol to access remote repositories. IBR supports a central Subversion repository which is used for many projects (software, papers, etc.). A common scheme is to support http://www.ibr.cs.tu-bs.de/svn/project for anonymous read-only access for open source projects, and https://www.ibr.cs.tu-bs.de/svn/project for authors' read/write access to the same repository.

There is a lot of documentation on the web.

Since Subversion supports only a central auhorization file to configure access rules to different paths within the repository, we have a special way to allow Subversion users to configure their own access rules: Whenever a directory contains a file named .svnaccess it gets treated by the server as part of the central authorization file applied to the directory where it is located. The only special path for which different access rules can be applied in the .svnaccess file is the .svnaccess file itself. Example:

# only project members may write files
steinb = rw
timm = rw
# other staff members can only read files
@mitarb = r
# others and anonymous svn users cannot read anything
* =
[.svnaccess]
# only one user can configure access control
# others cannot even read/checkout the .svnaccess file
steinb = rw
* = 
    

Notes

• With the introduction of this .svnaccess-Feature on 2010-03-10 all maintainers of SVN projects should check their settings. Initial settings are derived from the former centrally maintained access configuration. But the important difference is that users with write permissions to SVN directories can now change access rules by creating or modifying .svnaccess files.
• The default for each path, i.e. the access permissions when no .svnaccess exists, is derived from the parent directory.
• It is possible that a project maintainer removes his/her own access permissions from a path. Take care! If that happens you have to bring some chocolate to the admin. It is a good idea to always have something like "myusername = rw" on the first line of the file (and on the first line of the [.svnaccess] section if it exists), even if subsequent group-based rules would match the maintainer.
• The syntax is quite strict: user and group names and permissions are case-sensitive, there must be no additional white space, "r" and "rw" must be written this way (not read or r/w).
• Svn commit transactions that change .svnaccess files may take a long time, because the server has to update its central authorization file. Do not interrupt these transactions. Otherwise you might experience an unexpectedly required update/commit cycle.
• Errors in the file (syntax errors, references to non-existent groups, etc.) are not signalled to the user and the affected lines are silently dropped from the .svnaccess file.
• For those users, who maintain Trac project pages: Trac access control is no longer affected by this kind of SVN access control. In other words: When a trac project is once set up, its configuration of permissions and group memberships is completely managed by its own and no longer magically synced from the SVN setup.

Git

You can set up your own Git repository and use it (even shared with multiple users), e.g., through SSH, but there is no central shared Git server due to Git's nature as a distributed revision control system.

Dr. Björn Hendriks is a great fan of Git. He is willing to help anyone at IBR in case of questions concerning Git. More information on Git is available at:

• Official Git Wiki with lots of useful information from beginners tutorials to very special documentations
• Very detailed manual of Git for beginners and advanced users
• A very nice (and short) page of the above mentioned wiki explaining how Git works

git-svn

Git-svn is a bidirectional interface to SVN repositories. So, git-svn can be used as a SVN frontend with the additional benefit of local branches and other Git features.

Unlike SVN git records the full name and e-mail address of the committer in each commit. To let git svn fetch and git svn rebase insert the correct name and address you need an authors-file which you can pass as a command line option or put into a config file (see documentation of git-svn). An automatically generated authors-file encoded in UTF-8 for the IBR SVN-server is provided here: /usr/local/etc/git-users.

Attention: Git includes name and mail address in the SHA1 of a commit. So if you plan to have several git repositories exchanging branches as well as fetching from the same SVN repository take care that all apply the same authors-file. Otherwise git will regard SVN-commits fetched from SVN as different commits leading to a mess after pulling offspring branches from other git repositories. Of course, git won't lose any objects but sorting it out could be tedious.

Setup a Git Repository on the IBR Webserver

NOTE: This approach is not supported "officially" and has some drawbacks. Maybe, it would be better to get a gitosis repository, see below.

It is possible to setup a git repo on the IBR webserver such that it is accessible via HTTP for pulling and also for pushing. This is a short tutorial how to do that without additional tools (e.g., gitosis). It gives you full control over the repo and all access rights.

In the following commands <name> denotes the name of the repo for HTTP.

First the setup described in many git manuals and tutorials about setting up git for HTTP access. See those documentations for details.

• Switch to the directory reserved for git repos (other directories might work as well if they have an appropriate webserver configuration):

  cd /ibr/www/git/
      

• Clone an existing repo as bare repo to this place (or init a new bare repo):

  git clone --bare <origin> <name>
      

• Activate the post-update hook as described in the git manuals, i.e., either set the executable bit (older git versions) or rename it from post-update.sample to post-update (newer git versions). This example is for older git versions:

  cd <name>/hooks/
  chmod +x post-update
      

• Call the hook to make sure it works and to call indirectly git-update-server-info:

  ./post-update
      

This was the general setup from the git manual. Now comes the special IBR part. The problem is that on one hand you (and maybe someone else) must have full access to the repo and on the other hand the webserver needs at least read access. But for security reasons the webserver runs under his own unix user and group and nobody else is member of that group.

The problem will be solved by using ACL (access control lists) which extend the common unix access rights for user, group and others. With ACL you can grant additional users and groups access rights. This is how it works for git repos.

• Go to the directory where your repo is hosted:

  cd /ibr/www/git/
      

• Remove all group and others rights from the repo. Especially if you cloned another repo from this place there might be some SGID bits set. It can also happen that you get some "Operation not permitted" errors which you can ignore.

  chmod -R go-rwsx <name>/
      

• Now we grant full read/write access to the webservers user www-data. -R stands for recursive. -m means to modify the ACL entries in this case for user (u:) www-data to be rwX. The capital X will set executable rights to directories and for normal files it will inherit executable rights if they are already set for someone.

  setfacl -R -m u:www-data:rwX <name>
      

• Next we have to make sure that new files and directories also have the correct access rights. This is done by the default ACL entries of directories set with option -d.

  setfacl -d -R -m u:www-data:rwX <name>
      

• Last we also have to make sure that we keep access to files and directories created by the webserver. Those files will belong to user and group www-data so without ACL you won't have access to them.

  setfacl -d -R -m u:<username>:rwX <name>
      

To check if all access rights are set correctly you can call getfacl for files and directories. It also shows the ACL mask which are the maximal rights granted to additional users and groups. With the above commands they should be set correctly but it never hurts to check.

If you want to give direct access to the repo to other users replace www-data in above commands by his/her username. In case of a unix group replace also "u:" by "g:". See man page of setfacl.

If you want to further limit the HTTP access to the repo to certain users you can add an .htaccess file to the base directory of your repo. See manual of the IBR webserver how to do that. The manual of the current webserver version can be found here.

gitosis

The approach described above has some drawbacks: It's quite complicated to set up, and it requires users to be able to login to the file server, so that it is limited to IBR staff members. That's why you can also setup a remote repository handled by gitosis on an IBR server:

• If not already done, set up ssh keys as described in the notes below.
• Clone the gitosis configuration (git clone gitosis@git.ibr.cs.tu-bs.de:gitosis-admin.git), add a section for your repository (in gitosis.conf), and push the changes back to the server (git commit -a ; git push). If you are unsure how to do this, please contact Frank Steinberg.
• Now you can push your repo to the server (git remote add ibr git+ssh://gitosis@git.ibr.cs.tu-bs.de/project-name.git ; git push ibr master)
• That's it.

Please note:

• Authenticated access requires the user to use an account known to the server and to have the public ssh key known to the server. This can be done through the user's key in $HOME/.ssh/id_dsa.pub, which is grabbed by the server every night, or through a specific field in the user's LDAP record (see LDAP editor). The command ssh-copy-id is not sufficient for this.
• If you've set gitweb = yes, then your repo is accessible throuh http://git.ibr.cs.tu-bs.de.