Difference between revisions of "Subversion"

Revision as of 08:00, 23 May 2006

This page introduce the use of subversion. If you're only intent is to get the files from subversion you should start with HOWTO: Obtain the library source from subversion which help you in getting the file and compiling CEGUI. This page dive deeper in the use of subversion as a standard user as well as a developer of the library itself. This page presents the use of subversion with the command line tool available for windows, mac and linux.

First of all here is some urls to get started with subersion usage :

• Repository url: https://svn.sourceforge.net/svnroot/crayzedsgui/
  • CEGUI library latest development files url: https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk
  • CEGUI Layout Editor latest version url: https://svn.sourceforge.net/svnroot/crayzedsgui/CELayoutEditor/trunk
  • Repository browser: http://svn.sourceforge.net/viewcvs.cgi/crayzedsgui/cegui_mk2/

Glossary

• Repository: That's the place storing all the files and revisions. It's hosted by sourceforge. In Subversion respository are identified using urls.
• Working Copy: A working copy is a local view of part of the repository. You can retrieve a local copy using the checkout command. A working copy contains the file as well as a lot of additional information. The size of the working copy is more than twice the size of the file of the project.
• Branches: Subversion does not provides branches concept, however it's possible to organize the project in several branches. The current development branch is known as trunk. The other branches are stored in a folder named .... branches. So a branch in Subversion is just a folder in branches.
• Tags: Subversion does not provides tags concept. Like branches tags are only subfolder of the tags folder.
• Revision: Snapshot of the tree at a given time. Each modification on the tree create a new revision.

Layout of the repository

At the moment there is two project in the CEGUI repository. The CEGUI library and the layout editor. The repository is organised the following

• cegui_mk2 : The cegui library itself
  • trunk : The main development stream
  • branches : Branches (features testing are prefix with pre-)
  • tags: Release of the CEGUI library
• CELayoutEditor : The editor files
  • trunk : The main development stream
  • branches : Branches
  • tags: Release of the editor

Getting a working copy of the project

In order to get the files from the sourceforge server one can use two command. Both command retrieves the files, however, the second command does not allow later use of subversion to update and maintain up to date local copy. If you plan to get the sources, create your library, install it, and remove them the second solution is the best for you.

svn checkout url [dest_dir] 
svn co url [dest_dir]

or

svn export url [dest_dir]

Using each of these command you will get the latest version of any file with url as root tree. You can get files at a particular revision using an additional parameter:

svn checkout/export [-r number] url [dest_dir]. It usefull to test older version. There is no named revision in subversion but it's easy to create tags which provides the same features. 

Updating your working copy

You'are now having a working copy by checking out a version of the project. You can keep it in sync with the repository at sourceforge using in any folder of your working copy. Only the current folder will be updated.

svn update 
svn up 

Getting history of modifications

In order to get a kind of changelog you can use subversion. Each modification of the repository comes with a text message explaining the last modification. You can get the history of any file or directory of your working copy using:

svn log [url]  (remote repository) 
svn log [path] (working copy)

Making change to your working copy

There is several change that can be made on subversion repository : adding, removing, renamming and modifying files, adding, removing and renamming directory. A standard work session consists in the following operation.

1. Update your working copy
2. Make your change
3. commit your change

This section focus on the second step of a work session. Files and directory are not handled automatically by subversion you must first explain to subversion that those file must be manage d. This is done using the add command:

svn add source.cpp // Add source.cpp to your local subversion copy 
svn add subdir  // Add subdir to your local subversion copy as well as all file contained in the repository itself 

One of the improvement of subversion compared to CVS is it's ability to remove file as well as folder this done by the rm or delete command

svn del source.cpp 

Finally you can rename file or directory using the mv command. This command does not allow mass moving like the standard mv command of unix system. rename is an alias of this command.

svn mv source dest 

You can use any text editor to edit your files. Subversion will do its best to send on the network only the change you've made to your working copy.

Must talk about loking facilities here

Branching, Tagging, Merging

In subversion a branch or a tag is just a folder in the corresponding folders. In order to create a branch one needs to use the copy operation. Copying a complete tree in subversion is cheap. In order to create a branch or tag use the following operation :

svn copy url_source url_dest 

I suggest using url of the repository directly. In order to create a branch of CEGUI use :

svn copy https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/trunk https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/branches/v0-5

To create a tag use :

svn copy https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/branches/v0-5 https://svn.sourceforge.net/svnroot/crayzedsgui/cegui_mk2/tags/v0-5-0 

A final notes on TAG. Nothing prevents someone to make changes on a tag. It's up to the developer to do changes only on trunk and branches.

If you have fixed a lot of bug in a subsystem or want to apply some of the change made to trunk to a specific branch you have to merge. Merging requires a working copy.

svn merge url_from url_to working_copy_path

Merging need some improvement Need to add some information on conflict

Properties

Subversion allows one to attach meta information to any file and folder in the repository. Those information are called properties. The table bellow list most interesting properties:

You can also defines your own properties for whatever use you might need them. When one adds a file to subversion it must add the svn:eol-style property to the value native for all text file. It can be made automatically using autoprops facilities of svn.

In order to manipulate properties you can use

svn propset name value url/file 
svn proplist url/file
svn propget name url/file 
svn propdel url/file
svn propedit name url/file

Pitfalls

Configuring subversion

External Links

• Subversion home (to get the software)
• Subversion book (to learn a lot more than what you read in this page)
• TortoiseSVN (Win32 client, a must)