Quick subversion tutorial

From Yade

ATTENTION! We have completely moved to Bazaar CVS on Launchpad. Please, read Quick Bazaar tutorial

Subversion is a revision control tool. It must be installed on your machine before you can use it. On debian/ubuntu, install the package subversion:

sudo apt-get install subversion

Getting latest revision from subversion

Download with read-only access

You can do it in one of three ways shown below:

svn checkout svn://svn.berlios.de/yade/trunk/

or this

svn checkout http://svn.berlios.de/svnroot/repos/yade/trunk

or this

svn checkout https://svn.berlios.de/svnroot/repos/yade/trunk

Which one of those above will work depends on your network and firewall configuration.

Also check out Installation page.

Download with read-write access

To have a read-write access you add svn+ to the download address:

svn checkout svn+ssh://svn.berlios.de/svnroot/repos/yade/trunk

But if your local account name differs from your berlios account name, you will need to use the command below. Putting it inside your ~/.bashrc or ~/.zshrc might be a good idea:

export SVN_SSH="ssh -l username"

You can also have a read-write access with the following command:

svn checkout https://developername@svn.berlios.de/svnroot/repos/yade/trunk

where developername is your own developer name. This command is usefull when you can't use ssh protocol.

Read-write access without password

SVN keeps nagging about passwords far too often, to solve this problem, you can upload your public key ~/.ssh/id_rsa.pub to username@shell.berlios.de:.ssh/authorized_keys to enable passwordless login. First generate your key, if you haven't a key yet:

ssh-keygen -q -f ~/.ssh/id_rsa -t dsa

Press enter to have a blank password. Then upload your file to remote host:

scp ~/.ssh/id_rsa.pub username@shell.berlios.de:.

Now login to your account on berlios to finish the configuration:

ssh username@shell.berlios.de
cat ~/id_rsa.pub >> ~/.ssh/authorized_keys
rm id_rsa.pub
chmod 644 ~/.ssh/authorized_keys

The last line, chmod 644 is especially important, it makes sure that nobody except you can read your public key. It is to ensure that your empty password is not a security problem, as long as you have a secure login password configured on work computer. To reach berlios without passoword someone will have to break into your own computer first. So never upload an id_rsa.pub from a computer that can be accessed by public.

Now you can enjoy a passwordless SVN access.

Working with subversion checkout

Check local diff, your changes

With subversion it is possible to check what modifications were done to the code. So if you have one version that works, and another that doesn't - subversion will show you the differences between them. This will only work with yade version downloaded from SVN. Without version from SVN it is possible to track changes with kompare, this method is described in the next section. The command below will show you all the files that you have modified. It can be invoked from any point in the yade directory tree, when invoked from trunk/ all modifications will be shown.

svn st -q

The flag -q instructs SVN to skip files that are not tracked by subversion. This command:

svn st

Will show all modifications and files that are not recognized by subversion. This can be sometimes useful when one wants to add new files into the repository.

It is sometimes useful to watch what modifications to the code were done, following command will do this:

svn diff | kompare -o -

With this method kompare will show only the differences, not the whole source code. If you don't like using kompare you can just do:

svn diff

Check diff between two trunks

You have two different copies of trunk/: one of them has something new. And another is working. And you want to merge them, but you need to see the differences between them. You can do:

diff --exclude=.svn -ru ./old/trunk ./new/trunk | kompare -o -

Check local diff with SVN-HEAD, other people's changes

To check how your local copy of yade relates to latest SVN snapshot (called SVN-HEAD) you can use -u flag, which instructs SVN to connect to the berlios server and compare both versions:

svn st -qu

If you want to see precise differences between your local copy and SVN-HEAD you can invoke:

svn diff -rHEAD | kompare -o -

Whether you want to use | kompare -o - to see the diff through kompare is up to you.

Check if svn up may have conflicts

If you just do svn up you sometimes may have conflicts, and need to resolve them later. Sometimes it is simpler to simulate an svn up command to see the potential conflicts before they happen:

svn merge --dry-run -r BASE:HEAD .

The --dry-run means: do nothing. Instead it will tell you where are possible conflicts for your update.

Update your local copy

After this check, you can decide to make an update of your local copy to the latest version on the server:

svn up

If the same file has been modified in the local copy and in the latest svn snapshot then subversion will inform you about the conflict, and you will have to investigate which file you prefer (or merge them together). Your conflicting files will not be deleted! they will be only renamed with *.merge added at the end of filename.

Adding new files

If you want to add new plug in files to SVN repository, you invoke this command:

svn add extra/screw/ScrewGen.cpp

Where the argument is your new file or whole directory. Remember to always add both .hpp and .cpp files. You can always verify with svn -st if all necessary files were added. Be careful with adding whole directories, because there is a fair chance that you will accidentally add a backup copy made by your text editor extra/screw/ScrewGen.cpp~, or some other unwanted files!

Committing your changes to repository

Important: all code that you are committing to yade SVN repository must be licensed on GPL. If you want to use different license for your code then don't commit it!

Now that some part of your work is done, you can commit your changes with this command:

svn commit

You will be asked to write some comments to your commit, try to be as descriptive as possible, and enumerate all new things you committed.

Going further with subversion

To see the list of available subversion commands type:

svn help

To see a help about a specific command, for example 'st' type:

svn help st

See also