Very Basic Subversion (SVN) Crib Sheet ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 0. Introduction ------------------- 0.1 Scope This is a crib sheet for working with the THEMIS software using the SVN command line interface. It is written in UNIX style, but the same SVN commands can be used from the WINDOWS cmd window (only the path separators and environment will be different). 0.2 Requirements SVN and SSH must be installed on your system. Details of installation are beyond the scope of this document, as they vary from system to system. Please consult with your system administrator, if necessary. The WINDOWS SVN command line interface is available for download from http://subversion.tigris.org/files/documents/15/35379/svn-1.4.2-setup.exe A suitable SSH client on Windows is PuTTY. PuTTYgen and Pageant should be installed along with PuTTY. 1. Getting Started ----------------------- 1.0 Basic SSH setup Generate an SSH key pair (which consists of a public key and a private key): > ssh-keygen -t rsa You will be prompted to enter a passphrase for your private key. Enter a passphrase to make your key pair secure. You may want to consider using an ssh agent, described in the Other Commands section, to avoid being prompted for a password when using SVN commands. Alternatively, you may choose to use an empty passphrase for your key--you won't be prompted for a password when you use SVN commands--but guard your private key well: anyone who obtains a copy of your private key file can access any machine where your public key is authorized. If you choose the default location for your key, your public key will be saved in .ssh/id_rsa.pub Email your public key to jimm@ssl.berkeley.edu or pcruce@igpp.ucla.edu. We will use your public key to authorize access to the SVN repository. 1.1 Setup 1.1.1 Environment To get set up (on most machines at SSL): > source /disks/socware/toolchain/current/setup If this does not work for you, try running svn --version to see if your sysadmin already has svn installed. The setup script does two things which you can easily do for yourself: 1) Set your path to point to the location where SVN is installed on your system (this may already be done for you by default). 2) Set the SOCREPOS environment variable as a shortcut to the location of the SOC Subversion repository (where the THEMIS software repository lives) : setenv SOCREPOS svn+ssh://thmsvn@ambrosia/repos or for bash: export SOCREPOS; SOCREPOS=svn+ssh://thmsvn@ambrosia/repos I'll be using this environment variable as a shorthand for the repository URL in the following notes. for READ ONLY access (at SSL -- no requirement for SSH!), you can set setenv SOCREPOS file:///disks/socware/thmsvn/repos 1.1.2 Subversion configuration file Run svn --version This will create a .subversion directory in your home directory. [On Windows, this will be a Subversion folder, most likely in the Application Data directory within your profile directory] Edit the .subversion/config file: 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. Keywords are discussed more fully below. 1.2 Checkout Your Own Workspace To check out a working copy of the THEMIS software: > svn checkout $SOCREPOS/idl_socware/trunk idl_socware To check out a working copy of just the THEMIS-specific IDL code: > svn checkout $SOCREPOS/thmsoc/trunk/idl/themis/ themis 2. Working with SVN ---------------------------- 2.1 Commands you can use within your working copy SVN has commands to add, move, delete, and copy files, as well as set properties on files within your working copy. Note that action scheduled by these commands does not affect the repository until you commit them. To schedule a new file or directory to be placed under version control: > svn add file_name Each file should have the following keywords included (the SVN keywords are similar to CVS an SCCS keywords, but SCCS keywords have a completely different format). $LastChangedBy$ $LastChangedDate$ $LastChangedRevision$ $URL$ The keywords will get substituted with the proper values automatically by SVN when you commit your file to SVN. For example, the above might be substitued with: $LastChangedBy: kenb-mac $ $LastChangedDate: 2006-12-20 16:14:32 -0500 (Wed, 20 Dec 2006) $ $LastChangedRevision: 139 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/doc/thm_cribsheet_svn_cmd.txt $ For IDL files, let's add a VERSION heading after the HISTORY heading in the auto-documentation area, so that the version info shows up in the IDL documentation: ;+ ; NAME: ; SYNTAX: ; PURPOSE: ; INPUT: ; OUTPUT: ; KEYWORDS: ; HISTORY: ; VERSION: ; $LastChangedBy$ ; $LastChangedDate$ ; $LastChangedRevision$ ; $URL$ ;- In order for SVN to make the keyword substitutions, you must set the svn:keywords property on each file. If you configure your .subversion/config file as recommended in section 1.1.2 before committing your file to SVN, this step will be unnecessary: they svn:keywords will be set automatically by SVN. If you need to do it manually, here's how to do that on the command line: > svn propset svn:keywords "Author Date Rev URL Id" To check if the svn:keywords property is set correctly: > svn propget svn:keywords To make a duplicate of a file: new file has same history as original file up to time of copy: > svn copy file_name new_file_name to move a file or directory which is under version control: > svn move file_name new_file_name to remove a file from the repository: > svn delete file_name To see at a glance which files have changed, been added, deleted, or are not under version control: > svn status To see detailed list of changes to all or specified files in your working copy > svn diff [path_name ...] 2.2 Commit and Update To commit local changes to files (including adds, moves and deletes scheduled with the above commands) to the repository: > svn commit [--file logfile] [-m "commit message"] [path_name] For the commit log comment: use --file logfile to take the log entry from a file, or the -m to enter the log entry on the command line. If --file or -m are omitted, svn will allow you to enter a log entry by starting up vi by default, unless you have specified a different editor by setting the SVN_EDITOR environment variable. e.g. > setenv SVN_EDITOR dtedit If SVN_EDITOR is not set, it will also check the VISUAL and/or EDITOR environment variables, which are used by other UNIX programs (e.g. cvs). Your commit will be blocked if someone else has committed changes to files that you have changed in your working copy. To see a status report which indicates if anyone has committed any changes to the files that you have in your working copy: > svn status -u To update your working copy with changes committed by others to the repository: > svn update To update /disks/socware/idl with the changes you committed: ssh thmsw@ambrosia cd idl svn update 2.3 Conflicts You will be prevented from committing a file if there is a conflict between your edits and edits someone else has committed to the repository. To resolve the conflict, edit the file to resolve conflict and remove conflict markers (<<<<<<, =======, and >>>>>>) You can use the filename.mine, filename.rOLDREV and filename.rNEWREV to help understand the difference between the conflicted file and your orginal edits, your pristine copy before your edits, and the new revision which someone else put in the repository, respectivey. When you (an the person with whom you had the conflict) are satisfied that you have resolved the conflict, run: > svn resolved filename and then SVN will allow you to commit your file. Some commands that might help in determining the source of a conflict: To find out who committed changes, and see their commit comments: > svn log filename To see which lines were changed (i.e. annotate lines by user and version number): > svn blame filename 3. Other Commands --------------------------- Other commands that may occasionally be useful: 3.1 Import If you have a directory full of things that you want to import into SVN, you can check out a working copy, move your stuff into the working copy to the appropriate place, 'svn add' them, then 'svn commit' your changes. Sometimes, it may be easier to work directly on the repository: > svn import path/to/new/stuff $SOCREPOS/project/trunk/newstuff -m 'your commit comment' Then, check out a version-controlled copy to work on with SVN. 3.2 Switch It may happen that we need to change the URL where you access the repository. If you have a working copy that you want to switch to use the new location of the repository: > svn switch $SOCREPOS/new/location 3.3 SSH agent The SSH agent is useful for eliminating the need to enter your SSH passphrase multiple times while working with SVN. For Windows, use pageant. For UNIX: To make sure the ssh-agent goes away when your terminal is closed (so as not to open up a security hole), start an ssh-agent enabled xterm as a sub-process of ssh-agent: > ssh-agent xterm & Inside the the xterm run > ssh-add Or just start a sub-shell, e.g. bash: > ssh-agent bash > ssh-add The ssh-agent will then go away when you exit your ssh-enabled shell. If you don't want to start a new shell, you can start ssh-agent in your current terminal session, but you will have to be careful to kill it manually when you are done. > eval `ssh-agent` > ssh-add When you no longer need the ssh-agent running, be sure to kill it, or it will remain active even if you kill your terminal. > ssh-agent -k