Using kdesvn

kdesvn features
kdesvn understands following protocols for browsing repositories:
http 	 Standard web browser protocol.
https 	 Standard encrypted web browser protocol.
(k)svn+http 	 Standard web browser protocol. May be used to let automatic call kdesvn.
(k)svn+https 	 Standard encrypted web browser protocol. May be used to let automatic call kdesvn.
(k)svn+file 	 Local repository protocol. May be used to let automatic call kdesvn.
(k)svn 	 Subversion's own server protocol.
(k)svn+ssh 	 Subversion over ssh.
file 	 Direct repository access. kdesvn checks if a given path is a repository or a working copy and opens it in the right mode. For subversion file:///dir and /dir is not the same!
This list may be used for s given for command line, too.

Beginning with subversion and kdesvn
This section is mostly for beginners not familiar with subversion and explains how subversion and/or revision control systems (RCS) works.

Creating a working copy
Working copies MUST be accessible via local paths. Subversion does not know anything about pseudo file systems like smb:// or fish://. kdesvn translates some of them if possible (like system:/home) but it is not possible over a network.
First of all you must create a working copy of your repository. For that select Subversion General Checkout a repository . Inside the following dialog you must select the of the repository you want to use, ⪚, something like http://localhost/repos/myproject. Subfolders of a repository are possible, too, ⪚, http://localhost/repos/myproject/trunk or similar.
Select and/or create a local folder, where the working copy should reside.
Last but not least, the revision to checkout. Mostly that should be HEAD. This ensures that the last stored version is the referenced version.
After clicking on OK kdesvn will create your new working copy and (if the box was checked) opens it.
When you have opened a repository for browsing you may mark a folder and than select Subversion Repository Checkout current repository path and fill out the dialogs as described above. Then only the marked path will checked out.

Committing local changes
Mark the entry or entries you want to send and select # Subversion Working copy Commit
If you try to commit if no item is selected, kdesvn uses the top-most element of opened working copy, , the working copy path itself.
This operation is always recursive, means, if selecting a folder kdesvn always send all changed items below it. When you setup that you want to review all items before commit inside the following dialog all items kdesvn would send are listed. There you may unmark items you don't want to send. In that case kdesvn sends all items alone, , not recursive. Or you may select items not versioned for add and commit (if them are not marked to be ignored). So you may see if there are newer items you forgot.
Enter a log message what you're sending and hit OK and the transfer starts.

Update working copy
This brings you local working copy in sync with the repository. You may setup that kdesvn checks on opening a working copy for newer/modified items in repository. This runs in background and you may work meanwhile with kdesvn. When this is finished, items with newer versions or folders with items where newer items are below are marked.
To retrieve the changes, select Subversion Working copy Update to head . This will update to the most latest version. If you want to get a specific revision select Subversion Working copy Update to revision and select the revision you want in the following box.
If no item is selected, the update will done on whole opened working copy, otherwise only recursive on the selected items.

Adding and Deleting from working copy
Both operations requires two steps: First add or delete and then committing that changes to repository. Before you commit you may undone add or delete.

Add items
Adding items into a working copy may be done due three ways:
Select not versioned items and add them 	 Copy with or any other tool into working copy area. Go trough list, mark them and select Insert Subversion Working copy Add selected files/dirs . When you want adding new folders with all subitems select Insert Subversion Working copy Add selected files/dirs recursive .
Check and add recursive 	 You may check if there are somewhere in working copy unversioned items. After selecting Subversion Working copy Check for unversioned items a dialog appears where all not versioned items are listed. Hitting OK adds all marked items to working copy, items you don't want versioned you should unmark before.
Drag and drop 	 Mark in or any other compatible file browser items you want to add and drag them to kdesvn. You may drop them on folders inside the opened working copy and then kdesvn copy the dropped items to it and add the items.

Deleting items from working copy and unversion
Deleting items is always recursive. For example, when you delete a folder all subitems will be deleted, too. Mark what you want and select Subversion General Delete selected files/dirs menu item. Items will be unversioned and removed from disk.

Displaying logs
The log display may start with L when one or none item is marked in overview. Depending on your settings (see Subversion) kdesvn retrieves some log entries beginning on HEAD and displays them.

The log display dialog
On the left side you see the list of log entries retrieved by kdesvn. The log message is stripped-down to one line to fit. The full log message appears in the upper-right window when marking an entry. In the lower-right window you will see the list of changed files. These windows only appear if this list is fetched, depending on your settings.
With the buttons on the top you may select another range of logs to display.
This range is called without any pre-limit, so be careful when using this feature on large repositories.
The buttons on the bottom of the dialog always work on the item selected for log, not on the item selected in the list of changed files. So when you select Diff previous there, it makes the diff over all changed items in this revision if they are equivalent or below the subversion entry selected before for retrieving logs. Same for Diff revisions.
Annotate of course works only if item to log is a file.
On all list entries (both lists) you have context menu enabled for some extra operations. In left list this is Set version as left side of diff ( beginning revision) and Set version as right side of diff ( end or target of diff, in unified the part marked with a +++). If you selected these revisions them are marked with some small arrows.

