Subversion is a version control software, which allows many people to work on a same project without running into conflicts with different versions of the same files. The concept behind Subversion is to have one central repository of the code and everyone having their own working copy of the code. Everyone working on the project modifies only their working copies, and no-one touches the central repository. Whenever someone has made modifications he or she commits his/her modifications to the repository. Everyone else should then update their own working copies to get the most recent version of the code.
This document is not about using Subversion, it is merely about how to set up a Subversion repository in the HUT computer labs. For information on using Subversion, please see the online book Version Control with Subversion and other Subversion documentation.
Subversion is installed on all Linux computers in HUT computer labs. Please
note that, kosh, vipunen, saha, etc are not
Linux computers. Please note that only one person in your project group should set up
the repository.
First you must set up a UNIX group for everyone in your project group. This is done with
UNIX command group create [group name] [users]. Group name cannot be
longer than 6 characters and the real UNIX group name will have a prefix `a-'. The
groups are updated once an hour, so it may take up to an hour to the group to
activate.
Create a group "myproj" with two users, "rsalmin2" and "aotuomi" $ group create myproj rsalmin2 aotuomi Successfully created group a-myproj.
Next, we will create a project skeleton. Create a directory with three subdirectories,
trunk, branches and tags. For more information about
these subdirectories and their meaning, see the Subversion book (link below). Now put all
the code you have written so far in the trunk-subdirectory. If you have
not written any code so far, it's ok, you can add more files later. Your skeleton directory
should now look like this:
skeleton
|-- branches
|-- tags
`-- trunk
|-- Makefile
|-- main.cc
|-- util.cc
`-- util.hh
Next, we will create the actual repository.
Check that you are in your home directory $ pwd /u/opi/43/rsalmin2 Create a new Subversion repository called "project" $ svnadmin create project
Now there is a directory in your home directory called "project". It is
the Subversion repository. You should not touch the repository directory, doing
so you will be asking for trouble. Next up, we will import the project skeleton
into the repository. The importing can be done only once. Importing will be done
with the command svn import [directory] file://[repository] -m "[message]".
Please note that you must give a message. If you don't you will find yourself
in emacs or another editor writing the message or you'll get an error message.
Import the directory "skeleton" to the repository "project" $ svn import skeleton file://$HOME/project -m "Initial import" Adding skeleton/trunk Adding skeleton/trunk/Makefile Adding skeleton/trunk/main.cc Adding skeleton/trunk/util.cc Adding skeleton/trunk/util.hh Adding skeleton/branches Adding skeleton/tags You can now delete the skeleton directory, the files are safely in your repository $ rm -rf skeleton
Next up, we'll set up file permissions for the repository. First, you will be required to give +x access for the "users" group to your home directory. This enables everyone in the "users" group to change directory (chdir/cd) into your home directory. That means all students and staff at HUT. Be sure to have your files secured with proper rights. Then we will change the owner group of the project repository to the group we created earlier. The last line gives the group read and write acces to the repository. The additional 2 in the mode (2770) is the SGID-bit, which makes sure that all files in this directory are owned by the owner group. This is crucial to make the repository accessible by others.
Give +x access for "users" group to your home directory $ chmod g+x . Change the owner group of the repository to our group $ chgrp -R a-myproj project Give the group read/write access to the repository $ chmod -R 2770 project Your repository should now look like this: $ ls -l project/ total 24 -rwxrwx--- 1 rsalmin2 a-myproj 229 Oct 5 11:42 README.txt drwxrws--- 2 rsalmin2 a-myproj 4096 Oct 5 11:42 conf drwxrwx--- 2 rsalmin2 a-myproj 4096 Oct 5 11:42 dav drwxrws--- 5 rsalmin2 a-myproj 4096 Oct 5 16:11 db -rwxrwx--- 1 rsalmin2 a-myproj 2 Oct 5 11:42 format drwxrws--- 2 rsalmin2 a-myproj 4096 Oct 5 11:42 hooks drwxrws--- 2 rsalmin2 a-myproj 4096 Oct 5 11:42 locks
We have now set up a Subversion repository properly. It's time to start working with the
code. As mentioned before you do not touch the repository itself, instead, you
checkout yourself a working copy. This is done with the command
svn checkout [repository address] [directory]. In the following, we will checkout
only the trunk subdirectory of the repository, since it's the only one which
contains any code. Everyone in the project group should do the checkout in their
own home directories.
Checkout the repository to directory myproject $ svn checkout file:///u/opi/43/rsalmin2/project/trunk myproject A myproject/Makefile A myproject/main.cc A myproject/util.cc A myproject/util.hh Checked out revision 1.
Now you have the most recent version of the source code in the myproject-directory. The
myproject-directory is your working copy. You can now modify the source in
the working copy. After you have done some modifications to the source, you commit
your changes to the repository. This is done with the command svn commit -m "message".
Again, you will have to enter a message here, otherwise and editor or error message will pop up.
Enter your working copy directory $ cd myproject Now you can edit your working copy $ emacs main.cc # (you don't actually have to use emacs, any editor will do) When you have finished coding, commit your changes $ svn commit -m "message about the modifications I made" Sending main.cc Transmitting file data . Committed revision 2.
Now, you have made changes to the repository and everyone in your group should
update their working copies to get the most recent revision. A good rule is
that every time you start coding, you update, when you're finished, you
commit. This way everyone has a recent working copy.
$ svn update U main.cc Updated to revision 2
When the project advances, you will need to have more files in it. If you add files to
the project, you must add them to Subversion. This is done with the command svn add.
This does not automatically add them to the repository, you must also commit your changes.
Add newfile.cc and newfile.hh to your project $ svn add newfile.cc newfile.hh A newfile.cc A newfile.hh Now commit your changes to the repository $ svn commit -m "Added newfile.cc and newfile.hh" Adding newfile.cc Adding newfile.hh Transmitting file data . Committed revision 3.
If two or more users make modifications to the same file and they both attempt to commit the same file with different modifications to the repository, a conflict occurs. In a trivial case, when the changes are simple additions to the files, Subversion automatically merges the new files. It is a good idea to look at the merged files and see that they are working togeher nicely.
Attempt to commit a file that has a newer version in the repository $ svn commit -m "modifications to main.cc" Sending main.cc Transmitting file data .svn: Commit failed (details follow): svn: Out of date: 'main.cc' in transaction '8-1' Updating to the most recent version $ svn update G main.cc Updated to revision 8. The 'G' before 'main.cc' tells us that the files have been merged
Not all conflicts are trivial and can be merged together automatically. In such cases, you will need to manually merge the modifications together.
Attempt to commit a file that has a newer version in the repository $ svn commit -m "more modifications to main.cc" Sending main.cc svn: Commit failed (details follow): svn: Out of date: 'main.cc' in transaction '10-1'' Updating to the most recent version $ svn update C main.cc Updated to revision 10. The 'C' before 'main.cc' tells us that there is a conflict $ ls main.cc main.cc.mine main.cc.r9 main.cc.r10 Three new files have been created by Subversion
The new three files in the above example are created by Subversion. main.cc
has now some modifications made by Subversion. main.cc.mine was the
code you had in your working copy before updating. The main.cc.r?? files
are unmodified versions of the file from the two most recent revisions, in this example
they are from revisions 9 and revision 10. Now you will need to modify main.cc
and merge the changes made by you and the other members of your group.
Now edit main.cc and merge the changes $ emacs main.cc # you can use any editor you want Changes merged, now tell Subversion, we're ok $ svn resolved main.cc Resolved conflicted state of 'main.cc' Conflict resolved, the three new files are removed $ ls main.cc Don't forget to commit changes! $ svn commit -m "Modified main.cc and fixed a conflict" Sending main.cc Transmitting file data . Committed revision 11.
It is possible to use your Subversion repositories outside of HUT computer labs, too.
It requires you to have access to the Linux machines in the network. After you
have set up your repository, you can checkout it from any computer using
svn+ssh://username@[linux-machine].hut.fi/[repository directory]
as the repository address. It actually connects to the computer with ssh
and then runs svnserve at the host machine.
$ svn checkout svn+ssh://rsalmin2@obelix.hut.fi/u/opi/43/rsalmin2/project/trunk myproject Password: Password: Password: A myproject/Makefile A myproject/main.cc A myproject/util.cc A myproject/util.hh Checked out revision 1.
Note that the password will be asked multiple times. This is a feature of svn+ssh. You can ease up your life with public key authentication so you don't have to enter your password when using ssh. Please consult the manual of your ssh client for more information.
The Linux machines cannot be accessed from outside the campus area. You can, however
tunnel your connection from the public UNIX servers (vipunen, saha
or kosh) to any Linux machine. See the manuals of ssh and Subversion for more
information.
It is also possible to use different Subversion clients, such as TortoiseSVN. Just use the svn+ssh repository address as described above.
If you want a job as a programmer, you will most likely need to be familiar with version
control software. Subversion is very widely used in the business, and knowing it will
certainly be an advantage when applying for a job. If you submit your svn logs (command
svn log > logfile.txt) together with your project, you might earn a few bonus points
in your project evaluation.