Working with Subversion
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.
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
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.
The server runs Subversion 1.5.
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").
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
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.
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.
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.
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
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
After the checkout, SVN will remember where the source came from.
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/
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
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.
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.
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.
Don't add generated files (usually mmakefile, strings.h) to the
repository. Otherwise these files won't be updated when the source file
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>
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:
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.)
Change to the directory containing the files you wish to import:
> cd name-1.2.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.
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" \
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.
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.
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 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
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: