UsingSubversionAtCSAIL < TIG

You are here: Foswiki>TIG Web>OperatingSystemsSupport>UsingSubversionAtCSAIL (06 Apr 2018, JonProulx) (raw view)EditAttach
---+!! %RED%Deprecated%ENDCOLOR%

%RED%
*EOL July 1 2018* - Support for this service is deprecated and being phased out.
%ENDCOLOR%

---+!! <strike>Using Subversion at CSAIL</strike>
%TOC%
---++ What is Subversion?

Subversion, or =svn=, is a [[http://en.wikipedia.org/wiki/Revision_control][version control system]] which intelligently tracks and combines changes made across many files (usually text files) by many collaborators (or sometimes a single person).  The master database of all files and changes is called the *repository*.  Viewing and modifying files can only be done from *working copies* that are checked out from the repository.

CSAIL's subversion server provides:
   * tested and maintained version of subversion (As of Feb. 2011: 1.5.1 with debian patches and security fixes)
   * svn+ssh:// access, allowing you to share your repository with other CSAIL accountholders
   * https:// (WebDAV) access, allowing you to share your repository with collaborators outside CSAIL
   * a stable, single location for "hooks" that run on checkout or checkin, allowing automatic emails to be generated on each checkin.

Recommended links:
   * http://subversion.apache.org/ -- Mailing lists, FAQ, etc
   * http://svnbook.red-bean.com/ -- In-depth information on every feature of subversion
   * The svn-users list, for members of the CSAIL community -- see MailingLists 


---++ Prerequisites
*If you're starting out a new project, [[SubversionRepositories][create a repository]] before reading further.*

*0. Make sure subversion is installed on the workstation(s) you will use*
   * Subversion is installed by default on all CSAIL Debian workstations. 
   * For Windows, [[http://tortoisesvn.tigris.org/][TortoiseSVN]] is recommended, which integrates into Windows Explorer (so that checkout, update, and similar operations are accessible by right-clicking a file or folder).  Currently "built against Subversion 1.6.x".
   * Mac OS provides subversion via XCode / Developer Tools; it should already be in =/usr/bin/svn=.  We recommend new users use [[http://scplugin.tigris.org/][SCPlugin]] which integrates into the Mac OS Finder. Mac OS 10.5 provides svn 1.4; 10.6 provides svn 1.6. [[https://tig.csail.mit.edu/software/software_title/show/116][ZigVersion]] is also available (a standalone application).  
   * Ubuntu provides the =subversion= package (may need to be manually selected).  Ubuntu 9.10 and later provide subversion 1.6.
   * Other OSes: see [[http://subversion.tigris.org/getting.html]].  If you have a choice, we suggest version 1.5.

*1. Get (or create) your Repository's URL*
   * This may mean asking a fellow project member for the URL that starts with svn+ssh:// or https://
   * Or see SubversionRepositories to set up your own new repository

*2a. If using svn+ssh:// from Mac OS or other non-CSAIL *nix*
   * Make sure Kerberos is installed properly ([[InstallingKerberosOnMacOSX][Mac]], [[InstallingKerberosForLinux][Ubuntu]]) and that you have valid Kerberos tickets
   * Configure =ssh= to forward Kerberos credentials (bottom of the appropriate Kerberos page above)
   * If your login name on your local name is *different* from your CSAIL username, add the line =User yourcsailusername= to your =/Users/yourlocalusername/.ssh/config= file, within the =*.csail.mit.edu= section you just created in the previous step.
   * Make sure the subversion command-line binary is installed and accessible -- =which svn= should return a full path, like =/usr/bin/svn=. 

*2b. If using svn+ssh:// access from Windows*
   * Make sure [[InstallingKerberosForWindows][Kerberos is installed properly]], and that you have valid CSAIL Kerberos tickets before each SVN session 
   * Install [[InstallingKerberosForWindows#Using_Kerberos_with_SSH][PuTTY >= 0.61]]
      * be sure to customize Auth/GSSAPI and add your username to a custom "csail" profile as described there
      * Accept the host key for svn.csail.mit.edu:  Connect to svn.csail by initiating a New Connection, clicking "csail" then "Load", and entering the host name "svn.csail.mit.edu".  Click Yes to the Security Alert (as of May 2012, the fingerprint should match =ssh-rsa 1024 19:36:f7:58:ab:84:78:0b:f1:ae:53:7e:28:62:e6:13=)
   * Install the version of [[http://tortoisesvn.tigris.org/][TortoiseSVN]] that matches your OS (32- or 64-bit), then configure it to use !PuTTY's =plink.exe=:
      1. Start -> Programs -> !TortoiseSVN -> Settings -> Network
      1. For "SSH client", use ="C:\Program Files (x86)\PuTTY\plink.exe" -load csail= (modify the path to !PuTTY\ as appropriate)
   * (Optional) It is possible to use Subversion integrated into Eclipse with the Subclipse plugin.  Please contribute full directions.  As an outline: you will want to add the !PuTTY directory to the PATH environment variable (My Computer -> Properties -> Advanced -> Environment Variables) and set the SVN_SSH variable to something like =plink.exe -load csail=

*2c. If using https://*

Note: non-CSAIL users may receive "untrusted certificate" errors, which are expected because they haven't installed the [[CertificatesIntro][Master CA]] that allows CSAIL users to distinguish legitimate CSAIL https:// sites. 


---++ Check out a copy of the repository

<verbatim>
csailuser@somehost:~$ mkdir checkouts
csailuser@somehost:~$ cd checkouts
csailuser@somehost:~/checkouts$ ls
csailuser@somehost:~/checkouts$ svn checkout svn+ssh://svn.csail.mit.edu/afs/csail.mit.edu/group/tig/REPOS/test_repo
A  test_repo/foo
A  test_repo/bar
A  test_repo/pub
A  test_repo/pub/beer
A  test_repo/baz
Checked out revision 1.
csailuser@somehost:~/checkouts$ 
</verbatim>

We now have a local working copy of the repository, and we can share the URL of the repository with our group mates so they can also check out a copy and begin working.


---++ Make edits and commit changes

There's no particular magic to editing a working copy; just use your favorite editor and hack away. Note that renaming and moving files must be done within subversion, for example =svn rm &lt;file&gt;= and =svn mv &lt;item&gt; &lt;new_name_or_location&gt;=  When you're done, you will want to commit your changes. In the following example, we've edited the file pub/beer, and want to push the change to the repository.

<verbatim>
csailuser@somehost:~/checkouts/test_repo/pub$ svn commit -m "added more beer"
Sending        pub/beer
Transmitting file data .
Committed revision 2.
csailuser@somehost:~/checkouts/test_repo/pub$ 
</verbatim>

---++ Bring updated files down into my working copy

Use =svn status -u= to show all edits (local and remote) that are pending, or just =svn update= to refresh the local copy from the repository.

<verbatim>
csailuser@somehost:~/checkouts/test_repo$ svn update
U  bar
Updated to revision 3.
</verbatim>

Hmmm, someone else went to the bar. Now I have an updated version of that file, which has version number 3.



---++ Warnings and Problems

   * *If your svn client version is different than 1.5,* it is important that you do *not* share working copies (checkouts) in AFS with CSAIL Debian users. Checkouts will become unusable to svn clients < 1.6.  Subversion designers expect you to only create separate checkouts for each machine, on local storage.
   * Years ago, TIG recommended using file:// repository URLs in simple cases.  This is no longer recommended in any circumstance.  For example, [[SubversionRepositories#Adding_hooks_to_a_subversion_rep][hooks]] will not run predictably.  If, checking a repository need to preserve, =svn info= returns "URL: file:///...", please investigate the =svn switch --relocate= command or email help. 

   * "permission denied" or "forbidden" errors
      * AFS permissions may be incorrect: compare to SubversionRepositories#Creating_a_Subversion_repository
      * You may have expired AFS tokens and/or Kerberos tickets.  Try =renew= or =kinit && aklog=
      * You may have attempted to use public-key authentication, for example =~/.ssh/authorized_keys=.  This is not supported at CSAIL because it leaves you without AFS tokens and unable to write any files.  See Prerequisites 2a/2b, above.
   * "fs: You don't have the required access rights" updating AFS permissions
      * You don't have AFS administer permissions -- =a= -- on the directory you're trying to fix.


---++!! Important note about SVN repositories on network filesystems

Older versions of Subversion used <nop>BerkeleyDB as their back-end storage mechanism.  Newer versions (1.6) use !SQLite. Neither mixes well with network filesystems like AFS or NFS, and their use on these filesystems could result in data loss.  We strongly recommend that you convert any repositories with the <nop>BerkeleyDB backend to the FSFS backend, and that you avoid creating repositories using client versions >= 1.6.  You can find out which backend you're using by examining the =db/fs-type= file in your repository.  If it contains the string =bdb=, you're using the <nop>BerkeleyDB format.  Instructions for converting a bdb repository to fsfs are given in the following example:

   * correct any errors in place
<verbatim>svnadmin recover /afs/csail.mit.edu/group/rvsn/papers </verbatim>

   * dump all svn actions to a log
<verbatim>svnadmin dump /afs/csail.mit.edu/group/rvsn/papers > svn.dump </verbatim>

   * move existing repos out of the way 
<verbatim>cd /afs/csail.mit.edu/group/rvsn/
mv papers papers.bdb
</verbatim>

   * recreate repos; default type is FSFS
<verbatim>svnadmin create papers
</verbatim>

   * replay the log
<verbatim>svnadmin load /afs/csail.mit.edu/group/rvsn/papers < svn.dump
</verbatim>

   * if everything worked
<verbatim>rm svn.dump
rm -rf papers.bdb
</verbatim>
Topic revision: 06 Apr 2018, JonProulx
HQ Wiki | TIG Wiki
