Impuls: Subversion
From Mariki
Contents |
Abstract
Starting with impuls 84 we use the SVN or subversion system for revision control of the impuls. This system has the advantage that end users no longer need to be concerned with what other users are editing and can concentrate fully on their creative work. This manual explains how to use svn for the impuls from a UNIX based system. For windows tools please look at the web. In writing this short manual I have extensively used the Version Control with Subversion book. Please consult this book for more in depth background information when needed.
Introduction
Subversion is a version control system based on the copy -> modify -> merge technique. This technique works as follows. A central repository containing all impuls files is held on a subversion server (Broglie in our case). This server is only accessed via the subversion system by means of the svn command and never directly. When a user joins a project in this case a new impuls, a copy is made from the server to the local machine the user is working on. The user then works on this copy locally using programs such as vi, gedit or nedit to edit text files. When the user is finished the file is copied back to the server so others may download the updated file. Subversion maintains a log of all changes and allows files to be reverted back to an earlier state. When multiple users edit the same file it provides them with means to safely merge their changes.
Prerequisites
To be able to work with svn you need a working copy of the subversion program please consult the web on how to install it. You also need to have /usr/local/bin in your $PATH variable at the University. To set this (for non login shells) enter the following command (from a terminal at the University):
echo PATH=/usr/bin:/bin:/usr/sbin:/sbin:/usr/local/bin:$HOME/bin >> .ssh/environment
Installation at home (currently only for Ubuntu)
To install svn at your Ubuntu pc at home, simply type the following line in a terminal.
sudo apt-get install subversion
SVN for impuls editors
Overview
As an impuls editor you always work on a local copy of the data for each new impuls. This work proceeds in several steps.
- Check out a local copy of the current impuls
- Add or edit the files locally
- Commit changes to the repository or merge if necessary
Daily life with svn
First we will check out a local copy of the current impuls. Please replace # with the current impuls version number.
Change to a local directory where you would like the impuls to be created. Then execute the following command:
impget #
As an alternative you may use the full command:
svn checkout svn+ssh://$USER@lilo.science.ru.nl/vol/subversion/broglie/impuls/main/branches/imp#
It asks for your password and then creates a local copy of the current impuls in your directory. You may then work at the files in the directory locally with your favorite program. Any changes made will not be transferred to the server until they are manually committed. When you feel the changes to the file are worth saving you may execute the following command from within the imp# directory (or one of it's subdirectories).
svn commit
This will merge your changes to the server if they do not conflict with the changes of other users. If they do conflict the commit will abort and you have to correct them with the help of the svn update
The following additional commands are at your disposal (all of them can be used with no arguments on the entire local copy or just on one file or directory):
- svn update
- Updates your local copy to the latest server version, also helps to merge non trivial changes.
- svn status
- Displays all changes without merging
- svn diff
- Compares file changes without merging
- svn revert
- Reverts file to it's original form before the changes
- svn resolved
- Marks a conflicting file as resolved (overwrites server version with local)
- svn add X
- Schedules file or directory X for upload to the server at next commit
- svn delete X
- Schedules file or directory X for deletion at next commit
- svn copy X Y
- Schedules copy of X to Y at next commit (X and Y need to be in the repository)
- svn log
- Displays log file
All changes to the repository (including deletions) can be undone by any user so don't be afraid to use it :) You may checkout any earlier revision of a file using the -r option. For more information consult the book or look at the manpage for svn using:
man svn
Making daily life easier, using ssh keys for secure automatic login
While working with svn on a regular basis it can be really annoying to have to type your password for each action. This section describes how create a ssh key and use it for secure automatic login (this can also be used for ssh in general and is not limited to svn). These instructions are for a UNIX based system. First change to the ssh directory using the following commands (enter at each newline):
cd cd .ssh
Note: Both on the local and remote machines the .ssh directory needs to exist. If you use ssh from the machine it will automatically be created. Now create a new public-private key pair using:
ssh-keygen -t dsa
When it asks for a filename use the default by pressing enter and when it asks for a password also press enter. WARNING: Do NOT enter a password. If you do, automatic login will not work!!! This is still secure because you have a login password on the local machine. Now copy the key to the remote machine using:
scp id_dsa.pub $USER@lilo.science.ru.nl:~/.ssh/localmachine.pub
Next login to the remote machine using:
ssh $USER@lilo.science.ru.nl
Now execute the following sequence of commands to enable automatic login (enter at each newline):
cd .ssh cat localmachine.pub >> authorized_keys rm localmachine.pub chmod 600 * cd chmod 700 .ssh
Now exit the remote machine and set permissions for your local ssh directory (enter at each newline):
cd chmod 700 .ssh cd .ssh chmod 600 *
You may now login without presenting a password to lilo using ssh or svn.
SVN for head editor or archive maintainer
WARNING
This section is only meant for the impuls head editor or the subversion archive maintainer if you do not fall in this category please read nor use any of the following commands in order to prevent breaking or contaminating the archive. The repository itself is a virtual database filesystem and should NEVER be edited directly. Only using the svn command. Also please maintain the file and directory structure layout in order to not break scripts or programs and prevent file chaos.
Repository structure
The subversion repository for the impuls is located at /vol/subversion/broglie and writable via porthos. All impuls members should be in the broglie group to be able to access the repository.
Repository Structure:
broglie
|
impuls
|
---------------------------------
| | |
documentation main general
: | :
------------ ------------
| | |
branches tags trunk
| |
------........ (default impuls)
| | :
imp84 imp85 imp#
Creating a new impuls
Creating a new impuls equals making a new branch of the trunk this is done with the following command (replacing # with the new impuls number):
createnewimpuls #
As an alternative you may use the full command:
svn copy svn+ssh://$USER@lilo.science.ru.nl/vol/subversion/broglie/impuls/main/trunk svn+ssh://$USER@lilo.science.ru.nl/vol/subversion/broglie/impuls/main/branches/imp# -m "Creating impuls #"
Users may then checkout this new impuls using the command in the previous section.
Changing the default impuls
To change the default impuls first checkout the trunk using:
svn checkout svn+ssh://$USER@lilo.science.ru.nl/vol/subversion/broglie/impuls/main/trunk
Then modify and commit as usual.
Troubleshooting
Connection errors
- svnserve command not found
- You receive this error because /usr/local/bin is not in the $PATH (of non interactive shells) on porthos see the Prerequisites chapter.
- you don't exist go away
- There's probably something wrong with the server, contact C&CZ.
Syntax
Conflicts
More Information
Detailed information about subversion can be found in the Version Control with Subversion book.
