This is a quick-reference guide for Geant4 developers who need to access to the Geant4 SVN repository and perform operations by using the subversion version control system.
The Geant4 SVN repositories are located on the svn server svn.cern.ch. There are repositories for source code (in geant4), documentation and papers (in g4documents), validation and testing (in g4tests), and Geant4-related tools (in g4tools). The repository is accessible only through svn/g4svn commands using either the https or svn+ssh protocol. The repository is only accessible to collaborators after signing-in once a year to confirm their Collaboration membership and acceptance of the Geant4 regulations. Access to the web form is only available to collaborators; if you cannot access the form, contact your working group coordinator to get you onto the list of collaborators.
- The GEANT4 SVN repository structure
- Browsing the Geant4 svn repository
- How to setup and access the repository
- Checkout and update the code
- Viewing changes and resolving conflicts
- Committing changes to the repository
- Tagging and versioning
- Useful SVN commands
- Information on svn
- Where to find released source code
The Geant4 source is actually structured in the source directory under geant4 in a tree of directories following the category and subcategory structure. Other directories under geant4 include examples, tests, etc. The source is distributed according to each sub-domain.
The sub-domain global is a place holder for all the development done which affects all the sub-domains.
include directories contain header files (.hh) and inline functions definition files (.icc); src directories contain the related implementation files (.cc); test directories contain unit test applications specific to the related sub-domain, to test the code under distinct conditions.
The Geant4 code repository has three top level directories, trunk, tags, and branches.
- Current development under the directory geant4 (corresponding to the HEAD in CVS);
- Contains tagged versions of geant4 and of all (sub)categories in a directory tree. The code therein cannot be modified;
- Contains branches of geant4 and for (sub)categories in a directory tree.
The svn repository can be browsed using the svnweb interface, to login use your CERN account.
To use svn, your need to check and install or set up the following:
- svn must be installed on your machine and must be in your PATH
- You need to get access to g4svn, a script to help with complicate svn commands.
- python is needed by g4svn, and version 2.4, or higher, is required. On slc4, python is version 2.3, and this will fail. On slc4 machines at CERN, use g4svn.sh from the geant4 dev area /afs/cern.ch/sw/geant4/dev/scripts to use g4svn with a recent version of python.
- access via ssh. If you are prompted for a password by svn, g4svn will prompt you many times for a single command. Please follow instructions below to set up "trusted" access for ssh.
You need to have svn installed on your machine. This is normally either installed or can be installed using system tools.
Access the tool g4svn
To work with Geant4, you also need a Phyton script g4svn to simplify the svn operations with most complicated syntax. Please note that in most cases below the plain svn command is used directly, while in a few cases you need to use g4svn.
This g4svn script is available either using directly svn, or at CERN its available from the Geant4 dev area, see blow. If you want to install svn into $HOME/bin, do:
cd $HOME/bin svn co svn+ssh://_Your_CERN_login_@svn.cern.ch/reps/g4tools/trunk/svntools/g4svn . - or - cd $HOME/bin svn co https://svn.cern.ch/reps/g4tools/trunk/svntools/g4svn .
using either the svn+ssh protocol (preferred, see below) or the https protocol. The "." at the end of the command can be replace by a directory "xyz", then checkout will then be placed into this directory, i.e. into $HOME/bin/xyz in the example above. In case of problems with the svn, you can can also download the g4svn tool as a zip file.
At CERN you can also use g4svn from the Geant4 AFS dev area /afs/cern.ch/sw/geant4/dev/scripts.
g4svn should be in your PATH, so you either copy g4svn into a directory in your PATH or you add its directory to your PATH; on Unix ~/bin very often is in the PATH.
For Windows follow the instructions in the g4svn documentation.
Set up trusted ssh access
If you are asked for a password by svn, you shoukd set up "trusted" access where you deposit the public part of an ssh key generated on you machine on the webserver. Detailed instruction for to set this up are available in the intructions from the CERN SVN service team.
Choice of protocol to access the svn server
Access to the repository is given either using the svn+ssh protocol, or using the https protocol. Using svn+ssh will in general be the simpler and safer method from all locations, if ssh is available. The use of the https protocol caches information locally, including the password in an encrypted form. Using the svn+ssh protocol nothing is cached.
Once the environment for the above is set, you are ready to checkout the software. In the following examples we use the svn+ssh protocol, if you prefer using https, replace svn+ssh with https in the examples below (let's suppose to use $HOME/ as checkout directory).
- If you are going to build the SVN tree in the local working-space for the first time, the command (for the SVN geant4 module) to check out the current trunk of the repository (what referred to be the HEAD in CVS), is:
cd $HOME g4svn co trunkNOTE that the trunk in general will fail to compile. You should check out a reference tag, or release instead (i.e. using the reference tag geant4-09-04-ref-00):
cd $HOME g4svn co geant4-09-04-ref-00will checkout the reference tag into the directory geant4. If your local account differs from the login at CERN, you will need to provide the login using the option --login:
cd $HOME g4svn co --login="your_CERN_login" geant4-09-04-ref-00Alternatively you directly may use svn to do the checkout:
cd $HOME svn co svn+ssh://"your_CERN_login"@svn.cern.ch/reps/geant4/tags/geant4/_symbols/geant4-09-04-ref-00 geant4Next you will need to update, or switch, the subcategory/ies you are working with to the trunk using g4svn. As example, if you want to change files in the run category, you need to switch run to the trunk:
cd geant4/run g4svn switch trunk
- To update the local geant4/ tree and checkout from the repository all last modifications and new files:
svn updateThis will the current directory and all subdirectories with changes from the repository. Directories "switched" to a specific tag will not have updates in the repository, so this will only update those parts of the (sub)directory tree which had been switched to the trunk or are on a branch. If there are local changes, svn will attempt to merge local and remote changes. This merging of changes may fail or clash, and svn will warn you, and will not allow to commit before this clash is resolved using svn resolve.
- To see what has changed since the last checkout, update, or commit in the local tree geant4/:
svn statusThe letters indicating the status of the individual files are documented in the svn manual descritpion of svn st This command just prints to the standard output.
- To see differences of the repository and the local tree geant4/:
svn status -uThis command just prints to the standard output.
- To update just a category in the local geant4/ tree, to a specified tag for it (example, tag "run-V09-03-00" for the run category):
cd $HOME/geant4/source/run g4svn switch run-V09-03-00
- To update to a specific reference tag (e.g. tag "geant4-09-04-ref-00"):
cd $HOME/geant4 g4svn switch geant4-09-04-ref-00
The User Documentation is in a separate git repository:
- The README.md file (below) should contain sufficient explanations about how to manage commits to the documentation and utilise sphinx/ReST (framework/format):
From whatever sub-tree of $HOME/geant4/, by typing ...
svn status -u
the system will print out to the standard output which files have been changed in the repository or modified in the local sub-tree. It will also display the contents of new directories which may have been introduced in the repository !
svn status -h
to get a full explanation of the output produced by svn status.
Once sure of all modifications made, having checked that there are no clashes with files, and locally tested that everything works fine, changes and new files can be committed to the repository.
- First update to the trunk revision of the repository (unless you need to work on a branch...):
g4svn switch trunk
- If there are new files which must be committed, SVN has to be instructed first to add them to the repository. So first, locate to the right sub-tree where the new files are placed and then do:
svn add new_filefor each new file (where new_file is the name of the file), or else
svn add *to add at the next committal all new files placed in that sub-tree (be careful not to add "rubbish" files...).
If there's a new directory to be added, then on doing:
svn add new_directorySVN will be instructed to add the new directory and every file inside it at the next committal.
- If there are files to be deleted from the repository, SVN has to be instructed as well. So first, locate to the right sub-tree where the affected files are placed and do:
svn remove old_file to "delete" the repository version at the next commit
- To commit to the repository, locate to the right sub-tree and do:
svn commit -m "description"where description is a reasonable message specifying what the committal is meant to update. This command will commit all modified files in the current sub-tree. If the -m option is not specified, SVN will open an editor forcing the user to write the description of the committal for each sub-directory which has files for committing.
svn commit -m "description" file_name(s)only the file file_name(s) will be committed in the repository.
NOTE 1 - Pay attention - the svn commit command is going to modify the files in the repository!
NOTE 2 - If you are NOT working on a branch, you must always update on the trunk before committing. Our SVN repository will not allow commiting, adding or removing files to/from a tagged version!
Symbolic tags are meant to permanently record which revisions of which files were used in creating a software distribution. The checkout and switch commands then allow one to extract an exact copy of a tagged release at any time in the future, regardless of whether files have been changed, added, or removed since the release was tagged.
- To create a tag version of a directory tree, locate first in the sub-directory corresponding to the sub-tree to be tagged and then do:
g4svn tag tag_IDwhere tag_ID is the label-name of the symbolic tag (e.g. run-V09-03-00). This command will tag all files contained in that sub-directory recursively and the sub-directory itself.
- To update to the tag just done:
g4svn switch tag_IDThis will switch your local tree to the tagged tree.
- Tagging individual files is not supported in general, as our svn setup always operates on directories. An exception to this rule currently is that tags for Makefiles and/or geant4/Configure are supported, following a specific tags naming scheme any-gmk-Vxx-xx-xx or Configure-Vxx-xx-xx.
Pay attention, the g4svn tag command writes directly to the repository!
- To see the history and log messages for a specific file xyz.cc:
svn log xyz.ccThis will give change history for the given file showing your the svn revisions numbers the file was changed and the log message given at the commit.
- To compare a checked out file to specific previous revision svn revision number rev1
svn diff -r rev1 xzy.cc or tkdiff -r rev1 xyz.ccshow changes made in xyz.cc since revision rev1. Ommitting the optional revision number
svn diff xzy.cc or tkdiff xyz.ccwill show changes made to the local file.
- To compare two revisions identified by their svn revision numbers rev1 and rev2 of a file, see svn log command to get the revision numbers,
svn diff -r rev1:rev2 xyz.cc or tkdiff -r rev1 -r rev2 xyz.ccWill show changes made in xyz.cc between revision rev1 and rev2. Note the slightly different syntax using svn and tkdiff. One can also compare the trunk against a revision in a branch or tag using full repository URLs:
svn diff svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/g3tog4 \ svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/_symbols/geant4-09-04-patches_branch/source/g3tog4This will show all differences for all files under these two paths. A more useful output is given by the --summarize option, showing which files were modified:
svn diff --summarize svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/g3tog4 \ svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/_symbols/geant4-09-04-patches_branch/source/g3tog4
- To browse the repository
svn lswill show the files in the repository of the current directory, useful option are -R to recurse subdirectories and -v for verbose output showing the date, revision, and author of last modification. With a repository URL specified, this path is used instead of the working directory.
- To see the repository URL, the revision, and other info
To have a complete view of the available commands on SVN, see the documentation from the originalSVN Home Page.
To have a detailed description of both g4svn, and more detail on svn commands, please see the g4svn documentation. Also the documentation of the CERN SVN service will be helpful.
To help the transition from CVS to SVN, here is a list of svn commands equivalent to cvs commands.
The last publicly available code of geant4 is accessible from the Web.