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 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

Logging into the server

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

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. To compile AROS, it is essential to check out at least the "necessary" subdirectory of this source tree. To check out only the necessary directory, use the following commands:

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

Alternatively, the entire "contrib" directory can be checked out as follows:

> cd AROS
> 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 is 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/necessary

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 recurse 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 them. Well written log messages are very important, since they make it much easier for the other developers quickly can see what you have done and perhaps why. The log messages are collected and then sent in a daily mail 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 in the meantime since you've been working on them. In case that happens, you need to resolve any problems before committing. Also please make sure you have tested 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 recurse 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). Firstly, make sure that the [miscellany] section of this file contains the following line:

enable-auto-props = yes

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

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

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 get correct properties in most cases. However, sometimes it's 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 which codes are used for line endings. To ensure that text files that aren't generated/modified on Linux have the right line ending it is necessary to do:

svn propset svn:eol-style native <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 some 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. Import the files with the "svn import" command:

   > svn import -m <logMessage> <destinationPath>
   

   This will recursively import all files from the current directory and below into the repository, into the destination path and with the log message you've specified. Actually, not all files will be added: SVN will ignore filenames that are common for backup and hidden files, like #?.bak, .#? and #?~ (where #? is the AROS wildcard).

   Nonetheless, you should remove all files which you don't want to end up in the repository before you start the import. Don't try to interrupt SVN during the import when you see a file being added that you don't want, though. 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
   

Further reading

More detailed information about SVN can of course be found in the manual pages and info files distributed with SVN itself, and 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