http://www.aros.orgAROS-ExecAROS-Exec ArchivesPower2People
kitty mascottop logo menu

Working with Subversion

Abstract

Subversion, or SVN for short, is a version control tool which maintains a database of the files in a project. With SVN, it is possible to inspect and control the changes applied to any specific file: what changes were made and when, who did those changes, what the purpose of some change was (as long as there is a log entry), possibly reverting bad changes made, merging changes from several different people and much more.

In essence, it makes it much easier for a group of people to collaborate on a common project, by allowing everyone to know what is happening to the files, making sure that people do not trash each other's changes by mistake, and providing the means to do this over the Internet. For this reason, we use it to collaborate on AROS.

Introduction

The SVN server maintains a central "repository", which is the main database containing the published common codebase of the project. Individual developers have their own "working copies", which are local copies of the database from a specific time, together with local changes that the developer hasn't as yet uploaded to the server. When a developer wants to share his changes with the rest of the team, he simply "commits" his changes to the server using the client program, which takes care of uploading them and merging them with changes done by other developers.

The software

Unix

If you are running Linux, FreeBSD or any other modern Unix clone, you simply need to install the official SVN software, version 1.0 or higher, for your OS. All common Linux distributions come with SVN packaged.

There's also a cross-platform GUI front-end for Subversion called RapidSVN, available for Unixes (GNU/Linux distributions, FreeBSD, Sun Solaris and others), Mac OS X and Windows.

Note

The server runs Subversion 1.5.

AmigaOS

If you are running AmigaOS, you will need a TCP/IP stack and some SVN port installed. One option is the Amiga Subversion port by Olaf Barthel, which can be found on AmiNET (search for "subversion").

Windows

If you run Microsoft Windows, you can use the TortoiseSVN SVN client, especially if you like using Windows Explorer. This program is Open Source and free, feature-rich and well-supported. Please do make sure that the text files you submit have the svn:eol-style property set (see the Setting Properties section), otherwise you can break code generation. If files you're changing already have the eol-style:LF SVN property set (basically, they would not be new files) then you can forget about it, and line endings (EOLs) will automatically be converted.

MacOS X

If you run MacOS X you can use one of several SVN ports available such as Martin Ott's Subversion port. You may also want to install an additional SVN GUI client such as Versions or svnX. The svnX client is the most up-to-date SVN client for OS X and also supports integration with, among others, the freeware Textwrangler texteditor (former BBedit Lite). The RapidSVN client is also available, as noted above.

Note that when using Textwrangler or other Mac text-editors, you will need to change the character encoding from 'Macos roman' to 'ISO latin 1' (ISO8859) for your documents (change this in preferences). For Textwrangler all other settings are correct by default.

All named applications are freeware, and are available as Universal Binaries for PowerPC and Intel Macs.

Logging into the server

Unlike CVS, you don't have to log into the server. Instead, when SVN needs to know your login and password, it will ask them.

Note

The AROS repository is running on a password protected SVN server, which means that you need to apply for access to it to be able to collaborate in the development. At the request of Amiga Inc., anonymous read-only access to the repository has been disabled.

Getting the AROS sources

To get a copy of the AROS sources you use the "checkout" command, like this:

> svn checkout https://svn.aros.org/svn/aros/trunk/AROS

This will create a directory called AROS and populate it with all the sources, which might take quite some time if you have a slow network connection.

In addition to the main repository, there is also the "contrib" repository, containing third-party programs that have been ported to AROS. Additionally, the entire "contrib" directory can be checked out as follows:

> cd AROS
> mkdir contrib
> svn checkout https://svn.aros.org/svn/aros/trunk/contrib

Tip

After the checkout, SVN will remember where the source came from.

Getting the extra sources

Apart from the AROS main sources which we checked out in the previous section, there are also other things on the SVN server not directly related to the core of the operating system. For example, the "binaries" module which contains images like screenshots, backdrops and similar, and the "documentation" module which contains the sources to the website.

You can get a list of the available modules with:

> svn ls https://svn.aros.org/svn/aros/trunk/

Updating the sources

After having checked out the sources, you will probably want to periodically update them to get the latest changes the other developers have committed. For this you use the "update" command:

> cd AROS
> svn update . contrib

This will merge any changes that other developers have made into your sources and also check out new directories and files that have been added. If someone committed changes to a file that you also have changed locally, SVN will try to merge the changes automatically. If both of you changed the same lines SVN might fail in merging the sources. When this happens, SVN will complain and put both versions in the file separated by <<<<. You need to edit the file and resolve the conflict manually. Once this is done, you also need to use the "svn resolve" command to tell SVN that all is well.

Warning

Just because SVN successfully merged the other developers changes with yours doesn't mean everything is fine. SVN only cares about the textual content; there could still be logical conflicts after the merge (e.g. the other developer might have changed the semantics of some function that you use in your changes). You should always inspect files that were merged and see if they still makes sense.

Committing changes

If you have made some changes and feel that you want to share your work with the other developers, you should use the "commit" command:

> svn commit

