University of California at Berkeley Department of Electrical Engineering & Computer Sciences Instructional Support Group /share/b/pub/isvn.help /share/b/pub/svn.help /share/b/pub/cvs.help /share/b/pub/mercurial.help Apr 6, 2016 CONTENTS: Revision Control Utilities SVN (SubVersioN) Creating SVN Repository for an Individual - No Authentication Creating SVN Repository for an Individual - With Authentication Creating SVN Repositories for a Class - Overview Creating SVN Repositories for a Class - Sys Admin tasks Creating SVN Repositories for a Class - Instructor tasks Creating SVN Repositories for a Class - access via SSH Creating SVN Repositories for a Class - access via HTTPS Using SVN Troubleshooting SVN Data Retention Policy GIT on the Instructional Systems Mercurial on the Instructional Systems Course Repos for Instructors Revision Control Utilities -------------------------- SVN is the recommended utility for document version control on the EECS Instructional systems. EECS Instruction (inst@eecs) will create SVN repositories and access control for a class at the instructor's request. Individuals can create and manage their own SVN repositories in their UNIX home directories. These are available for document version control: SVN on UNIX in /usr/sww/bin/svn. Type "man -M /usr/sww/pkg/subversion/man svn" for usage information. CVS on UNIX in /usr/sww/bin/cvs. Type "man -M /usr/sww/pkg/cvs/man cvs" for usage information. PRCS on UNIX in /usr/sww/bin/prcs. Type "man -M /usr/sww/pkg/prcs/man prcs" for usage information. TortoiseSVN (http://tortoisesvn.net/) on Windows (on request). SVN (SubVersioN) ---------------- SVN (SubVersioN) is a public domain version control utiltity for files to keep track of who makes changes and to keep a history of older versions. It is more full-featured than older revision control packages such as CVS, RCS and SCCS. See http://subversion.tigris.org/ for a comparision with CVS. SVN repositories are stored either in your UNIX home directory (for indivuduals) or in a central location that instructors can administer (for class accounts). There are several options for accessing an SVN repository: 1) Use a local repository in your home directory and access it only when you are already logged in. That is, there is no authentication to the SVN repository itself, so it can't be shared with other users. 2) Use a local repository in your home directory and access it via ssh (using the "svn+ssh://" protocol) so you can access it from other accounts or computers. These repositories can be accessed with "svn" using SSH keys to grant access to other users. 3) Use a group repository that is set up for a specific class and access it (using the "https://.." protocol) via the Instructional SVN server. These repositories can be accessed using "svn" or a WEB browser using the existing UNIX passwords of the class accounts. The Instructional Suport Group (inst@eecs) can setup SVN repositories and access control for a class at the instructor's request. Then the teaching staff can create repositories and administer access. Creating SVN Repository for an Individual - No Authentication ------------------------------------------------------------- Individual users can create and manage their own SVN repository in their home directory and access it directly using the "svn" command while logged in. On UNIX and MacOS, the command is "svn" and usage is given by "svn help" on the UNIX command line. On Windows, the command is TortoiseSVN, which is found in the Start-> Programs menu. [Still under development.] Creating SVN Repository for an Individual - With Authentication --------------------------------------------------------------- Individual users can create and manage their own SVN repository in their home directory and access it using ssh from other accounts or computers. These repositories can be accessed with "svn" using SSH public/private keys to grant access to other users. [Still under development.] Creating SVN Repositories for a Class - Overview ------------------------------------------------ SVN repositories can be created for groups or individual users in a class, and the teaching staff can have administrative control. To enable network access to SVN repositories via a secure connection (SSL over HTTPS), we have set up this server: hostname: isvn.eecs.berkeley.edu OS: solaris 10 x86 Software: apache, subversion, swig, openldap, openssl The initial setup for a class repository is done by the sys admins (inst@eecs). The teaching staff then edits the configuration file "svngroups" to add users and groups. The configuration file is re-read by the Apache server on isvn.eecs every 30 minutes, so there is a delay in the effect of changes to that file. To remove a student from an svn group, locate the group with the student's current login and remove it from the list. To add a student into an svn group, locate the group and add the student's current login to the list. To get the svngroups content into Apache, first the sysadmins have to add an entry for it in isvn:/usr/local/apache2/conf/extra/ (just once for each svngroups file). Then the Apache server needs to be restarted. Apache is restarted every 30 minutes via a cronjob on isvn.eecs. If this hasn't happened yet after the conf/svngroups is created, one side effect is that the repos will be accessible without a password. The "require" field in "svngroups" is what forces authentication. Creating SVN Repositories for a Class - Sys Admin tasks ------------------------------------------------------- The repositories for students in a class are stored next to the class account home directories. The sysadmin staff (inst@eecs) need to set up the initial repository. This are the steps: 1. cd /home/cc/$MASTER/sp12 (where "sp12" is the current semester) 2. mkdir -p repos/conf 3. chmod 750 repos repos/conf 4. touch repos/conf/svngroups 5. chown ${MASTER}:daemon repos 6. chown -R ${MASTER}:$MASTER repos/conf repos/conf/svngroups 7. Insert the following into repos/conf/svngroups (replace $MASTER and $user] with a real value): #------------------------------------------------------------- # Sample Entry SSLRequireSSL AuthType Basic AuthBasicProvider ldap AuthName "Subversion Auth" AuthzLDAPAuthoritative off AuthLDAPURL ldap://ildap1.EECS.Berkeley.EDU/ou=people,dc=EECS,dc=Berkeley,dc=EDU?uid TLS require user [user] #------------------------------------------------------------- 9. on isvn.eecs, cd into /usr/local/apache2/conf/extra 10. Edit the httpd-svn.conf file and add the corresponding Location and Include lines. Example: Assume we are creating a respository for cs184. Add the following lines to httpd-svn.conf #------------------------------------------------------------- DAV svn SVNParentPath /home/cc/cs184/sp07/repos/ Include /home/cc/cs184/sp07/repos/conf/svngroups #------------------------------------------------------------- 11. Install the /home/cc/[classmaster]/[term]/repos/README file (this can be copied from another "repos" and customized for this class) That is it for the staff side of things. Creating SVN Repositories for a Class - Instructor tasks -------------------------------------------------------- To set up repositories for the students, the instructor or the TAs does these steps while logged into the instructor account (such as "cs184") on an Instructional UNIX computer: 1. cd into /home/cc/[classmaster]/[term]/repos/conf, ie: 2. Edit svngroups to create a new location for the new group. Note: In the "svngroups" file, "#" is a comment character. This file is read by the Apache server and follows the syntax of an http.conf file. 3. Use "svnadmin" to create a new subversion repository. For example: % cd /home/cc/[classmaster]/[term]/repos % umask 000 # temporary % svnadmin create GROUP1 % umask 77 # set it back Where GROUP1 corresponds to the location specified by svngroups. The students then access there repository using the https protocol, such as % svn info https://isvn.eecs.berkeley.edu/cs184/GROUP1 Notes: Apache is restarted on isvn.eecs every half hour in order to re-read these configuration files. 'umask 000' makes directories with drwxrwxrwx permissions under /home/cc/[classmaster]/[term]/repos, which is a little scary to see. But as long as the directory above them is only readable by the classmaster and by daemon, nobody else who is logged in on UNIX can access the contents. Only the server on isvn.eecs can read it. Please refer to /home/cc/[classmaster]/[term]/repos/README for more information. Creating SVN Repositories for a Class - access via SSH ------------------------------------------------------ Here are the instructions for creating an internal ssh-controlled subversion repository. To setup a class respository using ssh: 1. Each teaching staff logs his/her own account on UNIX and creates a new ssh key that will be used by SVN: % ssh-keygen -b 2048 -t rsa -f ~/.ssh/id_rsa_svn 2. Once the keys are created, the public key part should be copied over to the account hosting the subversion repository (such as the "cs184" instructor account). Append it to the file '.ssh/authorized_keys' using the following template command="/usr/sww/bin/svnserve -t --tunnel-user=USER -r \ PATH_TO_REPOSITORY",no-port-forwarding,no-agent-forwarding,\ no-X11-forwarding,no-pty TYPE KEY COMMENT "TYPE KEY COMMENT" is the ssh key generated under the first step. PATH_TO_REPOSITORY is the path to the repository in the host account. USER is the id you want to pass to subversion for all transactions. 3. Create the repository in the host account (in this example, we put the repository in the top level directory): % svnadmin create $HOME/repo 4. Populate the repository (for example, let's assume the data we want to add to the repository is under "content"): % svn import -m "Initial Import" content file:///$HOME/repo/content We are now done on the server side. The following has to be done on the client or user side. 1. Create a config file under [WHOSE?] .ssh directory to bind the svn ssh key to our invocation of svn. A sample .ssh/config file: Host isvn HostName torus.berkeley.edu IdentityFile ~/.ssh/id_rsa_svn User mars The "Host" field is an alias and everthing below it pertains to that alias. So in this example, the alias is labeled "isvn". This alias will connect to the host "torus.cs.berkeley.edu" and use the identityfile "~/.ssh/id_rsa_svn". Specifying a HostName creates a unique HostName/User identity that SSH matches to the svnserve command. So a user can have a second SSH key in the $MASTER/.ssh/authorized_keys file, and if the user logins to it from any computer except torus, the second key will be invoked and open a normal ssh shell instead of the svnserve command. 2. Once you have created the config file you are ready to use subversion. The first thing you will need to do is checkout a copy of the repository. % svn co svn+ssh://isvn/content 3. You will now be prompted for your passphrase you used to create the rsa_svn key. Just supply this passphrase and you should now get a copy of the repository. From this point on you will no longer need to supply the 'svn+ssh://isvn' URL. So if you want to get a status report, all you would need to type is % svn status Note: If you want to avoid being prompted for your ssh key on every svn call, you will need to use ssh-agent. To do that, start ssh-agent using one of the following ways depending on your shell. % eval `ssh-agent -s` # for sh or bash shell % eval `ssh-agent -c` # for csh or tcsh shell Now add the subversion key into the agent. To do this type the following. % ssh-add $HOME/.ssh/id_rsa_svn To view a list of keys hosted by the agent type % ssh-add -l Creating SVN Repositories for a Class - access via HTTPS -------------------------------------------------------- Here are the directions to access your subversion repository via isvn.eecs.berkeley.edu. It is a way to setup a repository so that its read-only by the students but read-write for the instructors. 1. Edit the following file to add the logins of the individuals you want to give read/write access. /home/ff/$MASTER/repo.conf 2. To import files use the following command: % svn import -m "Initial import" https://isvn.eecs.berkeley.edu/$MASTER 3. For the students to check out a read only version: % svn co https://isvn.eecs.berkeley.edu/$MASTER svn 4. To check in changed files [Must be called from within svn-controlled repo]: % svn ci Troubleshooting SVN ------------------- Q: Is there a way to give students access to their group's hooks scripts? A: Due to limitations in the filesystem, you cannot give individual groups access to the hooks scripts. Q: Is it possible to allow PROPFIND requests on the instructor direcrory, such as 'svn cp https://staff/proj2 https://team/trunk/proj2'? A: No, the permissions prevent the owners of the target repository from reading the source repository (unless they are both under a shared repository). Using SVN --------- To access an SVN repository, you need an SVN client program. On the EECS Instructional systems, there is: /usr/sww/bin/svn on UNIX (http://subversion.tigris.org) TortoiseSVN on Windows (http://tortoisesvn.tigris.org) Some sample svn commands: % svn ls https://isvn.eecs.berkeley.edu/cs162/group7 You can also access your repository via our SVN WEB server, for example: % firefox https://isvn.eecs.berkeley.edu/cs162/group99/ [Still under development.] Data Retention Policy --------------------- SVN repositories that that are stored in a user's home directory will remain available for as long as the user's account exists. That is because the repository is included in the disk quota for that user, so there are controls on the size. SVN repositories that are created for class accounts and groups will be archived and deleted at the end of each semester. We do not support permament, group repositories at this time. This policy is because we can't afford to store and archive ever- growing, unlimited data stores. GIT on the Instructional Systems -------------------------------- Please see /share/b/pub/git.help. Mercurial on the Instructional Systems -------------------------------------- Mercurial (http://mercurial.selenic.com/) is in /usr/local/bin/hg on the Linux systems in 330 Soda ("hive-*"). Students can ssh into them and run it. The locations and hostnames of the systems can be listed from http://inst.eecs.berkeley.edu/cgi-bin/clients.cgi Course Repos for Instructors ---------------------------- Instructors are welcome to use the instructor accounts on the Instructional systems for the longterm storage of course materials, including an SVN repo. Our setup is pretty much self-service. Ideally, there is continuity amonsgt the instructors so that the content is managed and does not grow without bounds. The repos of student accounts are deleted at the end of each semester. We hope that the instructors won't need to permanently store large or personal (SIDs, etc) data from the past students. Instructional Support Group 384/386 Cory, 333 Soda inst@eecs.berkeley.edu