| Tutorial Series | Getting Started |
| Previous | None |
| What's Next | n/a |
| Further Reading | n/a |
Contents |
This is a quick KDE-specific introduction for using subversion to access files and software in KDE's repositories. For comprehensive coverage of Subversion we recommend reading the book "Version Control with Subversion".
In order to use the KDE Subversion repository, you will need two things:
Note: For anonymous read-only access use protocol "svn", no "yourname@" and server "anonsvn.kde.org" instead below.
Installing Subversion: instructions on installing the client are not presented here. Refer to your system installation instructions to find out how you can install Subversion. You will need version 1.1 at least. If you are compiling from sources and want to access the KDE repository by https (and not by svn+ssh), you will need SSL and ZLIB supports, so you will need the --with-ssl --with-zlib options.
Alternatively, you can install one of the many graphical clients out there. This tutorial is intended for people using the svn program only, referring to tasks accomplished with the usual cvs program.
Getting an account: if you had a CVS account before, it has been migrated to the new Subversion client. If you didn't, refer to the corresponding tutorial how to get one.
Note: if you have lost your CVS password, there are simple ways to retrieve it. Use cvspwd.c or cvs-unscramble (Perl).
svn.kde.org/home/kde
That's the address of the KDE Subversion repository. The repository is served by HTTPS or SVN+SSH protocol, which means your password is secure against third-party eavesdropping.
The SSL certificate md5 fingerprint for the repositories:
F6BF EDE2 D016 D1B2 4F18 742E 2C8F B7EF
The SSL certificate sha1 fingerprint for the repositories:
e1:e6:41:96:3c:eb:ae:78:e2:73:0d:a2:32:2f:6b:21:13:bf:3d:0f
For people using svn+ssh, here's the fingerprint of the server's RSA key:
86:f3:66:06:20:74:81:d0:1b:b4:2f:25:03:f7:8e:fb
The repository is organised in main directories:
You can explore the repository structure at http://websvn.kde.org/
The /trunk top-level subdirectory is where the main development for KDE occurs. What you will find here is what will become the next KDE release, and its associated programs. Here you will also find the www module, which contains webpages for KDE's site and related ones.
/trunk is further subdivided into these sub-directories:
This directory contains the official releases of the programs maintained and developed in the KDE repository. Each individual application has a subdirectory here. Inside it, you will find the release numbers.
For instance, the KDE 3.4.0 code can be found under /tags/KDE/3.4.0/.
This directory contains the branch versions of the applications after a major release.
Most KDE applications adhere to the philosphy that new features (as well as new user-visible strings) are added only to the next release cycle — the one that lives in /trunk/. However, bugfixes are applied to all applications, even after release.
In order to do that, a branch is created at the moment of the release, indicating the state of the files at that time. Bugfixes are then checked in to those files. Those branches are the ones in /branches/.
For instance, the KDE 3.4.x branch can be found under /branches/KDE/3.4/
The subdirectories you will find inside /branches are the application subdirs, like akregator/, amarok/, arts/, k3b/, etc. You will also find a KDE/ subdir, containing the official KDE releases since time immemorial.
One special subdir is found in /branches: work/. This subdir contains the so-called "work branches", that is, branches containing features being worked on, sometimes highly experimental. Multi-application work branches always are checked in to /branches/work/, but single-application branches may be found in each application's subdir. That is a decision left to the developers.
In order to check out something with Subversion, you use the checkout subcommand.
WARNING: If you checkout trunk/KDE/ or branches/KDE/foo/ you will download complete kde-i18n!
Suppose you wanted to check out only KDevelop from the KDE repository. You would do:
CVS command:
cvs -d :pserver:yourname@cvs.kde.org:/home/kde login cvs -d :pserver:yourname@cvs.kde.org:/home/kde checkout kdevelop
Subversion command:
CVS users currently using ssh access, should use protocol svn+ssh, CVS users currently using password access, should use protocol https in the following.
svn checkout <protocol>://<username>@svn.kde.org/home/kde/trunk/KDE/kdevelop
In order to update, you use the update subcommand.
This is no different from CVS: you change into your checked out copy and issue a svn update (or, shorter, svn up) command.
To know which local files you had modified, in CVS most people did
cvs up
and looked at the files with M, this does not work with svn so you have to do
svn status
to know the status of the files.
Just like in CVS, committing to the Subversion repository is accomplished with the commit or checkin (ci for short) subcommands.
CVS command:
cvs commit # or cvs ci # or cvs ci filename.cpp
Subversion command:
svn commit # or svn ci # or svn ci filename.cpp
This way, svn will launch the editor specified in $SVN_EDITOR for you to compose the commit message. If you prefer, you can give svn the -m oprtion with your full message:
svn ci -m "Updating protocol to conform to HTTP/1.1"
Subversion stores ignored files per directory. To edit the ignored files of the directory you are currently in, do
svn propedit svn:ignore .
that will launch your editor, write there the names of the files you want to ignore, one file per line. Once you are done, do a commit so the ignored list file gets updated on the server.
A lot of files were ignored in CVS with help from global ignore list which is not supported yet by SVN. You can wait for svn 1.3 or you need to add the ignore list to the [miscellany] group in your ~/.subversion/config (all in one line):
global-ignores = *.o *.lo *.la .*.rej *.rej .*~ *~ .#* #*# .DS_Store *.moc *.moc.cc *.moc.cpp config.log config.status config.cache *.gmo .deps .libs SunWS_cache *.lo *.la *.rpo *.la.closure *_la_closure.cpp *_la_closure.cc *_la_closure.cxx *.all_cc.cc *.all_cpp.cpp *.all_C.C *.all_cxx.cxx *_meta_unload.cc *_meta_unload.h *_meta_unload.cpp *_meta_unload.C *_meta_unload.cxx index.cache.bz2 .memdump Makefile.rules.in Makefile.calls.in Makefile.rules Makefile.calls autom4te.cache *.kidl
Unlike CVS, Subversion doesn't generate a revision number for each file modified. Instead, the full repository is versioned, as a whole. This way, a given revision number represents the state the repository was on a given date. In other words, a revision number is like a timestamp (in fact, the Subversion server uses this fact to search for dates in the repository faster).
So, for instance, when you check out the KDE repository, Subversion will tell you the following:
Updated to revision 403821.
This means that the latest revision available at the time of the operation was 403821. If you make a modification and commit, Subversion will update the server-side revision and will inform you of it. Like CVS, only the committed files will be updated: you will need run cvs up to update the rest of the files.
If you want to retrieve a specific revision of a file, you can use the -r switch. Besides the revision number itself, -r accepts a number of other possibilities:
The following illustrates the evolution of the keywords:
Those keywords are useful to retrieve logs and diffs for commits to the repository.
If you want to see the difference between your working copy and BASE, you can run:
svn diff
This is a very fast operation, since Subversion keeps a local copy of BASE. It doesn't need a network connection to accomplish this operation.
If you want to see the difference between your local copy and the latest available on the server, you will run:
svn diff -r HEAD
If you want to see what has changed in the repository since you've last updated, you can use:
svn diff -r BASE:HEAD
If you want to see the last change to a file before BASE, you can use:
svn diff -r PREV:BASE # or svn diff -r PREV:COMMITTED
That is also valid for the svn log command.
It can happen you would like to include a copy of a subdirectory from another place, but just for convenience, not for developing the code in there. Of course it should be updated automatically whenever the original changes. Subversion can help you. You need to edit the property svn:external of the directory the subdirectory should be added to. So for the current directory you use
svn propedit svn:externals .
and then enter lines of the form
libkhalkhi svn://anonsvn.kde.org/home/kde/trunk/playground/pim/khalkhi
Updating will now fetch /trunk/playground/pim/khalkhi into the subdirectoy libkhalkhi.
| Warning |
|---|
| Beware that you cannot commit changes you did to the local copy of the external subdirectory, it is just a readonly copy. |
You use svn://anonsvn.kde.org and not another protocol, because anonsvn.kde.org is accessible to everyone. Using https: or svn+ssh: would only work for users of that protocol. There are still some small disadvantage with anonsvn.kde.org: It is not always in synchronization with svn.kde.org, so updates in the original branch may take a while to appear on anonsvn.kde.org. And some strict firewalls are blocking the svn: protocol.
A special case in KDE 3 is the subdirectory admin, containing the KDE 3 build utilities. It is linked in to the top directory in all modules, and maintained in /branches/KDE/3.5/kde-common. For admin the KDE subversion server is configured to allow readonly access for everyone, so if you see
admin https://svn.kde.org/home/kde/branches/KDE/3.5/kde-common/admin
there is no need to change this.
See the KDE wiki for more information about subversion in KDE
KDE TechBase 