SVN(SourceForge.net document)

http://sourceforge.net/docs/E09

Document E09

SourceForge.net: Subversion (Version Control for Source Code)

Table of Contents

• E09- 01 Overview
• E09- 02 Connection Information
• E09- 03 Notice of New Connection Method
• E09- 04 SVN Documentation
• E09- 05 SVN Terminology
• E09- 06 Using SVN
• E09- 07 Importing Data into SVN
• E09- 08 SourceForge.net SVN Environment
• E09- 09 Hook Scripts
• E09- 10 Commit Notifications via Email (SVN::Notify)
• E09- 11 Case Insensivity Check (check-case-insensitive.py)
• E09- 12 MIME Type Property Check (check-mime-type.pl)
• E09- 13 CIA Activity Statistics (ciabot_svn.py)
• E09- 14 Permissions
• E09- 15 Web-based Repository Browsing (ViewVC)
• E09- 16 Backup Subversion Repository Contents
• E09- 17 Repository Upkeep and Management
• E09- 18 SVN Limitations
• E09- 19 Support

01
Overview

Subversion (SVN) is a tool which allows development teams to safely coordinate and track software source code changes.

While SVN is a powerful tool for managing software changes, the SourceForge.net File Release System is a better way to distribute releases to end-users. SVN and the FRS are complementary tools; SVN allows you to distribute the latest development source code within your team, and coordinate the influx of changes to that source code.

SVN is a complex tool. We encourage all new developers to practice SVN commands locally before using SourceForge.net SVN servers for the first time. Instructions on configuring a local SVN repository for testing are provided in SVN client configuration instructions.

SourceForge.net encourages projects to adopt a revision control system as a way to improve coordination of collaborative team-based development. Project SVN repositories are not bound by quotas. SVN does have some functional limitations which should be considered before use on your development project.

02
Connection Information

A list of supported SVN clients and configuration information is provided in Recommended User Software Configuration.

As a reminder, only Open Source licensed software may be hosted on SourceForge.net provided services, including SVN.

The following configuration settings are used to access a SourceForge.net-hosted SVN repository:

• Hostname: PROJECTNAME.svn.sourceforge.net (PROJECTNAME is the project's UNIX name)
• Port: 443
• Protocol: HTTPS
• Repository Path: /svnroot/PROJECTNAME (PROJECTNAME is the project's UNIX name)
• Username: Your SourceForge.net username for SVN write operations, none will be requested otherwise.
• Password: Your SourceForge.net user password for write operations, none will be requested otherwise.

If you receive a 403 Forbidden error, either your password doesn't match (it could be a sync issue, try changing your password and attempting to access the service a few minutes later with the new password) or your project administrator hasn't granted you SVN write permissions (if you are the project admin, you must still grant yourself that permission). Go to the members section of your project admin pages to set this option.

Firewalls and proxy servers may present a problem in using SVN. No workarounds are provided as HTTPS should be passed without modification from almost all ISPs world-wide. Should a firewall or proxy be causing issues with your connection, contact your network administrator or ISP for further assistance.

03
Notice of New Connection Method

Users new to the SourceForge.net Subversion Service should skip this section, it only covers changes that affect users who have been using Subversion prior to the switchover date

On November 31, 2006 the access method for Subversion changed. This document reflects those changes. The old method had numerous problems, including spurious 50x error messages and other issues that kept it from functioning fully. This newly documented access method solves many, if not all of the issues with the old mechanism.

Users of the old method (https://svn.sourceforge.net/svnroot/PROJECTNAME) should switch to the new access method (https://PROJECTNAME.svn.sourceforge.net/svnroot/PROJECTNAME) using these steps:

1. Make a copy of your local working copy.
2. Run 'svn info' at the root of the repository content, it should display a line that appears similar to: URL: https://svn.sourceforge.net/svnroot/PROJECTNAME/trunk
3. Run the following command at the root of the working copy: svn switch --relocate https://svn.sourceforge.net/svnroot/PROJECTNAME/trunk https://PROJECTNAME.svn.sourceforge.net/svnroot/PROJECTNAME/trunk

04
SVN Documentation

SVN is a complex tool.

The document you are reading now is meant to be an introduction to SVN as applied to SourceForge.net. Full reference materials exist, with extensive detail on how to use SVN.

We recommend that all users new to SVN read the following:

• Version Control with Subversion

05
SVN Terminology

The following is a list of common terms used throughout the SourceForge.net SVN documentation:

• SVN client: Software run by a SVN user to access the SVN server.
• SVN repository: The SVN server stores a copy of the software and data that the project has uploaded. The server retains both the most recent version and every historical version (past changes). This copy of the software and data uploaded by the project is a SVN repository. Each project hosted on SourceForge.net has its own SVN repository.
• Project UNIX name: The unique name the project founder selected when registering a project for hosting on SourceForge.net. This value can be located on the project summary page (e.g. https://www.sf.net/projects/PROJECTNAME/) to the right of the phrase, "Project UNIX name:".
• Working copy: Though the SVN repository stores every version of every file that has been uploaded to the repository, when you retrieve data from the SVN repository using your SVN client, only one version of each file is saved to your hard drive. The copy of the data you get from the SVN server is called a "working copy", obtained using the "checkout" command.
• Module: Unlike CVS, SVN has no concept of a module.
• Trunk: Development with SVN progresses similar to that of a tree. The main development occurs against the trunk. Conceptually, it is identical to that of the trunk in CVS.
• Branch: A split of development off of the trunk or another branch. This allows for development to diverge either permanently or temporarily for a variety of possible reasons.

Most other terms can be found in Version Control with Subversion.

06
Using SVN

To quickly begin using SVN:

1. Read this document.
2. Read the Guided Tour of Subversion.
3. Install and configure an appropriate SVN client for your platform.
4. Enable SVN in your project admin pages, and configure access for all project developers who need access.
5. If you have an existing CVS or SVN repository, import it. If you have content that has not been present in a CVS or SVN repository prior, use the SVN import command to add the content to your repository.
6. Checkout a working copy of the repository.

07
Importing Data into SVN

There is only one supported data source for importing data into a SourceForge.net Subversion repository. Due to issues with remotely running cvs2svn for end-users, we had to remove the import from SF.net CVS repostiory and CVS tarball. We support imports from a SVN dump file, compressed (.gz, .bz2, .zip, but not tarred) or uncompressed. As the process is largely automated on our side, it is imperative that these instructions be followed closely and in their entirety to ensure a successful import.

Making a Subversion dump file from CVS content:

1. Download and install a copy of cvs2svn.
2. Get a copy of the RCS files for the CVS repository (if not hosted on SourceForge.net, you may need to contact the repository administrator for a copy of the files). For SourceForge.net-hosted CVS repositories, this can be done via rsync (example for project filezilla: rsync -av rsync://filezilla.cvs.sourceforge.net/cvsroot/filezilla/* filezilla-cvsbackup).
3. Clean up any data from the archive. Ensure that any data that shouldn't be imported isn't present in the archive (you may want to remove the CVSROOT module, it likely doesn't contain anything useful for the future). Data cannot be readily removed from a Subversion repository.
4. Convert the repository to a SVN dump file with cvs2svn by going to the directory at the root of the repository and running the following command: "cvs2svn --dumpfile=svndump .".
5. If the conversion generates an error message, follow the promps indicating what the problem is, and attempt to resolve them using one of the various options for cvs2svn (--trunk-only will drop all branches and tags, but will likely make the process painless).
6. Compress the resulting SVN dump file (svndump) if so desired, using zip, gzip or bzip2 (but do not tar it).
7. Follow the instructions for importing from a Subversion dump file to finish the import.

Import from Subversion dump file (svnadmin dump or cvs2svn):

1. Backup your repository.
2. Create a SVN dump file (using svnadmin dump) if you haven't already done so. Filter anything out of the dump file that isn't to be imported.
3. Compress the dump file, if possible, to save space. We support zip, bzip2 and gzip compression.
4. Name the file using only alphanumeric characters and a period (Example: svndump.gz -- good; projectname-svndump.gz -- bad).
5. Upload the dump file into the root of your project group directory on the shell server (i.e. scp filename.gz USERNAME@shell.sourceforge.net:/home/groups/P/PR/PROJECTNAME/filename.gz).
6. Login to the SourceForge.net website.
7. Go to the project summary page (https://www.sf.net/projects/PROJECTNAME).
8. Click on the 'Admin' link.
9. Click on the 'Subversion' admin page link.
10. Click on the 'migrate' link on the 'Migration Instructions' section of the page.
11. Key in the filename of the archive into the 'Source path' field, noting that it must comply with the filename restrictions previously described.
12. Check the 'Replace' check box in the same column, if you wish to replace the existing content with the new content to be added.
13. Enter the value you want passed to the --parent-dir argument of the "svnadmin load" command into the 'Destination' field. For most users, this would be left blank. Note that the destionation directory must be created but empty for this to work.
14. Click on the 'Submit' button.
15. The migration will be finished within 24 hours. It could be finished in as soon as an hour or two, depending on the size of your CVS repository and the number of projects queued for migration in front of yours. Returning to the page will display whether it completed, failed or is still in queue.

08
SourceForge.net SVN Environment

SourceForge.net currently runs the 1.3.x series of SVN software. Regular version upgrades occur based on testing of new releases and security needs.

Interactive shell access to the SVN servers is not provided.

09
Hook Scripts

SVN is capable of running server-side scripts during the various stages of a SVN commit operation. These hook scripts are very powerful, but due to the implementation of hook scripts in SVN, projects are not permitted full control over them. This is quite a large change from how CVS handles pre- and post- commit scripts. Accordingly, SourceForge.net makes available to projects specific scripts which may be of use to hosted projects. The following scripts are available for your use:

• svnnotify: Sends email notifications of changes made during a SVN commit. Two versions of this hook script are available, one that includes a diff of the changes, and one that doesn't.
• check-case-insensitive.py: Checks to make sure filenames are valid for a case insensitive environment (Windows, for example)
• check-mime-type.pl: Checks to ensure a mime-type property is set for files added to the repository
• ciabot_svn.py: Reports commit activity to cia.navi.cx.

To install a hook script:

1. Login to the SourceForge.net website
2. Go to the project summary page (https://www.sf.net/projects/PROJECTNAME)
3. Click on the 'Admin' link
4. Click on the 'Subversion' admin page link
5. Select the hook script from the 'Hooks:' pulldown menu
6. Click the 'Add' button
7. Fill in any of the requested hook parameter fields, as displayed on the resulting page (if any)
8. Click the 'Finish Add' button

To remove a hook script:

1. Login to the SourceForge.net website
2. Go to the project summary page (https://www.sf.net/projects/PROJECTNAME)
3. Click on the 'Admin' link
4. Click on the 'Subversion' admin page link
5. Click the radio button to the left of the hook script to remove
6. Click the 'Delete' button

To request additional hook scripts be installed for use, submit a Feature Request.

10
Commit Notifications via Email (SVN::Notify)

SVN::Notify provides email notification of changes to the SVN repository. For simplicity, we only support one user-provided option to this script, the email address to send the notification to. Multiple copies of this script may be installed, should multiple notifications need to be sent out, but we highly recommend creating a mailing list to handle the distribution to more than 2 or 3 recipients.

11
Case Insensivity Check (check-case-insensitive.py)

The case insensitivity check ensures that all filenames in the repository that are added would properly function on a case insensitive filesystem (such as those provided with any version of Microsoft Windows) when checked out. We strongly recommend this hook script be installed by any project that may have users of a case insensitive system.

12
MIME Type Property Check (check-mime-type.pl)

The MIME type property check may be useful for some projects, especially those developing a web application. It checks to make sure that the svn:mime-type property is set on all files prior to being included into the repository. This script may need to be disabled when importing content into the repository, to bypass the initial check, afterwards it can be re-enabled and the files should have their mime-type property set.

13
CIA Activity Statistics (ciabot_svn.py)

Refer to documentation on CIA prior to implementing it for details on its use and function.

14
Permissions

Read access cannot be restricted: This limitation is imposed to ensure all code is available to the public per the spirit of the Open Source Definition. No means is provided nor supported to restrict anonymous access to a project's SVN repository.

Access for project developers: Developer SVN access is only provided to project members who have been granted 'Allow access to SVN repository (developer access)' on the developer permissions page. Project administrators can enable/disable SVN access entirely to a project developer with this setting. Developers without this enabled will have to use anonymous SVN access.

No means is provided to limit access to a repository on a per-path basis.

15
Web-based Repository Browsing (ViewVC)

ViewVC, formerly known as ViewCVS, provides a graphical interface for browsing a SVN repository using a web browser. This allows individuals to view SVN content without the use of a SVN client. It supports common actions such as viewing the contents of a file in SVN, viewing the diff between different file revisions, syntax highlighting and line based annotations (blame). This service is provided for every SourceForge.net project and may be accessed using the 'SVN Browse' link under the Code menu on the project summary page.

16
Backup Subversion Repository Contents

Read-only rsync access is provided to all SVN repositories. Rsync clients exist for all current UNIX platforms and under Cygwin for Windows. To make a full backup of your project:

# Replace PROJECTNAME with the project's UNIX name
rsync -av PROJECTNAME.svn.sourceforge.net::svn/PROJECTNAME/* .

The project 'filezilla' would do the following:

rsync -av filezilla.svn.sourceforge.net::svn/filezilla/* .

17
Repository Upkeep and Management

File and Directory Deletion: The SVN delete command will remove a file or directory from a branch or the trunk. Subversion also has a problem similar to CVS, in that files and directories cannot be removed in their entirety from a repository. A deleted file or directory can be retrieved by checking out an older revision that contains that content. This limitation is described a bit more fully in Version Control with Subversion. A workaround for this problem is documented with the SVN Limitations.

Repository Restructuring: The SVN delete, move, copy and propedit allow for full control to make changes to files in the repository. This will allow content to be moved around, copied and set executable when checked out, even if not initially checked in so.

Backups: A backup can be created by using rsync.

Restore: Generally, this should not be necessary. Initial imports can be done as documented prior. If its necessary to replace a repository entirely, a Support Request should be submitted.

18
SVN Limitations

Case Sensitivity in File and Directory Names: The SVN server stores files in a way that is case sensitive. That is, a file with the name 'FILE' is distinctly separate from a file with the name 'File'. Developers who have a potential audience using Operating Systems that are case-insensitive should be aware of this, and select case-insensitive filenames. The case insensitive hook script may be useful to check for this.

Speed: While we are taking all efforts to ensure our infrastructure is configured optimally, SVN is not as fast as CVS. This difference shouldn't affect most users doing normal daily operations in any meaningful way.

File and Directory Removal: Files and directories cannot be removed in their entirety from a SVN repository. This limitation is documented in Version Control with Subversion. To remove a file from a SourceForge.net Subversion repository, one would have to:

1. Get a copy of their repository backup
2. Create a SVN dump file from the repository backup
3. Filter out the undesirable data
4. Import the resulting SVN dump file back into the project's SVN repository, replacing its existing content.

File Naming Limitations: File and directory names should not contain spaces; not all platforms handle spaces well. Commonly-reserved filenames should also be avoided. Some reserved filenames follow (treat all as if they are case insensitive, don't use them with a different case):

• Windows: con, aux, com, com1 - com9, prn, lpt1 - lpt3, nul, a: - z:, clock$, _svn
• All: .svn

19
Support

SourceForge.net provides support for the SVN service and recommended SVN clients attempting to use the service. Other clients are unsupported; you should seek support from the vendor or user community if using a client not on our recommendation list.

Before reporting an issue to SourceForge.net staff, do the following:

• Ensure you are using and have properly configured a supported SVN client
• Read through this document to see if the operation can be completed by a project member
• Read through the SVN documentation

If unable to resolve the issue yourself, contact SourceForge.net staff by submitting a Support Request with this information:

• Operating System and Version
• SVN Client and Version
• The full output of the command, including the execution of the command itself and any of its output
• Any additional troubleshooting information collected as per the Support section in the SVN client configuration instructions
• A screenshot, if possible
• A brief description of the attempted operation
• What you believe may be causing the issue

Document links:

• Return to the top of this page.
• Return to the list of documentation.
• Search Site Docs using the 'Site Docs' search, which is accessible at the top of most pages.
• Get support, assistance, or help on a topic covered in this document.
• Report a broken link or bug in this document.
• This document was last updated $Id: document.xml 6764 2007-08-17 19:21:45Z wdavison $ by the SourceForge.net team.
• This document was prepared by SourceForge.net staff as part of our Site Documentation project.

Site Docs referenced in this document:

• B01 - Recommended User Software Configuration
• D06 - Screenshots
• E01 - File Release System: Offering Files for Download
• E04 - CVS (Version Control for Source Code)
• F01 - Secure SHell (SSH) Client

Document E09 - Subversion (Version Control for Source Code)
SourceForge.net Site Documentation

© Copyright 2001-2004 Open Source Development Network, Inc. All rights reserved.
© Copyright 2004-2007 SourceForge, Inc. All rights reserved.