Please read the [[documentation:dev:scm:svn|SVN documentation]] to learn about SVN structure and the RSBAC list of repositories. You will need them for SVK, and SVN is closely tied to SVK.
===== What is SVK =====
SVK is available from http://svk.elixus.org/
It is a "distributed" Version Control tool.
It uses FSFS from SVN as it's sublayer. From a 10,000 feet view, SVK allows to checkout any SVN/CVS/Perforce/Git repository to your local machine and commit/checkout remotely //and// locally, then submit the changes when you are done. So, it allows to work offline. And it allows to work on your very own branches, for testing.
From a more technical point of view, SVK is like a repository on your local machine where you have two kinds of sub-repositories: Mirrors of SVN/CVS/... or local branches.
Here's a diagram showing how this little world works: [[http://perlcabal.org/~autrijus/svk-overview.png|SVK overview diagram.]]
===== Getting started, mirroring a repository =====
So let's initialise where to keep the local repository (the depot):
# svk depotmap --init
You can choose where to put or change the location of this depot with the relocate command:
# svk depotmap --relocate /path/to/somewhere
You will probably want to make a depot dedicated to RSBAC, so that you can mess with it without destroying other depots.
# svk depotmap rsbac /home/youruser/.svk/rsbac
(or anywhere else)
We will now mirrors the RSBAC SVN repositories:
//For anonymous mirroring//
# svk mirror svn://rsbac.org/rsbac-2.6 /rsbac/rsbac-2.6
# svk mirror svn://rsbac.org/rsbac-admin /rsbac/rsbac-admin
//For developers with write access//
# svn+ssh://rsbac.org/daten/subversion/rsbac-2.6 /rsbac/rsbac-2.6
# svn+ssh://rsbac.org/daten/subversion/rsbac-2.4 /rsbac/rsbac-2.4
# svn+ssh://rsbac.org/daten/subversion/rsbac-admin /rsbac/rsbac-admin
And synchronise it:
# svk sync -a
When committing or using this path directly, changes will affect the real SVN repository directly, much like using SVN would do.
Whenever you want to checkout this path, just do it. You can delete the files afterwards and check them out again, or you can simply update then. There will be no ".svn" directories or the like. SVK is just flexible.
===== Making a local branch, working offline =====
To work offline or just do your stuff without modifying the official repository directly, you've to create a local branch. Once you are done with your work you can commit it to the mirrored path, or create a patch if you have no write access (and send it to us :-))
Basically the repository already lives on your harddrive so just make this branch whenever you are really offline, or have no write access.
So, create a directory for the local branches, and create your branch (example
for the 2.6 RSBAC kernel). With SVK, the convention is to use the ''%%//%%'' path as
local depot. (It is automatically created the first time you use SVK)
# svk cp /rsbac/rsbac-2.6 //rsbac/rsbac-2.6
You can now checkout "%%//%%rsbac/rsbac-2.6", modify, commit (using "svk commit -S",
please **never** ever use svn on svk repositories, it would corrupt it.)
Once done, you have to merge back your local branch to the mirrored path (this
will commit your changes to the real SVN repository). This is called pushing.
However, for safety concerns, using ''smerge'' and specifying path by hand is
prefered. Note that the ''push'' command is simply a wrapper around ''smerge''.
# svk smerge -I //rsbac/rsbac-2.6 /rsbac/rsbac-2.6
//note: IT IS EASY TO SCREW UP WITH PUSH. ONLY USE PUSH IF YOU KNOW WHAT YOU ARE DOING.//
Equivalent push command:
(from your /rsbac/rsbac-2.6 checkout)
# svk push
(from anywhere)
# svk push /rsbac/rsbac-2.6
You can also get the changes from the mirror to update your local branch with
the upstream mirrored repository:
//note: AGAIN, IT IS EASY TO SCREW UP WITH PULL. ONLY USE PULL IF YOU KNOW WHAT YOU ARE DOING.//
//To be safe, always specify the path to pull to instead of invoking pull from the checkout//
(from anywhere)
# svk pull /rsbac/rsbac-2.6
(from your /rsbac/rsbac-2.6 checkout)
# svk pull
===== Signing =====
If you are a RSBAC developper, please do not forget to sign every commit made to the mirrored path!
Simply add "-S" to every ''commit'', ''smerge'', ''merge'', or other commit-like command.
# svk commit -S myfile.c
# svk smerge -S ...
# svk import -S ...
You can verify the signatures with the verify command
# svk verify -r REVISION
===== Versionning, diffs, etc. =====
There are several ways to specify an SVK version (called changeset, revision).
Let's take a look at the log:
# svk log -r HEAD /rsbac/rsbac-2.6
----------------------------------------------------------------------
r105 (orig r104): kang | 2006-06-01 15:22:12 +0200
tagging 1.2.7 release
----------------------------------------------------------------------
r105 is your local SVK revision number. you can use it anytime, but its only **yours**.
r104 is SVN's revision number. If you want to talk about this very change to someone, //PLEASE// give this revision number.
r104 is also often seen as r104@ in SVK notation. The ''@'' tell you that we
are talking about the SVN repository's revision number.
In short, to see a diff from this change on **your** system:
# svk diff -r105:104
To see a diff on this change, for anyone you contact (also works for you):
# svk diff -r105@:104@
When diffing a file on your filesystem against the SVK (mirrored or local) repository latest's version, you can simply do:
# svk diff -rBASE:HEAD myfile
It will return the changes in the repository, that are not yet in your local file.
The reverse, to see what's in your file and not in the repository, is quite easy:
# svk diff myfile
You can also specify revisions per date:
# svk log -r {2005-09-22}
===== Ressources =====
For more information, see the [[http://svk.elixus.org|SVK website]], or the very good [[http://svkbook.elixus.org/|SVK book]].
You may want to use [[documentation:dev:scm:svk:script|this small script]] to create/sync svk for you, avoiding most errors, and brainless ;)