bboxVerbatimframe=single,xleftmargin = .8cm,commandchars=+^&

[frame=single,formatcom=\footnotesize,
tabsize=2,framesep=1em,#1,commandchars=+\(\)]}
\newcommand{\codesnipper}[1]{\begin{Verbatim}[frame=single,formatcom=\footnotesi
ze,tabsize=2,framesep=1em,#1,commandchars=+\{\}]}
% Header
\date{June 3. 2004}
\author{Benjamin Grauer}
\title{Subversion usage at open.datacore.ch}

% Beginning of the Documentation
\begin{document}
\maketitle
\tableofcontents
\newpage

% Kapitel 1
%%%%%%%%%%%%%%%%%%%%%%
\section{Subversion}
\subsection{Introduction}
Subversion is an easy to use, good to have tool for sourcecode-control, especially, if working in a group on one big project. It helps every member to be up to date with the leatest code, and that nothing will get lost. Not even things you have deleted will ever be lost (maybe there was some good stuff in it after all). 
Subversion lets you see all the changes that have been made to your programs, and even lets you go back to an older version of it, to check what you have done the last few days. (Subversion can be your calendar.)
But the best thing, is that it helps you to structure your programming process. With Subversion you are always asked to give a topic, to the changes you've just made, and like this, ther evolves a certain flow in the engeneering of your growing software.


Subversion is like CVS a subversion-controll-tool. It is meant to help all of us, in developing good software, without the unconvenient User-Backup, and mailsendings of new Code. 
\\\\
For one person this means:
\begin{itemize}
  \item{Whenever you make a new change that works you check it in.}
  \item{Now you can play around with the code, and if you fail, you can allways look at all the differences, you have made since previous releases. Like this you can correct many errors.}
  \item{If you really f***ed it off, you can revert all of your code back to a state, where it worked, and start over again.}
  \item{Now after your new change woked again, you can check them in again, and you can begin a new task.}
  \item{You don't have to worry about silly backup-files. Subversion is the Ulta-Automated-Backup-System.}
  \item{You can code wherever you want. On the Laptop, on a Solaris, even on Mac OS X and Windows. The one won't interfere with the other.}
\end{itemize}

For more than one person it means:
\begin{itemize}
  \item{Everything that's ok for single Developpers.}
  \item{You are allways up to date with the newest changes of your colleagues.}
\end{itemize}
Try it, and you will never ever code in another way again.

\subsection{How it works.}
Subversion is really quite easy. From the view of the user it consists of two parts: The repository and the working copy.
\subsubsection{Repository}
On one computer on the net there must be a Subversion-server which holds the repository. The server handels all incomming requests regarding changes of the sourcecode. Those changes are then appendet to the repository. And as a user the Storry ends there.
\subsubsection{Working Copy}
This is the interessting part for you. This is where you actually change your code.
The working copy is in its bases nothing else, than a copy of the repository. At the beginning you copy (checkout) the repository to your local computer, hack around, and if you are at peace with it, you submit the changes (and only the changes) back into the repository. So now your working copy is the repository again.

\subsection{Subversion in practical use}
 Subversion comes with many different commandos: svn, svnadmin, svnversion...
But from the user point of view only svn itself is important. It does everything, but creating and managing a repository. Thats what svnadmin is for, but this will not be discussed here.

\subsubsection{getting subversion}
Subversion is a product of tigris.org and can be found at http://subversion.tigris.org
Under Linux there are many ways to get Subversion.
Gentoo: emerge subversion :)\\
Debian: ???\\
Other Distributions: get it from http://subversion.tigris.org/project\_packages.html\\
I hope you receive in installing it. \\

On Windows I strongly recommend you to use the fully integrated graphical version TortoiseSVN that can be downloaded under 
http://tortoisesvn.tigris.org/download.html
There is also a non-graphical version, that can be more convenient for advanced Windows users (why are you still trying to pretend, you use a more easy system than Linux, if you are that advanced?)\\

Mac users: you Say, plug and play so do it... I never tried it.

\subsubsection{svn's commands}
First of all i give you the advice of looking up the help of svn. Do this either by ``man svn'' or by using the embebbed help, using the following commands
\codesnip{gobble=0}
   svn help             or              svn help [command]

By typing in the first one, you will receive a list of all the availiable subcommands: add blame (praise, annotate, ann) cat checkout (co) cleanup commit (ci) copy (cp) delete (del, remove, rm) diff (di) export help (?, h) import info list (ls) log merge mkdir move (mv, rename, ren) propdel (pdel, pd) propedit (pedit, pe) propget (pget, pg) proplist (plist, pl) propset (pset, ps) resolved revert status (stat, st) switch (sw) update (up) In this list you see all subcommands, and their aliases. This list comes from ``svn help''

I will now introduce all the really important commands an theit most used flags to you, so you can start working the code (the list wont be complete, but in most cases you won't need more, than what i will discuss here):

1. checkout, co
   With this option you can get the source out of a repository. It is the one command you should only use once. The default syntax is as follows: svn checkout [URL] [Path]

2. commit, ci
   So now you have worked with the code, and made some changes to, added new features, updated obsolete code, and all works better now than before. Now you are at a state, where you can commit all the good new changes to the software, that you have made.
   This is done as follows: svn update -m ''message'' Notice, that here you dont have to pass an URL. This is because svn knows, where to which repository the files reside. You can also tell svn, that it should only commit certain files, that will be done, by just adding a filename to the parameter list of ``svn ci''. Also be aware, to give a good topic about the changes you have just made to the changes, and pass them in ``message''. you can also leave -m ``message'' away, like this svn will use your default editor to write the message. Can be very handy, if you want to write a long message about what you have done.

3. update, up
   With this command, you fetch all the changes others have done to the repository, since you last updated (or checked out) the changes. svn update [-R [revision]] It is totaly necessary, to do this on a big project to do it before you start coding. Sometimes, if someone has commited a change to a file, where you have made a recent change too, you have to update before you can commit yourself, so that the repository never has to decide, what difference to take. (actualy this is a long story, and if you want to know more about it, look at the manual.)
   With the flag ``-R [revision]'' you can also update your workling copy to an older evision, like this you can check, when an error has occured, and look if it did not happen in older revisions.

4. revert
   This command comes in handy, if you absolutely failed with your try for doing some good update. It changes everything back to the state where you last updated your working Copy. svn revert [-R] [filename] if you want to revert everything -R (revursive) and [filename]=* will be a good choice.

5. add
   This command adds a new file to the repository: svn add [file] If you just add a new file in one directory in the working copy, this file will not be added to it. You have to do this, so subversion knows, it belongs to it. You understand the meaning of this if you work with emacs, that creates backup of files in the same directory.
   Important is, that you have to commit it, so that other people see the change.

6. delete, del, remove, rm
   The oposite of add svn delete [file] Important, if you accidentally delete a file with ``rm [file]'' you can call it back with ``svn update'' and then delete it with ``svn delete [file]''

7. status, st shows all the files, that have been changed or added, or that are just loosely swimming arround in the working copy.

8. diff
   shows you the differences you have done since the last update. svn diff [file] Leave [file] away to see all changes.
   If you want to see all changes since a certain revision, you can add the parameter -r [revisionnumber] to it.

9. copy, cp
   As the name implies, it copies some part of the working copy somewhere else. svn cp [source] [destination] What can come in handy, is that source may also be an entire path. You do not have to include a -R to recursivley add its contents.

10. move, mv
    Same as copy, but moves things around.

11. all other things
    Everything else is too advanced to be mentioned here, and as such will only be for complex svn transactions, between different structure. http://subversion.tigris.org/servlets/ProjectDocumentList This site has a great manual about all those actions. Visit it and read it if you like.