SESSION FOUR 4.1 What is Version Control? Subversion Version control or revision control is the management of the evolution of information. Typically it is used in engineering or software development where artifacts like specifications, source code or blueprints are undergoing constant revision. For these reasons, version control is often called source control or (source) code management, but it can be extremely useful beyond the management of source code. Each version or revision is identified with an alphanumeric code called a revision number or revision level. This is often abbreviated to revision. Version control systems allow retrieval of all previous versions. Version control is essential when more than one person in a team needs to modify critical shared information. Version control systems track who submitted each version and when, logs comments about the change, allows changes to be viewed and undone. Most version control systems store the revisions on a centralised server called a repository, although distributed version control is becoming increasingly popular. 4.1.1 Types of Version Control One of the central problems version control attempts to solve is how can multiple people work on the same file simultaneously? Opening the file from the repository in multiple text editors doesn t work. If more than one person saves a file (nearly) simultaneously, only some of the changes will be saved, or worse the entire file will be corrupted. The obvious approach is to prohibit concurrent access to a file, called file locking. When one user modifies a particular file, no other user is allowed to modify it. Another alternative is to provide software for semi-automatically merging changes made by multiple users. The merits and pitfalls of each approach continue to be religiously debated amongst software engineers. The problem with file locking is that a particular user can stop all other users modifying a file for potentially indefinite periods of time. This leads to the other users circumventing the version control system and making their own local modifications. The problem with merging is that if major changes are made the automatic merging fails and manual merging can be laborious. Lots of difficult merging can introduce errors and can become inefficient. Merging has won the battle in terms of popularity. The Concurrent Versions System (CVS) is by far the most popular version control system and it uses the merging model. 4.2 What is Subversion? Subversion is a (near) replacement for CVS. It solves a number of technical problems with CVS including atomic commits, maintaining version history on file/directory copying and renaming, and efficient branching and tagging. Subversion was started in early 2000 at CollabNet Inc. by Karl Fogel, Ben Collins-Sussman and others. It is now at version 1.4 and many projects have switched from using CVS to subversion. There is an excellent book Version Control with Subversion written by Collins-Sussman, Fitzpatrick and Pilato, and published by O Reilly in 2004. The good news is that the book is also freely available online at http: //svnbook.red-bean.com. The online versions of the book match the version of subversion itself. We find subversion easy to setup and use, and believe it will become the dominant version control tool over the next few years. There are also a large number of 3rd party GUI tools available that simplify using subversion. For example, we will be using Tortoise SVN under Windows. Astroinformatics School 2009 1
4.3 Checking out a repository By far the best way to understand how to use subversion is to give it a try, preferably in a group situation where multiple people are modifying files at once. We are going to do this with a shared Astro09 test repository. This repository is accessible from this URL: http://svn.ask.it.usyd.edu.au/astro09/test. 4.3.1 Checking out a repository at the command line Almost all of the subversion commands are carried out using a single command line program svn, followed by the name of the command e.g. checkout or commit, and then any arguments that command requires. To access a repository you first need to make a working copy. A working copy is the local copy of a revision of the repository which you make your changes to. No changes are transmitted back to the repository unless you decide to, so you can t break anything by making local changes or even deleting the working copy. So, like a sandbox in a Wiki, it allows you to try things out without doing any damage. Also, you don t get any changes in your working copy from the repository unless you decide to. So other people s changes won t interrupt you until you decide you need to integrate them. You make a working copy using the checkout (abbreviated to co) command. The arguments are the URL of the repository and what you want the directory to be called on your local system. We are using the shared repository mentioned above and will put it in a directory called test: 1 % svn co http://svn.ask.it.usyd.edu.au/astro09/test test Subversion controls who can access and modify the contents of a repository, so you must first confirm who you are. Subversion makes a first guess at your username based on your Unix username. If this is the correct username for the subversion repository then you can just enter your password here, but often you have a different username for the repository, in which case you just press Enter. 2 Authentication realm:... Astro09 test repository (SVN WebDAV) 3 Password for 'james': Now you can enter a different username. For Astro09, your subversion username is your first and last name concatenated, with any hyphens or apostrophes removed, e.g. JamesCurran or JohnOByrne: 4 Authentication realm:... Astro09 test repository (SVN WebDAV) 5 Username: JamesCurran It then asks for a password. Your Astro09 subversion password is astro09 6 Password for 'JamesCurran': astro09 7 A test/test.py 8 A test/test.txt 9 Checked out revision 1. Now we have checked out a working copy with revision number 1. 4.3.2 Checking out a repository with the Tortoise SVN (Windows only) Tortoise SVN is a GUI front-end for subversion that runs under Windows. Rather than being a separate program, it is a shell extension that adds functionality to Windows Explorer. Most of the subversion functionality is accessible from the context menu that pops up when you right-click. If you right-click on the desktop, one of the context menu options is SVN Checkout...: Tara Murphy and James Curran 2
Choosing that option brings up a dialog box where you can enter the URL (as above) and the local directory to save the repository. Remember to add test to the end of the local directory otherwise the files will go straight into the Desktop directory. This dialog box also allows you to check out a previous version rather than HEAD, the most recent version: Next you will be asked for your username and password (as above): The files will then be downloaded to the test directory on the desktop: If you then open Windows Explorer (by double clicking on the test directory) you will see that the two example files have a green tick on them. This indicates that the files are under version control and are up-to-date: Note, if you have Cygwin installed you can use both the command line tools and the Tortoise SVN GUI. Tara Murphy and James Curran 3
4.4 Committing changes Now that you have checked out a repository into a directory, the files can be modified in the regular way. For example, you can open the file test.txt in any regular text editor and add a line to the end. You can run the test.py file from the command line or within IDLE. Once you are happy with the changes to your working copy, usually because you have debugged and tested code, you can submit the changes in the working copy back to the repository. This is called checking in or committing the changes. Each change must be accompanied by a log message. Typically this message is used to record what changes were made and why. When the commit is successful the revision number is increased. 4.4.1 Committing changes at the command line Committing changes on the command line involves the commit svn command (or the abbreviation ci). There are two ways to add a log message. One is to supply a message on the command line using the -m switch, e.g.: 1 % svn ci -m 'added my name to test.txt' The other method is not to supply the switch in which case subversion will try to open an editor for you to type the message into. For this to work you either need to have the EDITOR or SVN_EDITOR environment variables set. By default, subversion will try to use vi. If you aren t a vi user, our preference for these simple messages is pico. You can set the environment variable like this (in bash): 1 % export SVN_EDITOR=pico or like this (in csh/tcsh): 1 % setenv SVN_EDITOR pico When you commit using an editor without the -m option, this is what you will see in your editor: 1 2 --This line, and those below, will be ignored-- 3 4 M test.txt You can type any log message you like above the line and it will be included. The list of files below the line is just a reminder of the status of the files for the current commit. We will talk more about status below. Once you save the file and exit the editor, svn will perform the commit: 1 Sending test.txt 2 Transmitting file data. 3 Committed revision 2. 4.4.2 Committing changes with the Tortoise SVN (Windows only) When you make a change to a working copy, Tortoise changes the Explorer icon to indicate that the file has been modified. For example, test.txt has been modified here: Tara Murphy and James Curran 4
To perform a commit we again use the context menu by either right-clicking on the modified file, or the whole directory. Notice that the same red exclamation mark appears on the directory of the modified repository: SVN Commit... pops up a dialog box which allows you to enter a log message and choose which files to commit: Once the commit is complete another dialog box shows the same output as the command line commit: 4.5 Working copies When subversion checks out a working copy it stores some extra files in.svn sub-directories within each directory. In Unix, if you type: 1 % cd test 2 % ls -al 3 total 16 4 drwxr-xr-x 5 james james 170 Feb 18 15:38. 5 drwxr-xr-x 17 james james 578 Feb 18 17:44.. 6 drwxr-xr-x 9 james james 306 Feb 18 15:38.svn 7 -rw-r--r-- 1 james james 28 Feb 18 15:38 test.py 8 -rw-r--r-- 1 james james 21 Feb 18 15:38 test.txt you will see the extra.svn directory. This directory contains the information subversion needs to synchronise your working copy with the repository. It also allows you to get the original working copy back even if you are not connected to the internet. Deleting the.svn directory is bad news if you want to continue synchronising the working copy with the repository. The only way to recover is to check out another copy of the repository and move your modified files across, and then check it back in. Tara Murphy and James Curran 5
4.6 Adding, moving and deleting files to/from a repository The working copy does not automatically know about created, added or deleted files or directories. You must tell subversion explicitly that the working copy is responsible for tracking the changes to a file or directory. This is done using the add, copy, move and remove svn commands. Say we have created a new file or copied a file from somewhere outside of the working copy, for this example new.txt. We use add to tell subversion that from now on we want to track the changes to this file in the repository: 1 % svn add new.txt 2 A new.txt Basically, the copy, move and remove commands (mostly) replace the standard cp and rm Unix commands. copy (or cp) is used to make a copy of a file or directory in the repository to another name or location. svn cp will automatically add the new file to the working copy, and more importantly, the new file will have the history of the original file from the repository. move (or mv) is used for moving and renaming files and delete (or rm) is used for deleting files. They work just like Unix mv or rm except that they also keep the working copy bookkeeping up-to-date. In particular, svn rm will remove the files from the file system as well as from the working copy bookkeeping. Subversion also provides an mkdir command which performs the additional task of adding the necessary.svn bookkeeping to the new directory. However, you can also create a directory using Unix mkdir and then run svn add on the new directory. In this case, subversion will add all of the files in the directory to the repository at the same time. The file will not actually added or removed to/from the repository until the next commit, just like any other change to files in the working copy. This includes the removal of files. Subversion will not allow the moving or removal of files that have been modified. To do this you need to either try forcing the operation using the --force flag. If this doesn t work then you must commit the changes to the files first and then remove/move them in a separate step. 4.6.1 Add, move and delete with Tortoise SVN (Windows Only) The same rules apply to manipulating files in Windows subversion repositories. You must use the special versions of copying, moving, renaming and deleting that Tortoise SVN provides otherwise the working copy bookkeeping will not be up-to-date. Tortoise SVN supplies these alternative versions on a sub-menu under the Tortoise SVN... context menu item: Tortoise SVN also has an Add... menu item, but you don t need to use this since the commit dialog box gives you the option of adding files to the repository. However, the sooner you add a file, the sooner you have the safety and power of modification tracking. Tara Murphy and James Curran 6
4.7 Status of a working copy In Windows, seeing the status of your files, that is which files have been modified, added or removed etc, is relatively easy because Windows Explorer changes the icons. To see the status on the command line, use the status command: 1 % svn status This produces a listing of all of the files that have been changed since the last commit. It also lists all of the files that have not been added to the repository that are in the working copy directories. For example, running svn status after adding the file new.txt and modifying test.py returns: 1 M test.py 2 A new.txt There are many status modes run svn status --help to see the full set. 4.8 Updating your working copy If you are the only person working on a project and you only use a single working copy it will always be at least as up-to-date as the central repository. However, if you work in a team or have separate copies on a desktop machine and a laptop (for example) then at some point your local working copy will be out of date. To update your working copy, use the update (or up) command: 1 % svn up Typically you would do this at the beginning of a work session and when you know there are changes in the repository you want to incorporate. You also do an svn up just before you try to commit changes to your working copy. The reason is that subversion requires you to have an up-to-date working copy (this is how subversion protects against overwriting others work). 4.8.1 Merging and conflicts In most update situations everything will go smoothly. If a file has been modified in either the repository or the working copy then subversion will make the update automatically. The same is true for files that have been added, moved or removed. Subversion can even handle many cases where a file has changes in both the repository and the working copy. In this case, subversion will try to do a line by line merge of the repository and working copy. For example, if two people were editing a single L A TEX document but working in different sections, subversion will successfully merge the changes together because it is (reasonably) clear that the changes are independent of each other. Sometimes changes directly conflict with each other, either because one or more lines have been changed in both the repository and the working copy, or lines in the vicinity of each other have been changed. In these cases, subversion does not make the change but instead saves copies of the conflicting revisions of the file in the working copy, marks the original with both versions and requires a human to resolve the conflicts. For example, let s start with a repository version of test.txt: 1 Hello Astronomy World! 2 Hello from JamesCurran! Two people have working copies checked out. If the first person changes their working copy like this: 1 Hello Astronomy World! 2 Hello from TaraMurphy! and the second person changes their working copy like this: 1 Hello Astronomy World! 2 Hello from AlanFekete! then the two versions are in conflict. Tara Murphy and James Curran 7
If Alan updates his version after Tara has committed hers, this happens: 1 % svn up 2 C test.txt 3 Updated to revision 4. The C indicates that test.txt is in conflict. Looking at the contents of the directory now, we see the extra files corresponding to the different versions: 1 % ls test.txt* 2 test.txt test.txt.mine test.txt.r2 test.txt.r4 test.txt.r2 was the working copy before Alan made his local changes. test.txt.mine is Alan s modified working copy and test.txt.r4 is Tara s version from the repository. Subversion also modifies test.txt to indicate where the conflicts occur: 1 % cat test.txt 2 <<<<<<<.mine 3 This is a test file. 4 Hello from AlanFekete! 5 ======= 6 This is a test file. 7 Hello from TaraMurphy! 8 >>>>>>>.r4 The angle brackets show that the pieces in conflict is a result of changing TaraMurphy and AlanFekete. Sometimes the conflict area looks larger than it is. The conflict can either be resolved by directly editing test.txt or by Unix copying one of the other files over the top of test.txt. Once the conflicts have been resolved, you must run the resolved command: 1 % svn resolved test.txt 2 Resolved conflicted state of 'test.txt' This will remove the other versions of test.txt from the working copy and update the subversion bookkeeping. Now you can commit your version back into the repository. 4.9 Other subversion commands to know about svn help svn command --help svn blame svn cat svn diff svn log svn log -v svn revert 4.10 Version control pitfalls lists all of the available commands get command specific help see who was responsible for changes cat a particular file/revision from the repository see the changes between revisions list all of the log messages corresponding to a file or directory include revision status in the log get back to the clean working copy version (including undelete) infrequent commits Version control offers as much protection as the frequency of your commits. If you only commit once a week and you delete your working copy you will have a week s work to repeat. This is just like backing up. excessive commits Committing too often (particularly with half finished work) is a problem too, especially when you are sharing code with other people. If they check out your broken revision then they can t get any work done until it is fixed either. whitespace Different editors do different things with whitespace. For example, some convert tabs to spaces. There is also the problem of Windows versus Unix versus Mac newlines. All of these make files look different to subversion when they really aren t which gets confusing. Tara Murphy and James Curran 8