Subversion
Introduction
In this workshop, we'll look at using a particular Version Control System (VCS) called Subversion (often abbreviated to SVN). Before getting into the nitty-gritty of using SVN, we'll pause to consider the motivations for adopting version control and also the key concepts that are common to most available systems.
Why is Version Control useful?
OK, here's the sales pitch:
- It removes confusion about versions. For example, you will no longer have to keep inventing names for different versions of essentially the same document e.g. blah.old, blah.sav, blah.older, blah.newest2 (look familiar?).
- It makes collaborative working easier. Version control assists in coordination as it removes any confusion about versions, highlights conflicts, allows the use of independent working copies, records log messages and much more besides.
- It makes distributing your code easier. A version control repository can be visible to the world (often as a URL). However, using some highly customisable access controls, you can arrange for some (perhaps anyone) to download your project while also specifying that only a select few may be trusted to upload.
- It makes reproducing experiments easier. The ability to reproduce an experiment is a key characteristic of science. However, all too often, in the digital age, people are unable to run the same version of a model that they ran six months ago. With version control, you can always access any previous version of your model.
- It aids disaster recovery. You computer is fried? No problem! Just checkout your code to another and you're working productively again in minutes.
Version Control Concepts
A picture can be worth a thousand words, so let's try illustrating some of the key version control concepts, before wading into acres of text:
Subversion is a centralised version control system. Centralised version control means that a copy of your project is held in a central location called the repository and the subversion server logs all operations happening on the repository: every time something is changed in the repository, the server logs the time and date, the changes, the author as well as a log message. The server can be configured to give privavcy; allowing some people actions which are disallowed for others. For instance, in the practical, the server allows anonymous read-only access but only a selected number of people can changes things.
All the operations described above (logging and authentication) happen on the server. However, the server is only accessible directly to system administrators. To interact with the server, a user makes use of a subversion client. Some of you might already know about some graphical subversion clients such as TortoiseSVN (see the screen grab below). This practical will show how the command line client can be used. The subversion client can be used to (1) ask information from and (2) send information to the server. The client can also be used to get information about your working copy which is the local copy of the project that resides on your filespace. You can use the client to ask questions such as:
- which files have I modified since I last synchronised with the server?
- when was that file last modified?
- who, inadvertently, created a bug at line 18 in file foo.c?
- what has changed in that file?
TortoiseSVN for MS Windows
svn command line client for Linux
Acquiring a Repository
For the purposes of this practical, you can get yourself a repository from one of the hosting sites that can be found out in the cloud. Or you could use another repository that you have access to--perhaps hosted here in the University, some other portion of UK academia or elsewhere. I've prepared the examples using a repository accessed via the GitHub website (https://github.com). Note, however, that to obtain a free repository on GitHub, you must agree to it being readable by anyone.
NB With that in mind, you may want to have a think about the right home for any of your intellectual property.
OK, let's assume that you are happy to work with a GitHub hosted repository--at least for your initial steps learning about version control and subversion. (A natty feature of GitHub repositories is that they can be used with both Subversion and Git VCS.)
Registering and creating a repository is easy, just follow the instructions on the webpage:
Be sure to check the box: Initialize this repository with a README
In addition to the command line client that we will describe in the following sections, you can manage your repository, view and even edit your files through the GitHub website:
svn: The Subversion Command Line Client
The subversion command line client is called svn. To execute a subversion command, simply type:
$ svn command arguments
Some commands can also use options which are given with dashes:
svn command arguments --option optionvalue
Subversion provides extensive help about the commands to use. To get help for a particular subversion command, simply use:
$ svn help command
Checkout a Working Copy
Now that you have access to a repository, let's create a working copy of the files in the repository. To do this we use the svn checkout command, or svn co, for short:
gethin@gethin-desktop:~$ svn co https://github.com/ggdagw/test ./test A test/branches A test/trunk A test/trunk/README.md Checked out revision 1.
This command gets a copy of the content at the URL and places it in a new directory called test. The letter "A" simply means that these files have been added to your working copy. You'll also notice two subdirectories called trunk and branches. This pattern follows an convention. Usually, subversion repositories are organised so that the main strand of development is in the trunk. Sometimes it is useful to store variants of the trunk version (more of that later) and the branches folder exists to accommodate those. This is purely semantics as far as subversion is concerned, however, and "trunk" and "branches" are merely two folders under the URL.
The content that you saw through your browser is now in your own file space. You may also notice hidden directories called ".svn". It is very important that you do not touch these directories.
gethin@gethin-desktop:~$ cd test/ gethin@gethin-desktop:~/test$ ls -al total 28 drwxr-xr-x 5 gethin gethin 4096 2013-07-26 12:29 . drwxr-xr-x 117 gethin gethin 12288 2013-07-26 12:29 .. drwxr-xr-x 3 gethin gethin 4096 2013-07-26 12:29 branches drwxr-xr-x 6 gethin gethin 4096 2013-07-26 12:29 .svn drwxr-xr-x 3 gethin gethin 4096 2013-07-26 12:29 trunk
Modifying your Working Copy
Right oh. The working copy is yours to work with so let's go ahead and modify the README.md file.
gethin@gethin-desktop:~/test$ cd trunk gethin@gethin-desktop:~/test/trunk$ ls README.md gethin@gethin-desktop:~/test/trunk$ emacs -nw README.md
To see what files you have modified, you ask the client for the status of your working copy:
gethin@gethin-desktop:~/test/trunk$ svn status M README.md
The status shows the letter "M" for README.md, indicating it has been modified.
Note that this status only shows the things that have changed in your working copy. It does not show any changes made by others, either in the repository or in their own working copies.
You can also add a new file. Let's add a file called foo.txt:
gethin@gethin-desktop:~/test/trunk$ touch foo.txt gethin@gethin-desktop:~/test/trunk$ svn status ? foo.txt M README.md
The question mark shows that the subversion client knows nothing about the new file (i.e. it is not currently under the auspices to version control). By default, svn will ignore new files. To indicate that a new file should be versioned, use the add command:
gethin@gethin-desktop:~/test/trunk$ svn add foo.txt A foo.txt gethin@gethin-desktop:~/test/trunk$ svn status A foo.txt M README.md
The letter "A" is used to indicate an addition.
Recording Changes in the Repository
Sending changes to the repository is called a commit. Here's the command I used to send our two local modifications:
gethin@gethin-desktop:~/test/trunk$ svn commit --message "Added text to README.md and added the empty file foo.txt" Sending trunk/README.md Adding trunk/foo.txt Transmitting file data .. Committed revision 2.
where the --message, or -m for short, allows us to write a log message inline.
Notice the revision number. These numbers encode the state of the whole repository at a given juncture and are the passport to retrieving earlier versions of your project. As you commit future changes to your repository, your revision numbers will steadily increase.
Sometimes, you want a long message to go with a commit. To do this, simply execute the commit without the --message option. A text editor will then pop-up to be used to write the message and by saving and exiting, the commit will be done. Note that svn uses the editor indicated by the EDITOR environment variable. The editor often defaults to vi if this variable is undefined. If you are an emacs fan, set the variable first:
$ export EDITOR=emacs
(Note that you can use :q! to get out of vi, if you started it by accident. You could also set EDITOR=nano or gedit etc. You can also use the SVN_EDITOR environment variable.)
Revert: Your "Get-Out-of-Jail Card"
Just as we can add files, we can delete, for example:
gethin@gethin-desktop:~/test/trunk$ svn delete foo.txt D foo.txt gethin@gethin-desktop:~/test/trunk$ ls README.md
The letter "D" indicates deletions and we see from typing 'ls' that the file has gone.
Subversion allows you to revert changes when you have made an error. Let's assume that 'foo.txt' was deleted in error. Fear not, you can get it back with:
gethin@gethin-desktop:~/test/trunk$ svn revert foo.txt Reverted 'foo.txt' gethin@gethin-desktop:~/test/trunk$ ls foo.txt README.md gethin@gethin-desktop:~/test/trunk$ svn status gethin@gethin-desktop:~/test2/trunk$
and foo.txt is back! A silent return from svn status, svn stat for short, indicates that the working copy matches the latest version of the project held in the repository, i.e. no local changes compared to the server.
Updating your working copy
You can update your working copy to synchronise it with the latest version (known as the HEAD) held in the repository. The general form of the update command is:
$ svn update ... <- list of files that have been added/modified At revision X.
If I update my working copy now:
gethin@gethin-desktop:~/test/trunk$ svn update At revision 2.
we see an empty list of files--i.e. there is nothing to update and my working copy perfectly matches the HEAD of the repository.
status, commit and update will probably be your most widely used commands:
- update regularly to bring other people's work
- status to make sure all is well
- commit frequently so that you can always recover a version you care about
However the subversion client can also be used to looks at changes in the repository and this can boost productivity.
Investigating changes
This section shows some subversion commands. Some of these commands can also be done directly from the websvn interface.
log
To get a log of what happened in the repository, use the log command. To see the files that have been modified as well as the log messages, use the --verbose option:
$ svn log --verbose ------------------------------------------------------------------------ r2 | jprenaud | 2008-05-14 15:18:44 +0100 (Wed, 14 May 2008) | 1 line Changed paths: M /trunk/file2 A /trunk/newfile First commit ------------------------------------------------------------------------ r1 | jprenaud | 2008-05-14 13:42:43 +0100 (Wed, 14 May 2008) | 2 lines Changed paths: A /trunk A /trunk/file1 A /trunk/file2 A /trunk/folder1 A /trunk/folder1/somefile A /trunk/folder2 A /trunk/folder2/somefile Initial import into the repository.
You can also invoke the log command on a particular file/path and provide a range of revisions. For instance to see which commits affected file1 between revisions 4 and 6, one could use:
$ svn log --verbose --revision 4:6 file1 ... <- log output
diff
After you have modified something, it can be handy to highlight what you've done. You can do this using the diff command.
For instance add some text to file1 and use diff to see what you have done.
$ svn diff file1
Index: file1
===================================================================
--- file1 (revision 20)
+++ file1 (working copy)
@@ -8,3 +8,4 @@
testing
purposes.
+Here are my changes, right at the end..
You can also use diff to highlight differences between two versions of some file, as stored in the repository:
$ svn diff -r73:74 havana Index: havana =================================================================== --- havana (revision 73) +++ havana (revision 74) @@ -1,4 +1,4 @@ Ring-a-Ring o'Rosies A Pocket full of Posies -"A-tishoo! A-tishoo!" +Ashes, ashes, We all fall Down!
blame (praise)
Sometimes, you want to know who wrote a particular bit of code. Subversion makes that easy with the blame command:
$ svn blame file2
2 jprenaud Added some stuff
3 jprenaud Another line
4 jprenaud A third line.
You see the content of file2 and for each line the name of the author and the revision number. You could then fetch the log message for that particular revision to get more information.
$ svn log file2 --revision 3 ------------------------------------------------------------------------ r3 | jprenaud | 2008-05-14 16:03:45 +0100 (Wed, 14 May 2008) | 1 line More things. ------------------------------------------------------------------------
Conflicts
Sometimes, a commit or an update will fail because of conflicting changes. As a rule, you should always update before a commit so the example here will show a conflict created after an update.
Creating the conflict
Let's create a conflict. This requires audience participation:
- One brave volunteer modifies file1, by adding a line, and commits the change (let's assume revision5)
- Everyone, update your working copies
- Our plucky volunteer makes more modifications to the new line
- Everyone modify the same line too
- Our volunteer commits (revision 6)
- Everyone, try to update..
The update does not immediately fail. Rather, you will be presented with some options:
Conflict discovered in 'file1'.
Select: (p) postpone, (df) diff-full, (e) edit,
(mc) mine-conflict, (tc) theirs-conflict,
(s) show all options: df
If you choose "df", then you will be presented with a summary of the 3-way difference: First how it was prior to your local change; second how it is in your working copy and lastly how it currently is in the repository. You will also be presented with the list of options again. If you choose mine-conflict, "mc", your local modifications will be preferred--at least in this working copy, since nothing has been committed back at this stage. Theirs-conflict, "tc", will prefer the repository version. If you elect to postpone, "p", then file1 is flagged with the letter "C" indicating a conflict and you will notice new files in your working copy:
$svn status ? file1.r5 ? file1.r6 ? file1.mine C file1
- file1.r5 is file1 as at revision 5 (i.e. the one at your last update)
- file1.r6 is file1 at revision 6 (i.e. the one that is on the repository now)
- file1.mine is file1 as it was in working copy before the update
- file1 contains an attempt at merging the changes (this will be similar to what you see with "df").
The last option, edit (e), will present to you the attempted merge in a text editor, for you to resolve as you see fit. Note that if you type "svn status" after editing file1 in this situation, you will see that the file is still marked as conflicted and you will not be able to commit your changes until you have resolved the conflict by typing e.g.:
svn resolved file1
Other useful commands
info
From inside a working copy, e.g.:
svn info
will give:
Path: . URL: https://svn.ggy.bris.ac.uk/subversion-open/subversion/trunk Repository Root: https://svn.ggy.bris.ac.uk/subversion-open/subversion Repository UUID: d9f57dc2-3d1f-4de2-a317-ca3b2cf76729 Revision: 136 Node Kind: directory Schedule: normal Last Changed Author: emma-stone Last Changed Rev: 136 Last Changed Date: 2011-10-21 16:05:07 +0100 (Fri, 21 Oct 2011)
list
svn list https://svn.ggy.bris.ac.uk/subversion-open/subversion
will give:
trunk
and
svn list https://svn.ggy.bris.ac.uk/subversion-open/subversion/trunk
will give:
athens berlin bern cairo dublin file1 file2 folder1/ folder2/ havana helsinki lisbon london madrid moscow oslo ottawa paris rome tokyo
move & copy
If you rename a file or directory manually, you loose its history, this is because subversion needs to be notified that a tracked file or directory will have a new name. It is simpler to use the subversion move command. For instance, to rename "file2", do:
$ svn move file2 new_file2 A new_file2 D file2
You notice that the new file is added and the old one deleted. You could have done this manually but the advantage of this is that the history of the new file before the new name is still available.
A close relation to move is copy. This creates a new file, with a copy of the revision history of it's template:
$ svn copy havana havana2 A havana2
import
When you ask for a new repository, it is empty by default. To populate it, you can use the import command. (import is because the action is done from the server, it imports something). The syntax is:
$ svn import PATH URL/trunk --message "Log message."
- PATH is the path to the local folder (by default it ses "./", i.e. the current folder)
- URL is the full URL of the repository. In the example, I also added "trunk/" at the end and the trunk would be created automatically.
mkdir and copy
Often people ask how then can create the "branches/" directory in the repository to store some specific versions of their code. This can be done by invoking mkdir directly on the server. The syntax is:
$ svn mkdir URL/branches --message "Log message."
Then you might want to create a branch of your project, for instance to call it "version1" as you start to work on version2. Here we see that we can use copy for directories, as well as files:
$ svn copy URL/trunk URL/branches/version1 --message "Creation of the version1 branch."
Then you could check out URL/branches/version1 to work on version1 rather than the trunk.
export
Sometimes, you want to get the files from the version control system but this will not be used as a working copy, for instance you are going to send the files to somebody who is not involved in the development. For instance, it is the command that was used for the Linux1 and Linux2 practicals.
You could do a checkout and remove all the hidden ".ssh" directories manually, but the easiest to to use the "export" command. It works exactly like a checkout except that you end up with a normal local folder, not a working copy. The syntax is:
$ svn export URL PATH
branching and merge
Subversion can support multiple development strands via the creation of branches. The svn copy command is used to make a (space efficient) copy of an entire file tree from, say, the trunk to a subdir called "branches". A popular reason for creating a branch is for a particular developer (or team) to work on something speculative or disruptive:
svn copy https://svn.ggy.bris.ac.uk/subversion/ourproject/trunk \ https://svn.ggy.bris.ac.uk/subversion/ourproject/branches/sally_dev \ -m "The reason why I'm branching is..."
When you have different branches in your project, you might want to merge the changes from one branch to another. For instance somebody has fixed a bug on a branch that is still present in the trunk. You might want to apply the changes done on branch back onto the trunk. Subversion allows you to do this and it is called a merge operation. We will cover this topic very quickly here but you can refer to the Subversion Red Book for more information about merging.
For example, the following command will merge in a change set from revA to revB from the sally_dev branch of ourproject into your working copy:
svn merge -r revA:revB https://svn.ggy.bris.ac.uk/subversion/ourproject/branches/sally_dev
You can then commit these changes--should you so desire--which will end up in the development line of whatever you chose to checkout in order to obtain your working copy.
To go further
The Subversion Red Book is the bible of subversion. Highly recommended.
In the book, you can see how to create your own repository, should you desire. For example, some simple repository setup commands will provide you with a working facility via the filesystem (i.e. the repository is on the same computer that you typically work on), or SSH (i.e. you have SSH access to the machine that will host the respository):
svnadmin create $HOME/my_test_repo
Next you might import some files (that you have stored in a directory called 'projectX'). If you're working on the same filesystem you would use:
cd projectX svn import . file://$HOME/my_test_repo/trunk -m "my import message" svn list file://$HOME/my_test_repo/trunk ...
Which--via SSH--would translate to:
cd projectX svn import . svn+ssh://user@host/absolute/path/to/my_test_repo/trunk -m "my import message" svn list svn+ssh://user@host/absolute/path/to/my_test_repo/trunk ...
NB where the components of user@host/absolute/path/to are:
- user: your username on the remote machine hosting your repository
- host: the hostname of the remote machine
- /absolute/path/to: you must specify the absolute path to your repository ($HOME will be evaluated on the machine to SSH'ing from
And you're away!
Pragmatic Programming
That's all folks. We hope you have the "Pragmatic Programming" course was useful and that you feel (at least a bit) more confident about coding on the Linux platform. Have fun.