== Checking out ==

To check out the software of FACT (or just a part of it) you need to know the URL for the 

    {{{
    user@host:~$ svn checkout <URL> 
    }}}

call.
In order to find out this URL, just click on the "Browse Source" button on the upper right side of this page. Browse to the partent folder you want to checkout and copy the URL from your browsers address field to your command line, the URL you copy might look like this:

    {{{
    https://trac.fact-project.org/browser/trunk/Mars
    }}}

Note: Before you hit <Enter> replace '/browser/' with '/svn/'. So for the example the call might look like this:

    {{{
    user@host:~$ svn co https://trac.fact-project.org/svn/trunk/Mars mars
    }}}

This call will checkout the current version of Mars form our SVN repository and dump it into a new folder called mars/ in your home folder.

== Start working -- Create A Branch ==

If you have an idea and want to try it, we invite you to profit from FACTs code versionion system right from the start. Who knows, maybe your idea will one day be a vital part of the std-analysis. 

However it's reasonable not to mess with other peoples work, so you might just create a Branch(http://svnbook.red-bean.com/en/1.7/svn.branchmerge.using.html) for your private work.
If later you want to share your work with others, or have it revised, just tell them about your branch.

=== Creating a Branch ===

Let's look at branching using the Example of Mars. Suppose you want to develop something in Mars, you may create your private branch of Mars. Branches are cheap in the sense, that on the svn server, there is not actually made a copy. It merely notes from which part of the trunk your branch springs off.
Is suppose you are creating a branch of the most recetn version of the trunk (of course it is also possible to create branches of historic versions, we'll come to that later)

Technically your branch could sit anywhere in the svn repository, but we agreed on having them in one central place for simplicity.

    {{{
    svn copy https://trac.fact-project.org/svn/trunk/Mars https://trac.fact-project.org/svn/branches/MyAwesomeNewMarsBranch -m "Just having an awesome idea..."
    }}}
    
Now just checkout your new branch as you would checkout the trunk version of mars.

    {{{
    svn co https://trac.fact-project.org/svn/branches/MyAwesomeNewMarsBranch mars_mybranch
    }}}

Actually if you checked out the trunk version into a folder called `mars` and your private branch into a folder called `mars_mybranch`, you might want to rename `mars`now to `mars_trunk` and create a symlink called `mars` that points to the version you are currently working with most.

In case you set `LD_LIBRARY_PATH` or `PATH` to the `mars` folder, changing versions is nothing more than overwriting that symlink.

    {{{
    ln -s mars_trunk mars
    rm mars
    ln -s mars_mybranch mars
    }}}

Feel free to work in your branch the way you like best, but if you later want to merge your branch back into the trunk, it might be useful to rather do many smaller commits than one big commit. 

=== Creating a Branch from a historic version ===

It is actually common practice that not the most recent version of the trunk is used for production. Very often software developers create certain release versions of their code, which is used for production, while development continues in the trunk. Code releases are often marked by so called **tags** for easy reference, but so far FACT did not follow this practise.
However you might find yourself in the situation, that you want to base your development on 

== Before you commit something ==

Although the svn is a versioning system which keeps the history, it should be kept clean as much as possible. We are all humans, so we make mistakes, but svn should help us to cure real mistakes as fast as possible, not be sloppy and create more mistakes.

Here are a few simple rules which help a lot to make sure you know what you do when accessing the svn and which help you to properly document your changes. The later is important if a problems needs to be tracked. Not only the comments to the code of question might be important, but also other comments. To find the commit in question as soon as possible, comments which tells you the kind of the commit are very important (cosmetics, only includes, major code change, etc) and the meaning (fixed a compiler warning, fixed a memory leak, ...)

== Comitting ==

Before you commit anything, check which files would be committed:

     svn diff | grep Index

Now you have a list of files... choose the ones you want to submit and check the diff

    svn diff filename

You might find surprises sometimes. A change you forgot or a change which was only for debugging. Clean your change. Now you are ready to commit the file

    svn ci filename -m "Comment"

Write a comment which tells the type of change, the reason of change and maybe some details. Write comments for every change you made, try to be as detailed as possible. Hint: If you write a comment which needs the name of a file or class, most probably it is the wrong comment because it applies to another file.

Do that for each file independently, file by file. It is very rare that the same comment applies to several files. If this is the case, make sure that you checked all their diffs and then commit all of them together.

== Revert ==

Sometimes it might happen that you committed something by mistake. For example, you thought to do **svn ci filename** but in fact did **svn ci** and committed file which were not intended to be committed. Don't forget to keep the list of files which need to be reverted as soon as possible before it is off your console history!

I have created a short script (I called it *revert.sh*) which allows to revert the last change (unfortunately only file-by-file, but this makes sense to ensure you know what you do).

    svn merge -r COMMITTED:PREV $1\\
    svn ci $1 -m "Reverting to last revision."\\
    svn merge -r COMMITTED:PREV $1