OnlineHelp:Contents

You might prefer to follow this guide if you specifically need a quick outline to get started.

Introduction

As you can see, the user documentation for RapidSVN has just started. The first draft with the outline was created 2006-11-01 and it will grow in the weeks and months (and years!) to come.

Your help with the documentation is requested! If you want to proofread the texts or if you want to create whole sections of the documentation: just create an account and start working on the site.

In the past I had to disable the user account creation to the public after this was abused by wiki spammers who would come and insert invisible SPAM links in our pages (probably to get a better google pagerank). Hopefully this won't be that much of an issue anymore, since now a user has to verify her account.

Installation

Windows

  1. Download the installer package for windows operating system from here.
  2. Double click on it to start the installation process.
  3. Follow the steps that you see on the screen, you can leave the default options.
  4. You are done, now you need some SVN repository to start working!.

Mac OS/X

  1. Download the dmg package (RapidSVN-x.y.z.dmg) for Mac OS X operating system from here.
  2. Double click on dmg file to mount the disk image.
  3. Drag the RapidSVN.app file to your Applications folder.
  4. Go into the Application Folder and double click RapidSVN.app to start the program.
  5. You are done, now you need some SVN repository to start working!.

Linux/Unix

There appear to be pre-built RPM-format packages of RapidSVN for most major distros of Linux. Just Google to find the appropriate one.

If you're using Debian or Ubuntu, you can easily install RapidSVN by running "aptitude install rapidsvn" (Ubuntu users may need to use sudo) or by installing it from Synaptic.

For CentOS and RHEL there are excellent pre-built binaries including dependencies available from the RPMForge. The DAG Repository has further info: http://dag.wieers.com/rpm/FAQ.php#B.

Setting preferences

Programs

The 'Programs' tab must be filled with the paths pointing to the programs that perform Edit, Explore, Diff and Merge functions.

The suggested programs are:

Function Windows Linux Mac OS/X
Editor Scintilla/SciTE
Programmer's Notepad
notepad.exe		 Scintilla/SciTE

/usr/bin/xdg-open (to handle other file types)

 TextEdit
GVim
Explorer explorer.exe nautilus /usr/bin/open
Diff KDiff3 WinMerge KDiff3 Meld (to install Meld on ubuntu, aptitude install meld) KDiff3 DiffMerge
FileMerge (via opendiff) NOTE: Requires Mac OS X Developer Tools
Merge KDiff3 DiffMerge KDiff3 KDiff3 DiffMerge
DiffMerge Setup in Mac OS X

After installing the application in the Applications folder, copy the shell script from the disk image to /usr/bin/. Specify /usr/bin/diffmerge.sh in RapidSVN->Preferences->Programs->"Diff tool:". For "Program arguments" use "%2" "%1". %2 is the original file and %1 is the modified file. The quotes will properly encapsulate paths with spaces.

DiffMerge Setup for Use as Merge Tool

This is the commandline argument: 

/title1="Base" /title2="Mine" /title3="Theirs" /result="%4" "%1" "%3" "%2"
Meld Setup for Use as Merge Tool

This is the commandline argument: 

"%2" "%4" "%3"

User Interface

Basic Concepts

Tutorial, Part 1

Note: This tutorial was written to assist a user getting started with RapidSVN. It was not written to assist an administrator starting from the beginning.

RapidSVN has the notion of a server (a repository) and a client (a working copy). Both repositories and working copies can be bookmarked. By creating a bookmark, the user has quick access to either the working copy or repository in RapidSVN. The first thing a user should do is bookmark a repository.

