Developer
Status:
|
NOT LOGGED IN
|
BerliOS Developer Foundries
|
|
|
|
Project: BerliOSDocs - Docs
Summary |
Home Page |
Docs |
Memberlist |
Admin |
Submit new documentation | View Documentation | Admin Subversion (SVN) HowTo
This is very basic right now, but it will get you up and running Subversion (SVN).
Table of Contents [Next]
[Top] How to get an SVN repository [Next]
You will not get an SVN repository during the initial project registration and configuration process by default. You have to activate the "Use SVN" feature from your Project's Admin page first. Then after about 6 hours (if the Backend Scripts have finished which runs every 6 hours) the configuration of your repository is completed and accessable.
[Top] Login using SSH [Next]
For all developer (read/write) access, you will be using SSH.
SSH (2.x) client must be available to your local machine. The local
environment variable SVN_SSH must also be set to the path to ssh.
This is done on most linux (bash) systems by typing:
export SVN_SSH="ssh -l loginname"
Anonymous SVN access uses SVN server and does not require SSH.
If you get 'permission denied' errors with no prompt for a password,
you do not have this environment variable set properly or SSH is not
available to your system. Fix this before suspecting a password problem.
Ensure that the default umask is set correctly. Easiest way to do that, is to include following command to .bashrc
[Top] How to import source code into your repository via SSH [Next]
- On your local machine, change to the directory whose files (and subdirectories) you want to import. Everything now in the current directory
and all subdirectories will be imported into the tree.
- Type the following, where loginname is your BerliOS login name and
yourproject is the unix group name of your project.
export SVN_SSH="ssh -l loginname"
svn -m "import comment" import \
svn+ssh://svn.berlios.de/svnroot/repos/yourproject/trunk
[Top] How to import source code into your repository via HTTPS [Next]
- On your local machine, change to the directory whose files (and subdirectories) you want to import. Everything now in the current directory
and all subdirectories will be imported into the tree.
- Type the following, where loginname is your BerliOS login name and yourproject is the unix group name of your project.
svn -m "import comment" import \
https://loginname@svn.berlios.de/svnroot/repos/yourproject/trunk
[Top] How to check out source via SSH [Next]
Only project developers can access the SVN tree via this method.
- Type the following, making necessary obvious substitutions for
your loginname and yourproject.
export SVN_SSH="ssh -l loginname"
svn checkout svn+ssh://svn.berlios.de/svnroot/repos/yourproject/trunk
- After initial checkout, you can change into this directory and execute
SVN commands without the URL. For example:
svn update
svn commit -m "comments for this commit"
svn add myfile.c
[Top] How to check out source via HTTPS [Next]
Only project developers can access the SVN tree via this method.
- Type the following, making necessary obvious substitutions for
your loginname and yourproject.
svn checkout https://loginname@svn.berlios.de/svnroot/repos/yourproject/trunk
- After initial checkout, you can change into this directory and execute
SVN commands without the URL. For example:
svn update
svn commit -m "comments for this commit"
svn add myfile.c
[Top] How to check out source anonymously through SVN server [Next]
- Type the following, making necessary obvious substitutions for
your yourproject.
svn checkout svn://svn.berlios.de/yourproject/trunk
- After initial checkout, you can change into this directory and execute SVN commands without the URL. For example:
svn status
[Top] How to check out source anonymously through HTTP server [Next]
- Type the following, making necessary obvious substitutions for
your yourproject.
svn checkout http://svn.berlios.de/yourproject/trunk
- After initial checkout, you can change into this directory and execute SVN commands without the URL. For example:
svn status
[Top] How to control access to your SVN Repository [Next]
This must be done manually by the projects adminatrators. Proceed as follow:
- Login to the SVN Server:
ssh -l loginname svn.berlios.de
- Change to the conf subdirectory of your project's SVN directory:
cd /svnroot/repos/yourproject/conf
- If you don't want to permit access of anonymous users, uncomment the line in svnserve.conf:
# anon-access = none
- and add the following lines to svnserve.conf:
auth-access = none
# Specific access rules for specific locations
authz-db = /svnroot/user_access/SVNAccessFile
With auth-access = none the access via SSH is blocked. This is needed because adequate fine grained read access control cannot be achieved providing tunneling over SSH.
- Create an SVNAccessFile for your project's repository in the current conf directory and add the access rights.
The syntax of the file is the same familiar one used by svnserve.conf and the runtime configuration files. Lines that start with a hash (#) are ignored. In its simplest form, each section names a repository and path within it, and the authenticated usernames are the option names within each section. The value of each option describes the user's level of access to the repository path: either r (read-only) or rw (read-write). If the user is not mentioned at all, no access is allowed.
To be more specific: the value of the section-names are of the form [repos-name:path].
[yourproject:/branches/calc/bug-142]
harry = rw
sally = r
In this first example, the user harry has full read and write access on the /branches/calc/bug-142 directory in the calc repository, but the user sally has read-only access. Any other users are blocked from accessing this directory.
Of course, permissions are inherited from parent to child directory. That means that we can specify a subdirectory with a different access policy for Sally:
[yourproject:/branches/calc/bug-142]
harry = rw
sally = r
# give sally write access only to the 'testing' subdir
[yourproject:/branches/calc/bug-142/testing]
sally = rw
Now Sally can write to the testing subdirectory of the branch, but can still only read other parts. Harry, meanwhile, continues to have complete read-write access to the whole branch.
It's also possible to explicitly deny permission to someone via inheritance rules, by setting the username variable to nothing:
[yourproject:/branches/calc/bug-142]
harry = rw
sally = r
[yourproject:/branches/calc/bug-142/secret]
harry =
In this example, Harry has read-write access to the entire bug-142 tree, but has absolutely no access at all to the secret subdirectory within it.
The thing to remember is that the most specific path always matches first. The server tries to match the path itself, and then the parent of the path, then the parent of that, and so on. The net effect is that mentioning a specific path in the accessfile will always override any permissions inherited from parent directories.
By default, nobody has any access to the repository at all. That means that if you're starting with an empty file, you'll probably want to give at least read permission to all users at the root of the repository. You can do this by using the asterisk variable (*), which means “all users”:
[yourproject:/]
* = r
This is a common setup; notice that there's no repository name mentioned in the section name. This makes all repositories world readable to all users. Once all users have read-access to the repositories, you can give explicit rw permission to certain users on specific subdirectories within specific repositories.
The asterisk variable (*) is also worth special mention here: it's the only pattern which matches an anonymous user. If you've configured your server block to allow a mixture of anonymous and authenticated access, all users start out accessing anonymously. The server looks for a * value defined for the path being accessed; if it can't find one, then it demands real authentication from the client.
The access file also allows you to define whole groups of users, much like the Unix /etc/group file:
[groups]
yourproject-administrators = harry, sally, joe
yourproject-developers = frank, sally, jane
your-project-everyone = harry, sally, joe, frank, sally, jane
Groups can be granted access control just like users. Distinguish them with an “at” (@) prefix:
[yourproject:/trunk/admin]
@yourproject-administrators = rw
[paint:/trunk/src]
@yourproject-developers = rw
jane = r
Groups can also be defined to contain other groups:
[groups]
yourproject-administrators = harry, sally, joe
yourproject-developers = frank, sally, jane
yourproject-everyone = @yourproject-administrators, @yourprojects-developers
Attention! Updates happen via cron 4 times per day, so changes made on the SVNAccessFile will not take effect until the next cron update.
If access of anonymous users is permitted as well as access via SSH isn't blocked fine grained commit control could be installed by doing the following:
- Change to the hooks subdirectory of your project's SVN directory:
cd /svnroot/repos/yourproject/hooks
- Create the pre-commit script using the existing template:
cp pre-commit.tmpl pre-commit
- Change to the conf subdirectory of your project's SVN directory:
cd /svnroot/repos/yourproject/conf
- Create the configurarion file commit-access-control.cfg using the existing template:
cp /usr/local/bin/commit-access-control.cfg .
- Finally, set the commit access control rules in commit-access-control.cfg as you need. The configuration file contains examples of these rules:
# This is a sample configuration file for commit-access-control.pl.
#
# $Id: commit-access-control.cfg.example 5288 2003-03-12 05:56:21Z kfogel $
#
# This file uses the Windows ini style, where the file consists of a
# number of sections, each section starts with a unique section name
# in square brackets. Parameters in each section are specified as
# Name = Value. Any spaces around the equal sign will be ignored. If
# there are multiple sections with exactly the same section name, then
# the parameters in those sections will be added together to produce
# one section with cumulative parameters.
#
# The commit-access-control.pl script reads these sections in order,
# so later sections may overwrite permissions granted or removed in
# previous sections.
#
# Each section has three valid parameters. Any other parameters are
# ignored.
# access = (read-only|read-write)
#
# This parameter is a required parameter. Valid values are
# `read-only' and `read-write'.
#
# The access rights to apply to modified files and directories
# that match the `match' regular expression described later on.
#
# match = PERL_REGEX
#
# This parameter is a required parameter and its value is a Perl
# regular expression.
#
# To help users that automatically write regular expressions that
# match the beginning of absolute paths using ^/, the script
# removes the / character because subversion paths, while they
# start at the root level, do not begin with a /.
#
# users = username1 [username2 [username3 [username4 ...]]]
# or
# users = username1 [username2]
# users = username3 username4
#
# This parameter is optional. The usernames listed here must be
# exact usernames. There is no regular expression matching for
# usernames. You may specify all the usernames that apply on one
# line or split the names up on multiple lines.
#
# The access rights from `access' are applied to ALL modified
# paths that match the `match' regular expression only if NO
# usernames are specified in the section or if one of the listed
# usernames matches the author of the commit.
#
# By default, because you're using commit-access-control.pl in the
# first place to protect your repository, the script sets the
# permissions to all files and directories in the repository to
# read-only, so if you want to open up portions of the repository,
# you'll need to edit this file.
#
# NOTE: NEVER GIVE DIFFERENT SECTIONS THE SAME SECTION NAME, OTHERWISE
# THE PARAMETERS FOR THOSE SECTIONS WILL BE MERGED TOGETHER INTO ONE
# SECTION AND YOUR SECURITY MAY BE COMPROMISED.
[Make everything read-only for all users]
match = .*
access = read-only
[Make project1 read-write for users Jane and Joe]
match = ^(branches|tags|trunk)/project1
users = jane joe
access = read-write
[However, we don't trust Joe with project1's Makefile]
match = ^(branches|tags|trunk)/project1/Makefile
users = joe
access = read-only
[Top] How to import an existing SVN tree [Next]
This must be done manually by the projects adminatrators. Proceed as follow:
- Make a dump of your entire SVN tree.
svnadmin dump /path/to/yourproject >yourproject-repos.dump
- Transfer the dump to your BerliOS user account.
scp yourproject-repos.dump loginname@shell.berlios.de:/home/users/loginname
- Login to the SVN Server:
ssh -l loginname svn.berlios.de
- Load the dump to your projects SVN repository.
svnadmin load /svnroot/repos/yourproject <yourproject-repos.dump
- If the load was successfull, you will not be able to
access the imported SVN repository via ViewCVS immediately,
because the ownership of some files were changed to your
loginname. Ignore this, they will be changed back to wwwrun at least
in the next 6 hours automatically by the backend scripts, so
you will see it correctly.
[Top] How to convert an existing CVS tree to SVN [Next]
This must be done manually by the projects adminatrators. Proceed as follow:
- Login to the SVN Server using SSH2.
ssh -l loginname svn.berlios.de
- Stay in your user home directory and convert CVS to SVN using cvs2svn.
cvs2svn --existing-svnrepos -s /svnroot/repos/yourproject /cvsroot/yourproject
- If the conversion was successfull, you will not be able
to access the converted SVN repository via ViewCVS immediately,
because the ownership of some files were changed to your
loginname. Ignore this, they will be changed back to wwwrun at least
in the next 6 hours automatically by the backend scripts, so
you will see it correctly.
[Top] How to recover your SVN Repository [Next]
This must be done manually by the projects adminatrators. Proceed as follow:
- Login to the SVN Server using SSH2.
ssh -l loginname svn.berlios.de
- Stay in your user home directory and recover SVN using svnadmin.
svnadmin recover /svnroot/repos/yourproject
[Top] How to save space [Next]
You can save space if you remove Berkeley DB log files associated with, but no longer used by, the repository. This can be done manually by the projects administrators. Proceed as follow:
- Login to the SVN Server using SSH2.
ssh -l loginname svn.berlios.de
- Stay in your user home directory and remove the unused SVN log files using svnadmin.
svnadmin list-unused-dblogs /svnroot/repos/yourproject | xargs rm
The same procedure is also done in the next 6 hours automatically by the backend scripts. So you can neglet your duty.
[Top] How to get your SVN tree back [Next]
Daily dumps of entire project SVN Repositories are available
for backup or mirroring purposes. These are available at:
http://download.berlios.de/svndumps/projectname-repos.gz.
Where projectname is the Unix name of your project.
[Top] Additional References [Next]
Return to the top of this document
|
|