Working on repositories
Simple repository browsing may be done within , or similar file browsers: Open a URL with protocol described in kdesvn features (the variants starting with k) and them will display the content. So simple operations like copy, move and delete may work. When appending a query ?rev=xxx the listing comes from a specific revision. Format of revision-query is described in Syntax for revisions, some more information about KIO::ksvn are in , KIO, kdesvn
All work except Copy may only done when browsing at revision HEAD.

Restoring deleted items
In subversion restoring deleted items is a copy operation of item at specific revision. So when you plan restoring view repository at revision before item was deleted. Select Subversion Repository Select browse revision and enter the wanted revision. Now kdesvn displays the content at this term. Mark the entry you want to restore, select C Subversion General Copy . Inside the following dialog the target is always at HEAD revision, the source is at revision you selected for browsing. Fill in the path and click OK and copy starts. After successful copy switch browsing back to HEAD revision and the restored item should appear.

Importing folders
Due restrictions of subversion itself only folders, not single files, may imported.

With drag and drop
Mark in any compatible file manager the folder you want to import and drag it to the folder entry in kdesvn where you want to import it.

Select folder to import with directory-browser
Mark the folder where you want to import a new folder. Then select Subversion General Import folders into current and select your wanted folder.

Other Operations

Merge
Open repository or working copy, mark item you want to merge and select Subversion General Merge . Enter in the following dialog the values wanted. If opened from repository, source 1 and source 2 are filled, when open from within working copy, target is filled with current selected item. The handling of this parameter is a little bit different between using the internal diff of subversion or an external merge-program like . The target must ALWAYS a local folder or file. You may switch between external or internal merge with the check box Use external merge.

Internal merge
The meaning is exactly like from within subversion's own command line tool. When source1 and source2 are equal, start and endrevision must different. If sources aren't equal, start-revision is assigned to source1 and end-revision to source2. The target MUST be a working copy otherwise subversion will send an error message.
The check boxes have following meanings:
Recursive 	 Do all operations recursive when working with folders.
Handle unrelated as related items 	 If set, unrelated items will be diffed as if they were related. Otherwise subversion will remove one side and add it on other side again.
Force delete on modified/unversioned items 	 If not set and merge would require deletion of an modified or unversioned item the subversion merge fails. Otherwise this items will be deleted.
Just dry run without modifications 	 If set, subversion sends only notifications what it would do but doesn't modify the working copy.

Using external program for merge
See Diff & Merge for details how to setup the external merge tool. kdesvn generates the command line as described there. Before it does following:
Assign start-revision as revision to source 1 and end-revision to source 2. Then checks if them are different (path and/or revision). If yes, it is a three-way merge otherwise a simple merge from source to target. If source 2 is left empty it is a simple merge, too.
Make an export into temporary folder. If it is a simple merge only source 1 at start-revision, otherwise both sources with their revisions. If item is a file and not a folder then get the content at a specific revision.
Generate the call to your external merge program as you setup in Settings. The error output will displayed in log window so you may see what is going wrong (if something is gone wrong).
In difference to internal merge target may a flat folder/file not under version control because external tools do not care about it.
If recursive is not set, the export is done as a flat export. Be care: when doing this with working copies externals will not be exported.

