$Revision: 1 $
| Revision History | ||
|---|---|---|
| Revision 1.1 | 2006-12-26 | adn |
| XML'ized SGML version of document. | ||
Abstract
This document is meant to show you how to access and use the Arabeyes SubVersion repository. It is based on Arabeyes' CVS HOWTO.
Table of Contents
SVN stands for SubVersioN. It is a version control system that has been developed under a Apache/BSD style license to replace CVS. Using SVN, you can record the history of your source files and/or documents. It does not check your work for you, but it is a good safeguard against disasters, should they happen.
This HOWTO is not going to teach you everything about SVN, but it is designed to be a quick guide to using the SVN Repository. For more information on using SVN you can check:
SubVersioN Home - http://subversion.tigris.org/
SVN Book - http://svnbook.red-bean.com/
There are many free SVN clients you can download. If you are a Linux/Unix user, then you probably have it as part of the subversion package. If you are a Windows user, you have two options:
Cygwin bash shell - http://sources.redhat.com/cygwin/
Cygwin is a UNIX environment for Windows, which comes with a command-line SVN client.
WinSVN - http://www.winsvn.org/
WinSVN is a graphical SVN client for MS-Windows
TortoiseSVN - http://tortoisesvn.tigris.org/
TortoiseSVN is another graphical SVN client for MS-Windows
It is strongly recommended that you use the linux/unix SVN client. However, if you must use Windows, Cygwin bash shell is what we recommend. This HOWTO assumes that you either know the equivalent of commands on the graphical front-end, or use the command-line interface.
There are two types of SVN access: Anonymous (read-only access; open to all), and developers (read/write access;restricted).
To commit to the SVN server, you will need to have an account (username and password). For the purpose of this document, we will assume your username is myaccount and password is rocks.
Anonymous access is the same as the account based access, except that you would not be able to commit files to the SVN repository. Unlike CVS, you do not need to login to access the files.
$ svn co https://svn.arabeyes.org/svn/module
In the above example, be sure to replace the module with the approrpriate module name from the SVN repository.
SVN write access is not lightly given. You may want SVN access if you are:
Starting a new project
Contributing to an existing project
If you are requesting an account to start a new project, then your account will be approved once the Core Management Team has apporoved your project. However, if you are requesting an account to contribute to an existing project, then the coordinator of that particular project will have to approve your account creation first.
In order to request SVN write access on Arabeyes' SVN repository, you must file a bug-report via bugs.arabeyes.org. It is also expected that you have read this document and know exactly why you are needing SVN access.
If at any point you wish to change your SVN password, you will need to email the SVN administrator with an encrypted version of your password. This can be done by taking the output of one of the following methods:
$ perl -e 'print crypt("PASSWORD", XY),"\n"'
Or
$ python -c 'import crypt; print crypt.crypt("PASSWORD", "XY")'
Where PASSWORD is your password and XY are two random alphanumeric characters of your choice.
The word 'checkout'[1] in SVN refers to downloading the files to your local machine. It is analogous to you checking out a book from the library, however you are not only expected to bring it back, but update it too!
$ svn checkout https://svn.arabeyes.org/svn/projname
The above command will create a directory structure on your computer, which will have everything that is under projects on the SVN repository. So, let us say we don't want everything under projects. Let us assume that you want the bicon project source and everything for it.
$ svn checkout svn checkout https://svn.arabeyes.org/svn/projects/bicon
When you 'commit' a file, you are essentially uploading it to the repository. So, now that you have downloaded the files and have made some changes, you would like to put it back on the repository.
For the sake of this example, we will say you are modifying the file 'myfile.cc'. Here is how to commit it:
$ svn commit myfile.cc
If the file does not already exist, and you are creating a new one then you need to 'add' it first. Here is how:
$ svn add myfile.cc $ svn commit myfile.cc
The first command creates an entry for the file in the repository, and the second one actually makes the commit to the repository (making it available). If the file already exists and you are making changes to it, you can ignore the 'svn add' command. For more help do 'svn help' from your linux/unix prompt.
Once you execute the commit command, a text editor will be launched so you can enter a brief log of what you have done. This is especially useful for others who are working on the same project - as it gives them an insight of what you have changed without having to look through the file(s). The editor is usually vi, on most Linux/Unix systems.However, that is not necessarily the case. It is whatever you have the environment $EDITOR set to. To find out what it is set to in your environment, do:
$ env | grep EDITOR
In order to get into insert mode under VI, press i. Then you may continue to type in your brief log. Once you are done, press ESC (which will get you out of the insert mode), and enter :wq then hit return. This will write (to save) and quit. Your commit will then be executed.
When you have made changes that span across multiple files it is best to commit them in one batch, as opposed to doing so one at a time. That is for 2 main reasons:
Minimizes on the amount of svn notification mail that goes out to everyone on the 'cvs' list, whenever a commit is made.
Most of the time the multiple files changed involve the same issue. For
example, if the two files test.cc and
test.h were changed, it is unnecessary to commit them
individually.
There are two ways of committing multiple files.
$ svn commit file1 file2 file3
Or you can simply let it recursively do it:
$ svn commit
The first gives you more flexibility in what the files are exactly, whereas the latter simply commits any file that has changed in the current directory and all subdirectories.
New directories are either created as part of an existing project or to create a new module for a newly imported project. Before creating any new directory, please always consult the SVN administrator. This is particularily important to avoid redundancy and maintain an ordered organization.
This does not apply to those who are module owners. For instance, if the
author of X decided to add
X/yz/ to his X/ directory, it does
not require any approval from the SVN administrator.
Although this does not happen very often, it is worth noting here, especially for those who own a project and would like to add a new directory with some content in it already.
When that is the case, use svn import. For example, if
projX in projects/projX is
about to add a new directory called games with 10 files
in it, do this:
$ svn import projects/projX/games https://svn.arabeyes.org/svn/projects/projX/
For more information type svn help import' or consult the SVN Manual.
It goes without saying that it is very important to enter a useful and meaningful comment on commits.
Translation (PO's):
When committing .po file(s) always make sure the
comment includes the output of:
$ msgfmt --statistics file.po [2]
This is to avoid commit logs such as "translated a little", which mean very little if anything at all.
Development Source Code:
Comments on source code commits may be a little easier (as the types of changes will vary). Always make sure you keep track of the changes you make AS you make them, so you remember what they are before committing.
An example of a bad log is: "I made a few fixes". What fixes? If you can't remember what you did anymore, then do a diff of the changes, go through it and note the changes you made.
Documents:
Generally documentation comments are inevitably going to be vague. If the document is small, that's not a problem. If it is not, point to the location you made the changes to. For example: "Chapter 3, Section 4 - Re-wrote the second paragraph for clarity" is a good comment.
There is a very simple rule to follow on this one. Any file that is generated by a program from another file that resides on SVN should not be put on SVN. That is unnecessary redundancy.
Compressed files (gzip/bzip2/Z/etc) should not be put on SVN in their compressed/tarred forms.
Generally the only binary type of files acceptable on SVN are graphics images and audio files. Every other file type is expected to be text.
Since there are others who are likely to have made changes during the course of the project, your local working copy of the SVN contents may not always be up to date. In order for you to keep your copy up-to-date you can:
$ svn update
Note that this can only be done while you are inside the directory you are intending to update.