= SVN =

When working with any relevant amount of code, you'll soon notice it is a good idea to keep
regular backups of working states in case things go wrong. Also, working on the same code in teams
is near impossible without some kind of software to manage who changed what at what point in time.
This is where tools like SVN come into play: They keep a record of all changes done to the code in 
a project and provide tools to add new changes, revert changes, keep different copies of the same
code in parallel and much more.

SVN uses a central server to store all this information. The typical workflow of a programmer in 
a project is hence as follows:
  * Download ("Check out" in SVN terminology) the newest version of the code 
  * Make changes to the code
  * When done, upload your changes ("commit" in SVN terminology) to the central server ("repository")
Ideally, SVN commits are done regularly over the course of a programming session and not just after
hours and hours of coding. If you screw up in any way, you can always revert to the last working state.

[[TracNav(TracNav/TOC_Development)]]

{{{
#!div style="background-color: #FFFFDD; border: 3px solid #000000; margin: 5px; padding: 10px; width: 710px;"
[[span('''SVN Clients''', style=font-family: sans-serif; font-size: 16px)]]

There are many SVN clients, the two below are just examples. Of course you can use whatever client you like. A client with a graphical user interface however might protect you from mistakes due to mistyped commands.
 * Windows: [http://tortoisesvn.tigris.org/ TortoiseSVN]
 * Linux/Tardis: [http://www.rabbitvcs.org/ RabbitVCS] (is already installed on Tardis computers at ETH and can also be found in your distribution's repository)
}}}

{{{
#!div style="background-color: #F4F4FF; border: 3px solid #000000; margin: 5px; padding: 10px; width: 710px;"
[[span('''SVN Command Description''', style=font-family: sans-serif; font-size: 16px)]]

This section below contains a collection of the most used svn commands including some examples. This page does not claim to be complete. For further reading use the built-in help function from svn. The syntax is ''svn help <command>'', if command is omitted, a complete list of valid svn command in printed to the comsole. Furthermore it is assumed that the user has a basic understanding of the shell and knows the way around in the file structure. Svn allows for most of the flexibilities the bash shell allow.[[br]][[br]]

These are some examples, which are elaborated further down.
{{{
#!html
<pre class="wiki" style="white-space:normal;">
svn co https://svn.orxonox.net/game/data/trunk data_extern<br/>
svn up<br/>
svn ci -m "some message"<br/>
svn add myFile.cc myFile.h<br/>
svn rm trash-folder<br/>
svn mv myFile.cc myFile.h myFolder<br/>
svn cp https://svn.orxonox.net/game/code/trunk https://svn.orxonox.net/game/code/branches/test<br/>
svn resolved somefile.cc<br/>
svn revert<br/>
svn diff<br/>
</pre>
}}}

Read the [http://svnbook.red-bean.com/en/1.5/index.html official guide to subversion] for further information.

If not noted otherwise all commands are recursive.
}}}

{{{
#!div style="background-color: #F7F7F7; border: 1px solid #888888; margin: 5px; padding: 10px;"

{{{
#!html
<h3 style="margin:0;" id="checkout">checkout (co)</h3>
}}}

The checkout command is used to create a local copy of a svn subtree on the local computer.

The syntax used is ''svn co -r <revision> <remote-path> <local-path>'', if -r <revision> is omitted, the HEAD revision is assumed, which is also the newest one, if <local-path> is omitted the last remote folder will be used as <local-path>.

This will create a folder orxonox-trunk with the contents of the trunk
{{{
svn co https://svn.orxonox.net/game/code/trunk orxonox-trunk
}}}

This will create a folder called test, with the content of the test branch at revision 200.
{{{
svn co -r 200 https://svn.orxonox.net/game/code/branches/test
}}}
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="update">update (up)</h3>
}}}
Update is closely related to checkout, as it also download - or updates - the svn tree. while checkout is normally only used once, update is used all the time. 

The syntax is ''svn up <local-path>'', if <local-path> is omitted the current update will be allied to the current directory.

This will update the current folder including subfolders.
{{{
svn up
}}}

This will update the trunk and the test-branch.
{{{
svn up trunk branches/test
}}}

Updates may cause conflicts if the remote and local file has been changed in the same place. to resolve a conflict see [wiki:SVN#resolved here].
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="commit">commit (ci)</h3>
}}}
Sometimes also called checkin, does the opposite of checkout or update, it upload changes made to the local copy to the server. 

The syntax is ''svn ci -m <commit message> <local-path>'', if <local-path> is omitted, the current directory is assumed, if -m <commit message> is ommited, an editor will pop up where you can (and should) write a meaningful commit message.

This will checkin the current directory including subfolders with the comment "initial upload"
{{{
svn ci -m "initial upload"
}}}

A commit is only possible if the local version is up-to-date. If it isn't you will get an error, and the commit will fail. The solution then is to do an [wiki:SVN#update update].
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="add">add</h3>
}}}
Adding a new file to the local svn copy, that it gets uploaded with the next commit. 


