Code Management | geant4.web.cern.ch

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.

Please also look at the Tag & Release Policy document for Geant4.
For a more exhaustive tutorial on SVN, see documentation you find from the original SVN Home Page.

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.

1. The Geant4 code and SVN repository structure

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.

trunk: Current development under the directory geant4 (corresponding to the HEAD in CVS);
tags: Contains tagged versions of geant4 and of all (sub)categories in a directory tree. The code therein cannot be modified;
branches: 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.

2. Browsing the Geant4 repository

The svn servers allow to browse the Geant4 repository using the svnweb interface.

3. How to setup and access the SVN repository.

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.

Install svn

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.

4. Checkout and update the code

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 trunk
```
NOTE 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-00
```
will 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-00
```
Alternatively 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 geant4
```
Next 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 update
```
This 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 status
```
The 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 -u
```
This 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
```

4.1 Checkout of User Documentation

The User Documentation is in a separate git repository:

https://gitlab.cern.ch/geant4/geant4-documentation

The README.md file (below) should contain sufficient explanations about how to manage commits to the documentation and utilise sphinx/ReST (framework/format):
- First time updater of documentation
- ReST formatting help sheet

5. Viewing changes and resolving conflicts

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 !
Use

 svn status -h

to get a full explanation of the output produced by svn status.

6. Committing changes to the repository

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_file
```
for 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_directory
```
SVN 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.
With:
```
 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!

7. Tagging and versioning

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_ID
```
where 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_ID
```
This 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!

8. More Useful SVN commands

To see the history and log messages for a specific file xyz.cc:
```
 svn log xyz.cc
```
This 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.cc
```
show changes made in xyz.cc since revision rev1. Ommitting the optional revision number
```
 svn diff xzy.cc
or
 tkdiff xyz.cc
```
will 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.cc
```
Will 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/g3tog4
```
This 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 ls
```
will 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
```
 svn info
```

9. Information on SVN

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.

10. Where to find released source code

The last publicly available code of geant4 is accessible from the Web.