Login | Register
My pages Projects Community openCollabNet
Home News Screenshots Installation Roadmap Building Hacking Issues

Installing SCPlugin

These instructions describe, from an end user's perspective, how to install SCPlugin, enabling you to perform Subversion operations from the Mac OS X Finder.

SCPlugin is currently (as of this writing) at version 0.7.1, which is to say it's not done yet. All the usual caveats apply: there are certainly things which we know do not work; there may be things that cause you problems. We don't think so &emdash; we use it ourselves, every day &emdash; but you should be cautious.

If you want to build SCPlugin from source, see Building.

Requirements

  • You must be running Mac OS 10.3.9 (Panther) or some version of 10.4 or 10.5. Both PowerPC and Intel architectures are supported (this is a Universal Binary).
  • You may no longer need be familiar with the Subversion command line tools. SCPlugin now supports all the basic tasks of Subversion. You'll need to be familiar with basic terms and concepts of Subversion, in order to understand the examples. The Subversion project and the Subversion Book are excellent resources.
  • If have been using any form of Subversion 1.3, then you should also clear out your svn.simple auth cache. Directions are below. You should also be careful not to use any existing Subversion 1.3 tools in the same working copy as SCPlugin (or any Subversion 1.4 tool). The 1.4 tools will silently convert the working copy to 1.4 format; subsequently, the 1.3 tools will no longer be able to use it.

Installation

  1. Mount (double-click) the Disk Image file (*.dmg).
  2. Launch (double-click) the installation package.
  3. Log out and back in
  4. If you're upgrading from Subversion 1.3 to 1.4 (either now, or recently), then you should probably clear out the svn.simple auth cache, in order to benefit from the improved security of Subversion 1.4. The "auth cache" is where Subversion stores your user name and password. Before Subversion 1.4, a technique was used that is not very secure. With version 1.4, the technique is much more secure. However, any old, pre-1.4 auth cache you may have is still stored in the less-secure way. You should clear the old data, so that Subversion prompts you for the information once again. This time, it will be stored in the more-secure way. To do this:
    1. Open a Terminal window.
    2. cd ~/.subversion/auth/svn.simple
    3. You may remove all the files in this directory, with

      rm *

      , which will mean that all your repositories will go through the password prompt on next access. If you want to be selective, you can search the individual files to find the one you want. For example, if you wanted to find which file contains your auth cache for the SCPlugin repository, you would use

      grep scplugin *

      This will produce something like

      7ff6be4af26d10df46cef00a09db986b:<http://scplugin.tigris.org:80> CollabNet Subversion Repository

      Then, use

      rm 7ff6be4af26d10df46cef00a09db986b

      or similar.

Verifying your installation

In the Finder, summon up up the contextual menu in whichever way you like best:
  • Control-click
  • Right-click (if you have a multi-button mouse or Mighty Mouse)
  • Hold two fingers on the track pad and click the button (on the latest PowerBooks and MacBook Pros, if you've turned it on)
  • If you're on Leopard, slide down to the "More" submenu.
The resulting menu should have some Subversion commands.

Uninstalling SCPlugin

If you want to remove the product, you need to
  • Remove these 
    /Library/Contextual Menu Items/SCFinderPlugin.plugin
/Library/Receipts/SCPlugin.pkg
  • Log out or restart

Using SCFinderPlugin

Note: Due to some problems in Release 0.7, some of the features of SCPlugin are not available until the first time you summon up the contextual menu, and sometimes you have to use the "Refresh Icons" command to make everything look right. So, if these other experiments don't seem to be working quite right, summon the contextual menu and select Subversion > Refresh Icons. Things should be better.

Check out a Subversion working copy.

You'll need to know the URL for a Subversion repository. You can use any Subversion repository URL that begins with "http", "https", or "svn". You can use "svn+ssh" URLs if you have arranged SSH to allow you access without a password prompt.
Check out with SCPlugin
As of version 0.7.1, you no longer need to do a command-line checkout first. Just go ahead with the "Check out" menu item, and fill in your credentials. Subversion saves off your user name and password for future operations (you can just leave the credentials set to "Anonymous" and your cached credentials will be sued). Neither the command line nor SCPlugin will need to ask for them again, unless you change your password, or want to access the repository as a different user.
Note: Subversion 1.4 and later store this information in the Mac OS Keychain, a very secure way to store this sensitive information. Subversion 1.3 and earlier use a different technique which is not as secure. This is one of the big reasons we advise you to use Subversion 1.4 or later.
To perform a checkout using SCPlugin, follow these steps:
  1. Using the Finder, browse to the location where you want the new files to appear &emdash; or, just use the Desktop
  2. Summon up the contextual menu, and pick Subversion > Checkout
  3. In the Repository URL field of the resulting dialog, enter the URL, s uch as http://scplugin.tigris.org/svn/scplugin/trunk
  4. Use the Checkout to Local Path field to designate where the files should go:
    • If you leave it as it is when it first appears, all the files will go into your current directory (which is probably not what you want)
    • In the most common case, you'll want to create a new directory whose name is the same as the name of the project being checked out ("scplugin", in this example). You can simply add that to the value preloaded in the field, so it reads /Users/you/Desktop/scplugin
    • The other controls may be left a their default settings; see the Subversion documentation for what they mean
    • Click Checkout, and watch the progress dialog display, which is similar to what you saw at the command line before.
  5. If you've never checked out files from this particular repository before, provide your user name and password. Otherwise, you can leave it set to "Anonymous," and the credentials cached from your previous access will be used.

Browse around your file system

Browse around your file system, using the ordinary Finder windows, clicking one folders and so forth. When you're browsing in a Subversion working copy, files and directories will bear "badges" that tell you what Subversion knows about them. See the Screenshots page for some examples.

Update a file or tree

Select some versioned file in your Subversion working copy. Summon up the contextual menu. Notice that the main menu has a Subversion Update item, and also an Update item in the Subversion submenu. (If it doesn't, you're probably not working on a file controlled by Subversion. Look around for some file or directory with a green check-mark badge.) These two commands are completely identical; they're duplicated only for your convenience. Pick either of these commands. A progress dialog will appear. It probably won't show any real progress, since you just checked this working copy out, only the status message "Unchanged".

Update something for real

In order to see an update that actually does something, you can first delete some file inside your versioned directory.
  1. Find a directory with a green check mark (a "versioned directory").
  2. Open it
  3. Find some file with a green check mark (a "versioned file")
  4. Drag that file to the Trash
  5. In the white space where there are no files shown, summon the contextual menu and pick either of the Update commands.
  6. The progress window appears again, and reports that it Restored the file you had trashed
$Id: installation.html 587 2008-02-14 01:26:11Z jackrepenning $