Introduction

The SVN server maintains AROS' 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.

Alternative access to the repository has been set-up as well. This can be used by those not (yet) registered for access as a developer.

The software

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.

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

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.

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.

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:

• Version Control with Subversion
• Subversion Home

Alternative access

There are other ways to access the repository. These methods are, however, read-only. One would be able to set up a working directory but it would then not be possible to commit any changes this way. Instead, suggesting a modification has to be done by way of the developer list or to individual developers.