Basic Subversion (SVN) Crib Sheet ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 0. Introduction ------------------- 0.1 Scope This is a crib sheet for working with the SPEDAS 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 will not 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, pcruce@igpp.ucla.edu, or jwl@ssl.berkeley.edu. We will use your public key to authorize access to the SVN repository. 1.1 Setup 1.1.1 Environment First, try running svn --version to see if your sysadmin already has svn installed. If not, then you need to get in touch with your sysadmin to have svn installed. Most Linux operating systems now have svn pre-installed. Set the SOCREPOS environment variable as a shortcut to the location of the SOC Subversion repository (where the SPEDAS software repository lives) : setenv SOCREPOS svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos or for bash: export SOCREPOS; SOCREPOS=svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos This environment variable will be used 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. [For Windows users, 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 SPEDAS software: > svn checkout $SOCREPOS/spdsoft/trunk my_spdsoft In the my_spdsoft directory, you will find the following subdirectories: external = IDL_GEOPACK, IDL_ICY, developers, external_spdf. The external area contains code that is not developed by SPEDAS developers, but may be used/released. projects = THEMIS, ERG, IUGONET. MAVEN, FAST, WIND software. spedas = IDL SPEDAS software general = IDL tplot software, with some (small) mission-specific packages. 1.3 Partial checkouts: Although we recommend checking out the full package, some developers do not need or want all of it. Here are some options: To check out the minimal distribution of software, including the TPLOT package, and some mission-specific software, (e.g., ACE, FAST, RBSP, STEREO-IMPACT, WIND): > mkdir my_spdsoft > svn checkout $SOCREPOS/spdsoft/trunk/general my_spdsoft/general (The full SPEDAS distribution and general are the two main "released" packages. By "release" we mean that the software is zipped into a file and made available to the general public from the SPEDAS website.) Some developers also need to check out software from certain projects, e.g., THEMIS or MAVEN. A MAVEN developer requires the general package and the maven directory under projects: > mkdir my_spdsoft > mkdir my_spdsoft/projects > svn checkout $SOCREPOS/spdsoft/trunk/general my_spdsoft/general > svn checkout $SOCREPOS/spdsoft/trunk/projects/maven my_spdsoft/projects/maven We recommend keeping the same directory structure as in the actual repository to avoid confusion; this is the reason for the extra "mkdir" commands. To check out a working copy of just THEMIS-specific IDL code: > mkdir my_spdsoft > mkdir my_spdsoft/projects > svn checkout $SOCREPOS/spdsoft/trunk/spedas my_spdsoft/spedas > svn checkout $SOCREPOS/spdsoft/trunk/general my_spdsoft/general > svn checkout $SOCREPOS/spdsoft/trunk/projects/themis my_spdsoft/projects/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. 2.1.1 Adding files: 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 should be 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 $ 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 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$ ;- 2.1.2 Copying files: 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 2.1.3 Moving files: to move a file or directory which is under version control: > svn move file_name new_file_name 2.1.4 Deleting files: to remove a file from the repository: > svn delete file_name 2.1.5 Checking Status: 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 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