The syntax is ''svn add <file>''

This will add the files myFile.cc and myFile.h in the folder myFolder to the svn
{{{
svn add myFolder/myFile.cc myFolder/myFile.h
}}}
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="remove">remove (rm)</h3>
}}}
Also called delete (del), which deletes an item from the svn tree. Please note that this also removes the file/folder from the local harddrive. 

The syntax is ''svn rm <file/folder>''.

This will remove the file myOldFile.cc from the svn tree
{{{
svn rm myOldFile.cc
}}}
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="move">move (mv)</h3>
}}}
Sometimes called rename (ren) - as a rename is the same as a move. The command simplifies the rearranging of files in the svn tree. 

The syntax is ''svn mv <source files> <target-folder>''

This will move the files myFile.cc and myFile.h to myFolder
{{{
svn mv myFile.cc myFile.h myFolder
}}}

This will rename the file myFiel.cc to myFile.cc - to correct a typo. Please note the mv and rename are the same command
{{{
svn ren myFiel.cc myfile.cc
}}}
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="copy">copy (cp)</h3>
}}}
A command which is rarely used on the local tree - why would someone need a file twice in the same tree? - but it is rather useful to create new branches. Though it is normally done by the supervisors, it can be done by the students.

The syntax is ''svn cp <source-tree> <target-tree>'' or ''svn cp <source-files> <target>''

This will create a new branch called test from the current version of the trunk
{{{
svn cp https://svn.orxonox.net/game/code/trunk https://svn.orxonox.net/game/code/branches/test
}}}
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="resolved">resolved</h3>
}}}
If a conflict arises - this normally happens if someone changes a file on the server (committed it) while you were doing changes in the same place. This command '''does not solve''' the conflict, but it removes the other unnecessary files. To resolve the conflict use a diff tool to look at and edit the different versions next to each other. On Tardis we suggest {{{meld}}}, which even allows three way comparisons.

The syntax is ''svn resolved <conflicting file>''

This will resolve the conflict in in myConflictFile.cc, and make the copy committable again.
{{{
svn resolved myConflictFile.cc
}}}
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="revert">revert</h3>
}}}
One of the major advantages of a version control system, is that you can always revert to a known saved state - in this case the last updated local revision. Revert removes all local changes and restores the file to a state prior editing, i.e discarding all local changes.

The syntax is ''svn revert <target>''.

This will discard all local changes made to myFile.cc
{{{
svn revert myFile.cc
}}}
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="diff">diff (di)</h3>
}}}
Another rarely used but very useful command. It shows the difference between the downloaded revision and the current state, which basically what will be uploaded at the next commit. It is also useful to check if all new files have been added to the svn tree - it happens very often, that there are two commits in short time, first the updates, then the new files. 

The syntax is ''svn di <local-path>'', if <local-path> is omitted, the current directory is assumed. 

This will show - print to the console - the current changes made to the revision
{{{
svn di .
}}}
{{{
#!html
<hr style="margin:0px;">
<br/>
<h3 style="margin:0;" id="merge">merge</h3>
}}}

For those of you, who are courageous enough to merge two branches, or adequate, here's a little description about merge:
The merge command takes the difference between two repositories (or revisions) and inserts the diff into a working copy.

You can for example use it like that: 
{{{
svn merge <remote-trunk> -rOLDREVISION:NEWREVISION <destination>
}}}


It is important to understand, that this command acts like a diff-patch combination. You could also type:
{{{
svn diff <remote-trunk> -rOLDREVISION:NEWREVISION > patch-file && cd <destination> && \
    patch -p0 < <path-to-patch-file>
}}}
}}}