"Version control is the art of managing changes to information. It has long been a critical tool for programmers, who typically spend their time making small changes to software and then undoing those changes the next day." (Version Control with Subversion book, page 1).

Note: on 19th May 2005, Ashley gave an introductory seminar "Subversion for EDEN source code" and handed out copies of this page, the files shown in the left hand menu as well as chapters 2 and 3 of the Subversion book.

We have configured a Subversion ("svn" for short) server at Computer Science to host a repository containing various EM-related source code, including EDEN. Our svn server runs on the machine emsvn.dcs.warwick.ac.uk. It hosts several repositories, one of which is named test. Below are some brief hints on how to go about using it.

1. You can look at the contents of the various repositories that we host by visiting http://emsvn.dcs.warwick.ac.uk/ in a web browser (read access only).

2. Obtain a username and password for the EM Subversion server (emsvn for short) from Ashley Ward or Russell Boyatt. Note your emsvn password is not the same as your DCS password. There is presently no automated way for you to change your password: if you would like your emsvn password changed, please speak to us. If you do not have an emsvn username and password, you will have anonymous, read-only access.
3. Check out a working copy of the latest version of the trunk directory from our test repository. (A working copy is your own local, private copy of some source code. The trunk directory holds the main line of development. There are directories other than trunk that you could use, but this is not explained here.)
   • On a DCS Linux machine, type the command below (all on one line):

     /dcs/emp/empublic/bin/svn \
  checkout svn://emsvn.dcs.warwick.ac.uk/test/trunk/

     Your working copy will be created in a new subdirectory named trunk. (If you would prefer this to be named test instead, say, then you would need to provide that name as another argument on the end of the previous command line.) The first time you run the command, if your DCS username is the same as an emsvn username, you will be asked to enter your emsvn password. Once entered, your password will be stored in your ~/.subversion/ directory and you should not be asked for it again for further access to emsvn repositories. If your DCS username is not an emsvn username, you will not be asked to enter a password and you will have read-only access to the repository.

   • On other platforms, you will need to download a Subversion client program. Try it out first on our test repository. The test repository URL is svn://emsvn.dcs.warwick.ac.uk/test/ and you probably want the trunk subdirectory. Use the emsvn username and password we have provided you.

4. Make a change to your working copy. For your first test, modify an existing file and create a new one, using your usual tools.
5. Query Subversion about the changes you have made. (This may seem unnecessary in this small example, but in a real situation it is good to "preview" what changes you are committing.) Change directory to the top level of your working copy. Type:

   /dcs/emp/empublic/bin/svn status

   and notice it lists the files that you have changed. (It doesn't list the new file since you haven't told svn about it yet by using svn add.) Now, for each file, look at the changes you are about to commit and check they are only what you expect.

   /dcs/emp/empublic/bin/svn diff filename

6. Commit your changes to your working copy to the central repository:
   • On a DCS Linux machine, tell svn about your new file. If it was called newfoo.txt, type:

     /dcs/emp/empublic/bin/svn add newfoo.txt

     Then check in both your modified file and your new file. First, cd to the top level of your working copy. Then run:

     /dcs/emp/empublic/bin/svn commit

     An editor will start in which you should write a log message which describes your change. The editor used is determined by your EDITOR environment variable. Note that in our cygwin Windows build environment, Windows Notepad (notepad.exe) doesn't work well for this as Notepad doesn't cope well with UNIX line feeds very well. When you have written your log message, your changes will be transmitted to the repository server.
   • If you are using another Subversion client program or another platform, you will have to modify the instructions above slightly.
7. Once you are happy with making changes to the test repository (and please, not before then), check out and work on the EDEN source code. At the moment, the central repository for recent EDEN source code is named EDEN-recent and so the following URL can be given to the svn program: svn://emsvn.dcs.warwick.ac.uk/EDEN-recent/trunk/. The repository name may change in the future when older source code history is added.
8. Please subscribe to the eden-development mailing list, where discussion about changes to the EDEN source takes place.
9. If you would like to know when the code in the repository is changed, you could subscribe to the emsvn-commits mailing list, which is automatically sent messages when a developer commits to the emsvn repository.

Notes on using emsvn

