Page locked

This page is currently locked for editing by another user. You have to wait until this user finishes editing or the lock expires.
Currently locked by: 47.128.112.225
Lock expires at: 2024-05-07 21:24 (8 min)
This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
======How to use version control (and why)======

[[:Version control]] is a way to develop software in a scalable way. Even if you are the only person working on a project, it enables you to write code with more confidence, as you know you have every change tracked - no more wondering what you did which broke everything, as you can find out easily. You can also tag points in development for retrieval later on - it's a good idea to do this before working on big structural changes which could cause instability while you work on them.

Version control can be also be used in order to share development between groups of people, up to hundreds of developers. It takes care of merging all the changes together, which often worries people new to version control, but it generally works well. If it finds a confusing case (normally where two developers have changed the same line of code) it asks you to confirm what it's doing. 

It won't do all this magically though. Some usage patterns need to be followed by developers to make sure that they don't tread on each others toes.

=====Revision control usage pattern=====

This usage pattern is common to all revision control systems, languages and types of project. You avoid causing other people problems and get the most out of version control if you make it part of your daily programming routine in this way. 

The general idea is that code lives on a remote server, and you keep a local copy of the source on your hard drive. You edit files and compile as normal then 'commit' your changes to the remote server. You also need to periodically update your code to get changes that other people have made. If someone has changed a file you have also changed and you try to commit it, the revision control system will ask you to update it first.

The smaller the changes, and the more frequently you commit code, the better. This is an example day's work:

  * First thing, update to get the latest code from the server
  * Build the new code, check it works
  * Start working on a new feature as normal, edit - compile - test...
  * Finish working on the new feature
  * Update and test the latest code on your machine with your new feature
  * Commit your new code with a message explaining what has been added
  * Start working on the next feature

And so on. You only have to be strict about updating when there are other people actively working. The messages are important - they only need to be short one liners, but they need to explain why you changed what you did - but there is no need to explain what the changes were (you can tell this from the code, so it would be redundant information).

You can also deal with more complex sequences of events:
 
  * Start working on a new feature
  * While doing this, you find a bug in another part of the code, and fix it
  * Update and test the latest code on your machine
  * Commit only the files you changed for the fix
  * Finish working on the new feature
  * Update and test the latest code on your machine
  * Commit the new feature

The key point is that everyone is trying to make sure the version of the code on the server works as much of the time as possible. It's not a massive problem if the central version is broken, but it should be a priority to fix it, as it will hold people up from working.

If you discover a problem with the current central version, send an email around to all the people working on it, as they should avoid updating until it's been fixed.

=====SVN Basics=====

Firstly install svn using your favorite package manager, or get it from here: [[http://subversion.tigris.org/]].

This guide is written for the commandline version of svn, and heavily biased towards linux. If you prefer buttons to press, read through this document as the concepts are the same, and then have a look at [[http://tortoisesvn.tigris.org/|Tortoise SVN]] or [[http://subclipse.tigris.org/|SubClipse]] if you use Eclipse or [[http://www.visualsvn.com/|VisualSVN]] if you use VisualStudio.

Firstly svn likes to know what editor you like to use so it can launch it to add comments for your code commits. Put this environment variable in your .bashrc (set to your editor of your choice, of course):

<code>export EDITOR=vi</code>

Or do the equivalent in windows [TODO].

====Getting the code====

Firstly go to the directory where you want to keep your code and run:

<code>svn co --username=yourlogin https://svn.lirec.eu lirec</code>
Replace "yourlogin" with your lirec [[http://trac.lirec.eu/|trac website]] login. The username is required so svn knows who changed what. Read-only anonymous access is also available.

This will populate a directory called lirec with all the code. This is called your working copy.


====Make some changes====

I've added an example project in svn for you to play with and break without fear. I've laid this out so that the project contains it's own directories called trunk, tags and branches. The code is contained in the trunk directory, the tags and branches are used later to store other versions of the code for this project. I'd recommend this structure for other projects. Look in lirec/example-project/trunk/example-app/ and edit the impressive application you'll find there. When you've saved run:

<code>svn commit</code>

This will pop up the editor you specified earlier. Add a nice informative message, save the file, and close the editor. If all is well, your change is now sent to the svn server. If, as sometimes happens to me, you realise at this point that you've forgotten something, close the editor without saving - svn will then ask you if you want to abort the commit.

If the editor popping up is annoying for you, then you can also specify the message like this on the command line:
<code>svn commit -m "your message"</code>

====Adding files====

<code>svn add filename</code>
Will add individual files to the repository, or recursively add files in a directory.

====Adding directories and moving files====

<code>svn mkdir mydirectory</code>
Will make a new empty directory registered with svn.

<code>svn mv /path/to/file /another/path/to/file</code>
Will move or rename a file.

====Updating====

<code>svn update</code>

This will merge everyone's changes (if any have been made) into your working directory, and print out the status of the files it merges. If there is a conflict (where someone has changed the same line you have) it will put a 'C' next to the filename, eg on the command line:

<code> 
$ svn update
C    GraphNode.cpp
Updated to revision 150.
$
</code>

If you have a look at this file, it will indicate the line affected in the following form:

<code>
<<<<<<< .mine
void GraphNode::ProcessChildren_I_Changed_This(unsigned int bufsize)
=======
void GraphNode::ProcessChildren_I_Changed_This_Too!(unsigned int bufsize)
>>>>>>> .r150
{
	for(vector<GraphNode*>::iterator i=m_ChildNodes.begin(); 
		i!=m_ChildNodes.end(); ++i)
	{
		if (*i!=NULL)
		{
			(*i)->Process(bufsize);
		}
	}
}
</code>

You can then choose which line to use, save and commit the change.

====Diffing====

It's often really useful to check where your copy of the code is different in comparison to the one on the server. This allows you to see what you've changed since you last committed code, and is really helpful when you need reassuring that you've changed what you think you've changed.

<code>svn diff</code>

This will diff the entire sourcecode, and print out a list of changes it found. You can also specify individual files to diff too. There are utilities which read the output of this command and display it graphically if it's helpful, but you don't generally need them for small changes.

======More Information======

  * "Version Control with Subversion" A complete online book > http://svnbook.red-bean.com/