Crib Sheet for SVN GUI ============== K. Bromund 2007/01/29 21:44 EST Here's a crib sheet for getting set up with a GUI client for SVN. For Windows, TortoiseSVN is recommended. If you need a GUI that works on UNIX-like systems, as well as Windows, SmartSVN is an OK solution, but may be slow on some systems. Installation: ~~~~~~~~~ For UNIX: UNIX-like systems on the UCB/SSL network can use the version which is installed on /disks/socware: source /disks/socware/toolchain/current/setup To start SmartSVN, type smartsvn.sh on the command line. If you don't have access to the UCB/SSL /disks/socware, you can download and install SmartSVN from: http://www.syntevo.com/smartsvn (download the version that includes Java if you are not sure that Java is installed on your machine) For Windows: You can choose between SmartSVN and TortoiseSVN. * TortoiseSVN is made for Windows. It is free, full-featured and well-integrated into the Windows Explorer. * SmartSVN is java-based, and works on many platforms. The basic features you will need are free, but some convenient features require a professional license (~$60). Also, there is no way to set auto-properties with SmartSVN, so you will have set the keyword properties manually on every new file you create (or someone else will have to clean up after you...) TortoiseSVN ----------------- Downloading and installing TortoiseSVN is a quick simple operation using the Windows-style installer available at: http://tortoisesvn.net/downloads Choose the win32 or x64 version of the installer, depending on the type of machine you have. [You can determine if you have a 32- or 64- bit machine by running idl and looking at the message it presents at startup] TortoiseSVN requires an external SSH client program to access the THEMIS SVN repository. PuTTY is the recommended client to use. PuTTY is easly to install and there is no problem with installing it alongside an existing Secure Shell Client from ssh.org. You will want to download and install PuTTY, PuTTYgen, and Pageant. The simplest thing is to download the entire PuTTy suite from: http://www.chiark.greenend.org.uk/~sgtatham/putty/download.html Scroll down to where it says: 'A Windows-style installer (x86 only) for everything except PuTTYtel' and download and execute the Windows-style installer for the latest release version (currently 0.58) putty-0.58-installer.exe SmartSVN -------------- Download and install SmartSVN: http://www.syntevo.com/smartsvn (download the version that includes Java if you are not sure that Java is installed on your machine) SmartSVN includes its own OpenSSH client, but you will have to generate an OpenSSH format private key. The easiest way to generate the key in the proper format is to use PuTTYgen. You can install PuTTYgen following the directions given in the TortoiseSVN section above. SSH setup: ~~~~~~~~~ Windows: ------------ PuTTY >>>> You will need an SSH key pair to access the THEMIS SVN repository. PuTTYgen can generate a key pair and save it in the necessary formats. If you already have an exiting key pair, you can import it into PuTTYgen and then export it in the proper formats required by PuTTY or SmartSVN. Start PuTTYgen: From the Start menu, choose Programs->PuTTY->PuTTYgen To generate a new key pair: Click Generate (keep default SSH-2 RSA setting for type of key under Parameters) Move the mouse around. Enter a key comment: e.g. kenb-lepkrblap-win2000 (this identifies me, my machine, and my OS) Enter and confirm a passphrase, and then press 'Save private key'. You can save the keys where you like, but you might want to create a new directory named SSH under the default location, to save the .PKK key file in: C:\Documents and Settings\username\Application Data\SSH Copy the key in the window where it says 'Public key for pasting into OpenSSH authorized_keys file' and copy it into an email to: jimm@ssl.berkeley.edu or pcruce@igpp.ucla.edu. We will use your public key to authorize access to the SVN repository. For SmartSVN: You will also need to create an OpenSSH version of your private key for use with SmartSVN: In the menu bar, select Conversions->Export OpenSSH key Save the key (e.g. in the SSH folder) for use when setting up SmartSVN, in the instructions below. Secure Shell Client from ssh.org >>>>>>>>>>>>>>>>>>>>>>>>> You can use the Secure Shell Client application from ssh.org to generate a key pair for use with SmartSVN, but you will need to convert your keys to OpenSSH format to use them. The menu path to the wizard is: Edit-->Settings-->Global Settings (branch)-->User Authorization (branch) \ -->Keys (leaf) --> Generate New... (button) The key pair created by the wizard was stored under: C:\Documents and Settings\davin\Application Data\SSH\UserKeys\ To make it work with SmartSVN, you will have to convert your *private key* to OpenSSH format. One way to do this is to copy the file to a UNIX machine running OpenSSH and run: ssh-keygen -i -f Private_key > Private_key_openssh I haven't tested the ssh.org client with TortoiseSVN: it is simple enough to just install PuTTY. Setup: ~~~~~ TortoiseSVN: -------------- First, we configure and test a connection to the THEMIS SVN server, using your SSH key pair created above. In order to do this, we open the program "PuTTY" and create a new session like this: Session->HostName: ambrosia.ssl.berkeley.edu Session->Protocol: SSH Session->Saved Sessions: thmsvn Connection->Data->Auto-login username: thmsvn Connection->SSH->Prefered SSH Protocol version: 2 Connection->SSH->Auth->Private Key file for auth: $PATH$\mykey.PKK (replace $PATH$ with real path to the mykey.PKK file) Then go back to Session tab and hit "save" button. You will see "thmsvn" in the list of available connections. Next click "open" and you should see a telnet window. You may be prompted for your passphrase. If everything is ok, you won't be prompted for a password in the telnet window. You will know that you are successfully connected to the SVN server if you see the following text in the terminal: ( success ( 1 2 ( ANONYMOUS EXTERNAL ) ( edit-pipeline svndiff1 absent-entries ) ) ) Register your private key with Pageant: Start Pageant Click on the Pageant icon (bottom right) Add Key -- Browse to find your private key. Open Enter your passphrase. Press OK Close the Pageant Key List window. You will need to restart Pageant and register your key each time you boot your computer. Next, you need to set up TortoiseSVN to use the PuTTY as its SSH client. Right click on the Windows Exporer desktop, and select TortoiseSVN->Settings from the context menu. In the TortoiseSVN Setting popup, select Network in the list on the left. Where it says 'SSH Client,' click 'browse' to find the location of TortoisePlink on your system, probably: C:\Program Files\TortoiseSVN\bin\TortoisePlink.exe Press OK Finally, it is highly recommended to set up auto-properties so that new files you create will have the proper properties set. In the TortoiseSVN Settings window, select General in the list on the left. Where it says 'Subversion configuration file:' click 'Edit' Edit the file as follows: At the end of the [miscellany] section, uncomment the line to enable auto-props: enable-auto-props = yes In the [auto-props] section at the end of the file, add the following lines: *.c = svn:eol-style=native;svn:keywords=Author Date Rev URL Id *.f = svn:eol-style=native;svn:keywords=Author Date Rev URL Id *.pro = svn:eol-style=native;svn:keywords=Author Date Rev URL Id *.cpp = svn:eol-style=native;svn:keywords=Author Date Rev URL Id *.h = svn:eol-style=native;svn:keywords=Author Date Rev URL Id *.dsp = svn:eol-style=CRLF *.dsw = svn:eol-style=CRLF *.sh = svn:eol-style=native;svn:executable;svn:keywords=Author Date Rev URL Id *.txt = svn:eol-style=native;svn:keywords=Author Date Rev URL Id *.png = svn:mime-type=image/png *.jpg = svn:mime-type=image/jpeg Makefile = svn:eol-style=native;svn:keywords=Author Date Rev URL Id makefile = svn:eol-style=native;svn:keywords=Author Date Rev URL Id These lines in your configuration will ensure that keyword substitution will work properly in files that you add to the SVN repository. Now you are ready to check out a working copy of the THEMIS software. Create a directory where you want the IDL code to live e.g. Desktop/themis_socware open the directory in Explorer, and right click to get the context menu select 'SVN Checkout ...' In the dialog box, enter the 'URL of the repository' svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/idl_socware/trunk Keep the other default settings and press OK If a security Alert pops up, press Yes to trust that you believe you are connecting to the real ambrosia (lucky you!) SmartSVN -------------- You when you first run SmartSVN you will be using the Professional license or using the 'Foundation' version, which lacks a few of the features from the Professional version. You can purchase or get a demo license from http://www.syntevo.com/smartsvn/purchase.asp Once you've done this, you will be presented with a new dialog. Choose: Check out a new project Since this is the first time you are accessing the SOC repository, need to set up SmartSVN to know how to access to the repository. Click on "Manage..." In the "Repository Profiles" window: Click on "Add..." Click on "Enter SVN URL..." Enter svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos Click "Next..." Select "public/private-key-authentication" Enter the path to the OpenSSH private key file you exported from PuTTYgen or converted from ssh.com. (see above) Click "Next..." Enter a name if you like SOCREPOS Click "Finish" Select the new SVN-Location Click "OK" In "Check Out Project" Click "Next >" Click the "+" next to idl_socware Select "trunk" under idl_socware Click "Next >" Enter location of local directory for your local copy, e.g.: /home/yourname/idl_socware Click "Next >" Keep the selection "Check out a working copy and manage as project" Click "Next >" Click "Finish" It may take a couple of minutes to load all the files (SmartSVN is a bit slow for checkouts involving large numbers of files) You should now have a workspace which includes at least 3 subdirectories: external ssl_general themis To Update Your Workspace With the Latest Software ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ At any time you can update your workspace: any changes made by others to the repository will be brought over to your workspace. Here's how to do that, depending on which client you are using. TortoiseSVN ----------- In windows explorer, right click on the directory or file you want to update, and select 'SVN Update' from the context menu. SmartSVN -------- In the SmartSVN Directories window, Right click the top level of your workspace, and select 'Update...' Keep the setting 'Update to: HEAD' (i.e. the latest revision), and 'Recurse into subdirectories' and press 'OK'. You will be asked to enter your passphrase. Just press OK if you are using an empty passphrase. If you are using the 'Professional' version, you can use SmartSVN to see if there are changes to be brought over, before you update: select 'Refresh Remote State' To Add new files or Commit changes to the SVN repository ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ TortoiseSVN ------------ Right click your new file or folder, and select TortoiseSVN->Add... from the context menu Verify that you want to add all the files which are checked in the dialog box, and Press OK. If you have added files or made changes to existing files in your working copy, you must commit these changes to the repository when you are ready to share them: Right click on the file or folder, and select 'SVN Commit...' You will be prompted for a commit message. SmartSVN -------- Right click on the file or folder icon, and select 'Add' from the context window. You will have the option to set 'Recurse into Subdirectories' to commit changes to an entire directory sub-tree at once. To commit changes to the the repository, Right click the file or folder icon and select 'Commit' You can tell SmartSVN whether you want to 'recurse into Subdirectories', enter a Commit Message, and click Next. Other SVN features ~~~~~~~~~~~~~~~~~~ Please review the command line crib sheet for an overview of all the features available with SVN. You will find analogs of all the command line commands in the menus of the GUI applications. Both TortoiseSVN and SmartSVN include conprehensive online help.