• See the book "Version Control with Subversion" for more details. It is available online (note we are using Subversion 1.1), and the department owns a printed copy -- ask to borrow it. See also the Subversion home page.
• The command line tools have built-in help syntax reminders. Try svn --help. Each sub-command also has help: try (eg) svn commit --help.
• You might need to use the --username argument to svn if the account name you are using on your machine is not the same as your emsvn username. This should only be necessary the first time you authenticate to emsvn: the Subversion client remembers your credentials and re-uses them the next time.
• We only allow access to the repository over the network using the svn program as described above: you cannot log in to the machine emsvn.dcs.warwick.ac.uk... although repository administrators can log in using the emsvnadm administrator user code.
• Although the full hostname emsvn.dcs.warwick.ac.uk can sometimes be abbreviated to emsvn, this is not recommended as Subversion may see the two as two different repositories, which can cause problems later... we would recommend that you always use the full hostname for consistency.
• If you don't want your working copy any more, just remove it (after having made sure any important changes are committed to the repository). There is no record on the server of check outs -- only commits are recorded.
• Subversion repositories do not nest: note then that svn://emsvn.dcs.warwick.ac.uk/ is not a repository: that URL needs to be followed by a repository name. To find a repository name, use the web interface.
• File names within a repository, repository names themselves, and therefore repository URLs are case-sensitive.
• Checkouts and commits seem to be separate as far as authentication is concerned. Therefore it seems to be fine to check out a working copy anonymously (with read-only access) but later commit using an emsvn username.

• Log messages on emsvn must conform to the following rules. If your log message does not meet these requirements, you should get a helpful error message.

  Log messages must:

  • not be blank (so others can tell what the change is)
  • not contain lines longer than 74 characters (avoiding the need to scroll to read the message in the web view)
  • not contain tab characters (as tab characters introduce uncertainty into the line length)
• Some of the content of emsvn is exposed in the new EM website, using SiteBuilder's "get content from" facility, notably EDEN's Quick Reference documents, so note that the HEAD revision of these files are publically visible in a non-development context. SiteBuilder requires content to be enclosed in HTML body tags -- which the raw documents are not, so Ashley added a custom 'wrap' parameter to the web view facility implementing this. See the details in the relevant SiteBuilder edit pages.

Guidelines on committing changes to EDEN source

• Please commit related change together. Please don't commit unrelated change together. Another way of describing this is to say that the log message for a commit should describe a single coherent change. A log message should not contain two separate descriptions linked by the word "and".

  For example: if you have globally searched and replaced the name of a function to rename it and also change all the callers, you have changed multiple files, but you should make one commit. Conversely, if you have fixed two separate bugs, but you did this by making changes to one file, you should make two commits.

  The reasoning for this is (1) if the changes in a commit have a single purpose, it is easier for everyone else to understand, since disentangling multiple changes are not required, (2) commits can be merged "backwards" to undo changes, which is sometimes a useful debugging technique -- to make this easier, we need to ensure that winding state back undoes only one change.

  (NB: Unfortunately this desirable feature of data in a repository isn't easy to reconstruct in the pre-Subversion source code history -- so don't take that history as a good example!)

  Making a single commit describing changes to multiple files is easy: just provide multiple filenames as arguments to one svn commit command. The converse example from above is more tricky. If you have made multiple unrelated changes to a single file and need to make multiple commits as advised here, it may be easiest to make a backup copy of the file, revert all your changes, reapply just one change, commit that, make the second change and commit that. For example: svn diff file.c; (note multiple changes); cp file.c file.c-allchanges; svn revert file.c; (edit file.c to introduce just one of your changes); svn commit file.c; mv file.c-allchanges file.c; svn commit file.c.

  In practice, of course, things probably won't be as black and white as described here: let's discuss this on the eden-development list as issues arise.

• Please don't add generated source files to the repository. Careful: there might be more of these than you think. Some generated files are Makefile (edit Makefile.in instead), configure (edit configure.in instead), generic.mk, config.h, parser.c (edit parser.y instead), dd_*, lsd_*, st_* and so on. Again, ask on the eden-development list if you aren't sure.
• Please test your changes before committing them, on at least one platform. Try to commit only changes that you have proved working -- otherwise you may "break the build". (Sometimes testing all cases is hard: please make a reasonable effort in this situation.)
• Please don't commit incomplete work to the trunk. If you must, comment it out, or make a branch to store it instead. See the Subversion book for details on branching.

Document history

• 12-Oct-2010: Added information (originally from the Building EDEN for Windows document) about using Notepad as an svn commit editor. [Ash]
• 24-Jun-05: Added information about exposing of EDEN Quick Reference documents in the new EM website. [Ash]
• 22-Jun-05: Added information about automated log message rules. [Ash]
• 10-Jun-05: Added svn status and svn diff to the tutorial example. Added this document history section. [Ash]
• 19-May-05 to 9-Jun-05: Many small improvements, detail unrecorded. [Ash]
• 18-May-05: Initial version. [Ash]

You might like to see:
• emsvn web view
• eden-development list
• emsvn-commits list
• Subversion home page
• Subversion book
• Download Subversion