Subversion Rules
This page describes the use of the
Subversion version control system
(SVN for short) in the SE working group.
If you are new to version control, please consult the introductory chapters of the
SVN book. Below we will refer to this book quite frequently.
If you understand
CVS,
but are new to Subversion, please consult the Appendix "Subversion for CVS users" in the SVN book.
Quick start
To get up and running with SVN quickly, proceed as follows:
- Install the TortoiseSVN client (requires a restart).
- Create a folder in a convenient location.
- Unless there is a good reason to do otherwise, we use
d:/svn by default and maintain the exact same directory structure there as exists in the repository.
- Right click the folder and select "SVN Checkout"
- Enter the URL of repository (see below)
- It may not be the brightest idea to check out the whole repository, though…
- Use your regular institute account name and password to authenticate.
- Now use Subversion commands as needed to work with your files.
- If you are working with Eclipse, you will also want to install Subclipse there.
Things to remember while working with Subversion:
- Changes to the content of files will be reflected in the repository as soon as you perform
commit (if and only if the file is versioned)
- You can freely mix versioned and unversioned files in your working area.
- Consider using the
svn:ignore property to reduce the hassle.
- Files become versioned only if you use SVN
add or import.
- Directories become versioned only if you use SV
mkdir or import.
- To move, rename, or delete a versioned file or directory in the repository you need to use SVN
move or delete rather than plain file system operations.
- SVN
delete never really deletes in the repository, it just removes something from the youngest revision.
- SVN
copy copies with version history included, while file system copy followed by SVN add creates new-looking entries.
- SVN
copy is preferable, as it costs essentially no storage space in the repository (the copy is just a link internally). This is why SVN copy is the basis for tagging and for branching sets of files. See the SVN book for details.
- When using tortoiseSVN, always ignore the
.svn directories (they are meant to be invisible) and take care to never accidentally create a repository when in fact you mean to import a directory.
- Don't forget your SVN
commit calls.
Repositories
Location
We use the following repository:
- https://svn.imp.fu-berlin.de/agse/
- It is authenticated via Kerberos using your normal Zedat login and password
- Authorization is defined in the file
/import/svn_auth/agse/AuthzSVNAccessFile, which can be found on Linux machines like duesseldorf. See also Administration Issues below.
In order to keep path names short, we do normally not use the SVN convention of having project-level directories called
trunk, branches, tags.
Instead, we usually collect all branches in one single top-level directory
_allbranches and all tags in one single top-level directory
_alltags.
Use appropriate long names and/or directory hierarchies below this level.
Avoid cluttering the namespace.
Delete branches and tags if and when they are no longer needed.
Usage issues (client side)
Which client to use
There are quite a number of clients available for SVN, but most of them are not very good.
We use three different clients:
- The standard command-line client
svn; often under Cygwin. This is usually the most convenient for scripting (although SVN has API bindings for various languages, too) and for other heavy-duty use.
- tortoiseSVN, a GUI client that comes as an extension of Windows Explorer. Powerful and easy to use.
- Subclipse, a GUI client that comes as an Eclipse plugin.
What to put under version control
- Files for which old versions need to be kept for reference purposes (such as program source code and modifiable observation data files)
- Text files that will be changed by multiple persons concurrently.
- Typical examples are program source code of all kinds and latex/lyx files
- Automated merging does not work for binary files, so concurrent changes are not a reason for versioning binary files such as MS Office files.
- Merging complex XML files generated by applications (such as OpenOffice) makes sense only for some applications (whose file changes are always local in character) and only in certain settings (where overlapping changes almost never occur). Think!
What NOT to put under version control
- Avoid versioning very large files
- This both strains storage space on the server and slows down SVN client usage.
- Also please understand that an SVN working area always contains two copies of each file (the working file and a copy of it as it was when last checked out).
- Avoid versioning files that can be found publicly on the web.
- Avoid versioning files that will be of only short-term interest.
- Do not version files that can be (re-)generated automatically.
Server administration issues
Setting access rights
- Authentication is normally via Kerberos against the FB's
FU-BERLIN account database, so no local SVN user accounts are required.
- Note that the resulting user names are of the form
username@FU-BERLIN.DE.
- The access control file resides in
/import/svn_auth/agse/ and can be accessed from paste for instance, by all members of the agse.
- Our access files are under version control themselves: The directory
/import/svn_auth/agse/ itself is a SVN working copy. So after doing any changes to these files be sure to commit them.
- Definining groups. Access rights should not be defined for individual users, but rather for user roles. Each role is instantiated by a user group. SVN authorization by user groups can be defined in the SVN configuration as described in section "Server configuration/httpd/Authorization Options" in the SVN book.
- An exception is the 'students' subtree (for bachelor/master theses), where normally exactly one student user account will get access besides the AGSE group.