You can specify a list of files to commit; otherwise SVN will recurs down from the current directory and find all files you have changed and commit them. Before sending your changes to the server for incorporation, SVN will ask you to input a log message. This log message should contain a brief description of what you have changed and in certain cases a rationale for your changes. Well written log messages are very important, since they make it much easier for the other developers to quickly check what you have done, and perhaps why. The log messages are sent to the development mailing list, so everyone can keep up with developments to the code base.

Before committing your changes in a directory, you should first do an update there to see if anyone else has changed the files since you started working on them. In case that happens, you need to resolve any problems before committing. Also, please make sure you test your changes before committing them; at least so that they do not break the build.

Adding new files and directories

To add new files and directories to the repository, use the "add" command:

> svn add file.c
> svn add dir

SVN will not automatically recurs into newly-added directories, and add the contents; you have to do that yourself. After having added the file, you need to use the "commit" command to actually add them to the repository.

Note

Don't add generated files (usually mmakefile, strings.h) to the repository. Otherwise these files won't be updated when the source file has changed.

Setting properties

Subversion should be set up so, that it automatically adds appropriate properties to new files. To do this, the file ".subversion/config" needs to be edited (the .subversion directory is located in your home directory). The first thing to do is to make sure that the [miscellany] section of this file contains the following line:

enable-auto-props = yes

Then add these lines to the [auto-props] section of the file:

*.c = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.cpp = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.h = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.i = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.sh = svn:eol-style=LF;svn:executable;svn:keywords=Author Date Id Revision
*.txt = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.png = svn:mime-type=image/png
*.jpg = svn:mime-type=image/jpeg
Makefile = svn:eol-style=LF;svn:keywords=Author Date Id Revision
mmakefile.in = svn:eol-style=LF;svn:keywords=Author Date Id Revision
mmakefile = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.src = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.py = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.conf = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.css = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.cd = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.ct = svn:eol-style=LF;svn:keywords=Author Date Id Revision
*.en = svn:eol-style=LF;svn:keywords=Author Date Id Revision

If you are editing documentation files, add a line similar to the last one for each language you intend to use, replacing 'en' with the appropriate two-letter language code.

The above rules will ensure that new files you add to the repository will, in most cases, get correct properties. Occasionally, however, it'll be necessary to specify properties manually, for files not handled by the default rules. The most common properties that need to be set are svn:eol-style, svn:keywords and svn:ignore.

Operating systems differ in the codes they use to represent line-endings. To ensure that text files that aren't generated/modified on Linux have the right line-ending for AROS, it is necessary to do:

svn propset svn:eol-style LF <source.c>

Subversion can substitute special keywords in source files. To enable this you need to do:

svn propset svn:keywords "Author Date Id Revision" <main.c>

Importing

When you want to add a larger collection of files, e.g. the source code of existing software, "svn add" quickly becomes tiresome. For this you should use the "svn import" command. Unfortunately, the section about the import command in the SVN manual is quite poorly written, so an example is in order:

  1. Put the files and directories you want to import wherever you like, as long as it is not inside your working copy. (Running the "import" command on a directory situated inside an existing SVN working copy can lead to very strange results, so it's best to avoid that.)

  2. Change to the directory containing the files you wish to import:

    > cd name-1.2.3
    
  3. Remove any file that you don't want to import into the repository. SVN will actually ignore filenames that are common for backup and hidden files, like #?.bak, .#? and #?~ (where #? is the AROS wildcard). Nonetheless, it's best to remove them beforehand.

  4. Import the files with the "svn import" command:

    > svn import -m <logMessage> <destinationPath>
    

    This will recursively import the files from the current directory and below into the repository, into the destination path, and with the log message you've specified. Don't try to interrupt SVN during the import if you see a file being added that you missed earlier and don't want to import. Just make a note and then delete the file afterwards.

    For example, say that you wanted to import the SVN 1.1.3 sources into the "contrib/development/versioning/svn" directory:

    > cd subversion-1.1.3
    > svn import -m "Initial import of SVN 1.11.12" \
      https://svn.aros.org/svn/aros/trunk/contrib/development/versioning/svn
    

Vendor Branches

The AROS Subversion repository has support for vendor branches as documented in the Subversion book. You can list its current content by:

> svn ls https://svn.aros.org/svn/aros/vendor

The purpose is to keep stable versions of external packages. Prominent examples are some MUI classes, like NList, TextEditor, BetterString etc.

Tags

Additionally the repository contains a directory for tags:

> svn ls https://svn.aros.org/svn/aros/tags

So far no decision has been made how to use it. Please discuss this on the developer mailing list if you want to work with it.

Copying

Never use the copy functions of your console or filemanager to copy directories within your working copy. Subversion creates hidden ".svn" directories to store metadata. These would be copied too, and would corrupt your working copy. Depending on the task you want to do you might use:

svn copy

svn move
Moves files to another place, but keeps history.
svn export
Makes a copy without the metadata. This is recommended if you want to include files from another SVN repository or revert to an older version.

Further reading

More detailed information about SVN can, of course, be found in the manual pages and info files distributed with SVN itself; there are also numerous sites containing useful tutorials and guides which might be easier to read.

The following pages are highly recommended:


Copyright © 1995-2014, The AROS Development Team. All rights reserved.
Amiga® is a trademark of Amiga Inc. All other trademarks belong to their respective owners.