Subversion for Muffin Artists

Since we are mainly looking for artists we cannot expect that all people have clue about the more technical things. Therefore I tried to create a logic explaination of what Subversion is and how it works.

For Insiders

If you already have Subversion experience and want to take the shortcut, here is the repository URL:

http://svn.openmuffin.net/muffin

But wait: In order to speed up the checkout or update process, you can exclude all big media files by passing the “–ignore-externals” parameter to the svn command:

svn checkout --ignore-externals http://svn.openmuffin.net/muffin

Next time you update your copy without the –ignore-externals parameter, externals will get fetched automatically.

Introduction

Subversion (or short SVN) is a software that allows central version control of a file hierarchy. We use it to distribute and manage our project data. In order to work on The Muffin, you need to install the subversion software, which is freely available for all systems.
Unfortunately Subversion itself doesn’t have a graphical user interface. If you want to avoid typing commands in a terminal/command line, you need to install a second party user interface. I recommend Tortoise SVN for Windows users and the Subversion Scripts for Mac OS X Finder. Even though I recommend those user interfaces, I will provide you with the most important commands here, in case you need them.

Advantages

We use Subversion instead of other systems like a simple FTP access for those reasons:

• Version Control: you can go back in time and get any previous version of a file you want.
• Faster synchronization: If some files are changed, SVN will download only those files for you, not the whole project.
• User management: Everyone will get read access. Write permission is limited to some users only.

How it works

Checkout the files

All our project data is on a central server in a subversion repository. Everyone that wants to work with these files can make a local copy of that that repository (called checkout). We provide two different ways to checkout the data. The first way includes all project data. The second way omits bigger media files (like textures) and should be used in case your connection to the server is slow.

If you use TortoiseSVN on Windows, create a folder, right-click it and choose SVN checkout from the menu. A window just like this one will pop up:

Fill in the URL just like in the picture. If you want omit loading bigger media files, check the “Omit externals” option box.

To do the same via command line type (should work on windows/mac/linux):

svn checkout http://svn.openmuffin.net/muffin myMuffinFolder

This will create the folder “myMuffinFolder” in the current directory and fetch all the data from the repository into it.

svn checkout http://svn.openmuffin.net/muffin myMuffinFolder --ignore-externals

The second command includes the “–ignore-externals” option and won’t download any media data (like huge textures) for now. Use this if your connection to the server is rather slow. You can always load the media files later on.

Use and edit the files

Once you have your copy, you can now alter the files of your local copy and they won’t change on the server.

Update your copy

Once something changed on the server’s repository, you can update your local copy and instead of downloading the whole project again it downloads just those altered files for you. In case you changed those files on your local copy before, SVN will inform you that there is a version conflict that you need to resolve. So your changes won’t get lost.

TortoiseSVN users have to right click the folder or files they want to update (usually the project root) and choose “SVN update”. Note that this will update all files AND download all big media files. If you want the update process to also omit those files, right click the folder or file and chose the option TortoiseSVN->Update to revision:

A small window will pop up that looks like this:

Again you have the option to omit the media files here called “Omit externals”. That’s it.

Command line users have to update like this:

svn update

Again, you can also provide the “–ignore-externals” option to update as well:

svn update --ignore-externals

This command update the files and directories within the current working directory and below. So you can also update just a part of the whole repository, like just a single file:

svn update someFolder/someFile.blend

SVN repositories have a revision number, that increases by one each time someone commits changes. After every checkout or update you will see what the most current revision number is. By specifying a repository number you can access any previous version of a file or a whole directory. This way we don’t need to make backups of older versions.

Other useful SVN commands

SVN has a lot more functionality than we mention here. The following ones could be useful too for you:

svn status

This way you can find what files you have changed and you may want to submit for addition to the project.

svn revert

You can remove changes you made that were just experiments or didn’t work out.

Write access

All commits to the project have to be reviewed and rated by the community in the forums first anyways. So it wouldn’t make sense to grant write access to everyone. For now, the only person that has write permission is the project coordinator (atti).

However, if it speeds up the development process, we can grant write permissions to further project members.

For now i won’t describe how to commit changes to the repository.

Useful Links

http://subversion.apache.org – Subversion’s official homepage.
http://svnbook.red-bean.com – A complete Subversion documentation as PDF or to read online.

Tortoise SVN – a wonderful Windows SVN client that integrates into the Windows Explorer.
Subversion Scripts for Mac OS X Finder – some scripts that allow you to use SVN from within Finder.