Subversion Howto
From Wzdftpd
Here's a quick howto on subversion: how to use it, the features, the common commands, etc.
Basics
To install the client .. use your distro's tools ! (ex: apt-get install subversion)
Before we begin, you have to understand the basics: unlike CVS, where all informations are stored in one directory, subversion shows 3 logical directories: trunk (the current development branch), branches and tags. CVS users must remember that, because if you extract the svn root directory, you will end with a copy of every possible branch and tag of the repository !
Subversion uses url-like strings, here is the general form: protocol://user@hostname:/repository/dir
Subversion on Linux and *BSD
I'll explain here only the command-line client, but there are many graphical interfaces available: esvn, RapidSVN, and many others (see the links on subversion page).
Remember that svn is self documented, you can have some usefull help using svn help commandname.
Test !
Subversion allows you to make tests, so use this feature !
You an use the list command to list files in a particular directory inside the repository, even if you haven't checked out files:
~$ svn list svn+ssh://svn@svn.cpe.fr:/svn/wzdftpd Password: branches/ tags/ trunk/
Initial Checkout
If you want the 'normal' svn branch, you will need to extract the trunk dir:
~/SVN$ svn co svn+ssh://svn@svn.cpe.fr:/svn/wzdftpd/trunk Password: A trunk/Permissions.ReadMeFirst A trunk/m4 ... A trunk/install-sh U trunk Checked out revision 1001.
The directory will be named 'trunk', but you are free to rename it after the initial checkout.
If you want a particular release, just extract the correct directory in the tags/ subdir (remember you can list releases using the list command) ex:
~/SVN$ svn co svn+ssh://svn@svn.cpe.fr:/svn/wzdftpd/tags/rel-0-5-3
Check if updates are available (and for developpers: see if there will be conflicts before commit)
ALERT: For CVS users: you must NOT use the update command to check for update and do the update at the same time ! This is a bad habit, and will lead to conflicts. In svn the two steps are different.
In subversion the status<code> command is quite clear and show only modified files (locally modified, unless you specify the <code>-u argument).
The status -u command will show the files changed on repository, and the action needed to update them on your local version. This can help you, by predicting conflicts.
~/trunk$ svn status -u
* 997 visual/libwzd_core.def
Status against revision: 1001
Here the * shows that a new version (1001) is available in the repository, and that the local version of the file is 997.
ALERT: Never commit your changes if the version on the repository has changed !
Update
The update command will bring working copy up-to-date with the repository.
~/trunk$ svn up U visual/libwzd_core.def Updated to revision 1001.
The first letter reports the action taken on file: U for Update, D for Deleted, U for updated, C for conflict and G for merged.
If you made some local changes, svn will try to merge them wih the changes on repository when possible (and will report a G if ok). If the automatic merge is not possible, then you have a conflict (C) and you must resolve it locally (see section: Resolving conflicts).
Adding files / repositories (developers)
Simply use the add command:
~/wzdftpd$ svn add file1 dir1
Unlike CVS, files are added locally (you don't need to be connected to add files), until you commit.
ALERT: CVS users: default behaviour for adding a directory is recursive !
Reverting local changes (developers)
svn offers a more elegant way than the usual (horrible) remove file/update again methode from CVS, using the revert command:
~/wzdftpd$ svn revert ChangeLog Reverted 'ChangeLog'
Deleting files (developpers)
To remove files from the repository, use the delete command.
ALERT: the delete command also removes the local file if it exists, so be carefull for your files !
Commit (developers)
Before you commit, you have to review your modifications locally:
~/wzdftpd$ svn diff | less
You also have to check if the repository was not changed since your last update using the svn status -u command. If you do not, and cause conflicts on the server, be warned that the maintainer will insult you (or worse, if you live not far from him).
ALERT: you also have to check that your current version builds successfully before even thinking of a commit !
You can then commit your changes:
~/wzdftpd$ svn commit
This will open your favorite editor (the default is vim). Explain your changes here (this can be detailed if you want, but remember that changes should also include a line in the ChangeLog files). When you close te editor, the commit is done:
~/wzdftpd$ svn commit Sending ChangeLog Sending src/wzd.cfg.sample.in Sending src/wzd_main.c Transmitting file data ... Committed revision 1002.
Resolving conflicts
Suppose you run svn update and have a conflict:
$ svn update U INSTALL G README C ChangeLog Updated to revision 1001.
The G code shows that subversion has resolved one conflict automatically by merging your changes and the remote changes on your local version. However, the file marked with C contains conflicts and needs to be changed manually. Subversion will place 3 additional files: file.mine, file.rOLDREV and file.rNEWREV
At this point, svn will not allow you to commit the files until the 3 temporary files are removed.
If you get a conflict, you need to do one of three things:
- Merge the conflicted text “by hand” (by examining and editing the conflict markers within the file).
- Copy one of the temporary files on top of your working file.
- Run svn revert filename to throw away all of your local changes.
Merging conflicts by hand can be quite intimidating the first time you attempt it, but with a little practice, it can become easy. In the conflicting file you will find markers like the following:
common line to both version <<<<<<< .mine The local change ======= The remote change >>>>>>> .r998 common line to both version
Edit the file, and remove the markers, for ex:
common line to both version Both local and remote changes common line to both version
Once you've resolved the conflict, you need to let Subversion know by running svn resolved. This removes the three temporary files and Subversion no longer considers the file to be in a state of conflict.
$ svn resolved ChangeLog Resolved conflicted state of 'ChangeLog'
After resolving the conflict, you can commit your changes normally.
Merging changes from trunk to a stable branch
Sometimes you need to backport a bugfix to a stable branch. The usual way was to create a diff and apply it using patch. However, since the trunk is changing faster than the stable branch, you'll often get conflicts. svn offers the same feature, except the the algorithm used to merge the code is far more intelligent.
Go into the working directory for the stable branch, and look at the patch from the trunk using the svn diff command:
~/wzdftpd-0.7$ svn diff -r 1379:1380 svn+ssh://svn.cpe.fr/svn/wzdftpd/trunk | less
If everything is ok, you can merge the patch directly on your working copy:
~/wzdftpd-0.7$ svn merge -r 1379:1380 svn+ssh://svn.cpe.fr/svn/wzdftpd/trunk U libwzd-auth/wzd_tls.c
After, you just have to check the files and commit.