Resolving conflicts
kdesvn itself hasn't a module for resolving conflicts but you may use external software from within kdesvn. In Conflict resolver program is a description how to setup up this application.
When marking an item with status set to conflicted (you'll see a red cross in listview on such items) you may select Subversion Working copy Resolve conflict . or from within context menu Resolve conflict (only on conflicted items) kdesvn now starts the program you setup (or the default one). After finish this job you should mark item as resolved (Subversion Working copy Mark resolved) otherwise you will not able to commit your changes.

Properties used by kdesvn for configuration

Bugtracker integration
The TortoiseSVN project designed a nice property system for integrating bugtracker into subversion GUI. The current version of kdesvn does not support extra fields in commit box (will follow later) and doesn't understand all but following properties:

Bugtracker Integration Properties
Property	Description	Example
bugtraq:url	Holds the to bugtracker. It has to contain the %BUGID% marker.	https://bugs.kde.org/show_bug.cgi?id=%BUGID%

bugtraq:logregex	Contains one or two regular expressions, separated by a newline. If only one expression is set, then the bare bug ID's must be matched in the groups of the regex string. If two expressions are set, then the first expression is used to find a string which relates to the bug ID but may contain more than just the bug ID (⪚ Issue #123 or resolves issue 123). The second expression is then used to extract the bare bug ID from the string extracted with the first expression. Please keep care about not wanted spaces after the regular expression and don't forget the brackets around the number description.	Single (usable with TRAC): #(\d+) Now all numbers like #190 will parsed and translated to an in log output. Two expressions: [Ii]ssue #?(\d+)(,? ?#(\d+))* (\d+) Remember Keep care of white spaces after the (\d+)! This is one of the most common errors causing these expressions do not match!
On local opened repositories ( file:// protocol) and on working copies these properties will searched upward from opened folder until found or the subversion top level is reached. On repositories opened via network (all except file:// protocol) it is only searched on opened folder itself.
Support for multiple sets of these properties may follow later, (⪚, in subfolder extra values for other tracker ) but in most cases evaluating single tracker links should be enough.

The revision tree
The revision tree try to display the whole history of an item so user may get a better feeling about the history of an item. It has to scan the complete log of the repository 'cause it requires some information subversion does not (and I think will not) give. Because this produces a lot of traffic the revision tree uses always the internal log cache.

Requirements
The revision tree is generated via dot. So for a working revision tree the graphviz package must installed.

Internal log cache
kdesvn may use an internal log cache for some operations. Mostly it is used for the revision tree but when viewing simplified log in offline mode, too. The caches are organized as SQLite databases stored in $HOME/.sqvnqt/logcache. Every numbered file is a storage for a different repository.
The databases may get large! So you may disable automatic update of log cache in settings.
You may simply remove a database, than no cached log will be given back for that repository (and no revision tree!) but when you do not disable automatic filling the cache on next open this repository or an associated working copy of it the cache will be refilled again.

Offline mode
kdesvn may work without network access, you can switch off the network access for kdesvn. This may be useful when working without network like on notebooks. In such cases kdesvn always gets the logs from the internal cache. This log is reduced to base functions due to technical reasons, so the cached log may (but not must) differ from real log. Differ means that it will not display all copy operations even Log follows node changes is set.

Log cache and revision tree
The revision tree will only use the log cache because otherwise it must get always the logs again. It will not refresh the log cache (but this may changed in later releases).

Meaning of icon overlays
Entries may be marked with overlayed icons when not in normal state.
Locked 	 This entry is locked. In last column the owner of lock is listed. You may setup if kdesvn should check for locked items in repository, too. But be careful: depending of the kind of the server this may take a long time!
Needs locked 	 This entry must be locked before edit and commit. Until you'll not set a lock subversion keeps it read-only.
Updates 	 This entry or - if a folder - an entry below has newer version in repository.
Modified 	 This entry or - if a folder - an entry below was changed on local disc.
overlay added 	 This entry is locally added to subversion but not yet committed.
overlay deleted 	 This entry is locally deleted from subversion but hasn't yet been committed.
overlay deleted 	 This entry (or entry below if folder) got conflicts to resolve with last update.

kdesvn and passwords
kdesvn/subversion is able to save passwords. Saving passwords is always a security risk, but may let a graphical frontend more usable.

Not saving passwords
Most secure way, but sometimes unhandy with GUIs like kdesvn. In particular the background processes of kdesvn would always ask for a password in case the repository has restricted access for reading operations like update and status. The same for commit and so on. So if you are not saving passwords you should disable Start check for updates when open a working copy and so on.

Saving passwords in
Secured password storage used by a lot of programs like and . If you are saving passwords and mostly using kdesvn you should use this. Keep care that the encrypted storage isn't a high-secure storage. Details see documentation.

Saving to subversion's own password storage
This is not recommended 'cause the passwords are stored as clear text! Not believing? Take a look into the files in ~/.subversion/auth/svn.simple. You should only use this if you are frequently using other clients than kdesvn like rapidsvn or esvn or the original svn command line client. If you're using the command line client mostly for checkouts or updates which do not require a password and kdesvn for commit/move/copy you should use instead.

Internal password cache
You may activate an internal password cache which will hold passwords as long kdesvn is running in memory. So you must not enter a password twice even if you didn't save it in wallet.

Special case svn+ssh
When using subversion via svn+ssh password storage may done via ssh and ssh-agent. For this you must have ssh access to the remote machine and repository. When want to store something you should use the public key authentication of ssh, not the password authentication. (In fact ssh prefer the public key authentication). For this you must put your public ssh-key on the target, ⪚, the repository system. SSH passwords will never be handled by subversion passwords storage or or internal password cache.
If you don't want asked for the password of your SSH key you can use the ssh-agent, with selecting the menu Subversion Add ssh identities to ssh-agent you may store your SSH-key password for your current session so no further entering of your password is needed.