Browse an existing repository (via a bookmark):

  1. Under the Bookmarks menu select Add Existing Repository...
  2. Type the URL (e.g. http://TagentServer/svn/RFID) and click OK

After bookmarking a repository the user can browse (but not view or edit) all the files on the server.

Next a user may want to work with a file in the repository; this is done by checking out a working copy. But RapidSVN does not do checkout at the file level. Instead, only directories can be checked out. The user could checkout the entire repository from the Repository menu but often times this is undesirable due to time and space requirements to checkout a large repository. So instead the user can checkout the parent directory of the file to be worked on.

Edit a file (via Checkout) and Checkin the changes (via Commit):

  1. Using the repository bookmark created in the prior step, browse to the parent directory (or higher) that contains the file to be worked with.
  2. In the Bookmark browser, right-mouse click the desired parent directory and select Checkout New Working Copy... from the context menu.
  3. The URL will already be filled out (make sure it’s just the directory and doesn’t contain the filename (a bug), if you don’t remove the filename you’ll get an error).
  4. Enter your local path in the “Destination Directory” and click OK. This will populate your hard disk with the files and create a bookmark.
  5. Browse the bookmark in RapidSVN to the file to be edited and double-click the file.
  6. After editing and saving the file, reactivate the RapidSVN window. The status for the file should now indicate “modified”.
  7. In the right-hand window, right-mouse click on the modified file and select Update... to update your file with any changes by other members of your team. If the status of the file remains “modified” it is safe to proceed to the commit step. If the file status shows “conflicted” you should resolve the conflicts before committing.
  8. In the right-hand window, right-mouse click on the modified file and select Commit...
  9. Enter a log message that briefly describes your changes and click OK.

Undo a local edit (via Revert):

  1. Make another change to the file we worked with in the prior section and save it.
  2. Switch back to RapidSVN and in the right-hand window, right-mouse click on the modified file and select Revert.
  3. Click OK to the Revert dialog and observe the changes made in Step 1 have been lost.

Add a file (via Add)

If you have progressed this far then you have bookmarked a repository and a working copy. If a file is added to a directory that already has an existing “working copy bookmark,” the file will appear in the right-hand window with a status of "unversioned".

  1. In the right-hand window, right-mouse click on the file to be added and select Add. (If a file was Added by mistake, use Revert to undo the Add)
  2. Right-mouse on the file in the prior step and select Commit....
  3. Enter a message in the log window and click OK.

Add a directory (via Add recursive)

  1. Create a new directory in the directory we have been working in.
  2. Add a file or two. You can even create a subdirectory with more files in it.
  3. Return to RapidSVN. In the right-hand window you will notice the new directory appears as "unversioned".
  4. Right-mouse on the new directory and select Add recursive.
  5. Right-mouse on the new directory again and select Commit....
  6. Enter a message in the log window and click OK.

The new directory and its contents have been added to the repository. Note: It is possible to add empty directories.

Add your project directory

Up to this point we have been working in an existing directory in the repository. One of the first things you will likely want to do is add your project directory. This can sometimes be tricky. For instance, you want to put your directory at the root of the repository but you don’t want to store the entire repository on your hard disk. There are a couple of ways to accomplish this:

Option 1: Add a directory via Import

  1. In the Bookmark browser, select the repository you want to add the directory to.
  2. From the Repository menu select Import....
  3. For the "Repository URL" make sure you specify the full path to the new directory. For example, if I wanted to add the Reader directory to the path //TagentServer/svn/RFID/ enter http://TagentServer/svn/RFID/Reader for the "Repository URL".
  4. Next enter your local path in the "Path" field. In this example we’ll use /Users/gerrior/Projects/RFID/Reader.
  5. Type something in the "Enter log message" field.
  6. Confirm "Recursive" and "Path type:" "Tree" are selected and click OK.

This will add your directory and all the files and directories in your project. Unfortunately doing an import doesn't checkout your files. Your files are in the repository but you can't start working with them. The directory on your drive remains untouched (it doesn't contain the hidden .svn directories). The next step is to checkout what you just imported.) (Entered enhancement request)

  1. Rename the directory you just imported (.e.g. \Reader to \Reader.orig). If you do not do this, you will receive the error "object of the same name already exists" when you perform the next step. Checkout does not allow you to overwrite existing files.
  2. In the Bookmark browser, right-mouse click the newly imported directory (e.g. \Reader) and select Checkout New Working Copy... from the context menu.
  3. The URL will already be filled out (make sure it's just the directory and doesn't contain the filename (a bug), if you don’t remove the filename you'll get an error).
  4. Enter your local path in the “Destination Directory” and click OK. This will populate your hard disk with the files and create a bookmark.

Option 2: Add a directory to the repository

  1. In the Bookmark browser, select the parent directory for the new directory. This can be the repository bookmark or a subdirectory.
  2. In the right-hand window, right-mouse in an empty row and select Make directory... F7.
  3. In the Bookmark browser select the new directory (you may need to refresh the view).
  4. Right-mouse and select Checkout New Working Copy... , specify the "Destination Directory" and click OK.
  5. Now you can add your files as we did previously. (You may need to select another bookmark and then select the new bookmark again in order for the files to appear. Refresh View doesn't work in this scenario. Bug 566)

Tutorial, Part 2

Checkout a Working Copy

If you are new to both Subversion and RapidSVN, probably the first thing you are trying to do is checkout a working copy of an existing repository.

  1. Click on the 'Repository' menu
  2. Click on the menu item 'Checkout.. (CTRL-O)', this will open the 'Checkout' dialog box
  3. Enter the URL of the Subversion repository in the 'URL Text box'
  4. Select a local directory for your sandbox (working copy)
  5. Click the 'OK' button

View an existing subversion sandbox (working copy) with RapidSVN

If you are new to RapidSVN, but have used Subversion, probably the first thing you want to do is view an existing Subversion sandbox with RapidSVN.

  1. Right click 'Bookmarks'
  2. Click 'Add Existing Working Copy'
  3. Browse for the root of the local copy
  4. Click the 'OK' button

Review your Changes

Update your Working Copy

When working on a project with a team, you'll want to update your working copy to receive any changes made by other developers on the project. The update command will bring your working copy into sync with the latest revision in the repository.

Copy/Branch/Tag/Move/Rename

Copy, Branch, Tag, Move, and Rename are all the same in that the selected file is copied to its new location. Then in some instances the source file is deleted.

To Copy, Branch, and Tag: Select the file in the repository then from the Modify menu select Copy... F5 and copy the file to a new directory or filename.

To Move: Select the file in the repository then from the Modify menu select Move... F6 and move the file to a new directory or filename.

To Rename: Select the file in the repository then from the Modify menu select Rename... F6 and change the filename.

The edit field in the dialog that appears for Copy, Move, and Rename works the same even though the wording is slightly different for each. You can specify a new filename, a new relative path, or a fully qualified path to name a few of the options. For example, given the path //TagentServer/svn/RFID/Reader/src/readme.txt some possible choices for the destination edit field include:

    readme.old <- Operation happens in same directory as source file.
    ../dst/ <- In the parent's dst directory move/copy the file.
    ../dst/readme2.txt <- In the parent's dst directory move/copy the file and rename it.
    http://TagentServer/svn/RFID/Reader/dst/readme.txt <- Example of fully qualified path.

Merging

Merging is combining the contents of one branch with another, or combining one branch with your trunk (main) version. This is accomplished via the Repository > Merge... option. An important thing to know about merging is that you merge the versions on your local machine, not on the remote repository.

In brief, the steps are as follows. Assuming you want to merge branch1 and branch2,

  1. Update your local copy of branch1 from the repository
  2. Update your local copy of branch2 from the repository
  3. Select Merge... from the Repository menu
  4. In the "First working copy or URL", enter the local address of branch1
  5. In the "Second working copy or URL", enter the local address of branch2
  6. Enter revisions in the two "Revision" boxes (see below).
  7. In "Destination path", enter the local address of the folder you'd like your merge to be created in
  8. Click OK
  9. Select the lkocation where your merge has been placed and Commit it to the remote repository (use Ctrl-M, the toolbar icon, or Modify > Commit).

If you are merging a branch with a trunk (main) version, you may wish to have "Second working copy or URL" and "Destination path" both be the path to your main version.

"Revision" cannot be left blank. You are also unable to type "head". If you wish to use your head (latest) version, you will need to type in its number. This can be discovered by selecting your remote repository in Bookmarks (you can't do this while the Merge dialog is open) and selecting "Log..." from the "Query" menu. Use the Revision number from the latest entry in the log (top of the list).

Delete

Delete (available from the context menu or from the Modify menu > Delete) will remove a file from both SVN and the local hard drive. The local file can be read-only or read-write.

RapidSVN will not let you delete modified files - files under revision control with changes that haven't been committed to the repository. The following error will appear: "Error while performing action: 'readme.txt' has local modifications". The "Force Removal" checkbox in the Delete dialog will override this probation and let you delete modified files.

If you try to delete a file not under SVN control the following error appears, "Error while performing action: 'readme.txt' is not under version control." The "Force Removal" checkbox in the Delete dialog will override this prohibition and let you delete files not under version control.

Advanced Tutorial

Export from the Repository

A local repository contains hidden .svn directories used by Subversion to manage the repository. The Export... command creates a local copy of the repository without the .svn directories.

To export from a repository:

  1. Click on Repository and choose Export...
  2. In the "URL" box, type the URL of the repository you wish to export. You don't have to export the whole respository, you can export individual files or directories if you wish.
  3. In The "Destination Directory", type the path to the location you wish to export to.
  4. Click OK

Create a new Repository

As of version 0.9.4, a repository can be created only with the command svnadmin. At the command line type svnadmin create /path/to/repository.

For more information about repository administration, refer to the Repository Administration chapter of the Version Control with Subversion book.

Tips

Troubleshooting

Getting support

A good place to ask questions about RapidSVN is the users' mailinglist at mailto:users@rapidsvn.tigris.org.

The mailinglist central is at http://rapidsvn.tigris.org/servlets/ProjectMailingListList. You can use this page to search for messages that may address your problem.

The RapidSVN project uses an issue tracker to manage bugs/defects or feature requests. The URL for the issue tracker is http://rapidsvn.tigris.org/servlets/ProjectIssues. Please ask your questions / report your problem first on the mailinglist to keep duplicate entries in the issue tracker at a minimum.

I've sized a file list heading to zero and can no longer see it

You can also reset all columns to their default widths and selections from the View->Columns->Reset Columns menu pick.

Appendix

Glossary

Index